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

package/dist/with-audit/portability/request-withdrawal.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Two-party withdrawal ceremony.
+ *
+ * The conservative counterpart to `unilateralWithdrawal`: a non-owner —
+ * including a read-only `client`/`viewer` who cannot self-serve a deletion —
+ * files a durable REQUEST; an owner/admin reviews it and either APPROVES
+ * (extract-and-dispose under firm authority) or REJECTS it. Every step is
+ * audited in the tamper-evident ledger.
+ *
+ *   requester:  vault.user.requestWithdrawal({ scope, disposition?, legalBasis? })
+ *   owner:      vault.user.listWithdrawalRequests()
+ *               vault.user.approveWithdrawal(requestId, { reKey })  → { bundle, snapshot? }
+ *               vault.user.rejectWithdrawal(requestId, { reason })
+ *
+ * Requests live in the reserved `_user_withdrawal_requests` namespace. The
+ * record body is plaintext metadata (collection names + disposition + legal
+ * basis — none secret in this trust model; the owner sees the data anyway) and
+ * carries NO passphrase: the re-key passphrase is supplied by the approver at
+ * approval time and conveyed to the requester out-of-band, so no secret is
+ * stored at rest.
+ */
+import type { Vault } from '../../kernel/vault.js';
+import { NoydbError } from '../../kernel/errors.js';
+import { type WithdrawResult } from './withdraw-accessible.js';
+export declare const WITHDRAWAL_REQUESTS_COLLECTION = "_user_withdrawal_requests";
+/** Raised when a request is missing, already decided, or expired. */
+export declare class WithdrawalRequestError extends NoydbError {
+    constructor(message: string);
+}
+export type WithdrawalRequestStatus = 'pending' | 'approved' | 'rejected';
+export interface WithdrawalRequest {
+    readonly requestId: string;
+    readonly requester: string;
+    readonly collections: readonly string[];
+    readonly disposition: 'delete' | 'freeze';
+    readonly legalBasis?: string;
+    readonly status: WithdrawalRequestStatus;
+    readonly requestedAt: string;
+    readonly expiresAt?: string;
+    readonly decidedAt?: string;
+    readonly decidedBy?: string;
+    readonly rejectReason?: string;
+    readonly snapshotSha256?: string;
+}
+export interface RequestWithdrawalOptions {
+    readonly scope?: {
+        readonly collections?: readonly string[];
+    };
+    readonly disposition?: 'delete' | 'freeze';
+    readonly legalBasis?: string;
+    /** Time-to-live in ms; after this the request can no longer be approved. */
+    readonly expiresInMs?: number;
+}
+export interface RequestWithdrawalResult {
+    readonly requestId: string;
+    readonly status: WithdrawalRequestStatus;
+    readonly expiresAt?: string;
+}
+/**
+ * Requester side. Files a durable request for the caller's accessible scope.
+ * Gated by `user-request-withdrawal` (checked in the UserApi wrapper).
+ */
+export declare function requestWithdrawal(vault: Vault, opts?: RequestWithdrawalOptions): Promise<RequestWithdrawalResult>;
+/** Owner side. List filed requests (optionally by status). */
+export declare function listWithdrawalRequests(vault: Vault, opts?: {
+    status?: WithdrawalRequestStatus;
+}): Promise<WithdrawalRequest[]>;
+export interface ApproveWithdrawalOptions {
+    /** Re-key the handed-back bundle to a passphrase the requester will use. */
+    readonly reKey?: {
+        readonly passphrase: string;
+    };
+}
+/**
+ * Owner side. Extract the requester's recorded scope under firm authority,
+ * dispose of the source per the request's disposition, mark the request
+ * approved, and return the re-keyed bundle to hand back. Gated by
+ * `approve-user-withdrawal` (checked in the UserApi wrapper) + owner/admin role.
+ */
+export declare function approveWithdrawal(vault: Vault, requestId: string, opts?: ApproveWithdrawalOptions): Promise<WithdrawResult>;
+export interface RejectWithdrawalOptions {
+    readonly reason?: string;
+}
+/** Owner side. Decline a pending request (no data is touched). */
+export declare function rejectWithdrawal(vault: Vault, requestId: string, opts?: RejectWithdrawalOptions): Promise<WithdrawalRequest>;

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

