docs: define PII and credential authority boundaries

docs/planning/ADR-005-privacy-and-credential-authority-boundaries.md

@@ -0,0 +1,121 @@
+# ADR-005: Privacy Processing and Credential Authority Boundaries
+
+**Status:** Accepted
+
+**Date:** 2026-08-23
+
+**Decision owners:** Foundation Security and Architecture
+
+**Baton:** `deacf6eb`
+
+## Context
+
+`IPIITokenizationPort` exists in Foundation Security, while `GDPRComplianceAdapter` lives in Business Applications and handles consent, legal basis, retention, and data-subject rights. Current LLM clients accept prompt, chat, and embedding content without a repository-wide tokenization boundary. The architecture must decide whether PII protection belongs inside the GDPR adapter, at persistence, at LLM ingress, or at more than one controlled boundary.
+
+`ICredentialSyncPort` is provider-neutral and names Azure Key Vault, HashiCorp Vault, and AWS Secrets Manager. The repository also has a simulated in-memory `SecretsManagementEngine`, but it implements `ISecretsManagementPort` and does not provide external credential synchronization, dependent validation, or authoritative rotation. The architecture must decide whether Azure Key Vault is the only possible authority or the production default within a provider-neutral design.
+
+## Decision
+
+### 1. Tokenization is a Foundation privacy boundary
+
+The planned `PIITokenizationEngine` implements the existing `IPIITokenizationPort`. Authenticated composition hosts must invoke it before external LLM, embedding, reranking, or content-bearing tool calls and before writing raw content to general-purpose memory, vector, analytics, telemetry, log, or evidence stores.
+
+The boundary does not require all lawful systems of record to discard originals. Raw PII may remain only in an explicitly authorized source of record or encrypted token-map store with documented purpose, retention, and access policy. External/provider and general-purpose paths receive scoped tokens.
+
+### 2. GDPR remains the policy and data-rights orchestrator
+
+`GDPRComplianceAdapter` does not absorb token detection, token creation, or token-map persistence. It remains responsible for consent, lawful basis, retention, access, rectification, portability, and erasure. It may call `IPIITokenizationPort` to enumerate or delete a verified subject's mappings as one step in a broader data-rights workflow.
+
+This preserves dependency direction: Business Applications can consume Foundation ports, while Foundation does not depend on Business Applications.
+
+### 3. Tokens are scoped pseudonyms, not anonymous data
+
+Production tokens are opaque and scoped to tenant, internal subject identifier, processing purpose, policy, and key version. Cross-tenant or cross-purpose deterministic token reuse is forbidden. Token mappings and detokenization are protected data processing and remain subject to privacy policy.
+
+A request-level subject identifier describes the authenticated request context; it does not prove that every detected entity belongs to that person. Each mapping carries an ownership state (`Verified`, `Shared`, or `Unassigned`) and zero or more verified internal subject references. Detector adapters never infer identity ownership. Unassigned entities remain bound to protected source-record lineage, while shared mappings require a verified multi-subject data-rights decision rather than deletion under whichever person submitted the text.
+
+### 4. Credential authority is single-writer per namespace/environment
+
+Each credential namespace and environment has exactly one authoritative vault selected by reviewed configuration. Azure Key Vault is the production default for Cognitive Mesh. The existing provider-neutral contract remains valid so an explicitly approved namespace may use another provider adapter.
+
+This is not unrestricted multi-vault synchronization. Callers cannot select `VaultProvider` or `VaultUrl` for production operations, and two providers cannot write the same credential identity. Authority migration is a separate, explicit cutover with reconciliation and rollback.
+
+### 5. Credential synchronization is distinct from generic secret CRUD
+
+The planned `CredentialSyncEngine` implements `ICredentialSyncPort` and owns authority resolution, authorization, metadata reconciliation, rotation state, dependent validation, and revocation. Provider adapters own vault-specific API calls and native error/version mapping.
+
+`SecretsManagementEngine` remains a simulated implementation of `ISecretsManagementPort`; it is neither a production vault nor evidence that credential sync exists. A future production secrets adapter may share lower-level provider infrastructure, but the two public capability contracts are not merged or substituted.
+
+### 6. Values are used just in time
+
+Production consumers obtain credential values only through an authenticated, authorized, bounded use path. Persistent application state retains references and metadata, never plaintext. Managed/workload identity is preferred over reusable secrets where supported.
+
+## Alternatives Considered
+
+### Put tokenization only in `GDPRComplianceAdapter`
+
+Rejected. LLM, embedding, memory, telemetry, and tool paths can bypass that Business-layer adapter. It would also invert responsibility by placing a reusable Foundation security mechanism inside a business compliance component.
+
+### Tokenize only immediately before persistence
+
+Rejected. Raw PII could still leave the trust boundary through an external model or tool call before persistence occurs.
+
+### Tokenize only at each provider adapter
+
+Rejected. Repeating policy at every adapter creates inconsistent coverage and makes new providers unsafe by default. Provider adapters still enforce that they receive a privacy-qualified payload, but the composition boundary owns orchestration.
+
+### Make Azure Key Vault the globally hard-coded sole provider
+
+Rejected. Azure Key Vault is the production default, but hard-coding it contradicts the existing provider-neutral port and prevents bounded migrations or sovereign deployments. Single authority per namespace prevents split brain without sacrificing adapter portability.
+
+### Permit multi-vault fan-in or last-write-wins sync
+
+Rejected. It creates ambiguous provenance, rollback, revocation, and conflict semantics for sensitive credentials.
+
+### Reuse `SecretsManagementEngine` as credential sync
+
+Rejected. It is an in-memory demo implementation with a different contract and no external authority, dependent registry, or production rotation proof.
+
+## Consequences
+
+### Positive
+
+- New provider integrations are safe only when routed through one privacy boundary.
+- Data-rights policy and token mechanics remain decoupled in the correct layer direction.
+- Azure Key Vault can be the production default without turning provider strings into caller-controlled routing.
+- Credential provenance and rotation have one authoritative writer.
+- Existing public capability ports remain stable.
+
+### Costs and constraints
+
+- Composition hosts must carry tenant, subject, purpose, policy, and authenticated caller context.
+- Existing port models require additive versioned contracts before production enforcement.
+- Token-map and vault-provider adapters need independent threat modeling, authorization, retention, and recovery design.
+- Model outputs can still infer or introduce PII and require post-response detection policy where applicable.
+- Provider-specific rotations may require different overlap or atomic-cutover procedures.
+
+## Guardrails
+
+- No silent raw-content fallback when tokenization is required.
+- No raw PII, restored values, token-map values, lookup-capable token identifiers, cross-scope-linkable tokens, or credentials in logs, telemetry, evidence, chat, Git, or Baton.
+- No raw email/name/national identifier as `DataSubjectId`.
+- No caller-selected production vault URL/provider.
+- No plaintext durable credential cache.
+- No detokenization or credential read without authenticated identity and explicit scope.
+- No claim of production enforcement based on these documents.
+
+## Capability Status
+
+- **Implemented:** port contracts, GDPR workflows, direct LLM clients, and demo in-memory secret management.
+- **Experimental:** none accepted.
+- **Planned:** the engines, adapters, protected stores, composition boundary, authority registry, and rehearsal.
+- **Blocked:** enforcement and provider activation pending separately authorized implementation and security acceptance.
+
+## References
+
+- [`pii-tokenization-and-credential-sync.md`](../prds/01-foundational-infrastructure/pii-tokenization-and-credential-sync.md)
+- [`pii-tokenization-and-credential-sync.md`](../spec/pii-tokenization-and-credential-sync.md)
+- [`credential-rotation-and-token-leak-response.md`](../runbooks/credential-rotation-and-token-leak-response.md)
+- `src/FoundationLayer/Security/Ports/IPIITokenizationPort.cs`
+- `src/FoundationLayer/Security/Ports/ICredentialSyncPort.cs`
+- `src/BusinessApplications/Compliance/Adapters/GDPRComplianceAdapter.cs`

