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

package/dist/with-party/team/recovery.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Recovery profile persistence + dispatch.
+ *
+ * Wires the **paper** profile end-to-end through
+ * `@noy-db/on-recovery`. The other three profiles (Shamir,
+ * multi-channel, admin-mediated) ship the API surface and throw
+ * {@link RecoveryProfileNotImplementedError} during use; per-profile
+ * dispatch lands in follow-up issues.
+ *
+ * Storage layout:
+ *
+ * ```
+ * _meta/recovery-paper       — JSON { entries: RecoveryCodeEntry[] } produced by `on-recovery`.
+ * _meta/recovery-shamir      — reserved
+ * _meta/recovery-multi       — reserved
+ * _meta/recovery-admin       — reserved
+ * ```
+ *
+ * Like `_meta/policy` and `_meta/handle`, the documents are plain JSON
+ * with empty `_iv` — the recovery-code wrapping is what protects the
+ * KEK; the entries themselves are inert without the user's code.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { EnclaveKey } from '../../kernel/enclave/index.js';
+import { type WrappedDeksBlob } from './wrapped-deks.js';
+import type { ShamirRecoveryProvider } from './shamir-recovery-provider.js';
+/**
+ * One paper recovery code as persisted in `_meta/recovery-paper`.
+ *
+ * The hub's KEK is intentionally non-extractable (see `crypto.ts`),
+ * so the recovery entry can't AES-KW-wrap the KEK directly. Instead
+ * we wrap a serialized DEK set: the entry holds the AES-GCM
+ * ciphertext of `{ deks: { collection: rawDekBase64 } }`. Recovery
+ * deserializes the DEK set, then mints a fresh KEK from the new
+ * passphrase and rewraps the DEKs under it.
+ *
+ * This is the same pattern `@noy-db/on-pin` uses for tier-3 quick
+ * resume — the cryptographic guarantee is identical (AES-GCM with a
+ * PBKDF2-derived key), and it sidesteps the non-extractable-KEK
+ * constraint cleanly.
+ *
+ * Type-level composition: `PaperRecoveryEntry extends
+ * WrappedDeksBlob` — the three crypto fields (`salt`, `iv`,
+ * `wrappedDeks`) come from the shared primitive; `codeId` and
+ * `enrolledAt` are paper-recovery's own metadata. Wire format
+ * unchanged.
+ */
+export interface PaperRecoveryEntry extends WrappedDeksBlob {
+    readonly codeId: string;
+    readonly enrolledAt: string;
+}
+export interface PaperRecoveryDoc {
+    readonly _noydb_recovery: 1;
+    readonly profile: 'paper';
+    readonly entries: ReadonlyArray<PaperRecoveryEntry>;
+}
+/** Read the paper-recovery entries. Returns empty array when absent. */
+export declare function loadPaperRecoveryEntries(store: NoydbStore, vault: string): Promise<ReadonlyArray<PaperRecoveryEntry>>;
+/** Replace the paper-recovery entries (used after burn-on-recovery). */
+export declare function savePaperRecoveryEntries(store: NoydbStore, vault: string, entries: ReadonlyArray<PaperRecoveryEntry>): Promise<void>;
+/** Drop a single paper-recovery entry (burn-on-use). */
+export declare function burnPaperRecoveryEntry(store: NoydbStore, vault: string, codeId: string): Promise<void>;
+/** Whether at least one recovery profile has any enrolled entries. */
+export declare function hasRecoveryEnrolled(store: NoydbStore, vault: string): Promise<boolean>;
+/**
+ * Whether at least one **strong** recovery profile is enrolled.
+ *
+ * "Strong" excludes paper-alone — under managed-passphrase mode the
+ * user has no memorized passphrase, so a stolen/lost paper sheet
+ * would be a single point of total loss. Strong profiles today:
+ *
+ *   - `shamir` (k-of-n threshold; survives loss of up to n-k shares)
+ *   - `multi-channel` (when shipped — follow-up slice)
+ *   - `admin-mediated` (when shipped — follow-up slice)
+ *
+ * Managed mode requires this check to pass before `openVault` returns.
+ */
+export declare function hasStrongRecoveryEnrolled(store: NoydbStore, vault: string): Promise<boolean>;
+/**
+ * One Shamir-recovery entry as persisted in `_meta/recovery-shamir`.
+ *
+ * Like {@link PaperRecoveryEntry}, the entry composes
+ * {@link WrappedDeksBlob} (DEKs wrapped under a fresh ephemeral
+ * recovery secret) with profile-specific metadata. Unlike paper, the
+ * "credential" was never visible to the user — it was 32 random
+ * bytes split into N Shamir shares at enrollment. The shares ARE
+ * the credential; the user holds them, the hub never sees them
+ * again after `enrollRecovery` returns.
+ *
+ * The recovery secret is base64-encoded and
+ * passed as the `credential` arg to
+ * {@link mintWrappedDeksBlob} / {@link unwrapDeksFromBlob}. The
+ * PBKDF2 round over high-entropy input is harmless overhead — it
+ * keeps the shared primitive unchanged while letting Shamir reuse
+ * the same wrapping pipeline as paper.
+ */
+export interface ShamirRecoveryEntry extends WrappedDeksBlob {
+    /** Stable id for this entry. Allows multiple Shamir splits to coexist. */
+    readonly entryId: string;
+    /** Threshold — minimum shares to reconstruct. */
+    readonly k: number;
+    /** Total shares minted at enrollment. */
+    readonly n: number;
+    /** x-coordinates of the n minted shares. Informational. Omitted as of 0.2
+     *  (string-level provider doesn't expose share x-coords); kept optional so
+     *  pre-0.2 entries still read. */
+    readonly xCoords?: ReadonlyArray<number>;
+    /** ISO timestamp. */
+    readonly enrolledAt: string;
+    /** Optional caller-supplied label (e.g., "2-of-3 board escrow"). */
+    readonly label?: string;
+}
+export interface ShamirRecoveryDoc {
+    readonly _noydb_recovery: 1;
+    readonly profile: 'shamir';
+    readonly entries: ReadonlyArray<ShamirRecoveryEntry>;
+}
+/** Read the Shamir-recovery entries. Returns empty array when absent. */
+export declare function loadShamirRecoveryEntries(store: NoydbStore, vault: string): Promise<ReadonlyArray<ShamirRecoveryEntry>>;
+/** Replace the Shamir-recovery entries (used by enrollment and rotation). */
+export declare function saveShamirRecoveryEntries(store: NoydbStore, vault: string, entries: ReadonlyArray<ShamirRecoveryEntry>): Promise<void>;
+/**
+ * Mint a fresh Shamir recovery entry from a DEK set.
+ *
+ * 1. Generates a 32-byte recovery secret.
+ * 2. Wraps the DEK set under that secret via
+ *    {@link mintWrappedDeksBlob} (the recovery secret is base64-
+ *    encoded as the credential string — PBKDF2 over high-entropy
+ *    input is harmless overhead).
+ * 3. Splits the recovery secret via Shamir into `n` shares with
+ *    threshold `k`.
+ * 4. Zeros the in-memory recovery secret after wrapping + splitting.
+ *
+ * Returns:
+ *   - `entry` — the {@link ShamirRecoveryEntry} to persist.
+ *   - `shareStrings` — the `n` Base32-encoded share strings to
+ *     return to the caller. The HUB MUST NOT PERSIST THESE; once
+ *     returned they are the user's responsibility.
+ *
+ * @param deks - DEK set to wrap.
+ * @param entryId - Stable id for this entry (caller-supplied or
+ *                  hub-generated).
+ * @param k - Threshold (>= 2).
+ * @param n - Total shares (k <= n <= 255).
+ * @param label - Optional caller label.
+ */
+export declare function mintShamirRecoveryEntry(provider: ShamirRecoveryProvider, deks: Map<string, EnclaveKey>, entryId: string, k: number, n: number, label?: string): Promise<{
+    entry: ShamirRecoveryEntry;
+    shareStrings: string[];
+}>;
+/**
+ * Decrypt a Shamir recovery entry to recover the raw DEK set.
+ *
+ * Combines K or more `shares`, reconstructs the recovery secret,
+ * unwraps the DEKs via {@link unwrapDeksFromBlob}.
+ *
+ * Throws (AES-GCM auth-tag mismatch) when the shares don't combine
+ * to the secret originally used to mint the entry — typically
+ * because they came from a different enrollment or were tampered
+ * with. Callers iterating multiple entries should catch.
+ */
+export declare function unwrapDeksFromShamirEntry(provider: ShamirRecoveryProvider, entry: ShamirRecoveryEntry, shareStrings: readonly string[]): Promise<Map<string, EnclaveKey>>;
+/**
+ * Generate one paper-recovery entry from an unlocked DEK set.
+ *
+ * Returns the serializable entry (persisted via
+ * {@link savePaperRecoveryEntries}). The recovery flow unwraps the
+ * DEK set, then mints a fresh KEK from the user's new passphrase.
+ *
+ * Thin wrapper over {@link mintWrappedDeksBlob} — the crypto
+ * lives in the shared primitive; this function just adds paper-
+ * recovery's own metadata (`codeId`, `enrolledAt`).
+ *
+ * @param deks      Map of collection-name → DEK (extractable).
+ * @param code      The plaintext recovery code (caller-supplied;
+ *                  pair this with `@noy-db/on-recovery`'s code
+ *                  generator/parser if available).
+ * @param codeId    Stable id used by `burnPaperRecoveryEntry`.
+ */
+export declare function mintPaperRecoveryEntry(deks: Map<string, EnclaveKey>, code: string, codeId: string): Promise<PaperRecoveryEntry>;
+/**
+ * Decrypt a recovery entry to recover the raw DEK set. Used by the
+ * `recoverPassphrase` flow after the user's code has been parsed.
+ *
+ * Thin wrapper over {@link unwrapDeksFromBlob}.
+ *
+ * @throws when the code does not match the entry (AES-GCM auth tag fail).
+ */
+export declare function unwrapDeksFromPaperEntry(entry: PaperRecoveryEntry, code: string): Promise<Map<string, EnclaveKey>>;

