# Restricted Fragment Storage Contract `GH-510-RESTRICTED-FRAGMENT-STORAGE` defines the future storage envelope for retained restricted fragments. This contract does not enable retention by default and does not add a vault, KMS, or retrieval product surface. ## Scope Restricted fragment storage is exceptional. It is allowed only when a future structured workflow has an approved product need, tenant policy, retention class, and security review. Ordinary chat persistence remains redacted-only. The following values must not be retained raw in transcripts, logs, exports, evidence, markdown handoffs, telemetry, or provider requests: - credentials, passwords, API keys, tokens, secrets, and signing material - payment card data, CVV, track data, and payment account identifiers - regulated or sensitive PII unless a future structured policy explicitly authorizes encrypted retention ## Storage Boundary Restricted fragments must be stored outside `.agent-workflow/chat/v1` transcript JSONL and outside ordinary chat message tables. Chat records may keep only a redacted shadow and a restricted-fragment reference. The redacted shadow is the only transcript-safe representation: - fragment id - tenant id, workspace id, and source message id - classification category and policy id - redaction marker and short sanitized summary - optional digest of canonical plaintext for dedupe or audit correlation - lifecycle status, created timestamp, expiry timestamp, and legal-hold flag The shadow must not contain raw plaintext, ciphertext, encrypted data keys, KMS key ids that reveal tenant topology, provider payloads, or debug samples. ## Envelope Encryption Each retained fragment uses envelope encryption: 1. A tenant root key is managed by an external KMS or vault. 2. A workspace key-encryption context is derived from tenant id, workspace id, retention class, and policy id. 3. A fresh per-fragment data encryption key encrypts the fragment with `AES-256-GCM` or a reviewed equivalent AEAD. 4. The per-fragment data key is wrapped by the workspace key context. 5. The ciphertext object stores only ciphertext metadata and the wrapped key reference needed for an authorized decrypt operation. The envelope metadata must include: - envelope schema version - fragment id and redacted shadow id - algorithm, IV/nonce id, authentication tag id, and ciphertext digest - wrapped data-key id and key version - KMS provider alias and tenant/workspace key scope - classification category, retention class, policy id, and purpose - creation timestamp, expiry timestamp, and legal-hold flag The envelope metadata must not include raw plaintext, derived plaintext samples, complete provider prompts, route request bodies, or user-supplied secret names. ## Audit Contract The append-only audit trail must record sanitized lifecycle events: - `restricted_fragment_detected` - `restricted_fragment_shadow_recorded` - `restricted_fragment_encrypted` - `restricted_fragment_decrypt_denied` - `restricted_fragment_restore_attempted` - `restricted_fragment_ciphertext_deleted` - `restricted_fragment_key_destroyed` - `restricted_fragment_crypto_shredded` - `restricted_fragment_backup_expiry_pending` Audit entries include tenant id, workspace id, fragment id, policy id, actor id, decision id, category, timestamps, and counts. They never include plaintext, ciphertext, wrapped key material, provider payloads, or request bodies. ## Crypto-Shred Deleting a retained fragment requires both storage deletion and key destruction: 1. mark the redacted shadow as deletion requested; 2. hard-delete the ciphertext object and index entry; 3. destroy or disable the fragment data-key binding so decrypt is impossible; 4. record the KMS/vault destruction receipt or local equivalent; 5. record backup expiry status because immutable backups may age out later; 6. record a final `crypto_shredded` audit event. If raw restricted data was blocked and never persisted, delete reports `raw_not_persisted` instead of claiming a ciphertext deletion occurred. Crypto-shred is complete only when the active ciphertext object is gone and the key binding can no longer unwrap the fragment data key. Backups may still retain already-encrypted bytes until their retention windows expire, but those bytes must remain unrecoverable once key destruction is complete. ## Restore Constraints Restore is denied by default. A future restore operation must require: - tenant and workspace authorization - policy allowing restore for the exact category and retention class - legal basis or break-glass reason - active key material that has not been crypto-shredded - append-only audit before and after the attempt Restore must fail closed when the fragment is expired, the key is destroyed, the legal hold conflicts with the request, the actor lacks authorization, or the policy does not allow raw recovery. Restored plaintext must be streamed only to the authorized consumer and must not be written back into transcripts, evidence, logs, exports, or provider prompts. ## Export And Compliance Default chat export remains redacted-only. Export may include redacted shadows and audit summaries, but it must not include ciphertext blobs, wrapped keys, plaintext, KMS key material, or restoration receipts that expose internals. Telemetry, evidence compaction, support bundles, and Markdown reporting follow the same rule: only sanitized category, count, marker, decision, and lifecycle status data may leave the restricted-fragment boundary. Logical chat tombstones do not satisfy crypto-shred for retained fragments. Compliance delete must distinguish: - transcript tombstone only - `raw_not_persisted` - ciphertext hard delete - key destroyed - crypto-shred complete - backup expiry pending ## Implementation Slices 1. Add storage-agnostic domain types and validation for restricted fragment shadows, envelopes, audit events, and delete results. 2. Teach chat compliance exports to include redacted shadow summaries while excluding ciphertext and wrapped-key metadata. 3. Add a storage adapter interface for encrypted fragment object stores. 4. Add a KMS/vault adapter interface for wrap, unwrap, disable, and destroy. 5. Add delete orchestration that hard-deletes ciphertext before recording key destruction and crypto-shred audit events. 6. Add restore denial tests before any restore implementation exists.