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/
├── 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)

View File

@@ -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

View File

@@ -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
---