package/dist/with-party/team/reserved-secret-collections.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Secret-bearing reserved collections — the `_`-prefixed reserved collections
+ * whose record CONTENTS are directly-usable secrets (transport OAuth tokens,
+ * connection strings, API keys), as opposed to the *operational* reserved
+ * collections (`_ledger`, `_history`, `_sync`, …) whose contents are metadata
+ * (collection names, record ids, ciphertext hashes).
+ *
+ * This distinction matters at two trust-boundary seams:
+ *
+ *  1. `vault.collection()` — a secret-bearing reserved name must never be
+ *     reachable through the generic public collection handle. It is served
+ *     ONLY by its dedicated, role-gated API (e.g. `_sync_credentials` →
+ *     `getCredential`/`putCredential`, which enforce owner/admin access).
+ *
+ *  2. `grant()` DEK propagation — a sub-admin grantee (operator, viewer,
+ *     client, custodian) must NOT receive a secret-bearing collection's DEK.
+ *     Operational reserved DEKs still propagate to every role (grantees must
+ *     write ledger/history entries on every mutation), but handing a
+ *     sub-admin the `_sync_credentials` DEK would let them decrypt the firm's
+ *     transport secrets — a plaintext leak, not a metadata leak.
+ *
+ * Kept dependency-free so both the kernel (`vault.ts`) and the team layer
+ * (`keyring.ts`) can import it without an import cycle.
+ */
+/** Reserved collection holding per-adapter sync transport secrets. */
+export declare const SYNC_CREDENTIALS_COLLECTION = "_sync_credentials";
+/**
+ * Reserved (pre-allocated) name for the future credential broker (#479).
+ * Not yet implemented — reserved now so that neither the public collection
+ * handle nor grant propagation can ever expose it before its dedicated,
+ * role-gated API lands.
+ */
+export declare const BROKER_COLLECTION = "_broker";
+/**
+ * The set of reserved collection names whose record contents are
+ * directly-usable secrets. Membership here means: never served via
+ * `vault.collection()`, never propagated to sub-admin grantees.
+ */
+export declare const SECRET_BEARING_RESERVED_COLLECTIONS: ReadonlySet<string>;
+/** True when `name` is a secret-bearing reserved collection. */
+export declare function isSecretBearingReservedCollection(name: string): boolean;