@@ -0,0 +1,31 @@
+/**
+ * Portability capability strategy — the six on-demand data-sovereignty methods
+ * the vault's `UserApi` routes through (`exportAccessibleData` /
+ * `withdrawAccessibleData` / `requestWithdrawal` / `listWithdrawalRequests` /
+ * `approveWithdrawal` / `rejectWithdrawal`). The active engine
+ * ({@link withPortability}) dynamically imports the export/withdraw/request
+ * cores (keeping them reachable only via opt-in); {@link NO_PORTABILITY} throws.
+ * The Vault always injects the closures the UserApi calls; they delegate here,
+ * so an un-opted-in caller hits `NO_PORTABILITY`'s throw.
+ * @internal
+ */
+import type { Vault } from '../../kernel/vault.js';
+import type { ExportAccessibleOptions } from './export-accessible.js';
+import type { WithdrawAccessibleOptions, WithdrawResult } from './withdraw-accessible.js';
+import type { RequestWithdrawalOptions, RequestWithdrawalResult, WithdrawalRequest, WithdrawalRequestStatus, ApproveWithdrawalOptions, RejectWithdrawalOptions } from './request-withdrawal.js';
+export interface PortabilityStrategy {
+    exportAccessibleData(vault: Vault, opts: ExportAccessibleOptions): Promise<Uint8Array>;
+    withdrawAccessibleData(vault: Vault, opts: WithdrawAccessibleOptions): Promise<WithdrawResult>;
+    requestWithdrawal(vault: Vault, opts: RequestWithdrawalOptions): Promise<RequestWithdrawalResult>;
+    listWithdrawalRequests(vault: Vault, opts: {
+        status?: WithdrawalRequestStatus;
+    }): Promise<WithdrawalRequest[]>;
+    approveWithdrawal(vault: Vault, requestId: string, opts: ApproveWithdrawalOptions): Promise<WithdrawResult>;
+    rejectWithdrawal(vault: Vault, requestId: string, opts: RejectWithdrawalOptions): Promise<WithdrawalRequest>;
+}
+/**
+ * No-op stub — the floor default. Every capability method throws
+ * {@link PortabilityNotEnabledError}; opt in with
+ * `portabilityStrategy: withPortability()` in createNoydb. @internal
+ */
+export declare const NO_PORTABILITY: PortabilityStrategy;

package/dist/with-audit/portability/withdraw-accessible.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `unilateralWithdrawal`: a non-owner extracts their accessible scope
+ * AND disposes of the source copy. Destructive; gated by the default-off
+ * fail-closed built-in `client-unilateral-withdraw` policy (checked in the
+ * UserApi wrapper).
+ *
+ * Two source dispositions:
+ *  - 'delete'  — delete-closure: the records leave the source vault entirely.
+ *  - 'freeze'  — the firm retains a cryptographically-frozen, read-only, write-once
+ *                snapshot (hash-pinned in the tamper-evident ledger) while the live
+ *                records are removed.
+ *
+ * Ordering guarantees no data loss: the client's re-keyed export bundle (and the
+ * freeze snapshot) are produced BEFORE anything is deleted.
+ *
+ * The `freezeAndDeleteClosure` core is shared with the two-party approval path
+ * (`request-withdrawal.ts`).
+ */
+import type { Vault } from '../../kernel/vault.js';
+export declare const FROZEN_SNAPSHOTS_COLLECTION = "_frozen_snapshots";
+/** 24-hex-char random id (used for withdrawal ids + request ids). */
+export declare function randomId(): string;
+export interface FrozenSnapshotRef {
+    readonly withdrawalId: string;
+    readonly sha256: string;
+    readonly recordCount: number;
+    readonly frozenAt: string;
+}
+export interface WithdrawAccessibleOptions {
+    /** Legal/contractual basis recorded in the audit (e.g. 'gdpr-art-17'). */
+    readonly legalBasis: string;
+    /** Re-key the exported bundle to a new owner passphrase. */
+    readonly reKey?: {
+        readonly passphrase: string;
+    };
+    /** Source disposition. Default 'delete'. */
+    readonly disposition?: 'delete' | 'freeze';
+    readonly scope?: {
+        readonly collections?: readonly string[];
+    };
+    /** Stable id for idempotent resume (default random). */
+    readonly withdrawalId?: string;
+}
+export interface WithdrawResult {
+    readonly bundle: Uint8Array;
+    readonly snapshot?: FrozenSnapshotRef;
+}
+/**
+ * Freeze a write-once, hash-pinned snapshot of the current ciphertext for
+ * `collections` WITHOUT touching the live records. Returns the snapshot ref.
+ *
+ * This is the non-destructive core shared by two callers:
+ *  - `freezeAndDeleteClosure` (withdrawal, disposition `'freeze'`) — which
+ *    pins the snapshot and THEN delete-closures the live records.
+ *  - FR-6 `liberateVault` (custody) — which pins a PRE-liberation evidence
+ *    snapshot but PRESERVES the live data for the new owner (operational
+ *    continuity; liberation transfers, it does not erase).
+ *
+ * The snapshot put is write-once (CAS expectedVersion 0) and the ledger pin is
+ * appended on success, so a crashed run re-run with the same `withdrawalId` is
+ * safe. The snapshot is taken under the vault's own firm-owned DEKs — no re-key.
+ */
+export declare function freezeSnapshotOnly(vault: Vault, collections: readonly string[], opts: {
+    actorUserId: string;
+    withdrawalId?: string;
+}): Promise<FrozenSnapshotRef>;
+/**
+ * Dispose of the source records for `collections`: optionally freeze a
+ * write-once hash-pinned snapshot of the original ciphertext, then
+ * delete-closure the live records. Returns the snapshot ref on freeze.
+ *
+ * Caller MUST have produced the portable bundle FIRST — this is destructive.
+ * The delete is best-effort + idempotent (re-deleting an absent record is a
+ * no-op) and the snapshot put is write-once (CAS expectedVersion 0), so a
+ * crashed run re-run with the same `withdrawalId` is safe.
+ */
+export declare function freezeAndDeleteClosure(vault: Vault, collections: readonly string[], opts: {
+    disposition: 'delete' | 'freeze';
+    actorUserId: string;
+    withdrawalId?: string;
+}): Promise<FrozenSnapshotRef | undefined>;
+export declare function withdrawAccessibleData(vault: Vault, opts: WithdrawAccessibleOptions): Promise<WithdrawResult>;

