Sync docs: ARCHITECTURE, PROJECT, PROJECT_PLAN
- ARCHITECTURE.md §12: add mciasdb, mciasgrpcctl, internal/grpcserver, proto/, and gen/ to the directory structure diagram - ARCHITECTURE.md §17: replace buf generate references with protoc; the implementation uses protoc + protoc-gen-go + protoc-gen-go-grpc invoked via go generate ./... (proto/generate.go) - PROJECT_PLAN.md §7.1: replace buf.yaml/buf.gen.yaml acceptance criteria with the protoc-based go:generate approach actually used - PROJECT_PLAN.md §7.6: clarify that gen/ is committed to the repo (not gitignored); only the binary /mciasgrpcctl is excluded - PROJECT.md: replace scrypt with Argon2id (the actual algorithm); remove the redundant Argon2 suggestion line
This commit is contained in:
@@ -501,19 +501,28 @@ passphrase_env = "MCIAS_MASTER_PASSPHRASE"
|
||||
```
|
||||
mcias/
|
||||
├── cmd/
|
||||
│ ├── mciassrv/ # server binary entrypoint
|
||||
│ ├── mciassrv/ # server binary entrypoint (REST + gRPC dual-stack)
|
||||
│ │ └── main.go
|
||||
│ └── mciasctl/ # admin CLI entrypoint
|
||||
│ ├── mciasctl/ # REST admin CLI
|
||||
│ │ └── main.go
|
||||
│ ├── mciasdb/ # direct SQLite maintenance tool (Phase 6)
|
||||
│ │ └── main.go
|
||||
│ └── mciasgrpcctl/ # gRPC admin CLI companion (Phase 7)
|
||||
│ └── main.go
|
||||
├── internal/
|
||||
│ ├── auth/ # login flow, TOTP verification, account lockout
|
||||
│ ├── config/ # config file parsing and validation
|
||||
│ ├── crypto/ # key management, AES-GCM helpers, master key derivation
|
||||
│ ├── db/ # SQLite access layer (schema, migrations, queries)
|
||||
│ ├── grpcserver/ # gRPC handler implementations (Phase 7)
|
||||
│ ├── middleware/ # HTTP middleware (auth extraction, logging, rate-limit)
|
||||
│ ├── model/ # shared data types (Account, Token, Role, etc.)
|
||||
│ ├── server/ # HTTP handlers, router setup
|
||||
│ └── token/ # JWT issuance, validation, revocation
|
||||
├── proto/
|
||||
│ └── mcias/v1/ # Protobuf service definitions (Phase 7)
|
||||
├── gen/
|
||||
│ └── mcias/v1/ # Generated Go stubs from protoc (committed; Phase 7)
|
||||
└── go.mod
|
||||
```
|
||||
|
||||
@@ -719,11 +728,12 @@ proto/
|
||||
|
||||
gen/
|
||||
└── mcias/
|
||||
└── v1/ # Generated Go stubs (buf generate output)
|
||||
└── v1/ # Generated Go stubs (protoc output)
|
||||
```
|
||||
|
||||
Generated code is committed to the repository under `gen/`. `buf generate`
|
||||
is idempotent and is re-run via `go generate ./...`.
|
||||
Generated code is committed to the repository under `gen/`. The generator
|
||||
is invoked via `go generate ./...`, which runs the `protoc` command declared
|
||||
in `proto/generate.go` using `protoc-gen-go` and `protoc-gen-go-grpc`.
|
||||
|
||||
### Service Definitions (summary)
|
||||
|
||||
|
||||
@@ -38,7 +38,8 @@ Performance is secondary, and can be tuned later.
|
||||
|
||||
## Technical details
|
||||
|
||||
+ User passwords will be stored using scrypt.
|
||||
+ User passwords will be stored using Argon2id (PHC format), meeting
|
||||
OWASP 2023 recommended parameters (time=3, memory=64 MiB, threads=4).
|
||||
+ The service account tokens and user/password authentication can be
|
||||
used to obtain a JWT, if that is appropriate.
|
||||
+ All authentication events should be logged.
|
||||
@@ -46,8 +47,7 @@ Performance is secondary, and can be tuned later.
|
||||
git.wntrmute.dev/kyle/goutils for logging etc.
|
||||
+ The database should be sqlite.
|
||||
+ Modern cryptography should be used. Preference should be given to
|
||||
Ed25519 as the public algorithm for signatures, for example. Consider
|
||||
the use of Argon2 for password hashes.
|
||||
Ed25519 as the public algorithm for signatures, for example.
|
||||
|
||||
## Interfaces
|
||||
|
||||
|
||||
@@ -317,13 +317,14 @@ transport security requirements.
|
||||
- `proto/mcias/v1/` directory contains `.proto` files for all service groups:
|
||||
`auth.proto`, `token.proto`, `account.proto`, `admin.proto`
|
||||
- All RPC methods mirror the REST API surface (see ARCHITECTURE.md §8 and §17)
|
||||
- `buf.yaml` / `buf.gen.yaml` configured; `buf generate` produces Go stubs under
|
||||
`gen/mcias/v1/`
|
||||
- `proto/generate.go` contains a `//go:generate protoc ...` directive that
|
||||
produces Go stubs under `gen/mcias/v1/` using `protoc-gen-go` and
|
||||
`protoc-gen-go-grpc`
|
||||
- Protobuf field conventions: `snake_case` field names, `google.protobuf.Timestamp`
|
||||
for all time fields, no credential fields in response messages (same exclusion
|
||||
rules as JSON API)
|
||||
- `go generate ./...` re-runs `buf generate` idempotently
|
||||
- Tests: generated code compiles cleanly; `buf lint` passes with zero warnings
|
||||
- `go generate ./...` re-runs `protoc` idempotently
|
||||
- Tests: generated code compiles cleanly (`go build ./...` succeeds)
|
||||
|
||||
### Step 7.2: `internal/grpcserver` — gRPC handler implementations
|
||||
**Acceptance criteria:**
|
||||
@@ -379,8 +380,9 @@ transport security requirements.
|
||||
interceptor chain, dual-stack operation)
|
||||
- README.md updated with gRPC section: enabling gRPC, connecting clients,
|
||||
example `grpcurl` invocations
|
||||
- `.gitignore` updated to exclude `mciasgrpcctl` binary and `gen/` directory
|
||||
(generated code committed separately or excluded per project convention)
|
||||
- `.gitignore` updated to exclude the `mciasgrpcctl` binary (using a
|
||||
root-anchored path `/mciasgrpcctl`); generated code in `gen/` is committed
|
||||
to the repository so that consumers do not need the protoc toolchain
|
||||
- `PROGRESS.md` updated to reflect Phase 7 complete
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user