feat(crypto): enterprise hardening pass — correctness, KMS extensibility, framed §6.8, TS rigor

Harden @adonisjs-lasagna/crypto against the frozen design (01-crypto / 00-foundation)
without reshaping the RC surface. All changes are additive (no major bump, contract
version unchanged).

Correctness & fail-closed (WS-0):
- shred: serialize the destructive section (bounded jittered backoff → retriable
  `shred_in_progress`; Redis-down still fail-open) AND treat shredLive()'s return as
  authoritative, so a lost race yields `alreadyShredded` with no double WORM audit or
  duplicate SubjectShredded (§6.6). Ledger-absent check consolidated once before the lock.
- rekek: new `shreddedDuringRewrap` bucket so the accounting invariant is exact
  (scanned = current + rotated + shreddedDuringRewrap + failed).
- pg store: INSERT ... RETURNING fails closed (`insert_failed`) instead of a non-null bang.

KeyProvider extensibility + SSRF (WS-1):
- KeyProvider gains optional `contractVersion`; registry.register() enforces it via
  assertContractCompat (AI/billing parity).
- new HttpKeyProvider base routes every egress through core safeFetch (T13 by
  construction) + reference VaultKeyProvider (transit engine); raw KEK bytes never enter
  the process.
- new structural guard check-crypto-invariant-11 forbids raw egress outside
  http_key_provider.ts and requires the base to route through safeFetch (presence FLOOR).
- WORM ledger connection name resolved from config (was hardcoded 'backoffice').

Framed enc_v2 stream envelope §6.8 (WS-2):
- sealFramedV2 / openFramedV2 (+ streaming variants): a composition of core's per-frame
  seal, not a new cipher (I1). Frame index rides the authenticated keyId; a counted
  terminator seals the frame count. Strict-open rejects reorder / drop / duplicate /
  cross-stream / truncation / tamper and never returns partial plaintext.

TypeScript rigor (WS-3):
- mixin hooks typed EncryptableModel, decorator options generic <TRow>, command catches
  narrowed to unknown.

Tests & coverage (WS-4):
- split the shred spec into the design-named files; add concurrent-race, rekek/worm-ledger
  accounting, KMS-down, SSRF-blocked, framed-envelope matrix, contractVersion gate, and
  real-PG crash/governance-absent specs (+ gated real-Vault smoke).
- unit coverage floors 84/80/84 → 91/85/90/91 (measured 93.8/87.6/92.6); minMergedCoverage
  60/60/60 → 80/80/75; worm_shred_ledger removed from c8 excludes.

Docs (WS-5):
- fix encryptedColumnCheckSql example drift (positional, not object), Mermaid key
  hierarchy, rowscope/CHECK callouts, EncryptedRepository controller example, OLD_APP_KEY
  .env note, Custom-KeyProvider expansion, @searchable post-shred JSDoc, CHANGELOG,
  tests/README T1..T14 map.

Author: Arcoders

docs/guides/satellites/crypto.md

@@ -35,6 +35,19 @@ Three layers, so erasure stays cheap and blast radius stays small:
   envelope. The ciphertext carries a non-secret `keyId` tag pointing at the
   wrapped-DEK row, never the key itself.
 
+```mermaid
+flowchart TB
+  KP["KeyProvider (pluggable)<br/>env · AWS KMS · HashiCorp Vault"]
+  KEK["KEK — per-tenant Key-Encryption-Key<br/>wraps DEKs only, never encrypts data"]
+  DEK["DEK — per-(subject × category) Data-Encryption-Key<br/>stored ONLY wrapped, in crypto_wrapped_deks · the sole copy"]
+  FLD["encrypted field value<br/>enc_v2 sealed under the DEK"]
+  IDX["blind index (search HMAC)<br/>keyed by a KeyProvider index key, NOT a DEK"]
+  KP -->|derives| KEK
+  KEK -->|wraps| DEK
+  DEK -->|seals| FLD
+  KP -.->|index key survives a shred| IDX
+```
+
 Erasing a subject's data is then just tombstoning its wrapped-DEK row: null the
 `wrapped_dek`, and every value sealed under that DEK is permanently unrecoverable
 (**I6**). This is crypto-shredding, and it is what makes per-subject erasure a
