core-hub/docs/specs/auth-access-and-custody.md

Auth, Access, and Custody Spec

Purpose

Define Core Hub authentication behavior and credential boundaries without turning Core Hub into a secret-vending system.

Rules

• Core Hub may authenticate API clients and record non-secret access metadata.
• Core Hub must not store raw provider tokens, database passwords, OpenBao tokens, SSH private keys, or login secrets.
• API key full values are shown only at creation time if Core Hub owns key issuance.
• Stored API key material must be hashed; logs and progress notes must use prefixes or opaque ids only.
• Secret retrieval and custody follow ops-warden/OpenBao/key-cape routing.

Inter-Hub Compatibility

Core Hub should preserve protected-route behavior expected by existing consumers:

• public registry reads should remain public where they are public today;
• protected write routes should return authorization errors before executing business logic;
• bootstrap flows should support operator-created or approved API consumers;
• rate limiting and request logs should use database types compatible with Postgres.

Open Questions

• Whether token exchange should remain /api/v2/token compatible or become a Core Hub-native auth grant endpoint with compatibility alias.
• Whether API consumers are global, per-hub, or scoped by registry capability.