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

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

@@ -0,0 +1,67 @@
+/**
+ * Strategy seam for the optional sync engine + presence service.
+ * Core imports `SyncStrategy` type-only + `NO_SYNC` stub; the real
+ * `SyncEngine`, `SyncTransaction`, and `PresenceHandle` constructors
+ * are only reachable via `withSync()` in `./sync-active.ts`.
+ *
+ * Solo apps that never configure `sync` and never call
+ * `collection.presence()` ship none of the ~856 LOC behind this seam
+ * (`sync.ts` + `sync-transaction.ts` + `presence.ts`).
+ *
+ * Note: `keyring.ts` (~746 LOC) stays in core because it's required
+ * for any multi-user vault — even single-owner vaults use a keyring
+ * to wrap the DEK. The team package's grant/revoke/magic-link/
+ * delegation modules tree-shake naturally via direct named imports.
+ *
+ * Behavior under NO_SYNC:
+ *
+ * - **buildSyncEngine** — throws. Only fires when `createNoydb({ sync })`
+ *   passes a remote target.
+ * - **buildSyncTransaction** — throws. Only fires when `db.transaction(vault)`
+ *   is called on a vault with sync configured.
+ * - **buildPresence** — throws. Only fires when user code calls
+ *   `collection.presence()`.
+ *
+ * @internal
+ */
+import type { NoydbStore, ConflictStrategy, SyncTargetRole } from '../../kernel/types.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { SyncPolicy } from '../../kernel/sync-policy.js';
+import type { SyncEngine } from './sync.js';
+import type { SyncTransaction } from './sync-transaction.js';
+import type { PresenceHandle, PresenceHandleOpts } from './presence.js';
+import type { Vault } from '../../kernel/vault.js';
+/**
+ * Options accepted by `SyncStrategy.buildSyncEngine`. Mirrors the
+ * `SyncEngine` constructor verbatim — kept here so core code never
+ * imports the sync module at runtime.
+ *
+ * @internal
+ */
+export interface BuildSyncEngineOptions {
+    local: NoydbStore;
+    remote: NoydbStore;
+    vault: string;
+    strategy: ConflictStrategy;
+    emitter: NoydbEventEmitter;
+    syncPolicy?: SyncPolicy;
+    role?: SyncTargetRole;
+    label?: string;
+}
+/**
+ * @internal
+ */
+export interface SyncStrategy {
+    buildSyncEngine(opts: BuildSyncEngineOptions): SyncEngine;
+    buildSyncTransaction(vault: Vault, engine: SyncEngine): SyncTransaction;
+    buildPresence<P>(opts: PresenceHandleOpts): PresenceHandle<P>;
+}
+/**
+ * No-sync stub. Every constructor throws with an actionable pointer
+ * — there is no useful "off" mode for sync engine / presence /
+ * sync-transaction; if the consumer reached one of these surfaces,
+ * they intended to use it.
+ *
+ * @internal
+ */
+export declare const NO_SYNC: SyncStrategy;

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

@@ -0,0 +1,39 @@
+import type { SyncTransactionResult } from '../../kernel/types.js';
+import type { SyncEngine } from './sync.js';
+import type { Vault } from '../../kernel/vault.js';
+/**
+ * Sync transaction.
+ *
+ * Stages local writes and then pushes only those records to remote in a
+ * single batch. If any record conflicts during the push, the result
+ * carries `status: 'conflict'` — no automatic rollback is performed;
+ * the caller handles conflict resolution.
+ *
+ * Obtain via `db.transaction(compartmentName)`.
+ */
+export declare class SyncTransaction {
+    private readonly comp;
+    private readonly engine;
+    private readonly ops;
+    /** @internal — constructed by `Noydb.transaction()` */
+    constructor(comp: Vault, engine: SyncEngine);
+    /** Stage a record write. Does not write to any adapter until `commit()`. */
+    put(collection: string, id: string, record: unknown): this;
+    /** Stage a record delete. Does not write to any adapter until `commit()`. */
+    delete(collection: string, id: string): this;
+    /**
+     * Commit the transaction.
+     *
+     * Phase 1 — writes all staged operations to the local adapter via the
+     * collection layer (encryption + dirty-log tracking).
+     *
+     * Phase 2 — pushes only the records that were written in this
+     * transaction to the remote adapter. Existing dirty entries from
+     * outside this transaction are not affected.
+     *
+     * If any record conflicts during the push, `status` is `'conflict'`
+     * and `conflicts` lists the affected records. No automatic rollback is
+     * performed.
+     */
+    commit(): Promise<SyncTransactionResult>;
+}

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