@@ -170,6 +183,22 @@ const plain = await repo.decrypt(renterId, 'identity', sealed)
 const index = await repo.blindIndex('identity', passportNumber) // for a WHERE lookup
 ```
 
+In a controller the tenant comes from the active request scope, so you never pass it:
+
+```ts
+export default class RentersController {
+  async store({ request }: HttpContext) {
+    const repo = await app.container.make(EncryptedRepository)
+    const { id, passportNumber } = request.body()
+    // Resolved under the current tenant's (subject × category) DEK; fail-closed if
+    // there is no active tenant scope (never a cross-tenant DEK).
+    const sealed = await repo.encrypt(id, 'identity', passportNumber)
+    const index = await repo.blindIndex('identity', passportNumber)
+    await Renter.create({ id, passportNumber: sealed, passportNumberIndex: index })
+  }
+}
+```
+
 Use the decorators for fields that live on a tenant model, and the repository when
 the value is not a model column or when you want the encryption call to be
 explicit in the code path.
@@ -210,7 +239,12 @@ import { encryptedColumnCheckSql } from '@adonisjs-lasagna/crypto'
 
 export default class extends BaseSchema {
   async up() {
-    this.schema.raw(encryptedColumnCheckSql({ table: 'renters', column: 'passport_number' }))
+    // Signature is positional: encryptedColumnCheckSql(table, column, options?).
+    // Run this AFTER the column exists (in the same migration, after createTable, or a
+    // later one). The constraint name is derived per table+column (`<table>_<column>_is_ciphertext`),
+    // so it is unique; pass `{ constraintName }` only if the derived name would exceed
+    // Postgres' 63-char identifier limit.
+    this.schema.raw(encryptedColumnCheckSql('renters', 'passport_number'))
   }
 }
 ```
@@ -267,32 +301,78 @@ drop `OLD_APP_KEY` once no DEK is still wrapped under the old generation. Each
 unwrap attempt is a strict open of a DEK envelope, so the read window never
 weakens the fail-closed decrypt posture.
 
+```bash
+# .env during the rotation window (env provider only)
+APP_KEY=<the new key>
+OLD_APP_KEY=<the previous key>   # remove this once `rekek` reports 0 rows on the old generation
+```
+
+The `rekek` summary reports each row as `re-wrapped`, `already current`, or `failed`
+(a DEK wrapped under a generation the provider no longer holds — restore it from backup
+or re-enter the data). A KMS/Vault provider retains its prior key versions itself, so no
+`OLD_APP_KEY` is needed there.
+
 ## Custom KeyProvider
 
 The `env` provider is dev-grade: the KEK is a pure function of `APP_KEY`, which
 gives destruction granularity but no root-of-trust separation. Production binds a
