life-as-api 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,377 @@
+# life-as-api
+
+A personal context layer: a typed, encrypted, consent-gated claim log that lets authorised
+agents query structured facts about a person's life without exposing raw documents, crypto
+primitives, or the underlying storage engine.
+
+> **v0.2.0** · 3908 tests · typecheck clean
+
+The production auth boundary is complete for the documented MVP boundary: a scoped 8-method
+facade (`ProductionScopedLifeApi`) enforces subject and proposal scope on every call, backed by
+a SQLite persistence layer with an AES-256-GCM encryption boundary. Security-relevant decisions
+are recorded through an internal audit abstraction with a local hash chain over `audit_events`
+(tamper-evident locally — not court-grade, not external notarization). Operator tooling covers
+backup/restore, key-availability validation, and full decryptability scanning (D2–D4). On top of
+that closure, the platform layer (Platform-01 through 05) adds trusted-agent/data-source
+registries, guardianship, purpose enforcement, a GDPR Art. 15/20 subject data report, and three
+certified first-party agents — all optional, additive, and fail-closed. See
+[docs/specs/post-auth-product-boundary-spec.md](docs/specs/post-auth-product-boundary-spec.md)
+and [CHANGELOG.md](CHANGELOG.md) for exact claims and non-claims release by release.
+
+---
+
+## Concept
+
+> "Jarvis, what are my active subscriptions?"
+
+The system stores *claims* (immutable, encrypted, provenance-linked facts) and lets agents
+*query* them through a consent gate — seeing only what they've been explicitly granted.
+Nothing is ever mutated in-place. Everything is append-only and audited.
+
+---
+
+## Production factory (MVP-stable)
+
+```ts
+import { createSQLiteLifeApiForProduction } from "life-as-api";
+import type {
+  ProductionApiBundle,
+  ProductionScopedLifeApi,
+  ProductionFactoryConfig,
+  MintedContext,
+} from "life-as-api";
+
+// 1. Configure and build the production bundle
+const bundle: ProductionApiBundle = await createSQLiteLifeApiForProduction({
+  db:               yourMigratedSqliteDatabase,
+
+  // Encryption source — exactly one of encryptionKey or keyProvider must be provided.
+  // Option A: raw key bytes (dev/staging) — factory creates StaticKeyProvider internally.
+  encryptionKey:    { keyId: "key-v1", rawBytes: yourEncryptionKeyBytes },
+  // Option B: external KeyProvider (production) — plug in a KMS-backed adapter.
+  // keyProvider:   yourKmsKeyProvider,    // implements KeyProvider; encryptionKey must be absent
+
+  authAdapter:      yourAuthAdapter,       // implements AuthAdapter
+  rawDocumentStore: yourDurableDocStore,   // implements FactoryCompatibleRawDocumentStore
+  auditLog:         yourDurableAuditLog,   // implements FactoryCompatibleAuditLog
+  // ... see ProductionFactoryConfig for full field list
+});
+
+// 2. Mint a trusted context from bearer credentials
+const minted: MintedContext = await bundle.auth.mint(bearerCredential, targetPersonId, "owner");
+
+// 3. Get a subject-scoped production API
+const api: ProductionScopedLifeApi = bundle.createScopedApi(minted);
+
+// 4. Use the 8 scope-enforced facade methods
+await api.queryContracts(personId, queryInput);
+await api.requestErasure(personId);
+await api.getErasureStatus(personId);
+await api.acceptProposal(proposalId, acceptOptions);
+await api.rejectProposal(proposalId, { reason: "Not accurate" });
+await api.createProposal(proposalInput);
+await api.getProposal(proposalId);             // returns undefined if not found or cross-subject
+await api.listProposals({ status: "pending" }); // scoped to bound person only
+```
+
+All 8 methods enforce subject/proposal scope before delegation. Agents are bound to the
+`personId` from their grant (`authorizedPersonId`). Broad grants (no `personId`) are denied
+at context-minting time, not at query time.
+
+**Proposal read semantics:** `getProposal` returns `undefined` for missing, cross-subject,
+unknown-subject (empty `candidateClaims`), and multi-subject proposals — all four cases are
+indistinguishable. `listProposals` returns only proposals whose unique candidate subject
+matches the bound person; cross/unknown/multi-subject proposals are silently omitted.
+`listProposals` does not expose arbitrary `subject` or `underGrant` filters.
+
+```ts
+// 5. Optional: run the D2b local health diagnostic (no user/agent context required)
+const health = await bundle.healthCheck();
+// health.status: "ok" | "degraded" | "failed"
+// health.checks: readonly HealthCheckItem[]  — seven named checks
+// health.checkedAt: ISO timestamp
+// { status: "ok" } means all seven local checks passed.
+// It does NOT mean operational production readiness.
+```
+
+**This does not claim full OIDC/OAuth authorization flow, session revocation, rate limiting,
+external tamper-evident audit, GDPR/legal compliance, multi-process consistency, or operational
+production readiness.** RS256/JWKS adapter (`JwksKeyRingAuthAdapter`) is implemented — not exported
+from package root; host-supplied. ES256, full OIDC server, OAuth flow, session revocation remain
+unclaimed. See §3 below.
+
+---
+
+## Platform layer (0.2.0)
+
+Five optional, additive slices sit on top of the production auth closure. Every one of them is
+fail-closed and backward-compatible: if you don't configure it, behavior is byte-identical to
+0.1.0.
+
+### Platform-01 — Trusted Agent Registry + Purpose Binding
+
+When a `TrustedAgentRegistry` is configured, no `AgentConsentContext` is minted without
+`isAgentTrusted(agentId, purpose)` returning `true` — the check fires before `issuer.mintAgent`,
+before any context that could read data exists. Registry exceptions, unknown agents, or expired
+certifications deny the mint; the registry never fails open. Leaving `trustedAgentRegistry`
+unset leaves the agent-mint path unchanged.
+
+```ts
+const bundle = await createSQLiteLifeApiForProduction({
+  // ...required fields
+  trustedAgentRegistry: new InMemoryTrustedAgentRegistry([medicalAgentRegistryEntry(validUntilMs)]),
+});
+```
+
+`GrantDescriptor.purpose` remains declarative — the library does not enforce it on the plain
+access-context path; enforcement there is agent/host responsibility (see Platform-04 for the
+minting-time enforcement path).
+
+### Platform-02 — Trusted Data Source Registry + Proposal Policy
+
+`TrustedDataSourceRegistry` and `ProposalPolicy` (`DefaultProposalPolicy`,
+`RegistryBackedProposalPolicy`) decide whether an incoming proposal is auto-accepted,
+auto-rejected, or left for manual review. Unknown source, expired certification, unrecognised
+scope, or any exception during evaluation resolves to `"manual"` — the fail-safe default,
+identical to pre-Platform-02 behavior. An explicit `config.proposalPolicy` always wins over the
+`trustedDataSourceRegistry` convenience wiring when both are supplied.
+
+### Platform-03 — Guardianship / Bevollmächtigung
+
+`GuardianRegistry` plus `mintGuardianContext()` let an authorised guardian mint a scoped
+`MintedContext` for a ward. The registry check (`getRelationship` + `isAuthorized`) fires before
+`issuer.mintOwner` — no context exists if the check fails. The registry check is fail-closed on
+an unknown guardian/ward pair, an expired relationship, or a scope that isn't an exact match.
+`requestErasure` and `getErasureStatus` are always denied for guardian contexts, regardless of
+granted scopes — erasure is personal and not delegable. Without a configured `guardianRegistry`,
+`mintGuardianContext` throws `GUARDIAN_REGISTRY_NOT_CONFIGURED_001`; all other behavior is
+unaffected.
+
+```ts
+const minted = await bundle.auth.mintGuardianContext(bearerCredential, wardPersonId, "manage_finances");
+```
+
+### Platform-04 — Purpose-Enforcement + Subject Data Report (GDPR Art. 15/20)
+
+When a caller passes `MintOptions.declaredPurpose` **and** the resolved grant declares its own
+`purpose` **and** the two differ, the mint is denied with the same opaque error used for
+"grant not found" — the two denial reasons are indistinguishable to the caller. If either side
+omits a purpose, there is no enforcement and behavior matches pre-Platform-04. On a successful
+mint with a declared purpose, `MintedContext.declaredPurpose` carries the value.
+
+```ts
+const minted = await bundle.auth.mint(bearerCredential, personId, "agent", {
+  declaredPurpose: "diagnosis",
+});
+```
+
+`generateSubjectDataReport(personId)` produces a complete structured account of everything held
+about a person — grants across all statuses, proposals (metadata only, never the encrypted
+payload), and audit events (via grant join plus guardian ward events) — together with a SHA-256
+`dataIntegrityHash` over canonical JSON, making the report tamper-evident. The function does not
+itself enforce caller identity; restricting it to the subject (owner context or an authorised
+guardian) is host responsibility.
+
+### Platform-05 — Certified First-Party Agents
+
+`MedicalAgent`, `FinanceAgent`, and `LegalAgent` are read-only, purpose-bound reference agents,
+each with a matching `*AgentRegistryEntry()` factory that builds a `TrustedAgentRegistryEntry`
+certified by `"life-as-api-foundation"` for direct registration with a `TrustedAgentRegistry`.
+Each agent's constructor accepts only a query function — there is no propose/write capability
+anywhere on these classes. `run()` fail-closed throws a `*_SCOPE_DENIED_001` coded error for any
+`declaredPurpose` outside the agent's own allowed set, including an absent purpose. An optional
+`onAudit` hook fires on every `run()` call; persisting that audit trail durably remains a host
+responsibility.
+
+```ts
+const medical = new MedicalAgent({ query: bundle.createScopedApi(minted).queryContracts, clock });
+await medical.run(minted, queryInput); // only proceeds if minted.declaredPurpose is
+                                        // "diagnosis" | "treatment" | "emergency"
+```
+
+`PurposeTag` gained 11 additive values for these agents (`diagnosis`, `treatment`, `emergency`,
+`tax`, `credit_check`, `insurance_claim`, `account_overview`, `notary`, `contract_review`,
+`evidence_preservation`, `court_filing`) — union-widening only, fully backward-compatible.
+
+---
+
+## Test/dev quick start
+
+```ts
+import {
+  createInMemoryLifeApiForTest,
+  asPersonId, asSourceId, asContractId, asGrantId, asISOTime,
+} from "life-as-api";
+import type { OwnerContext, AgentConsentContext } from "life-as-api";
+
+const { api } = await createInMemoryLifeApiForTest();
+const owner: OwnerContext = { kind: "owner", personId: asPersonId("me") };
+
+// Store a claim with full provenance
+await api.createClaimWithNewEvidence(owner, {
+  document: { bytes: new TextEncoder().encode("...statement..."), mimeType: "application/pdf" },
+  source:   { id: asSourceId("src-001"), kind: "user_manual", label: "Bank statement" },
+  claim: {
+    subject:   asPersonId("me"),
+    predicate: "contract.amount",
+    payload:   { type: "money", currency: "EUR", minorUnits: 4999 },
+    validFrom:  asISOTime("2025-01-15T00:00:00.000Z"),
+    contractId: asContractId("cntr-001"),
+  },
+});
+```
+
+`createInMemoryLifeApiForTest` is for development and testing only. It does not enforce
+production auth boundaries.
+
+---
+
+## MVP-stable public API surface
+
+| Import | Kind | Notes |
+|--------|------|-------|
+| `createSQLiteLifeApiForProduction` | factory | Returns `Promise<ProductionApiBundle>` |
+| `ProductionApiBundle` | type | `{ auth: ContextMintingBoundary; createScopedApi; healthCheck }` |
+| `ProductionScopedLifeApi` | type | 8-method scoped facade |
+| `ListProposalsInput` | type | `{ status?: ProposalStatus }` — narrow filter for `listProposals` |
+| `ContextMintingBoundary` | type | Interface for the auth minting boundary |
+| `MintedContext` | type | Trusted context with scope metadata |
+| `ProductionFactoryConfig` | type | Factory configuration interface — `encryptionKey?` (raw bytes → `StaticKeyProvider`) **or** `keyProvider?: KeyProvider` (external KMS-backed adapter); exactly one required; both present → fail-closed; also optional `logger?: Logger`, `metrics?: MetricsRecorder` |
+| `Logger`, `LogEvent`, `LogLevel` | types | D2a best-effort operator diagnostics interface |
+| `noopLogger` | runtime | Safe frozen no-op logger — the library default |
+| `MetricsRecorder` | type | D2c optional push-style metrics adapter interface (`increment?`, `observe?`) |
+| `MetricName` | type | Closed union of the five D2c metric names |
+| `MetricLabels` | type | Closed interface of the six allowed low-cardinality label keys |
+| `noopMetricsRecorder` | runtime | Safe frozen no-op metrics recorder — the library default |
+| `HealthStatus` | type | `"ok" \| "degraded" \| "failed"` — aggregate and per-check status |
+| `HealthCheckItem` | type | `{ name, status, code, errorName? }` — one entry per check, no sensitive fields |
+| `HealthCheckResult` | type | `{ status, checkedAt, checks }` — full D2b result shape |
+| `RejectOptions` | type | `{ reason: string }` for `rejectProposal` |
+| `ProposalInput`, `AcceptOptions` | types | Proposal method parameter types |
+| `PersonId`, `ProposalId`, … | opaque ID types | Tagged string IDs |
+| `AuthAdapter`, `TenantBoundary`, `GrantResolver` | interfaces | Host adapter contracts |
+| `SubjectScopedLifeApi`, `ProposalScopedLifeApi` | lower-level | Host-adapter composition utilities |
+| `assertAuthorizedForSubject`, `inspectProposalScope` | helpers | Host-adapter scope utilities |
+| `createInMemoryLifeApiForTest` | dev/test factory | Not a production pattern |
+| `KeyProvider`, `KeyDescriptor` | types | Interface-only — external KMS adapter contract; no implementation exported |
+| `TrustedAgentRegistry`, `TrustedAgentRegistryEntry` | types (Platform-01) | Interface + entry shape for agent-mint gating |
+| `InMemoryTrustedAgentRegistry` | runtime (Platform-01) | Reference/dev implementation — production hosts supply their own |
+| `TrustedDataSourceRegistry`, `TrustedDataSourceEntry` | types (Platform-02) | Interface + entry shape for source trust/expiry |
+| `InMemoryTrustedDataSourceRegistry` | runtime (Platform-02) | Reference/dev implementation |
+| `ProposalPolicy`, `ProposalPolicyInput`, `ProposalDisposition` | types (Platform-02) | Auto-accept/auto-reject/manual policy contract |
+| `DefaultProposalPolicy`, `RegistryBackedProposalPolicy` | runtime (Platform-02) | Manual-default and registry-backed policy implementations |
+| `GuardianRegistry`, `GuardianRelationship` | types (Platform-03) | Guardian/ward relationship contract |
+| `InMemoryGuardianRegistry` | runtime (Platform-03) | Reference/dev implementation |
+| `GuardianContextMintingBoundary` | type (Platform-03) | `ContextMintingBoundary` extended with `mintGuardianContext()` |
+| `SubjectDataReport`, `GrantSummary`, `ProposalSummary`, `AuditEventSummary`, `SubjectDataReportOptions` | types (Platform-04) | Shape of the GDPR Art. 15/20 subject data report |
+| `generateSubjectDataReport` | runtime (Platform-04) | Builds the subject data report; caller-identity enforcement is host responsibility |
+| `MedicalAgent`, `medicalAgentRegistryEntry`, `MEDICAL_AGENT_ID`, `MEDICAL_AGENT_VERSION`, `ALLOWED_MEDICAL_PURPOSES`, `MedicalPurpose` | Platform-05 | Certified first-party medical agent (read-only, purpose-bound) |
+| `FinanceAgent`, `financeAgentRegistryEntry`, `FINANCE_AGENT_ID`, `FINANCE_AGENT_VERSION`, `ALLOWED_FINANCE_PURPOSES`, `FinancePurpose` | Platform-05 | Certified first-party finance agent (read-only, purpose-bound) |
+| `LegalAgent`, `legalAgentRegistryEntry`, `LEGAL_AGENT_ID`, `LEGAL_AGENT_VERSION`, `ALLOWED_LEGAL_PURPOSES`, `LegalPurpose` | Platform-05 | Certified first-party legal agent (read-only, purpose-bound) |
+
+### Not exported from package root (intentional)
+
+| Symbol | Reason |
+|--------|--------|
+| `LifeApiImpl` | Raw factory-internal API — bypasses scope enforcement |
+| `BackendContextMintingBoundary` | Factory-internal production dependency |
+| `AccessContextIssuer` (runtime) | Trust authority — instance-scoped only |
+| `ProductionScopedLifeApiImpl` | Implementation class — use the interface |
+| `JwtAuthAdapter`, `JwtKeyRingAuthAdapter`, `StaticJwtKeyRing` | Not package-root exported |
+| `SQLiteTenantBoundary`, `SQLiteGrantResolver` | Not package-root exported |
+| `SQLiteProposalQueue`, `SQLiteAuditLog`, `SQLiteRawDocumentStore` | Not package-root exported |
+| `JwksKeyRingAuthAdapter` | RS256/JWKS auth adapter — not package-root exported |
+| `TokenRevocationStore`, `RevocationAwareAuthAdapter` | Session revocation wrapper — not package-root exported |
+| `RateLimiter`, `RateLimitedContextMintingBoundary` | Rate-limiting wrapper — not package-root exported |
+
+The package exports map (`package.json exports`) is root-only. Unsupported subpath imports
+(e.g. `"life-as-api/src/…"`, `"life-as-api/dist/…"`) are not part of the public API and
+are blocked by Node.js for consumers respecting the exports map.
+
+---
+
+## What this is
+
+- A typed, immutable claim log with AES-256-GCM encrypted payloads
+- A consent-gated query surface (agents see only granted predicates)
+- A proposal queue (agents propose, humans/systems accept or reject)
+- A provenance chain: `RawDocument → EvidenceRef → Source → Claim`
+- A production auth boundary: factory returns a scoped production API bundle; trusted context minting is enforced; grant person scope propagates to agent contexts; erasure/query/proposal create/accept/reject/read enforce documented subject/proposal scope
+
+## What this is NOT
+
+- **No KMS / external key custody** — JWT secrets in process memory; at-rest keys via `StaticKeyProvider`
+- **No full OIDC/OAuth** — RS256/JWKS auth adapter (`JwksKeyRingAuthAdapter`) implemented (D5, `cbe40ed`); not exported from package root; host-supplied. ES256, full OIDC authorization server, OAuth flow not claimed
+- **No session revocation built in** — `TokenRevocationStore` interface and
+  `RevocationAwareAuthAdapter` wrapper are implemented (host-injectable denylist, fail-closed on
+  store error); not exported from package root; without wiring one in, compromised credentials
+  require out-of-band grant revocation
+- **No rate limiting built in** — `RateLimiter` interface and `RateLimitedContextMintingBoundary`
+  wrapper are implemented (host-injectable, principal-scoped, configurable fail-open/fail-closed
+  on store error); not exported from package root; no bundled limiter implementation or store, no
+  API-level throttle unless a host wires one in
+- **No external tamper-evident audit** — audit events in SQLite only; no hash-chaining or external sink
+- **No GDPR / legal erasure compliance** — tombstone model is not a legally valid erasure mechanism
+- **No multi-process ProposalQueue consistency** — single-process only
+- **No operational production readiness** — D2a adds best-effort operator diagnostics (logger); D2b adds seven local health checks (`healthCheck()` on the bundle — DB, schema, key provider, auth/tenant/grant adapters); `{ status: "ok" }` is not operational production readiness; D2c adds an optional internal `MetricsRecorder` boundary — push-style adapter for counters only; no external sink, no OpenTelemetry, no HTTP/Prometheus endpoint, no SLA/SLO claim; D3a adds internal SQLite backup/validation utilities (`backupSQLiteDatabase`, `validateBackup`) — recoverability tooling only, not an SLA or operational-readiness claim; D4b adds `validateBackupKeyAvailability(sourcePath, keyProvider)` — internal offline key availability check (are all referenced keyIds resolvable?); key availability does not prove correct key material or decryptability; D4c adds `scanBackupDecryptability(sourcePath, cryptoBoundary)` — internal offline AES-GCM decryptability scan across all three encrypted tables; `{ status: "ok" }` proves tag verification passed on all rows, not semantic correctness or DR readiness
+- **No UI, MCP server, OCR, LLM extraction, Open Banking connectors**
+- **No admin methods** — `createSourceAdmin`, `createGrantAdmin`, etc. are deferred
+
+---
+
+## Running tests
+
+```
+npm run build         # compile src/ → dist/ (required before dist/-dependent checks)
+npx vitest run        # full suite (3908 passing)
+npx tsc --noEmit      # typecheck
+```
+
+---
+
+## Installing / Releasing
+
+```
+npm install life-as-api   # once published
+```
+
+Releases are cut manually: `npm publish` runs `prepublishOnly` (`typecheck` → `test` → `build`)
+before anything is packed, so a broken typecheck or a failing test blocks publish. The publish
+step itself is deliberately manual — there is no CI-triggered auto-publish.
+
+---
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [docs/specs/post-auth-product-boundary-spec.md](docs/specs/post-auth-product-boundary-spec.md) | Post-auth product boundary freeze — capabilities, non-claims, post-MVP tracks |
+| [docs/specs/post-mvp-proposal-read-facade-spec.md](docs/specs/post-mvp-proposal-read-facade-spec.md) | Proposal Read Facade spec — scoped `getProposal`/`listProposals` (implemented `7bc55b4`) |
+| [docs/specs/post-mvp-audit-hardening-spec.md](docs/specs/post-mvp-audit-hardening-spec.md) | Audit Hardening spec — internal audit coverage C1 (implemented `ac44391`); read allow-path audit C3 (implemented `b85df38`); local hash chain C4: `sequence`/`prev_hash`/`event_hash` on `audit_events`, internal `verifyAuditChain` detects row deletion/reorder/naive modification (implemented `ebf52c2`; local-only — not court-grade, not WORM, not external notarization) |
+| [docs/specs/post-auth-mvp-packaging-exports-spec.md](docs/specs/post-auth-mvp-packaging-exports-spec.md) | Packaging/exports review — Phase 1 (type gaps, complete) and Phase 2 (exports map, complete) |
+| [docs/specs/post-auth-mvp-packaging-phase2-spec.md](docs/specs/post-auth-mvp-packaging-phase2-spec.md) | Package Exports Phase 2 spec — build strategy, exports map, deep import policy (implemented `0518c1a`) |
+| [docs/specs/production-auth-closure-recheck-spec.md](docs/specs/production-auth-closure-recheck-spec.md) | C1–C10 Final Audit — Option A accepted |
+| [docs/specs/production-auth-closure-spec.md](docs/specs/production-auth-closure-spec.md) | Auth closure criteria (C1–C10), MUST gaps, DEFER/NEVER inventory |
+| [docs/roadmap/production-auth-track-freeze.md](docs/roadmap/production-auth-track-freeze.md) | Canonical auth track record — all slices, invariants, claims allowed/forbidden |
+| [docs/INVARIANTS.md](docs/INVARIANTS.md) | Machine-checkable property table (all invariant codes) |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System components, data flow, intentional exclusions |
+| [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | Assets, actors, trust boundaries, threats, mitigations |
+| [docs/SDK_USAGE.md](docs/SDK_USAGE.md) | How to use every public API method |
+| [docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) | MVP gaps and production blockers |
+| [docs/releases/v0.1.0-architecture-ready.md](docs/releases/v0.1.0-architecture-ready.md) | Release notes — v0.1.0-architecture-ready (historical baseline) |
+| [docs/BACKUP_RESTORE.md](docs/BACKUP_RESTORE.md) | Backup and Restore operator procedure — `backupSQLiteDatabase`, `validateBackup`, restore steps, key boundary, non-claims (D3a) |
+| [docs/KEY_MANAGEMENT.md](docs/KEY_MANAGEMENT.md) | Key Management operator procedure — key inventory query, rotation steps, pre-restore key check, KMS adapter contract, non-claims (D4a) |
+| [docs/specs/post-mvp-observability-d2c-metrics-spec.md](docs/specs/post-mvp-observability-d2c-metrics-spec.md) | D2c Metrics Boundary Spec — `MetricsRecorder` interface, five metric names, six label keys, label policy, failure policy, non-claims; runtime accepted at `9820589` |
+| [docs/OPERATIONAL_RUNBOOK.md](docs/OPERATIONAL_RUNBOOK.md) | Operational Runbook — startup/backup/key-availability/restore-drill/promotion checklists, nine incident triage trees, four-layer observability guide, security-sensitive data rules, non-claims (D2/D3/D4 integration) |
+| [docs/specs/post-mvp-kms-adapter-spec.md](docs/specs/post-mvp-kms-adapter-spec.md) | KMS Adapter Spec — `KeyProvider` adapter contract, factory config extension (`keyProvider?`), envelope-encryption pattern, no provider binding, D4e non-exportable deferral; accepted, runtime at `f500719` |
+| [docs/specs/post-mvp-external-idp-oidc-spec.md](docs/specs/post-mvp-external-idp-oidc-spec.md) | External IdP / OIDC / JWKS Spec — `JwksKeyRingAuthAdapter` (RS256 + live JWKS), injectable `HttpClient`, host-injected `ClaimMapper`, OIDC discovery utility, algorithm binding, fetch-amplification bound; ✅ Accepted, runtime at `cbe40ed` |
+| [docs/specs/post-mvp-session-revocation-spec.md](docs/specs/post-mvp-session-revocation-spec.md) | Session Revocation Spec — `TokenRevocationStore` (host-injectable denylist), `RevocationAwareAuthAdapter` wrapper, JTI extraction from unverified payload, fail-closed store error policy, 8 invariants; ✅ Accepted, runtime at `28624ac` |
+| [docs/specs/post-mvp-rate-limiting-spec.md](docs/specs/post-mvp-rate-limiting-spec.md) | Rate Limiting Spec — `RateLimiter` (host-injectable interface), `RateLimitedContextMintingBoundary` wrapper, post-verification key derivation (`principalId + tenantId`), configurable fail-open/closed on store error, 7 invariants; ✅ Accepted, runtime at `88e88c9` |
+| [docs/specs/post-mvp-d4c-decryptability-scan-spec.md](docs/specs/post-mvp-d4c-decryptability-scan-spec.md) | D4c Full Decryptability Scan Spec — `scanBackupDecryptability(sourcePath, cryptoBoundary)`, covers all 3 encrypted tables, aggregate counts only, `"ok"\|"partial"\|"failed"` status, no entity IDs or plaintext in result; ✅ Accepted, runtime at `9995ac5` |
+| [docs/specs/post-mvp-kms-key-recovery-escrow-procedure-spec.md](docs/specs/post-mvp-kms-key-recovery-escrow-procedure-spec.md) | KMS Key Recovery / Escrow Procedure Spec — operator procedure for key inventory, recovery roles, retirement pre-checks (D3a/D4b/D4c chain), restore drill checklist, break-glass controls, evidence artifacts; docs-only, no runtime, no KMS integration, no key escrow implemented by library; 📋 Pending GPT-5.5 acceptance |
+
+---
+
+## Compliance disclaimer
+
+This repository describes software architecture decisions. It is not legal advice. Nothing here constitutes a GDPR compliance mechanism, a legally valid erasure mechanism, a security audit, or an operational readiness guarantee. Real production deployments require legal review, external security assessment, and compliance validation appropriate to the jurisdiction and data category.

package/dist/agent/finance-agent.d.ts

@@ -0,0 +1,44 @@
+import type { Clock, MintedContext } from "../auth/types.js";
+import type { QueryContractsInput, ContextQueryResult } from "../surface/evidence-backed-context-query.js";
+import type { TrustedAgentRegistryEntry } from "./trusted-agent-registry.js";
+export declare const FINANCE_AGENT_ID = "life-as-api/finance-agent-v1";
+export declare const FINANCE_AGENT_VERSION = "1.0.0";
+export declare const ALLOWED_FINANCE_PURPOSES: readonly ["tax", "credit_check", "insurance_claim", "account_overview"];
+export type FinancePurpose = typeof ALLOWED_FINANCE_PURPOSES[number];
+/**
+ * Builds the TrustedAgentRegistryEntry for the certified Finance Agent.
+ * FINANCE_AGENT_REGISTRY_ENTRY_001: certifiedBy is always "life-as-api-foundation".
+ * Permissions include every allowed purpose (the minting boundary passes
+ * decision.purpose as the scope argument to isAgentTrusted) plus declarative
+ * read:* scopes for operator documentation.
+ */
+export declare function financeAgentRegistryEntry(validUntilMs: number): TrustedAgentRegistryEntry;
+export interface FinanceAgentAuditEvent {
+    readonly at: string;
+    readonly agentId: string;
+    readonly reasonCode: "FINANCE_AGENT_RUN_001";
+    readonly decision: "allowed" | "denied";
+    readonly declaredPurpose?: string;
+}
+export interface FinanceAgentOptions {
+    readonly query: (ctx: MintedContext, input: QueryContractsInput) => Promise<ContextQueryResult>;
+    readonly clock: Clock;
+    readonly onAudit?: (event: FinanceAgentAuditEvent) => void;
+}
+/**
+ * Certified first-party Finance Agent.
+ * FINANCE_AGENT_READ_ONLY_001: query-capability only, no propose/write capability.
+ */
+export declare class FinanceAgent {
+    private readonly opts;
+    constructor(opts: FinanceAgentOptions);
+    /**
+     * FINANCE_AGENT_SCOPE_ENFORCED_001 / FINANCE_AGENT_PURPOSE_BOUND_001: run() only
+     * delegates to the configured query function when ctx.declaredPurpose is one of
+     * ALLOWED_FINANCE_PURPOSES. Any other value, or an absent declaredPurpose, denies
+     * fail-closed before the query function is ever invoked.
+     * FINANCE_AGENT_AUDIT_TRAIL_001: the onAudit hook (if configured) always fires,
+     * for both the allowed and denied outcome.
+     */
+    run(ctx: MintedContext, query: QueryContractsInput): Promise<ContextQueryResult>;
+}

package/dist/agent/finance-agent.js

@@ -0,0 +1,75 @@
+// Platform-05 — Certified First-Party Agents: Finance Agent.
+//
+// FINANCE_AGENT_PURPOSE_BOUND_001: this agent acts ONLY when the caller's MintedContext
+//   carries declaredPurpose "tax" | "credit_check" | "insurance_claim" | "account_overview".
+//   Any other declared purpose (or none) is denied before the query function is invoked.
+// FINANCE_AGENT_REGISTRY_ENTRY_001: financeAgentRegistryEntry() returns a
+//   TrustedAgentRegistryEntry certifiedBy "life-as-api-foundation" so hosts can register
+//   this agent with a TrustedAgentRegistry (Platform-01) without hand-rolling the entry.
+// FINANCE_AGENT_SCOPE_ENFORCED_001: run() throws FINANCE_AGENT_SCOPE_DENIED_001 when
+//   declaredPurpose is absent or not in ALLOWED_FINANCE_PURPOSES — fail-closed.
+// FINANCE_AGENT_READ_ONLY_001: the agent has query-capability only. The constructor
+//   accepts exclusively a `query` function; there is no propose/write capability anywhere
+//   on this class.
+// FINANCE_AGENT_AUDIT_TRAIL_001: every run() call invokes the optional onAudit hook with
+//   reasonCode "FINANCE_AGENT_RUN_001" (allowed or denied). Actual audit persistence is a
+//   host responsibility — this hook is a notification point only.
+export const FINANCE_AGENT_ID = "life-as-api/finance-agent-v1";
+export const FINANCE_AGENT_VERSION = "1.0.0";
+export const ALLOWED_FINANCE_PURPOSES = ["tax", "credit_check", "insurance_claim", "account_overview"];
+// TRUSTED_AGENT_REGISTRY_PUBKEY_ENFORCEMENT_DEFERRED_001: placeholder public key —
+// cryptographic signature verification at mint time is not yet implemented.
+const FINANCE_AGENT_PUBLIC_KEY_PEM_PLACEHOLDER = "-----BEGIN PUBLIC KEY-----\nPLACEHOLDER-FINANCE-AGENT-KEY-NOT-YET-ENFORCED\n-----END PUBLIC KEY-----";
+/**
+ * Builds the TrustedAgentRegistryEntry for the certified Finance Agent.
+ * FINANCE_AGENT_REGISTRY_ENTRY_001: certifiedBy is always "life-as-api-foundation".
+ * Permissions include every allowed purpose (the minting boundary passes
+ * decision.purpose as the scope argument to isAgentTrusted) plus declarative
+ * read:* scopes for operator documentation.
+ */
+export function financeAgentRegistryEntry(validUntilMs) {
+    return {
+        agentId: FINANCE_AGENT_ID,
+        name: "Certified Finance Agent (first-party)",
+        permissions: [...ALLOWED_FINANCE_PURPOSES, "read:finance", "read:tax", "read:insurance"],
+        certifiedBy: "life-as-api-foundation",
+        validUntil: new Date(validUntilMs).toISOString(),
+        publicKeyPem: FINANCE_AGENT_PUBLIC_KEY_PEM_PLACEHOLDER,
+    };
+}
+/**
+ * Certified first-party Finance Agent.
+ * FINANCE_AGENT_READ_ONLY_001: query-capability only, no propose/write capability.
+ */
+export class FinanceAgent {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * FINANCE_AGENT_SCOPE_ENFORCED_001 / FINANCE_AGENT_PURPOSE_BOUND_001: run() only
+     * delegates to the configured query function when ctx.declaredPurpose is one of
+     * ALLOWED_FINANCE_PURPOSES. Any other value, or an absent declaredPurpose, denies
+     * fail-closed before the query function is ever invoked.
+     * FINANCE_AGENT_AUDIT_TRAIL_001: the onAudit hook (if configured) always fires,
+     * for both the allowed and denied outcome.
+     */
+    async run(ctx, query) {
+        const purpose = ctx.declaredPurpose;
+        const allowed = purpose !== undefined &&
+            ALLOWED_FINANCE_PURPOSES.includes(purpose);
+        this.opts.onAudit?.({
+            at: this.opts.clock.now(),
+            agentId: FINANCE_AGENT_ID,
+            reasonCode: "FINANCE_AGENT_RUN_001",
+            decision: allowed ? "allowed" : "denied",
+            ...(purpose !== undefined ? { declaredPurpose: purpose } : {}),
+        });
+        if (!allowed) {
+            throw Object.assign(new Error("FINANCE_AGENT_SCOPE_DENIED_001: FinanceAgent may only run with declaredPurpose " +
+                `"tax" | "credit_check" | "insurance_claim" | "account_overview" (got: ${purpose ?? "undefined"})`), { code: "FINANCE_AGENT_SCOPE_DENIED_001" });
+        }
+        return this.opts.query(ctx, query);
+    }
+}
+//# sourceMappingURL=finance-agent.js.map

package/dist/agent/finance-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finance-agent.js","sourceRoot":"","sources":["../../src/agent/finance-agent.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,wFAAwF;AACxF,6FAA6F;AAC7F,yFAAyF;AACzF,0EAA0E;AAC1E,yFAAyF;AACzF,yFAAyF;AACzF,qFAAqF;AACrF,gFAAgF;AAChF,oFAAoF;AACpF,0FAA0F;AAC1F,mBAAmB;AACnB,yFAAyF;AACzF,0FAA0F;AAC1F,kEAAkE;AAMlE,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AAC/D,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAE7C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,CAAU,CAAC;AAGhH,mFAAmF;AACnF,4EAA4E;AAC5E,MAAM,wCAAwC,GAC5C,sGAAsG,CAAC;AAEzG;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,YAAoB;IAC5D,OAAO;QACL,OAAO,EAAE,gBAAgB;QACzB,IAAI,EAAE,uCAAuC;QAC7C,WAAW,EAAE,CAAC,GAAG,wBAAwB,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,CAAC;QACxF,WAAW,EAAE,wBAAwB;QACrC,UAAU,EAAE,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE;QAChD,YAAY,EAAE,wCAAwC;KACvD,CAAC;AACJ,CAAC;AAgBD;;;GAGG;AACH,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,IAAyB;QAAzB,SAAI,GAAJ,IAAI,CAAqB;IAAG,CAAC;IAE1D;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,GAAkB,EAAE,KAA0B;QACtD,MAAM,OAAO,GAAG,GAAG,CAAC,eAAe,CAAC;QACpC,MAAM,OAAO,GACX,OAAO,KAAK,SAAS;YACpB,wBAAkD,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAExE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACzB,OAAO,EAAE,gBAAgB;YACzB,UAAU,EAAE,uBAAuB;YACnC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ;YACxC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/D,CAAC,CAAC;QAEH,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CACP,iFAAiF;gBACjF,yEAAyE,OAAO,IAAI,WAAW,GAAG,CACnG,EACD,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAC3C,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/agent/legal-agent.d.ts

@@ -0,0 +1,44 @@
+import type { Clock, MintedContext } from "../auth/types.js";
+import type { QueryContractsInput, ContextQueryResult } from "../surface/evidence-backed-context-query.js";
+import type { TrustedAgentRegistryEntry } from "./trusted-agent-registry.js";
+export declare const LEGAL_AGENT_ID = "life-as-api/legal-agent-v1";
+export declare const LEGAL_AGENT_VERSION = "1.0.0";
+export declare const ALLOWED_LEGAL_PURPOSES: readonly ["notary", "contract_review", "evidence_preservation", "court_filing"];
+export type LegalPurpose = typeof ALLOWED_LEGAL_PURPOSES[number];
+/**
+ * Builds the TrustedAgentRegistryEntry for the certified Legal Agent.
+ * LEGAL_AGENT_REGISTRY_ENTRY_001: certifiedBy is always "life-as-api-foundation".
+ * Permissions include every allowed purpose (the minting boundary passes
+ * decision.purpose as the scope argument to isAgentTrusted) plus declarative
+ * read:* scopes for operator documentation.
+ */
+export declare function legalAgentRegistryEntry(validUntilMs: number): TrustedAgentRegistryEntry;
+export interface LegalAgentAuditEvent {
+    readonly at: string;
+    readonly agentId: string;
+    readonly reasonCode: "LEGAL_AGENT_RUN_001";
+    readonly decision: "allowed" | "denied";
+    readonly declaredPurpose?: string;
+}
+export interface LegalAgentOptions {
+    readonly query: (ctx: MintedContext, input: QueryContractsInput) => Promise<ContextQueryResult>;
+    readonly clock: Clock;
+    readonly onAudit?: (event: LegalAgentAuditEvent) => void;
+}
+/**
+ * Certified first-party Legal Agent.
+ * LEGAL_AGENT_READ_ONLY_001: query-capability only, no propose/write capability.
+ */
+export declare class LegalAgent {
+    private readonly opts;
+    constructor(opts: LegalAgentOptions);
+    /**
+     * LEGAL_AGENT_SCOPE_ENFORCED_001 / LEGAL_AGENT_PURPOSE_BOUND_001: run() only
+     * delegates to the configured query function when ctx.declaredPurpose is one of
+     * ALLOWED_LEGAL_PURPOSES. Any other value, or an absent declaredPurpose, denies
+     * fail-closed before the query function is ever invoked.
+     * LEGAL_AGENT_AUDIT_TRAIL_001: the onAudit hook (if configured) always fires,
+     * for both the allowed and denied outcome.
+     */
+    run(ctx: MintedContext, query: QueryContractsInput): Promise<ContextQueryResult>;
+}

package/dist/agent/legal-agent.js

@@ -0,0 +1,76 @@
+// Platform-05 — Certified First-Party Agents: Legal Agent.
+//
+// LEGAL_AGENT_PURPOSE_BOUND_001: this agent acts ONLY when the caller's MintedContext
+//   carries declaredPurpose "notary" | "contract_review" | "evidence_preservation" |
+//   "court_filing". Any other declared purpose (or none) is denied before the query
+//   function is invoked.
+// LEGAL_AGENT_REGISTRY_ENTRY_001: legalAgentRegistryEntry() returns a
+//   TrustedAgentRegistryEntry certifiedBy "life-as-api-foundation" so hosts can register
+//   this agent with a TrustedAgentRegistry (Platform-01) without hand-rolling the entry.
+// LEGAL_AGENT_SCOPE_ENFORCED_001: run() throws LEGAL_AGENT_SCOPE_DENIED_001 when
+//   declaredPurpose is absent or not in ALLOWED_LEGAL_PURPOSES — fail-closed.
+// LEGAL_AGENT_READ_ONLY_001: the agent has query-capability only. The constructor
+//   accepts exclusively a `query` function; there is no propose/write capability anywhere
+//   on this class.
+// LEGAL_AGENT_AUDIT_TRAIL_001: every run() call invokes the optional onAudit hook with
+//   reasonCode "LEGAL_AGENT_RUN_001" (allowed or denied). Actual audit persistence is a
+//   host responsibility — this hook is a notification point only.
+export const LEGAL_AGENT_ID = "life-as-api/legal-agent-v1";
+export const LEGAL_AGENT_VERSION = "1.0.0";
+export const ALLOWED_LEGAL_PURPOSES = ["notary", "contract_review", "evidence_preservation", "court_filing"];
+// TRUSTED_AGENT_REGISTRY_PUBKEY_ENFORCEMENT_DEFERRED_001: placeholder public key —
+// cryptographic signature verification at mint time is not yet implemented.
+const LEGAL_AGENT_PUBLIC_KEY_PEM_PLACEHOLDER = "-----BEGIN PUBLIC KEY-----\nPLACEHOLDER-LEGAL-AGENT-KEY-NOT-YET-ENFORCED\n-----END PUBLIC KEY-----";
+/**
+ * Builds the TrustedAgentRegistryEntry for the certified Legal Agent.
+ * LEGAL_AGENT_REGISTRY_ENTRY_001: certifiedBy is always "life-as-api-foundation".
+ * Permissions include every allowed purpose (the minting boundary passes
+ * decision.purpose as the scope argument to isAgentTrusted) plus declarative
+ * read:* scopes for operator documentation.
+ */
+export function legalAgentRegistryEntry(validUntilMs) {
+    return {
+        agentId: LEGAL_AGENT_ID,
+        name: "Certified Legal Agent (first-party)",
+        permissions: [...ALLOWED_LEGAL_PURPOSES, "read:legal", "read:contracts", "read:identity"],
+        certifiedBy: "life-as-api-foundation",
+        validUntil: new Date(validUntilMs).toISOString(),
+        publicKeyPem: LEGAL_AGENT_PUBLIC_KEY_PEM_PLACEHOLDER,
+    };
+}
+/**
+ * Certified first-party Legal Agent.
+ * LEGAL_AGENT_READ_ONLY_001: query-capability only, no propose/write capability.
+ */
+export class LegalAgent {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * LEGAL_AGENT_SCOPE_ENFORCED_001 / LEGAL_AGENT_PURPOSE_BOUND_001: run() only
+     * delegates to the configured query function when ctx.declaredPurpose is one of
+     * ALLOWED_LEGAL_PURPOSES. Any other value, or an absent declaredPurpose, denies
+     * fail-closed before the query function is ever invoked.
+     * LEGAL_AGENT_AUDIT_TRAIL_001: the onAudit hook (if configured) always fires,
+     * for both the allowed and denied outcome.
+     */
+    async run(ctx, query) {
+        const purpose = ctx.declaredPurpose;
+        const allowed = purpose !== undefined &&
+            ALLOWED_LEGAL_PURPOSES.includes(purpose);
+        this.opts.onAudit?.({
+            at: this.opts.clock.now(),
+            agentId: LEGAL_AGENT_ID,
+            reasonCode: "LEGAL_AGENT_RUN_001",
+            decision: allowed ? "allowed" : "denied",
+            ...(purpose !== undefined ? { declaredPurpose: purpose } : {}),
+        });
+        if (!allowed) {
+            throw Object.assign(new Error("LEGAL_AGENT_SCOPE_DENIED_001: LegalAgent may only run with declaredPurpose " +
+                `"notary" | "contract_review" | "evidence_preservation" | "court_filing" (got: ${purpose ?? "undefined"})`), { code: "LEGAL_AGENT_SCOPE_DENIED_001" });
+        }
+        return this.opts.query(ctx, query);
+    }
+}
+//# sourceMappingURL=legal-agent.js.map