@centient/secrets 0.9.0 → 0.11.0

package/README.md

@@ -2,8 +2,15 @@
 
 Cross-platform secrets vault with AES-256-GCM encryption and platform-native key storage.
 
+> **Before you deploy this:** read the [threat model](../../docs/threat-model.md). It states what the library defends against, what it explicitly does **not** defend against (including two gaps that are live on the default path — the shared `centient-vault` Keychain master-key item, and the master key transiting argv on the macOS Keychain key write), where the trust boundaries are, and a deployment checklist.
+
 > **Daemons / long-running processes:** see [Session-backed vault (`openVault`)](./docs/session-vault.md) for the recommended API — single master-key unlock per session, in-memory cached reads, mtime-check coherence with the CLI, rollback protection via monotonic version + sidecar.
 
+> **Creating a session vault:** use `createVault({ path, key })`. It composes the
+> initial AAD-bound ciphertext and rollback sidecar without exposing their
+> private wire format. It is non-destructive, never manages provider state, and
+> refuses incomplete vault/sidecar pairs. See the [first-use guide](./docs/session-vault.md#first-use-creation).
+
 ## Installation
 
 ```bash
@@ -21,23 +28,188 @@ pnpm add @centient/secrets
 - AES-256-GCM authenticated encryption for secrets at rest
 - Platform-native key storage (macOS Keychain, Linux secret-service)
 - Pluggable key providers (Keychain, 1Password, passphrase)
-- Credential vault with session management
+- Credential vault with session management, plus an opt-in 1Password credential backend
+- Instance-scoped `SecretsClient` factories with composable policy middleware
 - Environment detection (CI, Docker, SSH, headless, agent)
 - Built-in CLI for interactive secret management
 
 ## Quick Start
 
+The client factory is the primary API when a consumer needs an explicit storage
+provider, caller identity, or policies. Each client snapshots its policy-stack
+membership, so two consumers in one process cannot accidentally add or remove
+one another's enforcement. Policy instances may retain their own internal state.
+
 ```typescript
-import { storeCredential, getCredential, deleteCredential } from "@centient/secrets";
+import {
+  KeychainVault,
+  auditTrail,
+  createSecretsClient,
+  type CredentialAuditEvent,
+} from "@centient/secrets";
+
+const auditBuffer: CredentialAuditEvent[] = [];
+const client = createSecretsClient({
+  provider: new KeychainVault(),
+  policies: [
+    auditTrail({
+      sink: (event) => auditBuffer.push(event),
+      includeReads: true,
+    }),
+  ],
+});
+
+await client.storeCredential("my-service.api-key", "<your-api-key>", {
+  caller: { id: "my-service", kind: "service" },
+});
+
+const value = await client.getCredential("my-service.api-key", {
+  caller: { id: "my-service", kind: "service" },
+});
+
+await client.deleteCredential("my-service.api-key", {
+  caller: { id: "my-service", kind: "service" },
+});
+```
 
-// Store a credential
-await storeCredential("my-service", "api-key", "sk-abc123");
+`SecretsProvider` is the credential-*value* storage SPI used by the factory.
+The older `VaultBackend` name remains as a deprecated type alias, so existing
+implementations continue to compile. This is separate from `KeyProvider`, which
+locates the master key used to open an encrypted session vault.
 
-// Retrieve it
-const value = await getCredential("my-service", "api-key");
+Policies use onion ordering: `before` runs top-to-bottom and `after` runs
+bottom-to-top. A throwing `before` fails closed without contacting the provider;
+the rejecting policy and every previously entered policy still receive the
+rejection event while later policies do not run. Operation metadata includes the
+operation, key or prefix, and optional caller identity, but never the credential
+value. Because `auditTrail()` promises to observe policy denials, place it before
+every policy that has a `before` hook. Client construction and legacy policy
+replacement reject an unsafe order instead of silently leaving denials unaudited.
+
+### Audit telemetry: OpenTelemetry + OCSF
+
+Installing an `auditTrail()` policy maps every value-free credential outcome —
+including provider failures and policy denials — to an OCSF 1.9.0 Entity
+Management record. `auditTrail()` defaults to an OpenTelemetry sink; audit is
+not globally enabled merely by importing the package.
+
+```typescript
+import { auditTrail, createSecretsClient } from "@centient/secrets";
 
-// Delete when no longer needed
-await deleteCredential("my-service", "api-key");
+const client = createSecretsClient({
+  provider,
+  policies: [auditTrail()],
+});
+```
+
+`@centient/secrets` depends on `@opentelemetry/api`, not an SDK or exporter.
+The application owns tracer-provider, sampler, exporter, collector, and shutdown
+configuration. The sink reports a non-recording or unsampled span as degraded;
+for an audit pipeline, configure an always-on audit sampler and force-flush the
+application's SDK before shutdown.
+
+The released OCSF schema corrects an older ADR-002 label: `3` is the Identity &
+Access Management category and `3004` is the **Entity Management class**; there
+is no released class named Credential Activity. Stores are upserts and
+enumeration has no 3004 activity, so both use `activity_id: 99` (`Store` or
+`Enumerate`) instead of claiming a create/update distinction the provider SPI
+cannot observe. Policy denial is `action_id: 2` with `status_id: 2`.
+
+Sink migration: the pre-1.0 audit seam passed its internal `SecretsEvent`
+directly to a callback. A sink now receives `CredentialAuditEvent`. Read the
+credential key from `entity.name`, provider from `entity.data.vault_name`, raw
+event classification from `unmapped["centient.secrets.event_type"]`, and latency
+from `unmapped["centient.secrets.operation.duration_ms"]`. Credential values and
+provider/policy exception text are not copied into the OCSF record.
+
+Non-OTel deployments can use the JSONL or RFC 5424 syslog sinks. Both enqueue in
+emission order, bound their queues, report background failures, and expose
+`flush()`/`close()` so a caller can observe delivery failure:
+
+```typescript
+import { auditTrail, createSecretsClient } from "@centient/secrets";
+import { jsonlAuditSink } from "@centient/secrets/sinks";
+
+const sink = jsonlAuditSink({ filePath: "/var/log/my-service/secrets.jsonl" });
+const client = createSecretsClient({ provider, policies: [auditTrail({ sink })] });
+
+// ...credential operations...
+await sink.flush?.();
+```
+
+JSONL contains bare OCSF records. Syslog serializes the same record as the RFC
+5424 message body. New JSONL files/directories default to owner-only modes
+(`0o600`/`0o700`); existing permissions are not silently changed. UDP syslog's
+`flush()` confirms local socket acceptance, not remote persistence, and UDP does
+not provide transport encryption or authentication—use a local syslog daemon or
+inject a protected sender for a remote hop. Neither sink routes through
+`@centient/logger`'s
+`AuditWriter` or the SDK's remote `AuditResource`: both existing seams have a
+different closed event schema and async/failure contract. Keeping the
+`AuditSink` boundary structural prevents either package from silently reshaping
+or truncating a signed record.
+
+#### HMAC record-integrity chains
+
+Create an optional process-local chain with a dedicated 32-byte audit key. The
+consumer must load that key from its deployment trust store and inject it; the
+library never reads a file/environment/provider implicitly, silently generates
+a key, or reuses/derives from the vault-encryption key managed by `KeyProvider`.
+
+```typescript
+import {
+  auditTrail,
+  createHmacAuditChain,
+  createSecretsClient,
+  verifyHmacAuditChain,
+} from "@centient/secrets";
+import { jsonlAuditSink } from "@centient/secrets/sinks";
+
+const chain = createHmacAuditChain({
+  chainId: "my-service-secrets",
+  keyId: "audit-key-2026-08",
+  key: auditKeyBytes, // exactly 32 bytes, loaded by the application
+});
+const sink = jsonlAuditSink({ filePath: "/var/log/my-service/secrets.jsonl" });
+const client = createSecretsClient({
+  provider,
+  policies: [auditTrail({ sink, chain })],
+});
+
+// Rotate only at an explicit emission boundary; IDs and key material may never be reused.
+chain.rotate({ keyId: "audit-key-2026-09", key: nextAuditKeyBytes });
+
+await sink.flush?.();
+const anchor = chain.checkpoint();
+// Persist `anchor` outside the audit log's trust domain.
+```
+
+Each chained event uses OCSF 1.9's Record Integrity profile:
+`metadata.sequence`, a chain UID, the current HMAC fingerprint, and the previous
+event reference. `verifyHmacAuditChain()` accepts a trusted key resolver; bind
+verification to the deployment's trusted `expectedChainId` so another valid
+chain cannot be substituted. The verifier
+returns a discriminated result rather than throwing on hostile records. It
+detects content mutation (including the final event), insertion, duplication,
+internal deletion, reorder, unknown/wrong keys, and invalid rotations. Supply a
+trusted initial checkpoint when verifying a resumed segment and an expected
+final checkpoint to detect prefix/tail deletion; HMAC alone cannot prove that
+an attacker did not delete the whole log. Checkpoints carry chain-scoped,
+HMAC-derived key fingerprints (never key bytes), so historical key material
+cannot be reintroduced under a fresh ID after restart. A global multi-process sequence needs
+an external serialized coordinator—each independent process should otherwise
+use its own `chainId`.
+
+The module-level functions remain the simple, backwards-compatible path. They
+delegate through the process's default client and the legacy global policy
+configuration:
+
+```typescript
+import { storeCredential, getCredential, deleteCredential } from "@centient/secrets";
+
+await storeCredential("my-service.api-key", "<your-api-key>");
+const value = await getCredential("my-service.api-key");
+await deleteCredential("my-service.api-key");
 ```
 
 ### Encryption Utilities
@@ -60,6 +232,34 @@ if (isCIEnvironment()) {
 }
 ```
 
+### Auth CLI messages
+
+`AUTH_MESSAGES` is the shared, i18n-ready catalog of user-visible strings for
+the credential lifecycle a CLI drives on top of this vault — `login`, `logout`,
+`auth status`, `auth refresh`, device flow, and api-key entry. Import it; do not
+copy it. It is public precisely so a consuming CLI stops maintaining a fork that
+drifts from this one.
+
+```typescript
+import { AUTH_MESSAGES, type AuthMessages } from "@centient/secrets";
+
+process.stderr.write(AUTH_MESSAGES.error.vaultWriteFailed + "\n");
+process.stderr.write(AUTH_MESSAGES.info.loginPrompt(verificationUri) + "\n");
+process.stderr.write(AUTH_MESSAGES.warning.tokenExpiringSoon(5) + "\n");
+```
+
+No value interpolates at the call site: fixed messages are string constants and
+parameterized ones are template functions returning the finished string, so a
+translation layer can replace the catalog wholesale. `AuthMessages` is the
+catalog's type, for typing such a table.
+
+**Scope.** The catalog covers the auth lifecycle above, plus the one
+credential-storage warning this package itself emits
+(`warning.envVaultNoStorage`, from the read-only `EnvVault` fallback). It does
+**not** cover the `centient secrets …` operator CLI (`runSecrets`) or the
+`[secrets] …` vault diagnostics — those are command-specific and carry their own
+next-step lines, so they stay at their call sites by design.
+
 ## Key Providers
 
 | Provider | Platform | Description |
@@ -72,6 +272,100 @@ Provider auto-detection prefers OS-backed storage: 1Password, then Keychain,
 then passphrase as the last fallback. Set `secrets.provider: "passphrase"` in
 `~/.centient/config.json` to select it explicitly.
 
+## Credential storage backends
+
+The **key** layer above decides where the vault *encryption key* lives. This is
+the separate **credential** layer: where secret *values* are stored.
+
+| Backend | Platform | Selection |
+|---|---|---|
+| `KeychainVault` | macOS | auto |
+| `WindowsVault` | Windows / WSL | auto |
+| `LibsecretVault` | Linux | auto |
+| `GpgVault` | Linux / WSL | auto |
+| `EnvVault` | Any | auto (last resort) |
+| `OnePasswordVault` | Any (needs `op`) | **explicit opt-in only** |
+
+The first five form an auto-cascade, picked by `detect()` in that order.
+`OnePasswordVault` is deliberately **outside** it: having the 1Password CLI
+installed is not consent to route credentials into your personal vault, so it is
+reachable only when you ask for it by name (ADR-004).
+
+```jsonc
+// centient config file
+{
+  "secrets": {
+    "provider": "keychain",              // KEY layer  — key stays in the Keychain
+    "backend": "1password",              // VALUE layer — credentials in 1Password
+    "onePasswordBackend": {
+      "vault": "centient-credentials",   // REQUIRED — no default
+      "tag": "centient"                  // optional
+    }
+  }
+}
+```
+
+Environment equivalents, which take precedence:
+`CENTIENT_SECRETS_BACKEND=1password` and `CENTIENT_OP_VAULT=<name>`.
+
+Two behaviours worth knowing:
+
+- **No default vault, and it fails closed.** Unlike the key block (which defaults
+  to `Private`), an unset `onePasswordBackend.vault` under an explicit
+  `backend: "1password"` is an error. Guessing could write credentials into a
+  vault you did not intend.
+- **An explicit choice is never silently substituted.** If you name `1password`
+  and `op` turns out to be missing or unauthenticated, startup throws rather than
+  quietly falling back to the Keychain — otherwise your secrets would land
+  somewhere other than where you said.
+
+Secret values are written over **stdin** (`op item create -`), never as argv, so
+they never appear in `ps`. Only key *names* are cached (5s TTL, mirroring the
+Keychain backend); values are never cached, so a rotated or revoked credential is
+never served from memory.
+
+**Key constraint.** This backend enforces `isValidKey` (lowercase alphanumeric
+with `-` or `.` separators, 2–64 chars) on every operation, and refuses anything
+else rather than storing it. Reads address the value as
+`op://<vault>/<key>/password`, which is path-structured: a key containing `/`
+would store fine — a 1Password item title is just a string — and then re-parse on
+read into a different item and field, so the write would be silently unreadable.
+Refusing is the better failure; a caller believing a credential is saved when it
+cannot be read back is worse than a caller told no.
+
+### Environment fallback key mapping
+
+`EnvVault` is the read-only terminal backend for hosts with no secure credential
+store. Every valid logical credential key has exactly one environment-variable
+name, so a miss means that variable is genuinely unset rather than that the
+backend does not know how to address the key. The historical mapping is retained:
+
+| Credential key | Environment variable |
+|---|---|
+| `auth-token` | `ENGRAM_API_KEY` |
+| `sync-peers.dek` | `CENTIENT_SECRET_SYNC_2DPEERS_2EDEK` |
+
+For non-auth keys, alphanumerics are uppercased, `-` is escaped as `_2D`, `.` as
+`_2E`, and the result is prefixed with `CENTIENT_SECRET_`. `_` is forbidden by
+the credential-key grammar, so the mapping stays reversible even for adjacent
+separators. Use the exported helper instead of reimplementing it:
+
+```ts
+import { EnvVault, createSecretsClient, credentialKeyToEnvName } from "@centient/secrets";
+
+credentialKeyToEnvName("sync-peers.dek");
+// => "CENTIENT_SECRET_SYNC_2DPEERS_2EDEK"
+
+const client = createSecretsClient({ provider: new EnvVault() });
+```
+
+An unset variable probes as `absent`. A defined-but-empty variable returns
+`null` on retrieval and probes as `failed`, because zero bytes are not a usable
+credential. `store()` remains read-only and returns `false`; `delete()` remains
+an idempotent no-op. Environment values are unencrypted, inherited by child
+processes, and may be readable through `/proc/<pid>/environ`; this fallback is
+configuration plumbing, not secure storage.
+
 ### Per-consumer vault keys
 
 By default `KeychainProvider` targets a single shared Keychain item
@@ -81,6 +375,11 @@ let each consumer use its own key (issue #80). Both are additive — with no
 options the behaviour is byte-identical to before, and existing vaults keep
 opening.
 
+**This is opt-in, and the shared item is still the default.** Until you pass one
+of the options below, anything that can read the `centient-vault` Keychain item
+unlocks every consumer's vault on the machine — see
+[threat model §4.1](../../docs/threat-model.md#41-the-shared-centient-vault-master-key-item-is-still-the-default-issue-80).
+
 **Name your own Keychain item** — the lightweight path. Pass `keychain` to
 `openVault()` (threaded into internal provider resolution) so your consumer's
 master key lives under its own Keychain item:
@@ -122,6 +421,13 @@ const vault = await openVault({ keyProvider: stub });
 A custom provider can also wrap any backend (remote KMS, HSM, env-injected key)
 as long as it implements the `KeyProvider` interface.
 
+`KeyProvider` is intentionally separate from `SecretsProvider`, the
+credential-value storage SPI. A key provider establishes or retrieves the one
+master key used to unlock an encrypted session vault; a secrets provider stores
+the individual credential values. The same technology may fill both roles—for
+example, `OnePasswordProvider` and `OnePasswordVault`—but their instances,
+configuration, key spaces, and operation lifecycles remain independent.
+
 ### Passphrase provider
 
 For hosts without an OS keychain or 1Password CLI (e.g. a headless Linux box
@@ -153,6 +459,116 @@ Security tradeoffs vs OS-backed providers — choose deliberately:
   of ms); daemons should call `openVault()` once at startup, before entering
   their hot loop.
 
+## Compatibility floor for consumers
+
+Several releases of this package closed defects whose only symptom, at the old
+version, is **silence**: a denied credential operation that leaves no audit
+trace, a keychain write that reports success into a keychain the current
+context's reader cannot see, a malformed key that stores on one backend and
+reads as absent on the next. A consumer running such a version cannot learn
+that from the package — the behaviour looks fine and the logs look clean.
+
+So the provider publishes the list. `COMPATIBILITY_FLOOR` is a data table of
+every known behavioural gap, keyed by the version that closed it, and
+`assessCompatibility()` turns an installed version into a grade a `doctor`
+command can print.
+
+```ts
+import { assessCompatibility, SECRETS_PACKAGE_VERSION } from "@centient/secrets";
+
+const assessment = assessCompatibility(SECRETS_PACKAGE_VERSION);
+
+if (assessment.grade !== "ok") {
+  console.warn(assessment.summary);
+  for (const gap of assessment.openGaps) {
+    console.warn(`  [${gap.severity}] ${gap.symptom}`);
+    console.warn(`     fixed in ${gap.closedIn} (${gap.reference})`);
+    if (gap.adoptionNote) console.warn(`     on adoption: ${gap.adoptionNote}`);
+  }
+}
+```
+
+`SECRETS_PACKAGE_VERSION` is the version of the build you actually imported, so
+the assessment describes the code in your tree rather than whatever is latest on
+the registry. It is kept in step with `package.json` by the release flow and
+asserted by a test, so it cannot drift into a wrong answer.
+
+### The grades
+
+| `grade` | Meaning |
+|---|---|
+| `ok` | At or above every known fix. `openGaps` is empty. |
+| `degraded` | Assessable, and one or more known gaps are open. `openGaps` lists them, oldest fix first; `highestSeverity` is the worst. |
+| `unsupported` | Below `MIN_ASSESSABLE_VERSION` — older than the table describes. The gaps it *does* know about are still returned, but the list is not claimed to be complete. |
+| `unknown` | The version could not be parsed. `reason` says why. |
+
+### This is a graded floor, never a boot-time refusal
+
+Nothing in this surface runs at import, nothing throws from a constructor, and
+no vault path consults it. Every function is pure, total and advisory:
+malformed input comes back as a typed `unknown` grade carrying the reason, not
+as an exception. A package that refuses to load because its caller is old turns
+a documentation problem into an outage — so grade, report, and let the consumer
+decide.
+
+### Auditing a manifest pin instead of an install
+
+`assessCompatibility()` answers "what is open in the build I imported".
+`assessPin()` answers "what could be open in any build this pin admits", by
+grading the lowest version the range allows — which is also what a lockfile
+that has never been refreshed is most likely holding:
+
+```ts
+assessPin("^0.6.0").openGaps.map((g) => g.id);
+```
+
+#### The range grammar `assessPin()` accepts
+
+The whole range is matched against an anchored grammar, so an unsupported form
+is rejected *as* unsupported rather than partially interpreted. Exactly four
+forms resolve:
+
+| Form | Example | Resolves to |
+|---|---|---|
+| caret | `^0.6.0` | `0.6.0` |
+| tilde | `~0.9.1` | `0.9.1` |
+| inclusive lower bound | `>=0.8.0` | `0.8.0` |
+| exact | `0.10.0` | `0.10.0` |
+
+The version component is a full `major.minor.patch`. A conventional leading `v`
+(`v0.5.0`), horizontal whitespace after the operator (`>= 0.8.0`) and around the
+whole range, and a `-prerelease` suffix are all accepted; the pre-release is
+**kept**, because rounding `^1.0.0-rc.1` up to `1.0.0` would credit a consumer
+for a release it is not running.
+
+Everything else returns `grade: "unknown"` with a `reason` naming the accepted
+grammar: composite ranges (`>=0.6.0 <0.8.0`), `||` unions, hyphen ranges
+(`1.0.0 - 2.0.0`), wildcards (`*`), x-ranges (`1.x`, `1.2.x`), partial versions
+(`1.2`), upper and exclusive bounds (`<0.9.0`, `>0.9.0`), protocol pins
+(`workspace:*`, `npm:…`, `file:…`, a git URL), build metadata (`^1.2.3+build`,
+which a parser *discards* rather than interprets), and any form carrying a
+trailing token. A guess would grade the wrong version and hand back a clean bill
+of health for a pin nobody actually checked.
+
+#### Malformed input is graded, never thrown
+
+`assessCompatibility()` and `assessPin()` narrow their argument through the same
+guard before anything parses it, so a JS caller — or a `JSON.parse`d manifest,
+or an `any` at a module boundary — that passes `null`, `undefined`, a number or
+an object gets the documented `grade: "unknown"` result carrying a `reason`,
+never an exception. `installedVersion` and `summary` are strings in that case
+too, so the echo cannot hand back a value its declared type forbids.
+
+### Adding an entry
+
+A release earns a row when it closes a defect whose pre-fix symptom is silent.
+A fix a consumer would notice on its own does not need one. Each entry carries
+an `id` (stable — consumers may suppress by it), the `closedIn` version, a
+`severity`, a one-line consumer-facing `symptom`, the `reference` issue, and an
+`adoptionNote` whenever adopting the fix is not a pure no-op. The table is
+ordered oldest fix first; `tests/compatibility.test.ts` pins the ordering, the
+version parity, and the grade each known consumer pin earns.
+
 ## License
 
 MIT

package/dist/audit/hmac-chain.d.ts

@@ -0,0 +1,117 @@
+import type { CredentialAuditEvent, CredentialAuditMetadata, CredentialAuditTypeUid, CredentialAuditUnmapped, OcsfAttestation } from "./ocsf.js";
+export type AuditChainErrorCode = "INVALID_CHAIN_ID" | "INVALID_KEY_ID" | "INVALID_KEY" | "INVALID_CHECKPOINT" | "CHAIN_ID_MISMATCH" | "CHECKPOINT_KEY_MISMATCH" | "KEY_ID_REUSE" | "KEY_MATERIAL_REUSE" | "EVENT_ALREADY_CHAINED" | "SEQUENCE_EXHAUSTED" | "CHAIN_DESTROYED" | "CANONICALIZATION_FAILED";
+/** Configuration/state errors produced by the writer side of the chain. */
+export declare class AuditChainError extends Error {
+    readonly code: AuditChainErrorCode;
+    constructor(code: AuditChainErrorCode, message: string);
+}
+export interface AuditChainKey {
+    /** Stable, non-secret key version identifier. Never reuse an ID. */
+    readonly keyId: string;
+    /** Exactly 32 bytes. The chain copies the bytes and never owns this input. */
+    readonly key: Uint8Array;
+}
+/**
+ * Value-free state needed to resume or externally anchor a chain.
+ *
+ * A checkpoint is trustworthy only when the caller stores it outside the
+ * audit log's own trust domain. Supplying a checkpoint read from the same
+ * mutable log cannot prove that a prefix or suffix was not deleted.
+ */
+export interface AuditChainCheckpoint {
+    readonly chainId: string;
+    readonly sequenceNumber: number;
+    readonly eventUid: string;
+    readonly eventHash: string;
+    readonly typeUid: CredentialAuditTypeUid;
+    readonly keyId: string;
+    /** Ordered key IDs already used by this chain, including `keyId`. */
+    readonly usedKeyIds: readonly string[];
+    /**
+     * Chain-scoped, HMAC-derived key identifiers aligned with `usedKeyIds`.
+     * These are not key bytes; they let a trusted checkpoint prevent historical
+     * key material from being reintroduced under a fresh ID after restart.
+     */
+    readonly usedKeyFingerprints: readonly string[];
+}
+export type ChainedCredentialAuditEvent = CredentialAuditEvent & {
+    readonly metadata: CredentialAuditMetadata & {
+        readonly sequence: number;
+        readonly profiles: readonly ["record_integrity"];
+    };
+    readonly unmapped: CredentialAuditUnmapped & {
+        readonly "centient.audit_chain.key_id": string;
+    };
+    readonly attestation_list: readonly [OcsfAttestation];
+};
+export interface CreateHmacAuditChainOptions extends AuditChainKey {
+    readonly chainId: string;
+    /** Trusted external state from the last durable event, if resuming. */
+    readonly checkpoint?: AuditChainCheckpoint;
+}
+export interface HmacAuditChain {
+    /** Append and sign one previously unchained OCSF event synchronously. */
+    append(event: CredentialAuditEvent): ChainedCredentialAuditEvent;
+    /**
+     * Switch the signing key at an emission boundary.
+     *
+     * The first later event uses the new key ID while linking to the last event
+     * produced with the old key. IDs and key material can never be reused within
+     * one chain, including after resuming from a trusted checkpoint.
+     */
+    rotate(next: AuditChainKey): void;
+    /** Latest value-free state, or `null` before the first event. */
+    checkpoint(): AuditChainCheckpoint | null;
+    /** Zero the chain's private key copy and permanently close the writer. */
+    destroy(): void;
+}
+/**
+ * RFC 8785 JSON Canonicalization Scheme for the JSON data model used by OCSF.
+ *
+ * Objects are plain data objects, names are ordered by UTF-16 code units, and
+ * strings/numbers use ECMAScript JSON serialization. Values outside I-JSON
+ * (cycles, sparse arrays, accessors, non-finite numbers, lone surrogates,
+ * `undefined`, `bigint`, functions, symbols) fail closed.
+ */
+export declare function canonicalizeAuditEvent(value: unknown): string;
+/** Create one synchronous, process-local HMAC-SHA-256 audit chain. */
+export declare function createHmacAuditChain(options: CreateHmacAuditChainOptions): HmacAuditChain;
+export type AuditChainVerificationFailureCode = "MALFORMED_EVENT" | "UNSUPPORTED_ALGORITHM" | "UNSUPPORTED_CANONICALIZATION" | "UNANCHORED_SEGMENT" | "CHAIN_ID_MISMATCH" | "INVALID_SEQUENCE" | "SEQUENCE_GAP_OR_REORDER" | "PREVIOUS_EVENT_MISMATCH" | "PREVIOUS_HASH_MISMATCH" | "UNKNOWN_KEY_ID" | "KEY_RESOLUTION_FAILED" | "INVALID_KEY" | "KEY_ID_REUSE" | "KEY_ID_MATERIAL_MISMATCH" | "KEY_MATERIAL_REUSE" | "HASH_MISMATCH" | "FINAL_CHECKPOINT_MISMATCH";
+export interface AuditChainVerificationFailure {
+    readonly code: AuditChainVerificationFailureCode;
+    readonly message: string;
+    readonly index: number;
+    readonly sequenceNumber?: number;
+}
+export type AuditChainVerificationResult = {
+    readonly ok: true;
+    readonly value: {
+        readonly verifiedCount: number;
+        readonly rotations: number;
+        readonly checkpoint: AuditChainCheckpoint | null;
+    };
+} | {
+    readonly ok: false;
+    readonly error: AuditChainVerificationFailure;
+};
+export interface VerifyAuditChainOptions {
+    /** Trusted key lookup. Returned key bytes remain owned by the resolver. */
+    readonly resolveKey: (keyId: string) => Uint8Array | undefined;
+    /** Expected chain identity, required to reject whole-chain substitution. */
+    readonly expectedChainId?: string;
+    /** Required when verification starts after the genesis event. */
+    readonly initialCheckpoint?: AuditChainCheckpoint;
+    /** External terminal anchor used to detect deletion of a chain suffix. */
+    readonly expectedFinalCheckpoint?: AuditChainCheckpoint;
+}
+/**
+ * Verify one ordered chain segment without mutating records or key material.
+ *
+ * The function returns a discriminated failure for hostile input. It requires
+ * genesis (`sequence=1`, no `prev_event`) unless a trusted initial checkpoint
+ * anchors a later segment. An optional trusted final checkpoint detects suffix
+ * deletion; no hash-chain algorithm can detect deletion of the entire log by
+ * looking only at that log.
+ */
+export declare function verifyHmacAuditChain(events: readonly unknown[], options: VerifyAuditChainOptions): AuditChainVerificationResult;
+//# sourceMappingURL=hmac-chain.d.ts.map

package/dist/audit/hmac-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac-chain.d.ts","sourceRoot":"","sources":["../../src/audit/hmac-chain.ts"],"names":[],"mappings":"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"}