-real KMS. Implement the `KeyProvider` contract, then register it on the
-`KeyProviderRegistry` in your own provider and name it in `config.crypto.keyProvider`:
+real KMS. The `KeyProvider` contract is small:
+
+```ts
+interface KeyProvider {
+  readonly name: string                 // the name you put in config.crypto.keyProvider
+  readonly contractVersion?: number     // set = CRYPTO_CONTRACT_VERSION; checked at register time
+  wrapDek(tenantId, dek): Promise<WrappedDek>       // KEK-encrypt a 32-byte DEK
+  unwrapDek(tenantId, wrapped): Promise<Buffer>     // strict; throws on tamper/wrong KEK
+  currentKekId?(tenantId): Promise<string>          // optional rotation cursor for rekek
+  deriveIndexKey?(tenantId, category): Promise<Buffer>  // optional blind-index key (≥32 bytes)
+}
+```
+
+### HTTP-backed providers (AWS KMS, Vault): extend `HttpKeyProvider`
+
+Any provider that talks to a KMS over HTTP MUST route its outbound through core's
+`safeFetch` so a mis-set backend address can never reach loopback / RFC-1918 /
+cloud-metadata (T13). Do not call `fetch` yourself — extend `HttpKeyProvider`, whose
+`request` / `requestJson` are the pinned egress path. `check-crypto-invariant-11`
+enforces that no other crypto code opens a second, unpinned egress.
+
+crypto ships a reference `VaultKeyProvider` (HashiCorp Vault transit engine) built this
+way; bind it (or your own subclass) in your provider:
 
 ```ts
 // providers/kms_provider.ts
-import { KeyProviderRegistry } from '@adonisjs-lasagna/crypto'
+import { KeyProviderRegistry, VaultKeyProvider } from '@adonisjs-lasagna/crypto'
 
 export default class KmsProvider {
   async boot() {
     const registry = await this.app.container.make(KeyProviderRegistry)
-    registry.register(new MyKmsKeyProvider()) // name: 'aws-kms'
+    // Per-tenant transit key `lasagna-crypto-<tenantId>`; every call is SSRF-pinned.
+    registry.register(
+      new VaultKeyProvider({ address: env.get('VAULT_ADDR'), token: env.get('VAULT_TOKEN') })
+    )
   }
 }
 ```
 
 ```ts
 // config/multitenancy.ts
-crypto: defineCryptoConfig({ keyProvider: 'aws-kms', /* ... */ }),
+crypto: defineCryptoConfig({ keyProvider: 'hashicorp-vault', /* ... */ }),
 ```
 
-An unregistered provider name is fail-closed at resolve time: the platform never
-falls back to a weaker or shared key.
+A custom provider declares `contractVersion = CRYPTO_CONTRACT_VERSION` so
+`KeyProviderRegistry.register()` can reject a provider built against an incompatible
+crypto contract (a newer contract throws; an older/absent one warns once), exactly as
+the AI and billing satellites gate their extensions. An unregistered provider name is
+fail-closed at resolve time: the platform never falls back to a weaker or shared key.
+
+<Callout type="info" title="Encrypting large blobs">
+For blobs too large for a single GCM tag (vault's job), crypto exposes a framed
+enc_v2 stream envelope (`sealFramedV2` / `sealFramedV2Stream`): the payload is split
+into fixed-size frames, each an enc_v2 seal under the same DEK with the frame counter
+bound into the authenticated header, so a reordered / dropped / truncated frame fails
+closed. It is composition of the one core cipher, not a second construction.
+</Callout>
 
 ## Rowscope placement
 
@@ -302,6 +382,16 @@ wrapped under a per-tenant KEK, reading another tenant's `wrapped_dek` bytes is
 useless without that tenant's KEK, so crypto **can** live in a shared table (unlike
 the AI vector store, whose embeddings are invertible and which refuses rowscope).
 
+<Callout type="warning" title="Only under rowscope-pg, and mind the RLS flag">
+Run the `create_crypto_wrapped_deks_rowscope` stub ONLY under the `rowscope-pg` driver
+(schema-pg / database-pg get the per-tenant table from `tenant:migrate` instead). The
+RLS block is conditional on `isolation.rowScopeRls: true`: the store only sets the
+per-transaction GUC when the driver reports RLS is on, so if you keep the FORCE RLS
+policy but leave `rowScopeRls: false`, the policy matches no rows and every crypto
+read/write fails closed. Either set `rowScopeRls: true`, or drop the ENABLE/FORCE/policy
+block from the stub and rely on the store's always-on `tenant_id` predicate.
+</Callout>
+
 `node ace configure` publishes the central
 `create_crypto_wrapped_deks_rowscope` migration stub. It creates the shared table
 with a `tenant_id` scope column, a per-`(tenant_id, subject_id, category)` partial

packages/crypto/.c8rc.json

@@ -12,7 +12,6 @@
     "src/sdk/**",
     "src/commands/**",
     "src/internal/operation_lock.ts",
-    "src/services/worm_shred_ledger.ts",
     "build/**",
     "bin/**",
     "tests/**"
@@ -21,8 +20,8 @@
   "report-dir": "./coverage",
   "clean": true,
   "check-coverage": true,
