@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/walk-SVNDIZ62.js

@@ -0,0 +1,241 @@
+import {
+  jsonSchemaToFields
+} from "./chunk-VYYM3MEN.js";
+import {
+  derivePersistedSchema
+} from "./chunk-W22IKJE2.js";
+import {
+  loadPersistedSchema
+} from "./chunk-VZRODIM3.js";
+import "./chunk-XDYREZWE.js";
+import "./chunk-7DSTRQIJ.js";
+import "./chunk-HB3RFQSC.js";
+import "./chunk-JKJOGPZN.js";
+import "./chunk-5M5DVGV7.js";
+import "./chunk-LP7BEXCT.js";
+import "./chunk-CIE2BASH.js";
+import "./chunk-JNAI2HN2.js";
+import "./chunk-BIOUI4HL.js";
+import "./chunk-PZ5AY32C.js";
+
+// src/with-shape/introspection/walk.ts
+var INTERNAL_PREFIX = "_";
+var KNOWN_INTERNAL_NAMES = ["_keyring", "_ledger", "_meta", "_schemas", "_deltas"];
+async function dumpVaultSchema(vault, opts) {
+  const state = vault._introspectState();
+  const sampleSize = opts.sampleSize ?? 50;
+  const withStats = opts.withStats === true;
+  const cacheNames = [...state.collectionCache.keys()];
+  const storageNames = (await safeListAllCollections(state.adapter, state.name)).filter((n) => !n.startsWith(INTERNAL_PREFIX));
+  const allNames = Array.from(/* @__PURE__ */ new Set([...cacheNames, ...storageNames])).sort();
+  const collections = {};
+  for (const name of allNames) {
+    collections[name] = await describeCollection(state, name, sampleSize, withStats);
+  }
+  const materializedViews = describeMVs(state.mvRegistry);
+  const overlayViews = describeOverlays(state.overlayRegistry);
+  const derivations = describeDerivations(state.derivationRegistry);
+  let internal;
+  if (withStats) {
+    internal = {};
+    for (const name of KNOWN_INTERNAL_NAMES) {
+      const stats = await statsForCollection(state.adapter, state.name, name);
+      if (stats.records > 0) {
+        internal[name] = { records: stats.records, bytes: stats.bytes };
+      }
+    }
+  }
+  const snap = {
+    _noydb_snapshot: 1,
+    vault: state.name,
+    emittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    subsystems: state.subsystems,
+    ...state.vaultMeta !== void 0 ? { meta: state.vaultMeta } : {},
+    collections,
+    materializedViews,
+    overlayViews,
+    derivations,
+    ...internal !== void 0 ? { internal } : {}
+  };
+  return snap;
+}
+async function safeListAllCollections(adapter, vault) {
+  try {
+    const snap = await adapter.loadAll(vault);
+    return Object.keys(snap);
+  } catch {
+    return [];
+  }
+}
+async function describeCollection(state, collectionName, sampleSize, withStats) {
+  let fields = {};
+  let validator;
+  const refsRaw = state.refRegistry.getOutbound(collectionName);
+  const refs = {};
+  for (const [name, desc] of Object.entries(refsRaw)) {
+    refs[name] = { target: desc.target, mode: desc.mode };
+  }
+  try {
+    const dek = await state.getDEK(collectionName);
+    const persisted = await loadPersistedSchema(state.adapter, state.name, collectionName, dek);
+    if (persisted) {
+      validator = { kind: persisted.kind, source: "persisted" };
+      if (persisted.jsonSchema) {
+        fields = jsonSchemaToFields(persisted.jsonSchema, "persisted", refsRaw);
+      }
+    }
+  } catch {
+  }
+  const liveColl = state.collectionCache.get(collectionName);
+  if (!validator) {
+    const schema = liveColl?.getSchema();
+    if (schema) {
+      try {
+        const derived = await derivePersistedSchema(schema);
+        validator = { kind: derived.kind, source: "live-validator" };
+        if (derived.jsonSchema) {
+          fields = jsonSchemaToFields(derived.jsonSchema, "live-validator", refsRaw);
+        }
+      } catch {
+      }
+    }
+  }
+  if (Object.keys(fields).length === 0 && sampleSize > 0) {
+  }
+  const collMeta = liveColl?.getMeta();
+  const collConfig = liveColl?.getConfig();
+  const archivePresent = state.hasCollectionArchive?.(collectionName) === true;
+  const schemaUpdateNames = state.getCollectionSchemaUpdateNames?.(collectionName);
+  const hasSchemaUpdate = schemaUpdateNames !== void 0 && schemaUpdateNames.length > 0;
+  let mergedConfig;
+  if (collConfig !== void 0 || archivePresent || hasSchemaUpdate) {
+    mergedConfig = {
+      ...collConfig ?? {},
+      ...archivePresent ? { archive: true } : {},
+      ...hasSchemaUpdate ? { schemaUpdate: schemaUpdateNames } : {}
+    };
+  }
+  const descriptor = {
+    fields,
+    indexes: [],
+    refs,
+    ...validator ? { validator } : {},
+    ...collMeta !== void 0 ? { meta: collMeta } : {},
+    ...mergedConfig !== void 0 ? { config: mergedConfig } : {}
+  };
+  if (withStats) {
+    const stats = await statsForCollection(state.adapter, state.name, collectionName);
+    descriptor.stats = stats;
+  }
+  return descriptor;
+}
+async function statsForCollection(adapter, vault, collection) {
+  const ids = await adapter.list(vault, collection);
+  if (ids.length === 0) {
+    return { records: 0, bytes: 0, bytesAvg: 0, bytesMin: 0, bytesMax: 0, oldest: "", newest: "" };
+  }
+  let total = 0;
+  let min = Number.POSITIVE_INFINITY;
+  let max = 0;
+  let oldest = "\uFFFF";
+  let newest = "";
+  for (const id of ids) {
+    const env = await adapter.get(vault, collection, id);
+    if (!env) continue;
+    const size = env._data.length;
+    total += size;
+    if (size < min) min = size;
+    if (size > max) max = size;
+    if (env._ts < oldest) oldest = env._ts;
+    if (env._ts > newest) newest = env._ts;
+  }
+  return {
+    records: ids.length,
+    bytes: total,
+    bytesAvg: Math.round(total / ids.length),
+    bytesMin: min === Number.POSITIVE_INFINITY ? 0 : min,
+    bytesMax: max,
+    oldest: oldest === "\uFFFF" ? "" : oldest,
+    newest
+  };
+}
+function describeMVs(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const items = listFromRegistry(registry);
+  const out = {};
+  for (const item of items) {
+    const reg = item;
+    const spec = reg.spec;
+    if (!spec?.name) continue;
+    const sources = spec.unionSources ? spec.unionSources.map((u) => u.collection) : reg.dependencies ? [...reg.dependencies].sort() : [];
+    const groupBy = spec.groupBy ? Array.isArray(spec.groupBy) ? [...spec.groupBy] : [spec.groupBy] : void 0;
+    const aggregate = spec.aggregate ? Object.fromEntries(
+      Object.entries(spec.aggregate).map(([k, v]) => [k, summariseAggregateOp(v)])
+    ) : void 0;
+    out[spec.name] = {
+      sources,
+      ...groupBy ? { groupBy } : {},
+      ...aggregate ? { aggregate } : {},
+      refresh: spec.refresh ?? "eager"
+    };
+  }
+  return out;
+}
+function describeOverlays(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const specs = listFromRegistry(registry);
+  const out = {};
+  for (const spec of specs) {
+    const s = spec;
+    if (!s.name || !s.base || !s.overlay) continue;
+    out[s.name] = { base: s.base, overlay: s.overlay };
+  }
+  return out;
+}
+function describeDerivations(registry) {
+  if (!registry || typeof registry !== "object") return {};
+  const items = listFromRegistry(registry);
+  const out = {};
+  for (const item of items) {
+    const reg = item;
+    const s = reg.spec ?? reg;
+    if (!s.source) continue;
+    const outputCollections = s.outputs ? Object.values(s.outputs).map((o) => o.collection) : [];
+    const key = outputCollections.length > 0 ? [...outputCollections].sort().join("+") : s.source;
+    out[key] = {
+      source: s.source,
+      outputs: outputCollections
+    };
+  }
+  return out;
+}
+function listFromRegistry(reg) {
+  for (const method of ["all", "list", "specs", "values"]) {
+    const fn = reg[method];
+    if (typeof fn === "function") {
+      try {
+        const out = fn.call(reg);
+        if (Array.isArray(out)) return out;
+        if (out && typeof out.values === "function") {
+          return [...out.values()];
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return [];
+}
+function summariseAggregateOp(value) {
+  if (value && typeof value === "object") {
+    const op = value.op ?? value.kind;
+    const field = value.field;
+    if (op && field) return `${op}(${field})`;
+    if (op) return op;
+  }
+  return String(value);
+}
+export {
+  dumpVaultSchema
+};
+//# sourceMappingURL=walk-SVNDIZ62.js.map

package/dist/with/index.js

@@ -6,18 +6,18 @@ import {
   assertCanImport,
   canExport,
   canImport
-} from "../chunk-QABECTNN.js";
-import "../chunk-TUL5YQWF.js";
-import "../chunk-FZK3JJJK.js";
-import "../chunk-7TAV3BFQ.js";
-import "../chunk-PVC2FBCQ.js";
-import "../chunk-5UOPIPZC.js";
-import "../chunk-UWZ7O4NR.js";
-import "../chunk-REWTMYSF.js";
-import "../chunk-VFQOE76I.js";
+} from "../chunk-6QTNZJBS.js";
+import "../chunk-J2ZX2XUV.js";
+import "../chunk-4JBYV75E.js";
+import "../chunk-XDYREZWE.js";
+import "../chunk-7DSTRQIJ.js";
+import "../chunk-HB3RFQSC.js";
+import "../chunk-JKJOGPZN.js";
+import "../chunk-5M5DVGV7.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-5HZULLHE.js";
-import "../chunk-OJ64XMPJ.js";
+import "../chunk-CIE2BASH.js";
+import "../chunk-JNAI2HN2.js";
+import "../chunk-BIOUI4HL.js";
 import "../chunk-PZ5AY32C.js";
 export {
   ServiceBus,

package/dist/with-audit/attestation/active.d.ts

@@ -0,0 +1,10 @@
+import type { AttestationStrategy } from './strategy.js';
+/**
+ * Enable the attestation capability.
+ * Pass to `createNoydb({ attestationStrategy: withAttestation() })` to make the
+ * vault's `issueAttestation` / `getDocumentSigningPublicKey` / `revokeAttestation`
+ * / `unrevokeAttestation` / `getRevokedDocIds` / `publishRevocationList` methods
+ * live. The issue/revoke/signer engines are dynamically imported here, so they
+ * stay out of the floor bundle until opted in.
+ */
+export declare function withAttestation(): AttestationStrategy;

package/dist/with-audit/attestation/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @category capability
+ * Document attestation — issue side. Mint a signed, per-field commitment
+ * for a record and emit a QR credential verifiable offline via
+ * `@noy-db/attestation`. See docs/superpowers/specs/2026-05-29-attestation-core-and-issue-design.md.
+ */
+export { withAttestation } from './active.js';
+export { NO_ATTESTATION, type AttestationStrategy } from './strategy.js';
+export { AttestationNotEnabledError } from '../../kernel/errors.js';
+export { issueAttestationCore } from './issue.js';
+export type { IssueContext, IssueArgs, IssueResult } from './issue.js';
+export { ATTESTATIONS_COLLECTION } from './signer.js';
+export { revokeDocCore, unrevokeDocCore, getRevokedDocIdsCore, publishRevocationListCore } from './revoke.js';
+export type { RevokeContext } from './revoke.js';
+export { AttestationError } from '../../kernel/errors.js';
+export { verifyAttestation, decodeQr, verifyRevocationList, isRevoked, signRevocationList, type QrPayload, type AttestationFieldSchema, type VerifyResult, type VerifyInput, type RevocationList } from '@noy-db/attestation';

package/dist/with-audit/attestation/issue.d.ts

@@ -0,0 +1,29 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type AttestationFieldSchema, type QrPayload } from '@noy-db/attestation';
+/** Everything issueAttestationCore needs from the Vault, injected for testability. */
+export interface IssueContext {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly role: string;
+    /** The _attestations collection DEK (AES-KW-wrapped under KEK by the keyring). */
+    getDEK(): Promise<EnclaveKey>;
+    /** Decrypted source record + its envelope version, or null if absent. */
+    readRecord(collection: string, id: string): Promise<{
+        record: Record<string, unknown>;
+        version: number;
+    } | null>;
+}
+export interface IssueArgs {
+    readonly collection: string;
+    readonly id: string;
+    readonly fieldSchema: AttestationFieldSchema;
+}
+export interface IssueResult {
+    readonly docId: string;
+    readonly qr: string;
+    readonly payload: QrPayload;
+    readonly keyId: string;
+    readonly publicKeyB64: string;
+}
+export declare function issueAttestationCore(ctx: IssueContext, args: IssueArgs): Promise<IssueResult>;

package/dist/with-audit/attestation/revoke.d.ts

@@ -0,0 +1,15 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type RevocationList } from '@noy-db/attestation';
+/** Everything the revoke core needs from the Vault, injected for testability. */
+export interface RevokeContext {
+    readonly store: NoydbStore;
+    readonly vault: string;
+    readonly role: string;
+    /** The _attestations collection DEK. */
+    getDEK(): Promise<EnclaveKey>;
+}
+export declare function revokeDocCore(ctx: RevokeContext, docId: string): Promise<void>;
+export declare function unrevokeDocCore(ctx: RevokeContext, docId: string): Promise<void>;
+export declare function getRevokedDocIdsCore(ctx: RevokeContext): Promise<string[]>;
+export declare function publishRevocationListCore(ctx: RevokeContext): Promise<RevocationList>;

package/dist/with-audit/attestation/signer.d.ts

@@ -0,0 +1,33 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+export declare const ATTESTATIONS_COLLECTION = "_attestations";
+export declare const SIGNER_RECORD_ID = "_signer";
+export declare const REVOKED_RECORD_ID = "_revoked";
+export interface DocSigner {
+    readonly keyId: string;
+    readonly publicKeyB64: string;
+    readonly privateKeyPkcs8B64: string;
+}
+/**
+ * Pure read: return the firm's persisted document-signing keypair, or `null`
+ * if none has been minted yet. Never writes — callers that must NOT mint
+ * (e.g. an ungated public-key getter) use this instead of `loadOrCreateSigner`.
+ *
+ * Stored as an encrypted record `_attestations/_signer` under the
+ * `_attestations` collection DEK (resolved via `getDEK`, which is
+ * AES-KW-wrapped under the owner KEK + persisted by the keyring). The KEK
+ * itself is AES-KW-only and cannot AES-GCM-encrypt these bytes — hence
+ * storage under a normal collection DEK.
+ */
+export declare function loadSigner(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<DocSigner | null>;
+/**
+ * Lazily mint (or load) the firm's Ed25519 document-signing keypair.
+ *
+ * On a concurrent first-mint, two callers can both read `null` and both mint
+ * distinct keypairs. The `put(…, expectedVersion: 0)` ("must not already
+ * exist") lets exactly one win; the loser catches `ConflictError`, re-reads,
+ * and returns the winner's signer — converging on a single keypair rather than
+ * clobbering it or surfacing a raw conflict. (All real stores treat a missing
+ * record + `ev: 0` as a no-conflict write, so the catch fires on lost-race only.)
+ */
+export declare function loadOrCreateSigner(store: NoydbStore, vault: string, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<DocSigner>;

package/dist/with-audit/attestation/strategy.d.ts

@@ -0,0 +1,44 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { RevocationList } from '@noy-db/attestation';
+import type { IssueContext, IssueArgs, IssueResult } from './issue.js';
+import type { RevokeContext } from './revoke.js';
+/**
+ * Deps the signing-public-key lookup needs. Unlike issue/revoke there is no
+ * per-call context object for it, so the vault facade assembles this at call
+ * time (reading `role` fresh).
+ */
+export interface SignerLookupDeps {
+    readonly adapter: NoydbStore;
+    readonly vault: string;
+    /** The invoking keyring's role, read fresh by the caller per call. */
+    readonly role: string;
+    /** Per-collection DEK resolver (bound `vault.getDEK`). */
+    readonly getDEK: (collection: string) => Promise<EnclaveKey>;
+}
+/**
+ * Attestation capability strategy — the six on-demand methods the vault's
+ * attestation delegators route through. The active engine ({@link withAttestation})
+ * dynamically imports the issue/revoke/signer cores (keeping them out of the floor
+ * bundle); {@link NO_ATTESTATION} throws. The vault-side {@link VaultAttestation}
+ * facade holds the per-collection field-schema registry and builds the per-call
+ * contexts, then delegates here.
+ * @internal
+ */
+export interface AttestationStrategy {
+    issueAttestation(ctx: IssueContext, args: IssueArgs): Promise<IssueResult>;
+    getDocumentSigningPublicKey(deps: SignerLookupDeps): Promise<{
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    revokeAttestation(ctx: RevokeContext, docId: string): Promise<void>;
+    unrevokeAttestation(ctx: RevokeContext, docId: string): Promise<void>;
+    getRevokedDocIds(ctx: RevokeContext): Promise<string[]>;
+    publishRevocationList(ctx: RevokeContext): Promise<RevocationList>;
+}
+/**
+ * No-op stub — the floor default. Every capability method throws
+ * {@link AttestationNotEnabledError}; opt in with
+ * `attestationStrategy: withAttestation()` in createNoydb. @internal
+ */
+export declare const NO_ATTESTATION: AttestationStrategy;

package/dist/with-audit/attestation/vault-facade.d.ts

@@ -0,0 +1,62 @@
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { AttestationFieldSchema, RevocationList } from '@noy-db/attestation';
+import type { AttestationStrategy } from './strategy.js';
+export { NO_ATTESTATION, type AttestationStrategy } from './strategy.js';
+/** Everything the moving attestation methods touched on the vault's `this.*`. */
+export interface VaultAttestationDeps {
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** Vault namespace name. */
+    readonly vault: string;
+    /** Per-collection DEK resolver (bound `vault.getDEK`). */
+    readonly getDEK: (collection: string) => Promise<EnclaveKey>;
+    /** The invoking keyring's role (read fresh per call). */
+    role(): string;
+    /** Decrypt a collection record at `locale: 'raw'` (issue side reads the live record). */
+    getRawRecord(collection: string, id: string): Promise<Record<string, unknown> | null>;
+}
+export declare class VaultAttestation {
+    private readonly deps;
+    /**
+     * Opt-in capability gate. `NO_ATTESTATION` when
+     * `createNoydb({ attestationStrategy })` was omitted — every issue/revoke/
+     * signer call then throws `AttestationNotEnabledError`. The facade always
+     * exists (it holds the per-collection field-schema registry populated at
+     * `collection()` time); only the capability methods are gated.
+     */
+    private readonly strategy;
+    /**
+     * Per-collection attestation field-schema (issue side). Populated on
+     * `collection({ attestation })` via {@link register} and read by
+     * {@link issue}. Indexed by collection name.
+     */
+    private readonly registry;
+    constructor(deps: VaultAttestationDeps, 
+    /**
+     * Opt-in capability gate. `NO_ATTESTATION` when
+     * `createNoydb({ attestationStrategy })` was omitted — every issue/revoke/
+     * signer call then throws `AttestationNotEnabledError`. The facade always
+     * exists (it holds the per-collection field-schema registry populated at
+     * `collection()` time); only the capability methods are gated.
+     */
+    strategy: AttestationStrategy);
+    /** Register a collection's attestation field-schema (from `vault.collection`). */
+    register(collection: string, schema: AttestationFieldSchema): void;
+    issue(collectionName: string, id: string): Promise<{
+        docId: string;
+        qr: string;
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    getDocumentSigningPublicKey(): Promise<{
+        keyId: string;
+        publicKeyB64: string;
+    }>;
+    private makeIssueContext;
+    revoke(docId: string): Promise<void>;
+    unrevoke(docId: string): Promise<void>;
+    getRevokedDocIds(): Promise<string[]>;
+    publishRevocationList(): Promise<RevocationList>;
+    private makeRevokeContext;
+}

package/dist/with-audit/consent/active.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Active consent strategy. Calling `withConsent()` returns a
+ * `ConsentStrategy` that delegates to the real
+ * `writeConsentEntry` / `loadConsentEntries` functions. Only
+ * reachable through the `@noy-db/hub/consent` subpath.
+ */
+import type { ConsentStrategy } from './strategy.js';
+/**
+ * Build the default consent strategy. Pass into
+ * `createNoydb({ consentStrategy: withConsent() })` to enable
+ * per-operation audit writes into the reserved `_consent_audit`
+ * collection.
+ */
+export declare function withConsent(): ConsentStrategy;

package/dist/with-audit/consent/consent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Consent boundaries — per-access audit log.
+ *
+ * ```ts
+ * const audit = await vault.withConsent(
+ *   { purpose: 'quarterly-review', consentHash: '7f3a...' },
+ *   async () => {
+ *     const invoices = await vault.collection<Invoice>('invoices').list()
+ *     return invoices
+ *   },
+ * )
+ *
+ * const log = await vault.consentAudit({ since: '2026-01-01T00:00:00Z' })
+ * // → entries: { actor, purpose, consentHash, ts, op, collection, id }
+ * ```
+ *
+ * ## Contract
+ *
+ * Every `get` / `put` / `delete` that happens inside a `withConsent`
+ * callback writes one entry to the reserved `_consent_audit`
+ * collection. Entries are encrypted with the vault's consent-audit
+ * DEK (separate from per-user-collection DEKs so access-log queries
+ * don't require unwrapping individual collection keys). Outside a
+ * `withConsent` scope, no entries are written — consent is
+ * opt-in by design (GDPR Art. 7: *demonstrable*, *specific*
+ * consent).
+ *
+ * ## Why store the hash, not the consent text?
+ *
+ * The `consentHash` is the sha256 of whatever consent receipt the
+ * actor presented (a signed GDPR banner click, a HIPAA authorisation
+ * PDF, an API-level `X-Consent-Hash` header). Storing only the hash:
+ *
+ *   1. Keeps the audit log small and indexable.
+ *   2. Preserves zero-knowledge at the adapter — adapters see
+ *      ciphertext envelopes of `{ actor, purpose, consentHash, ts,
+ *      op, collection, id }`, never the consent record itself.
+ *   3. Lets the regulator verify a presented consent doc matches
+ *      the logged hash at audit time without the system ever
+ *      possessing the doc.
+ *
+ * ## Concurrency
+ *
+ * The consent context lives on the {@link Vault} instance. Two
+ * concurrent `withConsent` calls on the same Vault would stomp each
+ * other — documented limitation; adopters needing per-flight scope
+ * should use separate Vault instances or an AsyncLocalStorage shim.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/** Reserved collection for consent-audit entries. */
+export declare const CONSENT_AUDIT_COLLECTION = "_consent_audit";
+/**
+ * The consent scope active for a block of work. Set via
+ * `vault.withConsent()`; observed by the collection's access hooks.
+ */
+export interface ConsentContext {
+    /**
+     * What this access is for. Used by the audit query (`consentAudit
+     * ({ purpose })`) and carried in the stored entry. Free-form; the
+     * regulator or compliance tooling decides the vocabulary.
+     */
+    readonly purpose: string;
+    /**
+     * Hex-encoded sha256 of whatever consent artefact the actor
+     * presented. Stored as-is in each entry.
+     */
+    readonly consentHash: string;
+}
+/**
+ * Access operation recorded in an audit entry.
+ *
+ * Union-widening checklist (I-2) — these three sites widen together or a
+ * downstream exhaustive switch breaks at its next in-range minor:
+ *   1. `ConsentOp` here (public, re-exported at `index.ts`).
+ *   2. `onAccess` op union on `kernel/collection-config.ts`.
+ *   3. classified ctx `onAccess` op union on `port/with/classified-strategy.ts`
+ *      (the `ClassifiedVerifyCtx` one — the `ClassifiedRevealCtx` one stays `'reveal'`-only).
+ */
+export type ConsentOp = 'get' | 'put' | 'delete' | 'reveal' | 'verify' | 'find';
+/** One consent-audit record, as decrypted for the caller. */
+export interface ConsentAuditEntry {
+    /** ULID — stable insertion-order key. */
+    readonly id: string;
+    readonly timestamp: string;
+    readonly actor: string;
+    readonly purpose: string;
+    readonly consentHash: string;
+    readonly op: ConsentOp;
+    readonly collection: string;
+    readonly recordId: string;
+}
+/** Filter passed to `vault.consentAudit()`. */
+export interface ConsentAuditFilter {
+    /** Only entries at or after this ISO timestamp. */
+    readonly since?: string;
+    /** Only entries at or before this ISO timestamp. */
+    readonly until?: string;
+    /** Match entries targeting this collection. */
+    readonly collection?: string;
+    /** Match entries written by this actor. */
+    readonly actor?: string;
+    /** Match entries with this purpose. */
+    readonly purpose?: string;
+}
+/**
+ * Write one audit entry. Called by Vault's onAccess hook when a
+ * consent context is active.
+ */
+export declare function writeConsentEntry(adapter: NoydbStore, vault: string, encrypted: boolean, entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>, getDEK: (collection: string) => Promise<EnclaveKey>): Promise<void>;
+/** Load + decrypt + filter all entries. */
+export declare function loadConsentEntries(adapter: NoydbStore, vault: string, encrypted: boolean, getDEK: (collection: string) => Promise<EnclaveKey>, filter?: ConsentAuditFilter): Promise<ConsentAuditEntry[]>;

package/dist/with-audit/consent/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @noy-db/hub/consent — opt-in consent-audit service.
+ *
+ * @category capability
+ *
+ * Records per-operation consent entries into a reserved
+ * `_consent_audit` collection when a consent scope is active.
+ * Applications that don't need GDPR-style audit trails can omit this
+ * subpath and skip the ~194 LOC.
+ */
+export { withConsent } from './active.js';
+export type { ConsentStrategy } from './strategy.js';
+export { CONSENT_AUDIT_COLLECTION, writeConsentEntry, loadConsentEntries, } from './consent.js';
+export type { ConsentContext, ConsentOp, ConsentAuditEntry, ConsentAuditFilter, } from './consent.js';

package/dist/with-audit/consent/strategy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Strategy seam for the optional consent-audit service. Core
+ * imports `ConsentStrategy` as a TYPE-ONLY symbol and `NO_CONSENT`
+ * as a tiny runtime stub.
+ *
+ * `writeConsentEntry` / `loadConsentEntries` are only reachable from
+ * `withConsent()` in `./active.ts`, exported through
+ * `@noy-db/hub/consent`. Applications without a consent scope ship
+ * none of the ~194 LOC.
+ *
+ * @internal
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import type { ConsentAuditEntry, ConsentAuditFilter } from './consent.js';
+/**
+ * @internal
+ */
+export interface ConsentStrategy {
+    /**
+     * Record one consent audit entry. No-op under NO_CONSENT.
+     */
+    write(adapter: NoydbStore, vault: string, encrypted: boolean, entry: Omit<ConsentAuditEntry, 'id' | 'timestamp'>, getDEK: (collectionName: string) => Promise<EnclaveKey>): Promise<void>;
+    /**
+     * Read filtered consent entries. Returns `[]` under NO_CONSENT.
+     */
+    read(adapter: NoydbStore, vault: string, encrypted: boolean, getDEK: (collectionName: string) => Promise<EnclaveKey>, filter?: ConsentAuditFilter): Promise<ConsentAuditEntry[]>;
+}
+/**
+ * No-consent stub. `write` is a no-op (returns a resolved promise);
+ * `read` returns `[]`. Consumers get a consistent API surface without
+ * pulling the consent module into the bundle.
+ *
+ * @internal
+ */
+export declare const NO_CONSENT: ConsentStrategy;