From 7c79d00514811aa2833bfc8afbcef4ed7462102f Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Wed, 11 Mar 2026 14:44:08 -0700 Subject: [PATCH] =?UTF-8?q?Sync=20docs:=20ARCHITECTURE,=20PROJECT,=20PROJE?= =?UTF-8?q?CT=5FPLAN=20-=20ARCHITECTURE.md=20=C2=A712:=20add=20mciasdb,=20?= =?UTF-8?q?mciasgrpcctl,=20internal/grpcserver,=20=20=20proto/,=20and=20ge?= =?UTF-8?q?n/=20to=20the=20directory=20structure=20diagram=20-=20ARCHITECT?= =?UTF-8?q?URE.md=20=C2=A717:=20replace=20buf=20generate=20references=20wi?= =?UTF-8?q?th=20protoc;=20=20=20the=20implementation=20uses=20protoc=20+?= =?UTF-8?q?=20protoc-gen-go=20+=20protoc-gen-go-grpc=20=20=20invoked=20via?= =?UTF-8?q?=20go=20generate=20./...=20(proto/generate.go)=20-=20PROJECT=5F?= =?UTF-8?q?PLAN.md=20=C2=A77.1:=20replace=20buf.yaml/buf.gen.yaml=20accept?= =?UTF-8?q?ance=20=20=20criteria=20with=20the=20protoc-based=20go:generate?= =?UTF-8?q?=20approach=20actually=20used=20-=20PROJECT=5FPLAN.md=20=C2=A77?= =?UTF-8?q?.6:=20clarify=20that=20gen/=20is=20committed=20to=20the=20repo?= =?UTF-8?q?=20=20=20(not=20gitignored);=20only=20the=20binary=20/mciasgrpc?= =?UTF-8?q?ctl=20is=20excluded=20-=20PROJECT.md:=20replace=20scrypt=20with?= =?UTF-8?q?=20Argon2id=20(the=20actual=20algorithm);=20=20=20remove=20the?= =?UTF-8?q?=20redundant=20Argon2=20suggestion=20line?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 20 +++++++++++++++----- PROJECT.md | 6 +++--- PROJECT_PLAN.md | 14 ++++++++------ 3 files changed, 26 insertions(+), 14 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 04e2cf8..98e910f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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) diff --git a/PROJECT.md b/PROJECT.md index 305cd24..3f928f8 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -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 diff --git a/PROJECT_PLAN.md b/PROJECT_PLAN.md index be7ba77..3348398 100644 --- a/PROJECT_PLAN.md +++ b/PROJECT_PLAN.md @@ -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 ---