@@ -0,0 +1,174 @@
+import type { NoydbStore, DirtyEntry, ConflictStrategy, CollectionConflictResolver, PushOptions, PullOptions, PushResult, PullResult, SyncStatus, SyncTargetRole } from '../../kernel/types.js';
+import type { NoydbEventEmitter } from '../../kernel/events.js';
+import type { SyncPolicy } from '../../kernel/sync-policy.js';
+import { SyncScheduler } from '../../kernel/sync-policy.js';
+/** #650 Task 4 (#647) — the declared reserved-lookup (`_dict_*`/`_lookup_*`) collection-name
+ *  registry a `SyncEngine` enumerates on pull. Explicit, not a blanket underscore-glob — other
+ *  `_`-prefixed namespaces keep their `loadAll`-skip semantics untouched. */
+export interface ReservedLookupSource {
+    /** Declared reserved-lookup collection names to enumerate on pull. */
+    collections(): readonly string[];
+}
+/** Sync engine: dirty tracking, push, pull, conflict resolution, scheduling. */
+export declare class SyncEngine {
+    private readonly local;
+    private readonly remote;
+    private readonly strategy;
+    private readonly emitter;
+    private readonly vault;
+    readonly role: SyncTargetRole;
+    readonly label: string | undefined;
+    private dirty;
+    private lastPush;
+    private lastPull;
+    private loaded;
+    private autoSyncInterval;
+    private isOnline;
+    /** Sync scheduler. Manages push/pull timing. */
+    readonly scheduler: SyncScheduler | null;
+    /** Per-collection conflict resolvers registered by Collection instances. */
+    private readonly conflictResolvers;
+    /**
+     * Expands a collection-name filter to include its satellite pair partner(s)
+     * (spec #591 convergence rule 5b) — wired from vault satellite declaration
+     * via `setPairExpander`. `undefined` when no satellite has ever been
+     * declared for this vault: identity behavior, zero change for non-satellite
+     * users.
+     */
+    private pairExpander?;
+    /** #598: refreshes Collection in-memory views after a sync-applied local write. Wired by the
+     *  vault at open. `action` (#640): `'delete'` for a pulled tombstone/delete-marker, `'put'`
+     *  otherwise — classified at `applyRemote`, the one choke point that holds the envelope. */
+    private cacheInvalidator?;
+    /** Wire the Collection-cache invalidation hook (#598). Same injection pattern as `setPairExpander`. */
+    setCacheInvalidator(fn: (collection: string, id: string, action: 'put' | 'delete') => Promise<void>): void;
+    /** #638 Task 4: opens/flushes the vault's graph-dispatch touch batch around a whole `pull()`/
+     *  `push()` call, so N `applyRemote`d records feeding the same derivation/rollup/MV target
+     *  recompute once. Wired by the vault at open, mirroring `cacheInvalidator`. */
+    private graphBatchController?;
+    /** Wire the graph-dispatch batch controller (#638 Task 4). Same injection pattern as `setCacheInvalidator`. */
+    setGraphBatchController(controller: {
+        begin(): void;
+        flush(): Promise<void>;
+    }): void;
+    /** #650 Task 4 (#647): declared reserved-lookup collections `pull()` enumerates explicitly (the
+     *  store's `list()` does not skip `_`-prefixed names, unlike `loadAll()`). Wired by the vault at
+     *  open, same injection pattern as `setCacheInvalidator`/`setGraphBatchController`. */
+    private reservedLookup?;
+    /** Wire the reserved-lookup source (#650 Task 4). */
+    setReservedLookupSource(source: ReservedLookupSource): void;
+    /** #653: expands a (pair-expanded) collection-name filter to include the reserved `_dict_*`
+     *  collections those names depend on via their lookup fields — mirrors `pairExpander` so a
+     *  partial `push`/`pull({collections:[...]})` never drops the dictionary a named collection's
+     *  labels/membership rely on. Wired unconditionally from the vault's `dictKeyFieldRegistry` via
+     *  `setReservedDictExpander` (returns `[]` when the vault has no dict-backed collections); only
+     *  `undefined` on a standalone engine that was never vault-attached. */
+    private reservedDictExpander?;
+    /** Wire the reserved-dict expansion function (#653). Same injection pattern as `setPairExpander`. */
+    setReservedDictExpander(expander: (names: readonly string[]) => readonly string[]): void;
+    constructor(opts: {
+        local: NoydbStore;
+        remote: NoydbStore;
+        vault: string;
+        strategy: ConflictStrategy;
+        emitter: NoydbEventEmitter;
+        syncPolicy?: SyncPolicy;
+        role?: SyncTargetRole;
+        label?: string;
+    });
+    /** Start the sync scheduler. Called after vault is fully opened. */
+    startScheduler(): void;
+    /** Stop the sync scheduler. Called on close. */
+    stopScheduler(): void;
+    /**
+     * Register a per-collection conflict resolver.
+     * Called by Collection when `conflictPolicy` is set.
+     *
+     * Pair-coupled (#591 rule 5b): registering for one satellite-pair member
+     * registers the same resolver for both — the pair converges under one
+     * resolution policy. Expands with whatever the pair-expander knows *at this
+     * call*; resolvers registered before their pair existed are covered by
+     * `remirrorPairResolvers` at pair-registration time.
+     */
+    registerConflictResolver(collection: string, resolver: CollectionConflictResolver): void;
+    /**
+     * Wire a satellite pair-expansion function (vault registration, #591 Task 11).
+     * The closure re-reads the live `SatelliteRegistry` on every call, so pairs
+     * declared after this is set are still picked up by `push`/`pull` filters.
+     */
+    setPairExpander(expander: (names: readonly string[]) => readonly string[]): void;
+    /**
+     * Retroactively mirror per-collection conflict resolvers across a newly
+     * registered satellite pair (#591 rule 5b) — covers the NORMAL declaration
+     * order, where the base's `conflictPolicy` resolver was registered before
+     * the satellite was declared (so the call-time expansion in
+     * `registerConflictResolver` saw no pair yet). Tie-break: when BOTH members
+     * already carry (different) resolvers, the FIRST name in `names` wins —
+     * callers pass `[base, satellite]`, so the base's resolver is canonical.
+     * Idempotent; a later explicit registration on either member still
+     * overwrites both (last-wins, via the call-time expansion above).
+     */
+    remirrorPairResolvers(names: readonly string[]): void;
+    /** Record a local change for later push. */
+    trackChange(collection: string, id: string, action: 'put' | 'delete', version: number): Promise<void>;
+    /** Remove a dirty entry (satellite fan-out revert cleanup — spec #591). */
+    removeDirty(collection: string, id: string): Promise<void>;
+    /** Push dirty records to remote adapter. Accepts optional `PushOptions` for partial sync. */
+    push(options?: PushOptions): Promise<PushResult>;
+    /** Pull remote records to local adapter. Accepts optional `PullOptions` for partial sync. */
+    pull(options?: PullOptions): Promise<PullResult>;
+    /** Bidirectional sync: pull then push. */
+    sync(options?: {
+        push?: PushOptions;
+        pull?: PullOptions;
+    }): Promise<{
+        pull: PullResult;
+        push: PushResult;
+    }>;
+    /**
+     * Push a specific subset of dirty entries (for sync transactions, ).
+     * Entries are matched by collection+id from the dirty log; matched entries
+     * are removed from the dirty log on success.
+     */
+    pushFiltered(predicate: (entry: DirtyEntry) => boolean): Promise<PushResult>;
+    /** Get current sync status. */
+    status(): SyncStatus;
+    /** Start auto-sync: listen for online/offline events, optional periodic sync. */
+    startAutoSync(intervalMs?: number): void;
+    /** Stop auto-sync and scheduler. */
+    stopAutoSync(): void;
+    private handleOnline;
+    private handleOffline;
+    /** Apply an envelope to the local store and refresh in-memory views (#598). `action` (#640):
+     *  classified HERE — the one choke point that still holds the envelope — so the
+     *  cacheInvalidator seam (and, downstream, the dispatch wave) can tell a pulled delete from an
+     *  ordinary put. `isTombstoneShape` covers a forgotten-elsewhere record arriving as a shred;
+     *  `isDeleteMarker` covers an ordinary (#589) delete — both route to the SAME 'delete' action
+     *  (sync delete ≠ forget: freshness only, no shred/residue channel on the receiving side). */
+    private applyRemote;
+    /** Record + emit a tombstone enforcement (#590). */
+    private reportErasure;
+    /**
+     * Re-assert a local tombstone over a live remote envelope (#590): the shred
+     * wins in both directions, regardless of `_v`. Bumps the tombstone to the
+     * suppressed envelope's `_v` when higher so per-key version counters stay
+     * monotonic on every store; `_by` (the shredding actor) is preserved.
+     */
+    private reassertTombstone;
+    /**
+     * Resolve a conflict, checking per-collection resolvers first,
+     * then falling back to the db-level `ConflictStrategy`.
+     *
+     * Returns the resolved `Conflict` object (possibly with `resolve` set for
+     * manual mode) and a `handled` discriminant:
+     * - `'local'` — keep the local envelope; push it to remote.
+     * - `'remote'` — keep the remote envelope; update local.
+     * - `'merged'` — a custom merge fn produced a new envelope stored as `conflict.local`.
+     * - `'deferred'` — manual mode, resolve was not called synchronously.
+     */
+    private handleConflict;
+    /** DB-level ConflictStrategy resolution (legacy, kept for backward compat). */
+    private legacyResolve;
+    private ensureLoaded;
+    private persistMeta;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Hierarchical access — tier-aware keyring helpers.
+ *
+ * The keyring's existing `deks: Map<string, CryptoKey>` is keyed by
+ * collection name. extends the key space:
+ *
+ *   `'invoices'`      — tier-0 DEK (unchanged from v0.x)
+ *   `'invoices#1'`    — tier-1 DEK
+ *   `'invoices#2'`    — tier-2 DEK
+ *
+ * Tier 0 keeps the bare collection name so any keyring written
+ * before tiers existed loads without migration. Tiers ≥ 1 use `#N`
+ * suffixes that
+ * would be invalid as user-supplied collection names (see
+ * `ReservedCollectionNameError` — `#` is reserved).
+ *
+ * @module
+ */
+import type { UnlockedKeyring } from './keyring.js';
+/** Canonical DEK key for a given collection + tier. Tier 0 → bare name. */
+export declare function dekKey(collection: string, tier: number): string;
+/**
+ * Returns the user's effective clearance for a given collection: the
+ * maximum tier for which their keyring holds a DEK. Falls back to 0
+ * when the user has only the tier-0 DEK (or none — the getDEK caller
+ * will raise separately).
+ */
+export declare function effectiveClearance(keyring: UnlockedKeyring, collection: string): number;
+/**
+ * Assert the caller is cleared for the requested tier. Owners and
+ * admins always pass (they can mint any new tier DEK on demand);
+ * other roles must already hold the tier DEK — via a prior grant or
+ * an active delegation — otherwise this throws `TierNotGrantedError`.
+ *
+ * This gate runs BEFORE `getDEK()` on the mutation path so a
+ * non-cleared operator never has the opportunity to silently
+ * auto-create a tier DEK they shouldn't have.
+ */
+export declare function assertTierAccess(keyring: UnlockedKeyring, collection: string, tier: number): void;

package/dist/with-party/team/wrapped-deks.d.ts

@@ -0,0 +1,86 @@
+/**
+ * **Wrap-DEKs primitive** — a single canonical shape for the
+ * pattern of "serialize a DEK set, encrypt it under a credential-derived
+ * AES-GCM key." Used by:
+ *
+ *   - **tier-0** — paper recovery entries (`_meta/recovery-paper`),
+ *     credential = the printed code.
+ *   - **tier-2** — password authenticator slots (`KeyringFile.authenticators`,
+ *     `wrapKind: 'deks'`), credential = the user's password.
+ *
+ * **Not** used by `@noy-db/on-pin` — tier-3 wraps the DEK set under
+ * the same conceptual pattern but at **100,000 PBKDF2 iterations**
+ * (vs the 600,000 here), because the protection window for a PIN
+ * slot is short (idle-timeout-bounded, typically 15 min) and 600k
+ * iterations would make every PIN-resume noticeably slow. The wire
+ * formats are deliberately incompatible. See `@noy-db/on-pin`'s
+ * `PIN_PBKDF2_ITERATIONS` and the threat-model rationale in its
+ * module docstring.
+ *
+ * Previously, the same crypto lived in two places: `mintPaperRecoveryEntry`
+ * (in `team/recovery.ts`) and `enrollPasswordAuthenticator` (in
+ * `@noy-db/on-password`). Both functions did identical work — PBKDF2
+ * the credential, AES-GCM-encrypt the JSON-serialized DEK set — but
+ * their implementations had drifted apart enough that fixing a bug
+ * in one wouldn't fix the other.
+ *
+ * This module owns the canonical implementation. Consumers compose:
+ *
+ *   - `mintPaperRecoveryEntry` is now a thin wrapper that calls
+ *     `mintWrappedDeksBlob` and adds `{ codeId, enrolledAt }`.
+ *   - `enrollPasswordAuthenticator` calls `mintWrappedDeksBlob` and
+ *     wraps the result in the slot envelope.
+ *
+ * @module
+ */
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/**
+ * The wrap-DEKs primitive — a serialized + AES-GCM-encrypted DEK set
+ * keyed under a credential-derived key.
+ *
+ * All three fields are base64-encoded so the blob is JSON-safe and
+ * round-trips through `_meta/*` envelopes (which carry plaintext
+ * JSON in `_data`).
+ *
+ * Composition: `PaperRecoveryEntry extends WrappedDeksBlob` plus
+ * `{ codeId, enrolledAt }`. `KeyringAuthenticatorWrappingDEKs`
+ * carries the same three fields with `salt` stored in `meta` for
+ * slot-format back-compat (defers moving it to top-level).
+ */
+export interface WrappedDeksBlob {
+    /** Base64 PBKDF2 salt for the credential-derived wrapping key. */
+    readonly salt: string;
+    /** Base64 AES-GCM IV used for the `wrappedDeks` ciphertext. */
+    readonly iv: string;
+    /** Base64 AES-GCM ciphertext of `{ deks: { collection: base64rawDek } }`. */
+    readonly wrappedDeks: string;
+}
+/**
+ * Mint a fresh `WrappedDeksBlob` from a DEK set + a string credential.
+ *
+ * Generates a random salt + IV, derives a 256-bit AES-GCM key via
+ * PBKDF2-SHA256(credential, salt, 600K), serializes the DEK set as
+ * `{ deks: { coll: rawBase64 } }`, and AES-GCM-encrypts.
+ *
+ * The `credential` is the user-typed string (recovery code, password,
+ * PIN). Caller normalization rules apply (e.g. paper
+ * recovery uppercase-strips the code before reaching this function).
+ *
+ * @param deks - DEK set to wrap. Each DEK must be exportable via
+ *               `subtle.exportKey('raw', dek)` (the hub mints DEKs
+ *               this way; consumers feeding non-extractable keys
+ *               will get `InvalidAccessError` from WebCrypto).
+ * @param credential - String input the consumer minted (paper code,
+ *               password, PIN). Treated as opaque bytes by PBKDF2.
+ */
+export declare function mintWrappedDeksBlob(deks: Map<string, EnclaveKey>, credential: string): Promise<WrappedDeksBlob>;
+/**
+ * Reverse of {@link mintWrappedDeksBlob}. Re-derives the wrapping key
+ * from the credential + stored salt, AES-GCM-decrypts the wrapped DEK
+ * set, and re-imports each DEK as an extractable AES-GCM CryptoKey.
+ *
+ * Throws (AES-GCM auth tag failure) when the credential doesn't
+ * match the blob. Callers iterating over multiple blobs (e.g. paper
+ * recovery's "try every entry until one matches") should catch.
+ */
+export declare function unwrapDeksFromBlob(blob: WrappedDeksBlob, credential: string): Promise<Map<string, EnclaveKey>>;

package/dist/with-pod/backup.d.ts

@@ -0,0 +1,74 @@
+import type { NoydbStore, EncryptedEnvelope, ExportStreamOptions, ExportChunk } from '../kernel/types.js';
+import type { LedgerStore } from '../with-commit/history/ledger/store.js';
+/** Everything the moving backup methods touched on the vault's `this.*`. */
+export interface BackupContext {
+    /** The ciphertext store. */
+    readonly adapter: NoydbStore;
+    /** Vault namespace name. */
+    readonly vault: string;
+    /** The invoking keyring's user id (read fresh per call). */
+    userId(): string;
+    /** The vault's ledger store, or null when history is off. */
+    getLedgerOrNull(): LedgerStore | null;
+    /** Recompute an envelope's `payloadHash` (bound `historyStrategy.envelopePayloadHash`). */
+    envelopePayloadHash(envelope: EncryptedEnvelope): Promise<string>;
+    /**
+     * Refresh the in-memory keyring from the freshly-loaded keyring file and
+     * rebuild the DEK resolver. No-op when the vault has no `reloadKeyring`
+     * callback (plaintext vaults / test constructions).
+     */
+    reloadKeyringAndRebuildDEK(): Promise<void>;
+    /** Clear the vault's collection cache (post-load). */
+    clearCollectionCache(): void;
+    /** Reset the ledger store so the next `ledger()` rebuilds its head cache. */
+    resetLedgerStore(): void;
+    /** The vault's decrypt+ACL export stream (used by `exportJSON`). */
+    exportStream(opts: ExportStreamOptions): AsyncIterableIterator<ExportChunk>;
+}
+/** Result of {@link verifyBackupIntegrity}. */
+export type VerifyBackupResult = {
+    readonly ok: true;
+    readonly head: string;
+    readonly length: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'chain';
+    readonly divergedAt: number;
+    readonly message: string;
+} | {
+    readonly ok: false;
+    readonly kind: 'data';
+    readonly collection: string;
+    readonly id: string;
+    readonly message: string;
+};
+/**
+ * Dump vault as a verifiable encrypted JSON backup string.
+ *
+ * backups embed the current ledger head and the full `_ledger` +
+ * `_ledger_deltas` internal collections so the receiver can run
+ * `verifyBackupIntegrity()` after `load()` and detect any tampering between
+ * dump and restore. Backups produced without a ledger skip the integrity check
+ * with a warning — both modes round-trip cleanly.
+ */
+export declare function dumpVault(ctx: BackupContext): Promise<string>;
+/**
+ * Restore a vault from a verifiable backup. After loading, runs
+ * `verifyBackupIntegrity()` to confirm the hash chain, the embedded head, and
+ * every data envelope's payload hash. Legacy backups (no `ledgerHead`) load
+ * with a console warning and skip the integrity check.
+ */
+export declare function loadVault(ctx: BackupContext, backupJson: string): Promise<void>;
+/**
+ * End-to-end backup integrity check: `ledger.verify()` (hash chain) plus a data
+ * envelope cross-check (every current record's `_data` hash must match the
+ * latest `put` entry's `payloadHash`). Returns a discriminated union so callers
+ * can distinguish chain vs data failures.
+ */
+export declare function verifyBackupIntegrity(ctx: BackupContext): Promise<VerifyBackupResult>;
+/**
+ * Plaintext per-collection export, built on the vault's `exportStream`. Forces
+ * collection granularity (record-by-record output makes no sense in a single
+ * string) and merges dictionary snapshots across collections.
+ */
+export declare function exportVaultJSON(ctx: BackupContext, opts?: ExportStreamOptions): Promise<string>;