docs/prds/00-README.md

@@ -17,7 +17,8 @@ docs/prds/
 ├── 00-README.md            ← This file
 ├── global-nfr.md           ← Global Non-Functional Requirements Appendix
 ├── 01-foundational-infrastructure/
-│   └── deterministic-security-scanning-build-loop.md
+│   ├── deterministic-security-scanning-build-loop.md
+│   └── pii-tokenization-and-credential-sync.md
 ├── plugin-dashboard.md     ← Plugin-Based Dashboard Architecture PRD
 ├── convener-backend.md     ← Convener Backend Architecture PRD
 └── convener-widget.md      ← Convener Widget/Plugin PRD
@@ -30,6 +31,7 @@ docs/prds/
 | **00-README.md** | Orientation & conventions for all PRDs. |
 | **global-nfr.md** | Platform-wide security, privacy, SLA, compliance, and quality gates. All other PRDs inherit these requirements. |
 | **01-foundational-infrastructure/deterministic-security-scanning-build-loop.md** | Exact-input security qualification for pull requests and protected releases. |
+| **01-foundational-infrastructure/pii-tokenization-and-credential-sync.md** | Privacy-qualified external processing and authoritative credential lifecycle for agent tools. |
 | **plugin-dashboard.md** | Defines the core shell & extensible plugin/widget model. |
 | **convener-backend.md** | Specifies APIs/services that power Convener features (champion discovery, pulse, etc.). |
 | **convener-widget.md** | UI plugin that consumes Convener backend APIs & surfaces insights in the dashboard. |