@noy-db/hub 0.1.0-pre.3

package/dist/dev-unlock-KrKkcqD3.d.ts

@@ -0,0 +1,263 @@
+import { aq as Role, ar as UnlockedKeyring } from './types-BZpCZB8N.js';
+
+/**
+ * Session tokens —
+ *
+ * After a vault is unlocked (via passphrase, WebAuthn, OIDC, or magic-
+ * link), the caller can call `createSession()` to get a session token that
+ * allows re-establishing the KEK for the session lifetime without re-running
+ * PBKDF2 or any interactive auth challenge.
+ *
+ * Security model
+ * ──────────────
+ * A session consists of two pieces that must both be present to recover the
+ * KEK:
+ *
+ *   1. The **session key** — a non-extractable AES-256-GCM CryptoKey that
+ *      exists only in memory. "Non-extractable" is enforced by the WebCrypto
+ *      API: the key object cannot be serialized, exported, or sent over
+ *      postMessage. When the JS context is GC'd (tab close, navigation away,
+ *      worker termination) the key becomes unrecoverable.
+ *
+ *   2. The **session token** — a JSON object that carries the KEK wrapped
+ *      with the session key (AES-256-GCM, fresh IV per session), plus
+ *      unencrypted session metadata (sessionId, userId, vault, role,
+ *      expiresAt). The token can be serialized to JSON and stored in
+ *      sessionStorage or passed across callsites within the same tab, but
+ *      it is useless without the session key.
+ *
+ * The session key is kept in a module-level Map indexed by sessionId. Callers
+ * that need to re-use a session must hold on to the sessionId returned from
+ * `createSession()`; the key is looked up automatically by `resolveSession()`.
+ *
+ * Revocation: `revokeSession()` removes the entry from the Map. Because the
+ * key is non-extractable, removal is sufficient — no one holds a serializable
+ * copy of the key.
+ *
+ * Tab-scoped lifetime: the module-level Map lives only as long as the JS
+ * module. Tab close → module unloaded → Map GC'd → all session keys gone.
+ * This is the zero-effort logout: closing the tab is always a secure logout.
+ *
+ * Expiry: `createSession()` accepts a `ttlMs` option. `resolveSession()`
+ * checks `expiresAt` and throws `SessionExpiredError` if the token is stale,
+ * even if the session key is still in the Map.
+ */
+
+/** The serializable part of a session token. Safe to store in sessionStorage. */
+interface SessionToken {
+    readonly _noydb_session: 1;
+    /** Unique session identifier (ULID). Use this as the handle for resolve/revoke. */
+    readonly sessionId: string;
+    readonly userId: string;
+    readonly vault: string;
+    readonly role: Role;
+    /** ISO timestamp — resolveSession() rejects this token after this time. */
+    readonly expiresAt: string;
+    /** KEK wrapped with the session key (AES-256-GCM). Base64. */
+    readonly wrappedKek: string;
+    /** IV used for the wrapping operation. Base64. */
+    readonly kekIv: string;
+}
+/** Result returned from `createSession()`. */
+interface CreateSessionResult {
+    /** Serializable token — store in sessionStorage or pass to `resolveSession()`. */
+    token: SessionToken;
+    /** The sessionId — use this handle for `resolveSession()` and `revokeSession()`. */
+    sessionId: string;
+}
+/** Options for `createSession()`. */
+interface CreateSessionOptions {
+    /**
+     * Session lifetime in milliseconds. Defaults to 60 minutes.
+     * After this duration, `resolveSession()` throws `SessionExpiredError`.
+     */
+    ttlMs?: number;
+}
+/**
+ * Create a session for an already-unlocked keyring.
+ *
+ * Call this after any successful unlock (passphrase, WebAuthn, OIDC,
+ * magic-link). The returned `sessionId` is the handle for later
+ * `resolveSession()` and `revokeSession()` calls.
+ *
+ * The session key is generated fresh (non-extractable) and stored in the
+ * module-level Map. The KEK from `keyring.kek` is exported (it must be
+ * extractable — it was derived by `deriveKey()` which sets extractable: false,
+ * but it's unwrapped from the keyring which sets extractable: true) and then
+ * re-wrapped with the session key.
+ *
+ * @param keyring - An already-unlocked keyring whose `kek` is available.
+ * @param vault - The vault name this session is scoped to.
+ * @param options - Optional session configuration.
+ */
+declare function createSession(keyring: UnlockedKeyring, vault: string, options?: CreateSessionOptions): Promise<CreateSessionResult>;
+/**
+ * Resolve a session token back into an UnlockedKeyring.
+ *
+ * Looks up the session key by `sessionId`, checks the token is not expired,
+ * then decrypts the payload to reconstruct the keyring's DEK set.
+ *
+ * Throws `SessionExpiredError` if the token's `expiresAt` is in the past.
+ * Throws `SessionNotFoundError` if the session key is not in the store
+ * (tab was reloaded, session was revoked, or the sessionId is wrong).
+ *
+ * @param token - The SessionToken from `createSession()`.
+ */
+declare function resolveSession(token: SessionToken): Promise<UnlockedKeyring>;
+/**
+ * Revoke a session by removing its key from the store.
+ *
+ * After revocation, `resolveSession()` will throw `SessionNotFoundError`
+ * for this sessionId. The session token (if held by the caller) becomes
+ * permanently useless. This is the explicit logout path.
+ *
+ * No-op if the session was already expired or does not exist.
+ */
+declare function revokeSession(sessionId: string): void;
+/**
+ * Check if a session is still alive (key in store + not expired).
+ * Does not decrypt anything — purely a metadata check.
+ */
+declare function isSessionAlive(token: SessionToken): boolean;
+/**
+ * Revoke all active sessions. Used by `Noydb.close()` to ensure that
+ * closing the instance destroys all session state, not just the keyring
+ * cache.
+ */
+declare function revokeAllSessions(): void;
+/**
+ * Return the number of active sessions currently in the store.
+ * Useful for diagnostics and tests.
+ */
+declare function activeSessionCount(): number;
+
+/**
+ * Dev-mode persistent unlock —
+ *
+ * Solves the developer inner-loop friction: hot-reload destroys the session
+ * (page navigation semantics), forcing a passphrase re-entry every refresh.
+ *
+ * This module provides an opt-in, deliberately-named escape hatch that lets
+ * developers store the keyring payload in sessionStorage or localStorage so
+ * the vault auto-unlocks on every page load — without a passphrase,
+ * without a biometric prompt, without any OIDC flow.
+ *
+ * ⚠️ WARNING — this is a loaded footgun ⚠️
+ * ─────────────────────────────────────────
+ * The keyring payload stored by this module contains the DEKs. Whoever has
+ * access to sessionStorage/localStorage has access to the DEKs. On a shared
+ * development machine, a compromised browser extension, or a mis-configured
+ * origin, this is a complete key exposure.
+ *
+ * This module is ONLY safe for local development. It must NEVER be active
+ * in production builds.
+ *
+ * Guardrails (all enforced by the module, not by the caller)
+ * ──────────────────────────────────────────────────────────
+ * 1. **Production guard:** `enableDevUnlock()` throws immediately if
+ *    `process.env.NODE_ENV === 'production'` or if `import.meta.env?.PROD === true`
+ *    (Vite convention). Also throws if the hostname is NOT localhost or 127.0.0.1.
+ *
+ * 2. **Explicit acknowledgement string:** the caller must pass
+ *    `acknowledge: 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY'` or the call
+ *    throws. This string appears in every grep for `devUnlock` in the codebase,
+ *    making it impossible to enable this feature accidentally.
+ *
+ * 3. **Scope is vault + userId:** the storage key includes both the
+ *    vault name and the userId, so dev-unlock for vault-A does
+ *    NOT auto-unlock vault-B.
+ *
+ * 4. **Storage scope:** default is `sessionStorage` (cleared on tab close).
+ *    `localStorage` is opt-in and requires an additional
+ *    `persistAcrossTabs: true` flag in the options.
+ *
+ * 5. **Clear method:** `clearDevUnlock()` removes the stored payload. Wire
+ *    this to a dev toolbar button or `Ctrl+Shift+L` so clearing is one action.
+ *
+ * 6. **Console banner:** on first enable, a highly visible console warning
+ *    fires. Cannot be suppressed.
+ *
+ * Usage
+ * ─────
+ * ```ts
+ * // In your dev entry point only (guarded by import.meta.env.DEV):
+ * if (import.meta.env.DEV) {
+ *   const { enableDevUnlock, loadDevUnlock } = await import('@noy-db/hub')
+ *   enableDevUnlock('my-compartment', 'alice', keyring, {
+ *     acknowledge: 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY',
+ *   })
+ * }
+ *
+ * // On page load:
+ * if (import.meta.env.DEV) {
+ *   const keyring = await loadDevUnlock('my-compartment', 'alice')
+ *   if (keyring) {
+ *     // Skip unlock prompt, use keyring directly
+ *   }
+ * }
+ * ```
+ */
+
+interface DevUnlockOptions {
+    /**
+     * Required: the exact string 'I-UNDERSTAND-THIS-DISABLES-UNLOCK-SECURITY'.
+     * Any other value causes `enableDevUnlock()` to throw.
+     */
+    acknowledge: string;
+    /**
+     * If `true`, stores in localStorage (persists across tabs and browser restarts).
+     * If `false` (default), stores in sessionStorage (cleared on tab close).
+     */
+    persistAcrossTabs?: boolean;
+}
+/**
+ * Serialize and store a keyring to browser storage for dev-mode auto-unlock.
+ *
+ * Throws immediately if:
+ *   - The acknowledge string is wrong.
+ *   - Running in a production environment (NODE_ENV=production).
+ *   - Running on a non-localhost hostname.
+ *
+ * Emits a highly visible console warning that cannot be suppressed.
+ *
+ * @param vault - The vault name.
+ * @param userId - The user ID.
+ * @param keyring - The unlocked keyring to persist.
+ * @param options - Options including the required acknowledge string.
+ */
+declare function enableDevUnlock(vault: string, userId: string, keyring: UnlockedKeyring, options: DevUnlockOptions): Promise<void>;
+/**
+ * Load a dev-mode keyring from browser storage.
+ *
+ * Returns `null` if no dev-unlock state is stored for this vault + user,
+ * or if the stored payload is malformed.
+ *
+ * Does NOT perform the production environment check — it's safe to CALL
+ * `loadDevUnlock` in production (it will simply return `null` because no
+ * dev-unlock state was ever written). The guard only fires on `enableDevUnlock`.
+ *
+ * @param vault - The vault name.
+ * @param userId - The user ID.
+ * @param options - Optional storage override.
+ */
+declare function loadDevUnlock(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): Promise<UnlockedKeyring | null>;
+/**
+ * Remove dev-unlock state from browser storage.
+ *
+ * Safe to call in production (no-op if no dev state exists).
+ */
+declare function clearDevUnlock(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): void;
+/**
+ * Check if dev-unlock state exists for this vault + user.
+ *
+ * Safe to call in production (returns false if nothing is stored).
+ */
+declare function isDevUnlockActive(vault: string, userId: string, options?: {
+    persistAcrossTabs?: boolean;
+}): boolean;
+
+export { type CreateSessionOptions as C, type DevUnlockOptions as D, type SessionToken as S, type CreateSessionResult as a, activeSessionCount as b, clearDevUnlock as c, createSession as d, enableDevUnlock as e, isSessionAlive as f, revokeAllSessions as g, revokeSession as h, isDevUnlockActive as i, loadDevUnlock as l, resolveSession as r };