package/dist/with-audit/sealed-record/active.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Enable the sealed-record (grantor-side) capability.
+ * Pass to `createNoydb({ sealedRecordStrategy: withSealedRecord() })` to make a
+ * vault's `sealRecordToHost` / `revokeSealedRecord` / `rotateRecordCek` methods
+ * live. The `record-keys` grantor engine is dynamically imported here, so it is
+ * reached only via opt-in.
+ */
+import type { SealedRecordStrategy } from './strategy.js';
+export declare function withSealedRecord(): SealedRecordStrategy;

package/dist/with-audit/sealed-record/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `@noy-db/hub/sealed-record` — host-side opener for record-scoped CEK
+ * sealing.
+ *
+ * The **grantor** side (sealing a record's CEK to a host, revoking, and hard
+ * rotation) lives on `Vault` (`vault.sealRecordToHost` /
+ * `vault.revokeSealedRecord` / `vault.rotateRecordCek`) because it needs the
+ * collection DEK. This subpath exposes the **recipient host** side:
+ * {@link openSealedRecord} reconstructs a single record's plaintext from
+ * (a) the sealed-CEK delivery envelope, (b) the record's encrypted envelope
+ * body, and (c) the host's own unsealer — and **nothing else**. The host never
+ * touches a vault DEK and can decrypt exactly the one bound record.
+ *
+ * @module
+ */
+import type { SealedCekDeliveryEnvelope } from './types.js';
+export type { SealedCekDeliveryEnvelope, SealedCekBinding } from './types.js';
+export { SealedRecordExpiredError, SealedRecordMismatchError } from '../../kernel/errors.js';
+export { withSealedRecord } from './active.js';
+export { NO_SEALED_RECORD, type SealedRecordStrategy } from './strategy.js';
+export { SealedRecordNotEnabledError } from '../../kernel/errors.js';
+/**
+ * Host-side: decrypt a single record whose CEK was sealed to this host by a
+ * vault grantor via `vault.sealRecordToHost()`.
+ *
+ * Verification order (security-critical — do NOT reorder past the unseal):
+ *  1. **Fast-path expiry** — reject on the delivery envelope's clear-text
+ *     `expiresAt` before doing any (potentially expensive) unseal work. This is
+ *     a hint only.
+ *  2. **Unseal** the `payload` with the host's `recipientSealer.unseal` →
+ *     parse the {@link SealedCekBinding}.
+ *  3. **Binding match** — the binding's `{collection, id}` MUST equal the
+ *     expected pair, else {@link SealedRecordMismatchError}. This is the
+ *     host-denial boundary (a CEK sealed for record A cannot open record B).
+ *  4. **Authoritative expiry** — re-check `binding.expiresAt` (the copy that
+ *     cannot be forged by editing the delivery envelope), else
+ *     {@link SealedRecordExpiredError}.
+ *  5. **Decrypt** the record body under the unsealed CEK. A CEK from a
+ *     PRE-rotation seal applied to a POST-rotation live envelope passes (1)-(4)
+ *     but fails the AES-GCM auth tag → `TamperedError` from `decrypt`.
+ *
+ * @param sealedCekEnvelope The `SealedCekDeliveryEnvelope` written by the grantor.
+ * @param recordEnvelope    The record's `{ _iv, _data }` (the encrypted body).
+ * @param recipientSealer   The host's unsealer (`{ unseal(bytes) }`) — e.g. a
+ *                          KMS-backed sealer or `MemoryRecipientSealer`.
+ * @param expectedCollection Collection the caller believes `recordEnvelope` is in.
+ * @param expectedId         Record id the caller believes `recordEnvelope` is.
+ * @returns The decrypted record body as a JSON string.
+ */
+export declare function openSealedRecord(sealedCekEnvelope: SealedCekDeliveryEnvelope, recordEnvelope: {
+    readonly _iv: string;
+    readonly _data: string;
+}, recipientSealer: {
+    unseal(bytes: Uint8Array): Promise<Uint8Array>;
+}, expectedCollection: string, expectedId: string): Promise<string>;