-  "statements": 84,
-  "branches": 80,
-  "functions": 84,
-  "lines": 84
+  "statements": 91,
+  "branches": 85,
+  "functions": 90,
+  "lines": 91
 }

packages/crypto/CHANGELOG.md

@@ -20,7 +20,21 @@ Added:
   a per-tenant `crypto_wrapped_deks` table (no plaintext DEK at rest, I2); a field is
   sealed under its DEK with the kernel's authenticated `enc_v2` envelope. The
   built-in `EnvKeyProvider` derives the KEK from `APP_KEY`; a host binds AWS KMS,
-  HashiCorp Vault or a custom provider on the `KeyProviderRegistry`.
+  HashiCorp Vault or a custom provider on the `KeyProviderRegistry`. Every provider
+  declares a `contractVersion`, checked at registration (`assertContractCompat`) so an
+  incompatible provider is rejected fail-closed, matching the AI/billing extension gate.
+- **HTTP-backed KeyProviders are SSRF-pinned by construction.** An `HttpKeyProvider`
+  base routes every outbound through core `safeFetch` (DNS/IP pin, no redirects), so a
+  mis-set KMS address can never reach loopback / RFC-1918 / cloud-metadata (T13);
+  `check-crypto-invariant-11` forbids any second, unpinned egress. A reference
+  `VaultKeyProvider` (HashiCorp Vault transit engine) ships on that base, with a gated
+  real-Vault smoke test.
+- **Framed enc_v2 stream envelope (§6.8).** `sealFramedV2` / `openFramedV2` (and their
+  streaming forms) seal a large blob as fixed-size frames, each an enc_v2 seal under the
+  same DEK with the frame counter bound into the authenticated header and a counted
+  terminator frame, so a reordered / dropped / duplicated / truncated frame fails
+  closed. It is composition of the one core cipher (vault consumes it), never a second
+  construction (I1).
 - **Placement follows the isolation driver (I1).** `PgWrappedDekStore` asks the
   active driver `tableLocation(tenant)` and never hardcodes a schema, so it is
   correct on `schema-pg`, `database-pg` and `connection`. Under `rowscope-pg` the
@@ -50,6 +64,8 @@ Added:
 - **Isthmus guard registry.** Every fail-closed refusal emits the kernel's public
   `IsthmusGuardTripped` event with a `guard.crypto_*` id, counted per tenant on the
   `crypto_guard_rejections` metric.
-- **Structural guards** (`check-crypto-invariant-{1,2,3,4,5,8,9,10}`) pinning the
-  invariants at review time, plus a real-Postgres integration suite across every
-  placement.
+- **Structural guards** (`check-crypto-invariant-{1..11}`) pinning the invariants and
+  the KeyProvider SSRF discipline at review time, plus a real-Postgres integration
+  suite across every placement (KMS-down fail-closed, crash-between-PENDING-and-COMMITTED
+  reconciliation, KEK rotation, governance-absent refusal, and the framed-envelope
+  integrity matrix).

packages/crypto/package.json

@@ -45,9 +45,9 @@
     "migrations": "stubs/migrations",
     "perTenantMigrations": "build/tenant_migrations",
     "minMergedCoverage": {
-      "lines": 60,
-      "functions": 60,
-      "branches": 60
+      "lines": 80,
+      "functions": 80,
+      "branches": 75
     },
     "provider": "@adonisjs-lasagna/crypto/provider",
     "commands": "@adonisjs-lasagna/crypto/commands",

packages/crypto/providers/crypto_provider.ts

@@ -5,6 +5,7 @@ import {
   type SatelliteProviderContract,
 } from '@adonisjs-lasagna/saas-tenancy/sdk'
 import { getActiveDriver, MetricsService } from '@adonisjs-lasagna/saas-tenancy/services'
+import { getConfig } from '@adonisjs-lasagna/saas-tenancy/config'
 import { tenancy } from '@adonisjs-lasagna/saas-tenancy'
 import { setCryptoGuardMetricSink } from '../src/isthmus/crypto_guard_audit.js'
 import WormLedgerWriter, { type WormDb } from '@adonisjs-lasagna/saas-tenancy/worm-ledger'