package/dist/hash-9KO1BGxh.d.cts

@@ -0,0 +1,63 @@
+import { av as EncryptedEnvelope } from './types-Bfs0qr5F.cjs';
+
+/**
+ * Ledger storage constants — pinned in their own leaf module so
+ * always-on core code (vault.ts, dictionary.ts) can import them
+ * without dragging the `LedgerStore` class into the bundle.
+ *
+ * `splitting: true` in tsup is not enough on its own: when a
+ * source file exports both pure constants and a heavyweight class,
+ * the bundler keeps the entire chunk reachable from any importer.
+ * Extracting the constants lets the floor scenario import them
+ * without paying for the class.
+ *
+ * @internal
+ */
+/** The internal collection name used for ledger entry storage. */
+declare const LEDGER_COLLECTION = "_ledger";
+/**
+ * The internal collection name used for delta payload storage.
+ *
+ * Deltas live in a sibling collection (not inside `_ledger`) for two
+ * reasons:
+ *
+ *   1. **Listing efficiency.** `ledger.loadAllEntries()` calls
+ *      `adapter.list(_ledger)` which would otherwise return every
+ *      delta key alongside every entry key. Splitting them keeps the
+ *      list small (one key per ledger entry) and the delta reads
+ *      keyed by the entry's index.
+ *
+ *   2. **Prune-friendliness.** A future `pruneHistory()` will delete
+ *      old deltas while keeping the ledger chain intact (folding old
+ *      deltas into a base snapshot). Separating the storage makes
+ *      that deletion a targeted operation on one collection instead
+ *      of a filter across a mixed list.
+ *
+ * Both collections share the same ledger DEK — one DEK, two
+ * internal collections, same zero-knowledge guarantees.
+ */
+declare const LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+
+/**
+ * Envelope payload hash — pinned in its own leaf module so consumers
+ * (DictionaryHandle, the active history strategy) can import it
+ * without dragging in the `LedgerStore` class.
+ *
+ * see `constants.ts` for the broader rationale.
+ *
+ * @internal
+ */
+
+/**
+ * Compute the `payloadHash` value for an encrypted envelope. Used by
+ * `LedgerStore.append` for both put (hash the new envelope) and
+ * delete (hash the previous envelope) paths, and by
+ * `DictionaryHandle` so its ledger entries match the same contract.
+ *
+ * Returns the empty string when there is no envelope (delete of a
+ * never-existed record). The empty string tolerated by the ledger
+ * entry's `payloadHash` field as the canonical "nothing here" value.
+ */
+declare function envelopePayloadHash(envelope: EncryptedEnvelope | null): Promise<string>;
+
+export { LEDGER_COLLECTION as L, LEDGER_DELTAS_COLLECTION as a, envelopePayloadHash as e };

