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:
2026-03-11 14:44:08 -07:00
parent 59d51a1d38
commit 7c79d00514
3 changed files with 26 additions and 14 deletions

View File

@@ -501,19 +501,28 @@ passphrase_env = "MCIAS_MASTER_PASSPHRASE"
``` ```
mcias/ mcias/
├── cmd/ ├── cmd/
│ ├── mciassrv/ # server binary entrypoint │ ├── mciassrv/ # server binary entrypoint (REST + gRPC dual-stack)
│ │ └── main.go │ │ └── 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 │ └── main.go
├── internal/ ├── internal/
│ ├── auth/ # login flow, TOTP verification, account lockout │ ├── auth/ # login flow, TOTP verification, account lockout
│ ├── config/ # config file parsing and validation │ ├── config/ # config file parsing and validation
│ ├── crypto/ # key management, AES-GCM helpers, master key derivation │ ├── crypto/ # key management, AES-GCM helpers, master key derivation
│ ├── db/ # SQLite access layer (schema, migrations, queries) │ ├── db/ # SQLite access layer (schema, migrations, queries)
│ ├── grpcserver/ # gRPC handler implementations (Phase 7)
│ ├── middleware/ # HTTP middleware (auth extraction, logging, rate-limit) │ ├── middleware/ # HTTP middleware (auth extraction, logging, rate-limit)
│ ├── model/ # shared data types (Account, Token, Role, etc.) │ ├── model/ # shared data types (Account, Token, Role, etc.)
│ ├── server/ # HTTP handlers, router setup │ ├── server/ # HTTP handlers, router setup
│ └── token/ # JWT issuance, validation, revocation │ └── 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 └── go.mod
``` ```
@@ -719,11 +728,12 @@ proto/
gen/ gen/
└── mcias/ └── 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` Generated code is committed to the repository under `gen/`. The generator
is idempotent and is re-run via `go generate ./...`. 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) ### Service Definitions (summary)

View File

@@ -38,7 +38,8 @@ Performance is secondary, and can be tuned later.
## Technical details ## 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 + The service account tokens and user/password authentication can be
used to obtain a JWT, if that is appropriate. used to obtain a JWT, if that is appropriate.
+ All authentication events should be logged. + 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. git.wntrmute.dev/kyle/goutils for logging etc.
+ The database should be sqlite. + The database should be sqlite.
+ Modern cryptography should be used. Preference should be given to + Modern cryptography should be used. Preference should be given to
Ed25519 as the public algorithm for signatures, for example. Consider Ed25519 as the public algorithm for signatures, for example.
the use of Argon2 for password hashes.
## Interfaces ## Interfaces

View File

@@ -317,13 +317,14 @@ transport security requirements.
- `proto/mcias/v1/` directory contains `.proto` files for all service groups: - `proto/mcias/v1/` directory contains `.proto` files for all service groups:
`auth.proto`, `token.proto`, `account.proto`, `admin.proto` `auth.proto`, `token.proto`, `account.proto`, `admin.proto`
- All RPC methods mirror the REST API surface (see ARCHITECTURE.md §8 and §17) - 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 - `proto/generate.go` contains a `//go:generate protoc ...` directive that
`gen/mcias/v1/` 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` - Protobuf field conventions: `snake_case` field names, `google.protobuf.Timestamp`
for all time fields, no credential fields in response messages (same exclusion for all time fields, no credential fields in response messages (same exclusion
rules as JSON API) rules as JSON API)
- `go generate ./...` re-runs `buf generate` idempotently - `go generate ./...` re-runs `protoc` idempotently
- Tests: generated code compiles cleanly; `buf lint` passes with zero warnings - Tests: generated code compiles cleanly (`go build ./...` succeeds)
### Step 7.2: `internal/grpcserver` — gRPC handler implementations ### Step 7.2: `internal/grpcserver` — gRPC handler implementations
**Acceptance criteria:** **Acceptance criteria:**
@@ -379,8 +380,9 @@ transport security requirements.
interceptor chain, dual-stack operation) interceptor chain, dual-stack operation)
- README.md updated with gRPC section: enabling gRPC, connecting clients, - README.md updated with gRPC section: enabling gRPC, connecting clients,
example `grpcurl` invocations example `grpcurl` invocations
- `.gitignore` updated to exclude `mciasgrpcctl` binary and `gen/` directory - `.gitignore` updated to exclude the `mciasgrpcctl` binary (using a
(generated code committed separately or excluded per project convention) 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 - `PROGRESS.md` updated to reflect Phase 7 complete
--- ---