Initial commit: AS4/411 directory and discovery service for Sankofa Marketplace

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/security/key-reference-model.md

@@ -0,0 +1,34 @@
+# Key Reference Model and Rotation
+
+## Overview
+
+as4-411 does not store private keys or raw secrets. It stores **references** to key material held in a vault or KMS. This document describes the reference model and rotation procedure.
+
+## Key Reference Model
+
+### Stored Data
+
+- **credentials** table (per participant):
+  - `credential_type`: `tls` | `sign` | `encrypt`
+  - `vault_ref`: URI or identifier for the key in the vault/KMS (e.g. `vault://secret/tenant1/cert-id`, or KMS key ARN).
+  - `fingerprint`: Optional certificate or public key fingerprint for verification.
+  - `valid_from` / `valid_to`: Validity window for the referenced material.
+
+- No private key material, no PEM bodies, and no long-lived secrets are stored in the directory database.
+
+### Resolution Output
+
+- `RouteDirective.security.keyRefs` can carry the same vault/KMS references (or short-lived tokens) so that gateways resolve “which key” and then fetch material from the vault within their trust boundary.
+
+## Rotation Procedure
+
+1. **Stage new cert/key** in vault/KMS; obtain new `vault_ref` and optional `fingerprint`.
+2. **Add or update** credential record with new `vault_ref`, `valid_from` set to now (or overlap start).
+3. **Dual-valid overlap:** Keep previous credential valid until cutover. Configure overlap window so gateways can refresh to the new key.
+4. **Cutover:** Set old credential’s `valid_to` to end of overlap (or mark inactive). Prefer new credential via higher priority or by updating endpoint/participant metadata.
+5. **Revoke/archive** old key in vault per policy; remove or expire old credential record.
+
+## Compliance Notes
+
+- Audit log records changes to credential refs (who/what/when).
+- Per-rail requirements (e.g. card networks, DTC) may impose additional constraints on key lifecycle and storage; see [protocol docs](../protocols/) where applicable.