package/dist/hash-ChfJjRjQ.d.ts

@@ -0,0 +1,63 @@
+import { av as EncryptedEnvelope } from './types-BZpCZB8N.js';
+
+/**
+ * Ledger storage constants — pinned in their own leaf module so
+ * always-on core code (vault.ts, dictionary.ts) can import them
+ * without dragging the `LedgerStore` class into the bundle.
+ *
+ * `splitting: true` in tsup is not enough on its own: when a
+ * source file exports both pure constants and a heavyweight class,
+ * the bundler keeps the entire chunk reachable from any importer.
+ * Extracting the constants lets the floor scenario import them
+ * without paying for the class.
+ *
+ * @internal
+ */
+/** The internal collection name used for ledger entry storage. */
+declare const LEDGER_COLLECTION = "_ledger";
+/**
+ * The internal collection name used for delta payload storage.
+ *
+ * Deltas live in a sibling collection (not inside `_ledger`) for two
+ * reasons:
+ *
+ *   1. **Listing efficiency.** `ledger.loadAllEntries()` calls
+ *      `adapter.list(_ledger)` which would otherwise return every
+ *      delta key alongside every entry key. Splitting them keeps the
+ *      list small (one key per ledger entry) and the delta reads
+ *      keyed by the entry's index.
+ *
+ *   2. **Prune-friendliness.** A future `pruneHistory()` will delete
+ *      old deltas while keeping the ledger chain intact (folding old
+ *      deltas into a base snapshot). Separating the storage makes
+ *      that deletion a targeted operation on one collection instead
+ *      of a filter across a mixed list.
+ *
+ * Both collections share the same ledger DEK — one DEK, two
+ * internal collections, same zero-knowledge guarantees.
+ */
+declare const LEDGER_DELTAS_COLLECTION = "_ledger_deltas";
+
+/**
+ * Envelope payload hash — pinned in its own leaf module so consumers
+ * (DictionaryHandle, the active history strategy) can import it
+ * without dragging in the `LedgerStore` class.
+ *
+ * see `constants.ts` for the broader rationale.
+ *
+ * @internal
+ */
+
+/**
+ * Compute the `payloadHash` value for an encrypted envelope. Used by
+ * `LedgerStore.append` for both put (hash the new envelope) and
+ * delete (hash the previous envelope) paths, and by
+ * `DictionaryHandle` so its ledger entries match the same contract.
+ *
+ * Returns the empty string when there is no envelope (delete of a
+ * never-existed record). The empty string tolerated by the ledger
+ * entry's `payloadHash` field as the canonical "nothing here" value.
+ */
+declare function envelopePayloadHash(envelope: EncryptedEnvelope | null): Promise<string>;
+
+export { LEDGER_COLLECTION as L, LEDGER_DELTAS_COLLECTION as a, envelopePayloadHash as e };