package/dist/with-party/team/rotate-recover.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Tier-1 change flows — `rotatePassphrase` (user remembers old) and
+ * `recoverPassphrase` (user supplies a recovery proof).
+ *
+ * The two flows share the post-verification half — fresh salt, fresh
+ * KEK, rewrap every DEK — and differ only in how they re-derive the
+ * old KEK:
+ *
+ * - **Rotate**: derive from the supplied `oldPassphrase`.
+ * - **Recover (paper)**: unwrap from a `RecoveryCodeEntry` using a
+ *   user-supplied recovery code. The entry is burned on success.
+ *
+ * The non-paper recovery profiles (Shamir, multi-channel,
+ * admin-mediated) are not yet wired — calling them throws
+ * {@link RecoveryProfileNotImplementedError} with a tracking link.
+ *
+ * @module
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+import { type PaperRecoveryEntry } from './recovery.js';
+import type { ShamirRecoveryProvider } from './shamir-recovery-provider.js';
+import { type PassphrasePolicy } from '../../kernel/validation.js';
+import type { UnlockedKeyring } from './keyring.js';
+import type { KeyringAuthenticator } from '../../kernel/types.js';
+import type { EnrollAuthenticatorOptions } from './authenticators.js';
+/**
+ * Context handed to a {@link SlotRewrapCeremony} when `rotatePassphrase`
+ * preserves a tier-2 slot. The ceremony's job is to re-derive its
+ * method-specific wrapping material (PRF assertion, PBKDF2 of the
+ * password, etc.) and wrap the freshly rewrapped DEK set under
+ * the new wrapping key.
+ *
+ * Two surfaces are exposed:
+ *
+ *   - `newDeks` — the rewrapped (extractable) DEK set the slot will
+ *     wrap. This is what `mintPaperRecoveryEntry` / `enrollPassword-
+ *     Authenticator` / `wrapKeyringSummary` (in `@noy-db/on-webauthn`)
+ *     all consume; effectively the canonical input for every
+ *     post-Path C tier-2 ceremony.
+ *
+ *   - `newKek` — the freshly-derived KEK (extractable for the
+ *     ceremony scope only). Only relevant for forward-compatibility
+ *     with a hypothetical future on-* package that wants to wrap the
+ *     KEK itself under a method-derived key. None of the shipped
+ *     on-* packages need this; they all operate on `newDeks`.
+ *
+ * The ceremony MUST preserve `oldSlot.id` and `oldSlot.method` in the
+ * returned `EnrollAuthenticatorOptions`. Hub validates these — a
+ * mismatch throws `ValidationError` (prevents slot-type swap mid-
+ * rotation, e.g. converting a webauthn slot to a password slot under
+ * cover of preservation).
+ */
+export interface SlotRewrapContext {
+    readonly newKek: EnclaveKey;
+    readonly newDeks: Map<string, EnclaveKey>;
+    readonly oldSlot: KeyringAuthenticator;
+}
+/**
+ * Callback that re-enrolls one tier-2 slot during `rotatePassphrase`.
+ * Returns the new slot's `EnrollAuthenticatorOptions` — same shape
+ * the consumer would pass to `db.enrollAuthenticator` for a fresh
+ * enrollment. Hub persists the result atomically with the rotation.
+ */
+export type SlotRewrapCeremony = (ctx: SlotRewrapContext) => Promise<EnrollAuthenticatorOptions>;
+/** Caller payload for {@link rotatePassphrase}. */
+export interface RotatePassphraseInput {
+    readonly oldPassphrase: string;
+    readonly newPassphrase: string;
+    readonly passphrasePolicy?: PassphrasePolicy;
+    readonly allowWeakPassphrase?: boolean;
+    /**
+     * Map of slot id → re-enrolment ceremony. Slots whose id appears
+     * here are PRESERVED across rotation (the ceremony re-derives the
+     * method-specific wrapping under the new keyring); slots whose id
+     * is absent are DROPPED (the pre-slot-ceremony behavior).
+     *
+     * Without this map, `rotatePassphrase` wipes every tier-2 slot. Consumers building a
+     * "rotate without losing my biometric" flow supply ceremonies for
+     * each slot they want to keep.
+     *
+     * If a ceremony throws, the entire rotation throws — no partial
+     * state. Callers wrap individual ceremonies in try/catch + return
+     * a sentinel if they want graceful degradation per slot.
+     *
+     * Added when slot-ceremony rewrapping landed.
+     */
+    readonly slotCeremonies?: {
+        readonly [slotId: string]: SlotRewrapCeremony;
+    };
+}
+/**
+ * Re-derive the user's KEK from `oldPassphrase`, rewrap every DEK
+ * under a freshly-derived KEK from `newPassphrase`, and persist.
+ *
+ * Tier-2 authenticator slots are dropped UNLESS the caller supplies
+ * a `slotCeremonies` map — each ceremony re-derives its
+ * method-specific wrapping under the new keyring, and hub persists
+ * the rewrapped slots atomically with the rotation. Slots whose id
+ * isn't in the map are still dropped.
+ *
+ * @throws `InvalidKeyError` if `oldPassphrase` does not unwrap the keyring.
+ * @throws `WeakPassphraseError` if `newPassphrase` fails the strength rule.
+ * @throws `ValidationError` if a ceremony's result mismatches the
+ *         slot's id or method (anti-slot-swap guard).
+ */
+export declare function rotatePassphrase(store: NoydbStore, vault: string, userId: string, input: RotatePassphraseInput): Promise<UnlockedKeyring>;
+/**
+ * Caller payload for {@link recoverPassphrase}.
+ *
+ * `paper` and `shamir` are wired end-to-end.
+ * The remaining two profiles (`multi-channel`, `admin-mediated`)
+ * stay outside the union and throw
+ * {@link RecoveryProfileNotImplementedError} at the runtime guard
+ * when bypassed via `as unknown as RecoveryProof`.
+ */
+export type RecoveryProof = {
+    readonly profile: 'paper';
+    readonly payload: {
+        readonly code: string;
+    };
+} | {
+    readonly profile: 'shamir';
+    readonly payload: {
+        /** Optional disambiguator when multiple Shamir entries are enrolled.
+         *  When omitted, hub tries each entry until one combines. */
+        readonly entryId?: string;
+        /** K or more opaque share strings, as returned by `ShamirRecoveryProvider.splitToShares`. */
+        readonly shares: ReadonlyArray<string>;
+    };
+};
+export interface RecoverPassphraseInput {
+    readonly newPassphrase: string;
+    readonly recoveryProof: RecoveryProof;
+    readonly passphrasePolicy?: PassphrasePolicy;
+    readonly allowWeakPassphrase?: boolean;
+    /**
+     * After a successful paper-recovery, replace ALL remaining recovery
+     * entries with freshly-minted ones. Defaults to `true` (defensive).
+     *
+     * Rationale: the user just demonstrated they had access
+     * to AT LEAST one code. The remaining codes from the same printed
+     * sheet may also be compromised — photographed, leaked via a
+     * screen-share slip, or in the hands of whoever stole the sheet.
+     * Auto-rotation closes the window without requiring consumer action.
+     *
+     * Set to `false` to preserve the original behavior (only the matched
+     * code is burned; the rest stay valid).
+     *
+     * Hub-side orchestration is non-atomic with the recovery itself:
+     * if the rotation step fails after a successful burn, the user
+     * falls back to the pre-rotation state (remaining codes still
+     * valid). Strictly safer than the previous default — a failed
+     * rotation degrades gracefully rather than leaving the vault
+     * locked or codes dual-existing.
+     */
+    readonly rotateRemainingCodes?: boolean;
+    /**
+     * Number of fresh codes to mint when `rotateRemainingCodes` is on.
+     * Defaults to the count of remaining entries POST-burn (e.g. if
+     * the user enrolled 8 originally and just consumed 1, defaults to
+     * 7). Pass an explicit number to mint a different count — useful
+     * when the consumer wants to refresh to a target N regardless of
+     * how many were left.
+     */
+    readonly newCodeCount?: number;
+    /**
+     * Override the default raw-code generator. The default is hub's
+     * {@link generateULID} — uppercase Crockford-Base32, 26 chars,
+     * passes through `normalizePaperCode` untouched.
+     *
+     * Pass `() => generateRawCode()` from `@noy-db/on-recovery` when
+     * the consumer prefers the Base32 + checksum format with hyphenated
+     * display. The `mintPaperRecoveryEntry` helper accepts any string —
+     * the generator just needs to produce a high-entropy unique value.
+     */
+    readonly codeGenerator?: () => string;
+}
+/**
+ * Return shape of `db.recoverPassphrase`. `newCodes` is populated when
+ * `rotateRemainingCodes` was enabled and at least one entry was
+ * rotated; an empty array means no rotation happened (rotation
+ * disabled, or no remaining codes after burn). Show the codes to the
+ * user once — they are the canonical credential for future recovery
+ * and CANNOT be retrieved again.
+ */
+export interface RecoverPassphraseResult {
+    readonly newCodes: readonly string[];
+}
+/**
+ * Input for {@link Noydb.rotateRecovery} — deliberate
+ * recovery-credential regeneration when the user knows their
+ * passphrase but wants a fresh sheet (paper) or fresh shares
+ * (shamir). Symmetric to {@link RotatePassphraseInput}.
+ */
+export type RotateRecoveryOptions = {
+    readonly profile: 'paper';
+    /** How many fresh codes to mint. Default: existing sheet size. */
+    readonly count?: number;
+    /** Optional code generator — see {@link RecoverPassphraseInput.codeGenerator}. */
+    readonly codeGenerator?: () => string;
+} | {
+    readonly profile: 'shamir';
+    /** New threshold. */
+    readonly k: number;
+    /** New total share count. */
+    readonly n: number;
+    /** Disambiguator when multiple Shamir entries exist; required if there are 2+. */
+    readonly entryId?: string;
+    /** Optional updated label. */
+    readonly label?: string;
+};
+/**
+ * Result of {@link Noydb.rotateRecovery}. Shape varies by profile:
+ *
+ * - `paper` → `{ newCodes: string[] }` (and `entryId === 'paper-batch'`)
+ * - `shamir` → `{ newShares: string[], entryId }`
+ *
+ * `newCodes` is populated for paper rotations; `newShares` for
+ * Shamir rotations. Both are show-once — the hub does not
+ * retain them.
+ */
+export interface RotateRecoveryResult {
+    readonly newCodes?: readonly string[];
+    readonly newShares?: readonly string[];
+    readonly entryId?: string;
+}
+/**
+ * Result of {@link Noydb.enrollRecovery}. Shape varies by profile:
+ *
+ * - `paper` → `{ entryId: 'paper-batch' }` (caller minted the
+ *   entries; this is a sentinel since paper enrollments are batch-shaped).
+ * - `shamir` → `{ entryId, shares: string[] }` — shares are
+ *   show-once; the hub does not retain them.
+ */
+export interface EnrollRecoveryResult {
+    readonly entryId: string;
+    readonly shares?: readonly string[];
+}
+/**
+ * Input shape for {@link Noydb.enrollRecovery} and
+ * {@link Noydb.openVaultAndEnrollRecovery}. Discriminated
+ * union over recovery profiles.
+ *
+ * - `paper`: caller pre-mints entries (typically via
+ *   `mintPaperRecoveryEntry` or `@noy-db/on-recovery`'s
+ *   `generateRecoveryCodeSet`) and passes them in. The hub stores
+ *   them and surfaces an opaque batch id.
+ * - `shamir`: hub mints the recovery secret + the shares at
+ *   enrollment time. The shares are returned in
+ *   {@link EnrollRecoveryResult.shares} (show-once); the hub never
+ *   retains them.
+ *
+ * Multi-channel and admin-mediated will be added when the respective
+ * dispatch slices ship.
+ */
+export type RecoveryEnrollmentInput = {
+    readonly profile: 'paper';
+    readonly entries: ReadonlyArray<PaperRecoveryEntry>;
+} | {
+    readonly profile: 'shamir';
+    readonly k: number;
+    readonly n: number;
+    readonly label?: string;
+    readonly entryId?: string;
+};
+/**
+ * Reset the user's passphrase using a recovery proof.
+ * Supports `'paper'` and `'shamir'` profiles. The other profiles throw
+ * {@link RecoveryProfileNotImplementedError}.
+ *
+ * On success, the used recovery entry is burned (deleted from the
+ * stored set).
+ */
+export declare function recoverPassphrase(provider: ShamirRecoveryProvider | undefined, store: NoydbStore, vault: string, userId: string, input: RecoverPassphraseInput): Promise<UnlockedKeyring>;