@@ -62,13 +63,16 @@ export default class CryptoProvider implements SatelliteProviderContract {
         activeScopeTenantId,
       })
       // The two-phase shred audit: the shared core WORM ledger (per-tenant hash
-      // chain in backoffice, append-only), wrapped as a ShredLedger. The
+      // chain in the backoffice schema, append-only), wrapped as a ShredLedger. The
       // erasability gate is wired from governance's config seam (absent ⇒ shred is
-      // fail-closed refused, I7). encrypt/decrypt do not depend on either.
+      // fail-closed refused, I7). encrypt/decrypt do not depend on either. The
+      // connection name is resolved from config (never a hardcoded literal): the
+      // ledger's SQL is schema-qualified `backoffice.worm_ledger` but runs on the
+      // host's central connection, exactly as the real integration harness wires it.
       const ledger = new WormShredLedger(
         new WormLedgerWriter({
           getDb: async () => (await makeDb()) as unknown as WormDb,
-          connectionName: 'backoffice',
+          connectionName: getConfig().centralConnectionName,
           activeScopeTenantId,
         })
       )

packages/crypto/src/commands/tenant_crypto_rekek.ts

@@ -64,8 +64,10 @@ export default class TenantCryptoRekek extends BaseCommand {
       let tenant: TenantModelContract
       try {
         tenant = await repo.findByIdOrFail(this.tenant)
-      } catch (error: any) {
-        this.logger.error(`Tenant not found: ${error.message}`)
+      } catch (error: unknown) {
+        this.logger.error(
+          `Tenant not found: ${error instanceof Error ? error.message : String(error)}`
+        )
         this.exitCode = 1
         return
       }
@@ -92,20 +94,26 @@ export default class TenantCryptoRekek extends BaseCommand {
         scanned: acc.scanned + summary.scanned,
         current: acc.current + summary.current,
         rotated: acc.rotated + summary.rotated,
+        shreddedDuringRewrap: acc.shreddedDuringRewrap + summary.shreddedDuringRewrap,
         failed: acc.failed + summary.failed,
       }),
