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

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

docs/security/data-classification.md

@@ -0,0 +1,32 @@
+# Sensitive Data Classification
+
+Data in the as4-411 directory is classified into tiers. Storage, access control, and encryption must follow these tiers. See [ADR-004](../adr/004-sensitive-data-classification.md).
+
+## Tiers
+
+| Tier | Name            | Examples                                      | Storage / access |
+|------|-----------------|-----------------------------------------------|------------------|
+| **0** | Public          | BIC, LEI, public BIN range metadata           | No encryption required; may be shared across tenants where applicable |
+| **1** | Internal        | PartyId, endpoint URL, participant name       | Access-controlled; tenant-scoped; encrypt in transit |
+| **2** | Confidential    | MID, TID, contract routing, DTC participant/account IDs | Field-level encryption at rest; strict RBAC/ABAC; per-tenant keys preferred |
+| **3** | Regulated/secrets | Tokens, key refs, PII-like attributes       | Strongest controls; vault refs only; immutable audit; never log in plaintext |
+
+## Mapping: tables and fields
+
+- **identifiers:** `value` is Tier 0 when type is BIC/LEI/public; Tier 2 when type is mid, tid, dtc.participantId, dtc.accountId, or other contract-scoped IDs. `identifier_type` and `scope` are Tier 1.
+- **endpoints:** `address` and `profile` are Tier 1 (internal). If they encode tenant-specific routes, treat as Tier 2 in policy.
+- **credentials:** Only references (vault_ref, fingerprint)—Tier 3 for the ref; no private material in DB.
+- **routing_artifacts:** Payload content may include Tier 2 (e.g. BIN table overrides with tenant/MID). Encrypt payload or use per-tenant encryption for Tier 2 content.
+- **participants / tenants:** Names and IDs are Tier 1; tenant-private participant data is Tier 1 or Tier 2 depending on protocol (see protocol docs).
+- **policies / audit_log:** Tier 1; audit_log must be immutable and optionally hash-chained.
+
+## Enforcement
+
+- **Field-level encryption:** Tier 2+ fields must be encrypted at rest (application-level or TDE with per-tenant keys where required). Tier 3: store only references; material in vault/KMS.
+- **RBAC/ABAC:** Strict role- and attribute-based access; resolution and admin APIs enforce tenant scope and policy. See [tenant-model](../architecture/tenant-model.md) and [ADR-003](../adr/003-multi-tenancy-and-rls.md).
+- **Audit:** All access to Tier 2+ and all mutations must be logged in audit_log; logs must not contain Tier 3 material in plaintext.
+- **Allowed storage and access:** Document per table in operations runbooks; new fields must be assigned a tier before merge.
+
+## Trust model for resolve consumers
+
+Who may call resolve, what they can see, and how to prevent endpoint enumeration are described in [trust-model.md](trust-model.md).

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.

docs/security/trust-model.md

@@ -0,0 +1,23 @@
+# Trust Model for Resolve Consumers
+
+This document describes who can call the resolve API, what they can see, and how we limit abuse (e.g. endpoint enumeration). See also [data-classification.md](data-classification.md) and the [API spec](../api/openapi.yaml).
+
+## Who can call resolve
+
+- **Authenticated callers:** Resolve must be gated by authentication. Support at least: API keys or JWT scoped to a tenant (and optionally to a set of protocols or contracts). Per-tenant auth claims ensure that a caller only receives directives for data they are entitled to.
+- **Authorization:** After authentication, apply tenant scope and ABAC policies so that the result set only includes participants, endpoints, and routing artifacts the caller is allowed to use. No cross-tenant leakage.
+
+## What callers can see
+
+- Responses are **filtered by entitlement:** Only protocols and endpoints the caller is entitled to appear in the directive list. Internal identifiers or participant details not needed for routing may be omitted or redacted in the response.
+- **Evidence and trace:** Resolution evidence and `resolution_trace` may expose source names (e.g. "internal directory", "SMP cache"). Do not include raw confidential data (Tier 2+) in trace; use source labels and optional correlation IDs only where needed for debugging.
+
+## Preventing endpoint enumeration
+
+- **Rate limits and anomaly detection:** Apply per-tenant (and optionally per-API-key) rate limits to resolve and bulk-resolve. Detect and throttle anomalous patterns (e.g. large volumes of distinct identifiers in short windows) to reduce enumeration risk.
+- **Response filtering:** Only return directives for identifiers and contracts the caller is authorized for. Return a generic "not found" or empty result for unauthorized or missing keys where appropriate, without leaking existence of data the caller cannot access.
+- **Optional proof of possession:** For high-assurance deployments, require mTLS client certificates or signed tokens so that only approved gateways or clients can call resolve. Document in API and operations.
+
+## Operations
+
+- Document required auth method (e.g. API key, JWT, mTLS) in deployment and API docs. Document rate limits and any per-tenant TTL or quota in operations runbooks.