package/dist/with-party/team/shamir-recovery-provider.d.ts

@@ -0,0 +1,15 @@
+/**
+ * String-level Shamir provider injected into hub for `profile: 'shamir'`
+ * recovery. Keeps hub free of any `@noy-db/on-shamir` import — hub never
+ * sees `RawShare` or the share codecs. Implemented by
+ * `shamirRecoveryProvider()` from `@noy-db/on-shamir`.
+ */
+export interface ShamirRecoveryProvider {
+    /** Split `secret` into `n` base32 share strings; any `k` recombine it. */
+    splitToShares(secret: Uint8Array, k: number, n: number): string[];
+    /**
+     * Recombine `k`+ share strings into the secret. MUST throw on malformed,
+     * truncated, insufficient, or mismatched shares.
+     */
+    combineShares(shares: readonly string[]): Uint8Array;
+}

package/dist/with-party/team/strategy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Service-side shim for the team strategy seam (#267). The contract itself
+ * lives on the `/with` port (`src/port/with/team-strategy.ts`) so the
+ * kernel spine can hold the `NO_TEAM` floor default without a
+ * spine→service static import (the port-layering rule). This file keeps
+ * the conventional `<service>/{strategy,active,index}.ts` layout.
+ * @internal
+ */
+export { NO_TEAM, type TeamStrategy } from '../../port/with/team-strategy.js';

package/dist/with-party/team/sync-active.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Active sync strategy — `withSync()` returns the real implementation
+ * that wires the `SyncEngine`, `SyncTransaction`, and `PresenceHandle`
+ * constructors into the Noydb / Vault / Collection hot paths.
+ *
+ * Consumers opt in by:
+ *
+ * ```ts
+ * import { createNoydb } from '@noy-db/hub'
+ * import { withSync } from '@noy-db/hub/sync'
+ *
+ * const db = await createNoydb({
+ *   store: localStore,
+ *   sync: remoteStore,
+ *   user: ...,
+ *   syncStrategy: withSync(),
+ * })
+ * ```
+ *
+ * The factory delegates to the existing `sync.ts`,
+ * `sync-transaction.ts`, and `presence.ts` modules. Splitting the
+ * import chain through this file is what lets tsup tree-shake the
+ * ~856 LOC of replication + presence machinery out of the default
+ * bundle when no `withSync()` import is present.
+ *
+ * Keyring + grant/revoke/magic-link/delegation stay in the always-on
+ * core (or tree-shake via direct named imports) — those are required
+ * for any multi-user vault, even purely local ones.
+ *
+ * @public
+ */
+import type { SyncStrategy } from './sync-strategy.js';
+export declare function withSync(): SyncStrategy;

package/dist/with-party/team/sync-credentials.d.ts

@@ -0,0 +1,113 @@
+/**
+ * _sync_credentials reserved collection —
+ *
+ * Stores per-adapter OAuth tokens (and any other long-lived sync secrets) as
+ * encrypted records inside the vault itself. Tokens are wrapped with the
+ * compartment's own DEK, live on disk as ciphertext like any other record, and
+ * are accessed only through the dedicated API in this module — never via
+ * `vault.collection('_sync_credentials')`.
+ *
+ * Design decisions
+ * ────────────────
+ *
+ * **Why a reserved collection, not a separate store?**
+ * The compartment's existing encryption stack (AES-256-GCM + collection DEK)
+ * is exactly the right primitive for protecting OAuth tokens at rest. Using a
+ * separate store would require a new encryption surface, new adapter calls,
+ * and a new backup/restore path — all of which already exist for collections.
+ *
+ * **Why not exposed as a regular collection?**
+ * The same reason `_keyring` and `_ledger` aren't: they have invariants that
+ * must be enforced (naming scheme, no cross-user leakage, no schema
+ * validation, no history/ledger writes for privacy). Routing through a
+ * dedicated API enforces those invariants.
+ *
+ * **Token lifecycle:**
+ * - `putCredential(vault, adapterId, token)` — store or overwrite
+ * - `getCredential(vault, adapterId)` — load and decrypt
+ * - `deleteCredential(vault, adapterId)` — remove
+ * - `listCredentials(vault)` — enumerate adapter IDs (not tokens)
+ *
+ * The `adapterId` is the record ID within the `_sync_credentials` collection.
+ * It should be a stable, human-readable identifier for the adapter instance
+ * (e.g. `'google-drive'`, `'dropbox'`, `'s3-prod'`).
+ *
+ * **ACL:** only `owner` and `admin` roles can read/write sync credentials.
+ * Operators, viewers, and clients cannot call this API. The check is made
+ * against the caller's keyring role at call time.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import type { UnlockedKeyring } from './keyring.js';
+/**
+ * The reserved collection name. Never collides with user collections.
+ * Canonical definition lives in `reserved-secret-collections.ts` (shared with
+ * the `vault.collection()` guard and grant DEK-propagation); re-exported here
+ * for existing consumers.
+ */
+export { SYNC_CREDENTIALS_COLLECTION } from './reserved-secret-collections.js';
+/**
+ * An OAuth/auth token stored in `_sync_credentials`.
+ *
+ * Fields mirror the OAuth2 token response shape. `customData` is an escape
+ * hatch for adapter-specific secrets (API keys, connection strings, etc.)
+ * that don't fit the OAuth2 shape.
+ */
+export interface SyncCredential {
+    /** Stable identifier for the adapter instance (e.g. 'google-drive'). */
+    readonly adapterId: string;
+    /** OAuth token type, usually 'Bearer'. */
+    readonly tokenType: string;
+    /** The access token. Expires at `expiresAt` if set. */
+    readonly accessToken: string;
+    /** Long-lived refresh token for renewing the access token. */
+    readonly refreshToken?: string;
+    /** ISO timestamp when `accessToken` expires. Absent means "no expiry". */
+    readonly expiresAt?: string;
+    /** Space-separated OAuth scopes. */
+    readonly scopes?: string;
+    /** Adapter-specific opaque data (API keys, endpoints, etc.). */
+    readonly customData?: Record<string, string>;
+}
+/**
+ * Store or overwrite a sync credential for the given adapter.
+ *
+ * The credential is encrypted with the `_sync_credentials` collection DEK
+ * (auto-generated on first use). The record ID is the `adapterId`.
+ *
+ * Requires owner or admin role.
+ */
+export declare function putCredential(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring, credential: SyncCredential): Promise<void>;
+/**
+ * Load and decrypt a sync credential for the given adapter ID.
+ *
+ * Returns `null` if no credential exists for this adapter.
+ * Requires owner or admin role.
+ */
+export declare function getCredential(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring, adapterId: string): Promise<SyncCredential | null>;
+/**
+ * Delete a sync credential by adapter ID.
+ *
+ * No-op if the credential doesn't exist. Requires owner or admin role.
+ */
+export declare function deleteCredential(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring, adapterId: string): Promise<void>;
+/**
+ * List all adapter IDs that have stored credentials.
+ *
+ * Returns only the IDs, never the credential payloads. Useful for
+ * displaying "connected adapters" in UI without decrypting tokens.
+ * Requires owner or admin role.
+ */
+export declare function listCredentials(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring): Promise<string[]>;
+/**
+ * Check whether a credential exists and whether its access token has expired.
+ *
+ * Returns `{ exists: false }` if no credential is stored, or
+ * `{ exists: true, expired: boolean }` based on the `expiresAt` field.
+ * Requires owner or admin role.
+ */
+export declare function credentialStatus(adapter: NoydbStore, vault: string, keyring: UnlockedKeyring, adapterId: string): Promise<{
+    exists: false;
+} | {
+    exists: true;
+    expired: boolean;
+}>;