-      { scanned: 0, current: 0, rotated: 0, failed: 0 }
+      { scanned: 0, current: 0, rotated: 0, shreddedDuringRewrap: 0, failed: 0 }
     )
 
     if (this.json) {
       this.logger.log(JSON.stringify({ dryRun: this.dryRun, tenants: results, totals }, null, 2))
     } else {
       for (const { tenantId, summary } of results) {
         if (summary.scanned === 0) continue // quietly skip tenants with no DEKs
+        // A row shredded mid-rotation is a benign race; surface it only when it happened.
+        const shredNote =
+          summary.shreddedDuringRewrap > 0
+            ? `, shredded mid-rotate ${summary.shreddedDuringRewrap}`
+            : ''
         const line =
           `${tenantId}: scanned ${summary.scanned}, ` +
           `${this.dryRun ? 'would re-wrap' : 're-wrapped'} ${summary.rotated}, ` +
-          `already current ${summary.current}, failed ${summary.failed}`
+          `already current ${summary.current}${shredNote}, failed ${summary.failed}`
         this.logger.log(summary.failed > 0 ? this.colors.red(line) : this.colors.dim(line))
         for (const f of summary.failures) {
           this.logger.log(

packages/crypto/src/commands/tenant_crypto_shred.ts

@@ -73,8 +73,10 @@ export default class TenantCryptoShred extends BaseCommand {
     let tenant: TenantModelContract
     try {
       tenant = await repo.findByIdOrFail(this.tenant)
-    } catch (error: any) {
-      this.logger.error(`Tenant not found: ${error.message}`)
+    } catch (error: unknown) {
+      this.logger.error(
+        `Tenant not found: ${error instanceof Error ? error.message : String(error)}`
+      )
       this.exitCode = 1
       return
     }

packages/crypto/src/exceptions/crypto_exception.ts

@@ -4,13 +4,17 @@ export const CRYPTO_ERROR_CODES = [
   'dek_invalid', // an unwrapped DEK is not 32 bytes (a corrupt / wrong-provider wrap)
   'dek_conflict', // two live DEKs for one (subject, category) were attempted (partial UNIQUE, I10, T12)
   'keyprovider_missing', // no KeyProvider is registered for the configured name
+  'keyprovider_unavailable', // an HTTP-backed KeyProvider (KMS/Vault) backend is unreachable, blocked by the SSRF pin, or errored
   'index_key_unavailable', // the KeyProvider yields no blind-index key: fail closed, never a bare unkeyed hash (I5, T3)
   'no_tenant_scope', // EncryptedRepository was called with no active tenant scope: fail closed, never a cross-tenant DEK
   'tenant_scope_mismatch', // a raw-SQL query's tenant differs from the active tenancy scope (ContextSeal)
   'config_invalid', // a malformed `config.crypto` block
   'shred_refused', // governance absent, or the category is not erasable (legal hold): I7 fail-closed
   'shred_unaudited', // no WORM ledger, or the PENDING append failed before the delete: abort, nothing destroyed
   'shred_audit_unfinalized', // the COMMITTED mark failed after the delete: erasure done, a PENDING row remains (reported)
+  'shred_in_progress', // another shred/provision holds the serialize lock and it could not be acquired in the wait window (retriable)
+  'insert_failed', // a wrapped-DEK INSERT ... RETURNING produced no row (fail-closed rather than crashing on undefined)
+  'framed_stream_invalid', // a framed enc_v2 stream envelope failed integrity: reorder / drop / duplicate / truncation / cross-stream frame (§6.8)
 ] as const
 
 export type CryptoErrorCode = (typeof CRYPTO_ERROR_CODES)[number]

packages/crypto/src/index.ts

@@ -28,6 +28,21 @@ export type { CategoryKey, KeyProvider, SubjectId, WrappedDek } from './types/ke
 // Blind-index (deterministic search HMAC) options (crypto §6.5, I5).
 export type { BlindIndexOptions } from './internal/blind_index.js'
 
+// Framed enc_v2 stream envelope (crypto §6.8): the composition vault consumes to seal
+// large blobs before upload. One AEAD (core's), applied per frame with reorder/
+// truncation binding — NOT a new cipher (I1).
+export {
+  sealFramedV2,
+  openFramedV2,
+  sealFramedV2Stream,
+  openFramedV2Stream,
+} from './internal/framed_stream.js'
+export {
+  DEFAULT_FRAME_SIZE,
+  FRAMED_STREAM_PREFIX,
+  type FramedSealOptions,
+} from './types/framed_envelope.js'
+
 // Transparent field-encryption decorators (crypto §6.4 Option A).
 export { encrypted, searchable } from './models/encrypted_columns.js'
 export type {
@@ -60,6 +75,13 @@ export { default as EncryptedRepository } from './services/encrypted_repository.
 export type { EncryptedRepositoryDeps } from './services/encrypted_repository.js'
 export { default as KeyProviderRegistry } from './services/key_provider_registry.js'
 export { default as EnvKeyProvider } from './services/env_key_provider.js'
+// The SSRF-pinned base for HTTP-backed KeyProviders (KMS/Vault) + a Vault reference
+// (crypto §6.2, §8; T13). A host binds one of these (or a custom subclass) and names it
+// in `config.crypto.keyProvider`. Every outbound is routed through core safeFetch.
+export { default as HttpKeyProvider } from './services/http_key_provider.js'
+export type { HttpKeyProviderOptions, HttpKeyRequest } from './services/http_key_provider.js'
+export { default as VaultKeyProvider } from './services/vault_key_provider.js'
+export type { VaultKeyProviderOptions } from './services/vault_key_provider.js'
 export { default as WormShredLedger } from './services/worm_shred_ledger.js'
 export { default as PgWrappedDekStore } from './services/pg_wrapped_dek_store.js'
 export type {