package/dist/with-audit/sealed-record/strategy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sealed-record (grantor-side) capability strategy — the three on-demand vault
+ * methods the record-scoped CEK sealing surface routes through. The active
+ * engine ({@link withSealedRecord}) dynamically imports the `record-keys`
+ * grantor cores (keeping them reachable only via opt-in); {@link NO_SEALED_RECORD}
+ * throws. The vault always assembles the per-call {@link SealingContext} and
+ * delegates here, so an un-opted-in caller hits `NO_SEALED_RECORD`'s throw.
+ *
+ * Note: the recipient-host opener (`openSealedRecord`) is a pure decrypt
+ * function exported from this subpath and is NOT gated — it runs on a remote
+ * host with no `createNoydb` instance (the same way the attestation verifier
+ * stays ungated). Only the vault-side grantor operations are the capability.
+ * @internal
+ */
+import type { SealingContext } from '../../kernel/enclave/index.js';
+import type { RecipientSealer } from '../../with-party/team/managed-passphrase.js';
+export interface SealedRecordStrategy {
+    sealRecordToHost(ctx: SealingContext, collection: string, id: string, hostSealer: RecipientSealer, opts: {
+        expiresAt: string;
+    }): Promise<{
+        pid: string;
+        envelopeKey: string;
+    }>;
+    revokeSealedRecord(ctx: SealingContext, collection: string, id: string, pid: string, opts?: {
+        hard?: boolean;
+    }): Promise<void>;
+    rotateRecordCek(ctx: SealingContext, collection: string, id: string): Promise<void>;
+}
+/**
+ * No-op stub — the floor default. Every grantor method throws
+ * {@link SealedRecordNotEnabledError}; opt in with
+ * `sealedRecordStrategy: withSealedRecord()` in createNoydb. @internal
+ */
+export declare const NO_SEALED_RECORD: SealedRecordStrategy;

package/dist/with-audit/sealed-record/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wire + binding types for record-scoped CEK sealing.
+ *
+ * A vault owner who holds the collection DEK can **seal a single record's
+ * content-encryption key (CEK)** to an `at-*` host (e.g. a KMS-backed
+ * {@link RecipientSealer}) so that host — and only that host — can decrypt
+ * exactly that one record, with no access to the vault DEK and no ability to
+ * read any other record. This is the record-granular counterpart to the
+ * bundle-granular sealed-credential delivery (`SealedEnvelope`).
+ *
+ * Two shapes live here:
+ *
+ *  - {@link SealedCekDeliveryEnvelope} — the **thin delivery envelope** the
+ *    grantor writes to `_sealed_cek/<collection>/<id>/<pid>`. It carries only
+ *    routing metadata (`pid`, `expiresAt`) in the clear plus the opaque sealed
+ *    `payload`. The `expiresAt` here is a *fast-path* hint; the authoritative
+ *    expiry lives INSIDE the sealed payload (see below).
+ *
+ *  - {@link SealedCekBinding} — the plaintext struct that is sealed for the
+ *    host. It binds the CEK to its `{collection, id}` and an authoritative
+ *    `expiresAt`, so a host cannot take a CEK sealed for record A and apply it
+ *    to record B's envelope (mismatch is rejected), nor read past expiry. The
+ *    binding is the security boundary; the delivery envelope is just transport.
+ *
+ * @module
+ */
+export type { SealedCekDeliveryEnvelope, SealedCekBinding } from '../../kernel/types.js';

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

@@ -0,0 +1,9 @@
+/**
+ * Enable the hierarchical-tiers capability.
+ * Pass to `createNoydb({ tiersStrategy: withTiers() })` to make a collection's
+ * `putAtTier` / `getAtTier` / `listAtTier` / `elevate` / `demote` methods live.
+ * The tier read/write/re-key engine is dynamically imported here, so it stays
+ * out of the floor bundle until opted in.
+ */
+import type { TiersStrategy } from './strategy.js';
+export declare function withTiers(): TiersStrategy;