@noy-db/hub 0.2.0-pre.30 → 0.2.0-pre.31

package/dist/dev-unlock-0Z6yxfS7.d.cts

@@ -1,263 +0,0 @@
-import { aT as Role, aU as UnlockedKeyring } from './types-CdVfiQgt.cjs';
-
-/**
- * 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/discriminant-BN9REW3o.d.cts

@@ -1,60 +0,0 @@
-/**
- * Type-guard helper for narrowing discriminated-union records.
- *
- * `Collection<T>` correctly threads `T` through `get` / `query` / `scan`, but
- * accessing member-specific fields after reading from a `Collection<Union>`
- * still requires a narrowing step in application code. In regular `.ts` files
- * a simple `if (r.kind === 'IV')` block narrows correctly; in vue-tsc /
- * template contexts the inline comparison is sometimes not enough, and the
- * helper below makes the guard portable and avoids `as unknown as …` casts.
- *
- * **Usage with Collection<T>**
- *
- * ```ts
- * import { isDiscriminant } from '@noy-db/hub'
- *
- * type IV = { kind: 'IV'; invoiceNo: string; amount: number }
- * type RE = { kind: 'RE'; receiptNo: string; paidAt: string }
- * type Receipt = IV | RE | ...
- *
- * const receipts = await vault.collection<Receipt>('receipts').query().toArray()
- *
- * // Filter approach — result is IV[], invoiceNo accessible without cast:
- * const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))
- * console.log(ivs[0].invoiceNo)
- *
- * // Branch approach:
- * for (const r of receipts) {
- *   if (isDiscriminant(r, 'kind', 'IV')) {
- *     console.log(r.invoiceNo)  // r: IV here
- *   }
- * }
- * ```
- *
- * @module
- */
-/**
- * Type-guard for narrowing a discriminated-union record by its discriminant.
- *
- * Returns `true` when `record[key] === value`, and narrows `record` to
- * `Extract<T, Record<K, V>>` — the exact union member(s) that carry that
- * discriminant value.
- *
- * The discriminant key is a parameter (not hardcoded to `'kind'`), so this
- * works with any field name: `'kind'`, `'type'`, `'tag'`, etc.
- *
- * @example
- *   const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))
- *   // ivs: IV[]  — invoiceNo accessible, no cast needed
- *
- * @typeParam T - The union type of the record (e.g. `Receipt`). Both type-alias
- *   unions and interface-extended unions work; use a `type` alias (`type Receipt = IV | RE`) for best
- *   results.
- * @typeParam K - The discriminant key (must be a key of `T`).
- * @typeParam V - The discriminant value to match. The `const` modifier ensures
- *   TypeScript infers the string literal (e.g. `'IV'`), not the full union
- *   `T[K]`, so the predicate resolves to the exact member type.
- */
-declare function isDiscriminant<T, K extends keyof T, const V extends T[K]>(record: T, key: K, value: V): record is Extract<T, Record<K, V>>;
-
-export { isDiscriminant as i };