archetech / archon / 24363849444

89%

push

github

docs: language-agnostic service specs (gatekeeper, keymaster, mediators) (#408)

* docs: language-agnostic service specs for Gatekeeper and Keymaster

Adds two full service specifications under docs/services/<service>/README.md
that describe the complete contract a conforming implementation in any
language must satisfy to be a drop-in replacement for the TypeScript
reference.

Each spec covers:
- HTTP API surface (routes, admin auth, CORS, body limits, error envelope)
- Wire-format domain types with required/optional rules
- Cryptographic primitives (secp256k1, SHA-256, JWE Compact with
  ECDH-ES + A256GCM, PBKDF2 for the wallet at-rest key)
- State machines (DID resolution, event import, credentials/challenges)
- Storage backend semantics and reference schemas
- Prometheus metrics and required route normalization
- Container/runtime contract (env vars, healthcheck, startup sequence)
- Test fixtures and guidance for adding a new implementation

Gatekeeper spec is ~900 lines covering 30 routes plus DID generation,
proof verification, resolution, event import state machine, search, and
the IPFS/storage/metrics contracts.

Keymaster spec is ~700 lines covering 146 routes plus the full wallet
at-rest encryption scheme (PBKDF2 c=100000 must not change), BIP32/39
derivation, asset lifecycle, credential/challenge flow, polls/vaults,
dmail/notices, and Nostr/Lightning passthrough.

Both specs cross-reference each other and link to the existing
source-of-truth files (packages/*/src/types.ts, cipher-base.ts,
gatekeeper-api.ts, keymaster-api.ts, fixtures, etc.) so any claim can be
verified against working code.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: language-agnostic specs for the four mediator services

Adds spec docs under docs/services/mediators/<name>/README.md describing
the complete contract for each mediator. Same structure as the existing
gatekeeper / keymaster specs.

- hyperswarm — wire protocol (batch / queue / ... (continued)

1990 of 2192 branches covered (90.78%)

Branch coverage included in aggregate %.

4231 of 4345 relevant lines covered (97.38%)

1167.44 hits per line