[P0-18] Define the HTTP authentication threat model and principal/capability contract #26

New issue

Closed

opened 2026-07-22 00:12:54 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-22 00:12:54 +00:00

(Migrated from github.com)

Problem

The HTTP API currently has no authentication. CORS permits every origin, the Compose file publishes the API, and document/target/search/delete operations have no caller identity or authorization context. The unused *couchdb-auth-database* setting is not an auth design.

Required design

Define:

principal types: human user, API client, service instance, actor component, and administrator
credential types for v0.1 and explicit future OIDC/mTLS adapters
opaque high-entropy API key format with non-secret key id plus secret material
server-side credential hashing/verification and pepper/key rotation
capabilities such as documents:read, documents:write, documents:delete, targets:dispatch, targets:lease, search:read, and admin
tenant, dataset, actor, and target scope restrictions
authentication failure behavior, rate limits, lockout/abuse controls, and audit requirements
secret storage, bootstrap, rotation, revocation, and recovery
trust boundaries among HTTP, RabbitMQ, CouchDB, KV leases, and imported library callers

Acceptance criteria

A checked-in threat model enumerates protected assets, attacker profiles, flows, boundaries, failure modes, and residual risks.
Default policy is deny.
No credential or bearer token is logged or returned in an error.
Local development bypass, if retained, is explicit, off by default outside development, and impossible to enable accidentally.

## Problem The HTTP API currently has no authentication. CORS permits every origin, the Compose file publishes the API, and document/target/search/delete operations have no caller identity or authorization context. The unused `*couchdb-auth-database*` setting is not an auth design. ## Required design Define: - principal types: human user, API client, service instance, actor component, and administrator - credential types for v0.1 and explicit future OIDC/mTLS adapters - opaque high-entropy API key format with non-secret key id plus secret material - server-side credential hashing/verification and pepper/key rotation - capabilities such as `documents:read`, `documents:write`, `documents:delete`, `targets:dispatch`, `targets:lease`, `search:read`, and `admin` - tenant, dataset, actor, and target scope restrictions - authentication failure behavior, rate limits, lockout/abuse controls, and audit requirements - secret storage, bootstrap, rotation, revocation, and recovery - trust boundaries among HTTP, RabbitMQ, CouchDB, KV leases, and imported library callers ## Acceptance criteria - A checked-in threat model enumerates protected assets, attacker profiles, flows, boundaries, failure modes, and residual risks. - Default policy is deny. - No credential or bearer token is logged or returned in an error. - Local development bypass, if retained, is explicit, off by default outside development, and impossible to enable accidentally.