@noy-db/on-magic-link 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/index.d.cts

@@ -1,526 +0,0 @@
-import { NoydbStore, createNoydb, PassphrasePolicy, Noydb, Role, FactorProof, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
-export { MAGIC_LINK_GRANTS_COLLECTION, MagicLinkGrantPayload, deriveMagicLinkContentKey } from '@noy-db/hub';
-
-/**
- * **Invite + peer-recovery primitives** — issue #32.
- *
- * Layered on top of `db.grant` (for invite, mints a NEW user) and
- * `db.recoverUser` (for peer-recovery, rewraps an EXISTING user under
- * a fresh temp passphrase). These flows are SIBLINGS of the existing
- * delegation-grant primitives in `./index.ts` — different threat
- * model, different on-disk audit shape, no server-held secret.
- *
- * ## Threat model
- *
- * The temp passphrase travels in the **URL fragment** — server-blind
- * transport (fragments don't traverse TLS proxies, don't appear in
- * access logs). Trade-off: any party who sees the URL can claim the
- * invite once. Single-use semantics close the window: `acceptInvite`
- * rotates the passphrase atomically, marking the audit doc accepted —
- * a second `acceptInvite` call rejects.
- *
- * ## What this module does NOT do
- *
- * - Send emails / construct HTTPS URLs (that's the application layer)
- * - Validate the invite under HTTPS (caller's responsibility)
- * - Coordinate with a server-held secret (delegation grants do that;
- *   invite is server-blind by design)
- *
- * @see #32 #33 #34
- *
- * @module
- */
-
-/** Whether the payload mints a NEW user (invite) or rewraps an existing one (peer-recovery). */
-type InviteKind = 'invite' | 'peer-recovery';
-/**
- * Serializable payload encoded into the URL fragment. The temp
- * passphrase is the secret; the rest is metadata the recipient
- * needs to open the right vault as the right user.
- */
-interface InvitePayload {
-    /** ULID identifying this invite — used to look up the audit doc. */
-    readonly tokenId: string;
-    readonly vault: string;
-    readonly userId: string;
-    readonly displayName?: string;
-    readonly role?: Role;
-    readonly kind: InviteKind;
-    /** Issuer's userId (for forensics; not enforced cryptographically). */
-    readonly issuer: string;
-    /** Single-use temporary passphrase — replaced on `acceptInvite`. */
-    readonly tempPhrase: string;
-    readonly expiresAt: string;
-}
-/** Audit doc persisted at `_meta/invite-audit-<tokenId>`. */
-interface InviteAuditDoc {
-    readonly _noydb_invite_audit: 1;
-    readonly tokenId: string;
-    readonly kind: InviteKind;
-    readonly issuer: string;
-    readonly target: string;
-    readonly expiresAt: string;
-    readonly issuedAt: string;
-    readonly revokedAt?: string;
-    readonly acceptedAt?: string;
-}
-interface IssueInviteOptions {
-    readonly userId: string;
-    readonly displayName: string;
-    readonly role: Role;
-    readonly ttlMs?: number;
-    /** Override the generated temp phrase (rare; deterministic tests). */
-    readonly tempPhrase?: string;
-}
-interface IssuePeerRecoveryOptions {
-    readonly userId: string;
-    readonly displayName?: string;
-    readonly role?: Role;
-    readonly ttlMs?: number;
-    readonly tempPhrase?: string;
-}
-interface IssueInviteResult {
-    readonly payload: InvitePayload;
-    /**
-     * URL-fragment-safe base64url encoding of the JSON payload. Embed
-     * after a `#` in the application's invite URL. Decoded back at
-     * accept time via `decodeInvitePayload`.
-     */
-    readonly encoded: string;
-}
-interface AcceptInviteOptions {
-    /**
-     * The recipient's NoydbStore. Typically the same shared store the
-     * issuer used (e.g. a sync-peer pointing at a common backend) — the
-     * recipient must reach the same `_keyring/<userId>` and
-     * `_meta/invite-audit-<tokenId>` documents.
-     */
-    readonly store: NoydbStore;
-    /**
-     * The recipient's chosen new passphrase. `acceptInvite` rotates
-     * the temp phrase to this value atomically before returning. Must
-     * pass the vault's phrase strength policy (or the recipient must
-     * pass `validatePassphrase: false` via the underlying createNoydb
-     * options — currently exposed via `noydbOptions`).
-     */
-    readonly newPhrase: string;
-    /**
-     * Reference clock for TTL evaluation. Production callers leave
-     * this `undefined`; tests pass a fixed date.
-     */
-    readonly now?: Date;
-    /**
-     * Extra options forwarded to `createNoydb` when the recipient's
-     * session opens. Useful for `policy`, `validatePassphrase`, or
-     * `sessionPolicy` tweaks the application layer wants in scope.
-     */
-    readonly noydbOptions?: Omit<Parameters<typeof createNoydb>[0], 'store' | 'user' | 'secret'>;
-    /**
-     * Forwarded to the inner `keyringRotatePassphrase` call so the
-     * recipient's `newPhrase` is validated against the same policy the
-     * vault uses elsewhere. Without this, the rotation step applies the
-     * default phrase validator (lowercase letters + spaces) regardless
-     * of any `customValidator` / `pattern` set on the vault — a
-     * consumer using non-default phrase shapes (e.g. hyphen-separated
-     * alphanumeric, BIP-39 word-lists, Thai/EN-mixed scripts) hits a
-     * spurious `WeakPassphraseError`.
-     *
-     * `noydbOptions.policy.passphrase` is NOT auto-derived because
-     * `noydbOptions` flows to the post-rotation `createNoydb`, not the
-     * rotation itself. Passing the same `PassphrasePolicy` here and
-     * (via `noydbOptions.policy.passphrase`) keeps both gates aligned.
-     *
-     * Added in pre.9 (#53).
-     */
-    readonly passphrasePolicy?: PassphrasePolicy;
-    /**
-     * Skip phrase strength validation for the recipient's `newPhrase`.
-     * Forwarded to the inner rotation. Use sparingly — bypasses the
-     * structural rules that protect against weak phrases.
-     *
-     * Added in pre.9 (#53).
-     */
-    readonly allowWeakPassphrase?: boolean;
-}
-interface AcceptInviteResult {
-    readonly db: Noydb;
-    readonly payload: InvitePayload;
-}
-declare class InviteExpiredError extends Error {
-    readonly expiresAt: string;
-    readonly code: "INVITE_EXPIRED";
-    constructor(expiresAt: string);
-}
-declare class InviteRevokedError extends Error {
-    readonly tokenId: string;
-    readonly revokedAt: string;
-    readonly code: "INVITE_REVOKED";
-    constructor(tokenId: string, revokedAt: string);
-}
-declare class InviteAlreadyAcceptedError extends Error {
-    readonly tokenId: string;
-    readonly acceptedAt: string;
-    readonly code: "INVITE_ALREADY_ACCEPTED";
-    constructor(tokenId: string, acceptedAt: string);
-}
-declare class InviteAuditMissingError extends Error {
-    readonly tokenId: string;
-    readonly code: "INVITE_AUDIT_MISSING";
-    constructor(tokenId: string);
-}
-/**
- * Mint an invite for a NEW user. Generates a random temp phrase,
- * calls `db.grant({ userId, passphrase: tempPhrase })`, writes the
- * audit doc, and returns the URL-encodable payload.
- *
- * The recipient claims via `acceptInvite(encoded, { store, newPhrase })`;
- * the rotation inside `acceptInvite` invalidates the temp phrase
- * (single-use by construction).
- *
- * @throws Whatever `db.grant` throws (PrivilegeEscalationError,
- *         WeakPassphraseError if the temp phrase fails policy, …)
- */
-declare function issueInvite(db: Noydb, vault: string, options: IssueInviteOptions): Promise<IssueInviteResult>;
-/**
- * Mint a peer-recovery for an EXISTING user. Generates a random temp
- * phrase, calls `db.recoverUser` (atomic; closes the partial-failure
- * window of compose-from-primitives), writes the audit doc, returns
- * the payload.
- *
- * Owner→owner is allowed (the policy gate `peer-recover-user` carries
- * the freshness factor). The `factors` argument forwards to the gate.
- */
-declare function issuePeerRecovery(db: Noydb, vault: string, options: IssuePeerRecoveryOptions, factors?: {
-    factors?: ReadonlyArray<FactorProof>;
-    sharedDevice?: boolean;
-}): Promise<IssueInviteResult>;
-/**
- * Mark an outstanding invite as revoked. After this, `acceptInvite`
- * for the same token rejects with `InviteRevokedError` BEFORE opening
- * any session — closes #32's "revoked-link silent shadow keyring"
- * defense (without the audit doc check, a revoked link could fall
- * through to `createNoydb`'s no-keyring auto-create path and create
- * a fresh empty vault).
- *
- * Idempotent — revoking an already-revoked invite is a no-op.
- *
- * Note: this does NOT delete the granted/recovered keyring; it only
- * marks the invite token as unusable. To fully cancel the invite,
- * call `db.revoke(vault, { userId })` separately. The two are split
- * because peer-recovery doesn't have a "cancel" — the target user
- * already existed.
- */
-declare function revokeInvite(db: Noydb, vault: string, encodedOrPayload: string | InvitePayload): Promise<void>;
-/**
- * Open the recipient's session under the invite. Validates TTL +
- * revoke + already-accepted, opens `createNoydb` with the temp
- * phrase, immediately rotates to `newPhrase`, marks the audit doc
- * accepted, returns the live `Noydb` instance.
- *
- * Single-use is enforced two ways:
- *   1. The rotation inside this function invalidates the temp phrase.
- *   2. The audit doc's `acceptedAt` field is set on success — a
- *      second `acceptInvite` call sees it and throws
- *      `InviteAlreadyAcceptedError`.
- *
- * @throws {@link InviteExpiredError} when TTL has passed.
- * @throws {@link InviteRevokedError} when the issuer has revoked.
- * @throws {@link InviteAlreadyAcceptedError} on second call.
- * @throws {@link InviteAuditMissingError} when no audit doc — closes
- *         #32's revoked-link-shadow-keyring defense.
- */
-declare function acceptInvite(encoded: string, options: AcceptInviteOptions): Promise<AcceptInviteResult>;
-/** Encode the payload as a URL-fragment-safe base64url string. */
-declare function encodeInvitePayload(payload: InvitePayload): string;
-/** Decode a base64url string back to an InvitePayload. */
-declare function decodeInvitePayload(encoded: string): InvitePayload;
-
-/**
- * **@noy-db/on-magic-link** — one-time-link viewer unlock for noy-db.
- *
- * A magic link is a single-use URL that opens a vault in a read-only,
- * viewer-scoped session WITHOUT entering a passphrase. The link
- * expires after use or after a configurable TTL; the resulting
- * session is strictly limited to the `viewer` role.
- *
- * Part of the `@noy-db/on-*` authentication family. Sibling packages:
- * `@noy-db/on-oidc` (federated login), `@noy-db/on-webauthn` (passkey
- * / biometric). All follow the same shape: enrol once, produce a
- * short-lived token, unwrap a viewer keyring at unlock.
- *
- * ## Security model
- *
- * The viewer KEK is derived via:
- *
- * ```
- * HKDF-SHA256(
- *   ikm   = serverSecret,
- *   salt  = sha256(token),
- *   info  = "noydb-magic-link-v1:" + vaultId,
- * )
- * ```
- *
- * - `serverSecret` is a server-held secret that the SERVER knows but
- *   is NOT embedded in the link. If the link is intercepted, the
- *   attacker cannot derive the KEK without the server secret.
- * - `token` is a ULID embedded in the URL. It is single-use at the
- *   application layer (the server marks it consumed after first use).
- * - `vaultId` binds the derived key to a specific vault — a token for
- *   vault A cannot be used to unlock vault B.
- *
- * The resulting keyring is ALWAYS viewer-scoped (`role: 'viewer'`).
- * The DEKs available to the viewer are only the collections in the
- * viewer-specific subset, determined by the admin who created the link.
- *
- * ## What this package is NOT
- *
- * This module provides the CRYPTO layer only — it does not:
- *   - Issue HTTP tokens or send emails (that's the application layer)
- *   - Mark tokens as consumed (that's the server's responsibility)
- *   - Store viewer keyrings in the adapter (callers do this via `grant()`)
- *
- * ## Usage
- *
- * ```ts
- * import {
- *   createMagicLinkToken,
- *   deriveMagicLinkKEK,
- *   isMagicLinkValid,
- *   buildMagicLinkKeyring,
- * } from '@noy-db/on-magic-link'
- *
- * // SERVER — mint a token + grant the viewer keyring
- * const token = createMagicLinkToken('company-a', { ttlMs: 24 * 60 * 60 * 1000 })
- * const kek = await deriveMagicLinkKEK(serverSecret, token.token, 'company-a')
- * // ... use kek + db.grant(...) to create a viewer keyring entry ...
- *
- * // Email the link, e.g. https://app.example.com/view?t=<token.token>
- *
- * // CLIENT — derive the same KEK and unlock
- * if (!isMagicLinkValid(token)) throw new Error('expired')
- * const sameKek = await deriveMagicLinkKEK(serverSecret, token.token, token.vault)
- * const keyring = buildMagicLinkKeyring({ ... })
- * ```
- *
- * @packageDocumentation
- */
-
-/** Default magic-link TTL: 24 hours. */
-declare const MAGIC_LINK_DEFAULT_TTL_MS: number;
-/**
- * The serializable metadata describing a magic link.
- * Embed `token` in the link URL as a query parameter or path segment.
- */
-interface MagicLinkToken {
-    /** Unique one-time token (ULID). Embed this in the URL. */
-    readonly token: string;
-    /** The vault this link unlocks (viewer-only). */
-    readonly vault: string;
-    /** ISO timestamp after which the link is invalid. */
-    readonly expiresAt: string;
-    /** Role of the resulting session. Always `'viewer'` for magic links. */
-    readonly role: 'viewer';
-}
-/** Options for `createMagicLinkToken()`. */
-interface CreateMagicLinkOptions {
-    /** Link lifetime in milliseconds. Default: 24 hours. */
-    ttlMs?: number;
-}
-/**
- * Derive a viewer KEK from the server secret and the magic-link token.
- *
- * Both the server (at grant time) and the client (at unlock time) call
- * this with the same inputs to get the same key. The key is used to:
- *   - Server: derive the KEK, call `db.grant()` to create a viewer keyring.
- *   - Client: derive the KEK, call `db.openVault()` / `loadKeyring()` with
- *     this KEK directly (bypassing PBKDF2) to unlock the viewer session.
- *
- * @param serverSecret - Server-held secret (never sent to the client).
- * @param token - The ULID from the magic-link URL.
- * @param vault - The vault ID this link is for.
- */
-declare function deriveMagicLinkKEK(serverSecret: string | Uint8Array<ArrayBuffer>, token: string, vault: string): Promise<CryptoKey>;
-/**
- * Generate a magic-link token (server-side).
- *
- * Returns a `MagicLinkToken` whose `token` field should be embedded in
- * the URL sent to the viewer. The server must store the token metadata
- * (or reconstruct it from the URL) so it can:
- *   1. Validate that the token has not expired or been used.
- *   2. Call `deriveMagicLinkKEK()` to create the viewer keyring.
- *
- * @param vault - The vault to grant viewer access to.
- * @param options - Optional TTL configuration.
- */
-declare function createMagicLinkToken(vault: string, options?: CreateMagicLinkOptions): MagicLinkToken;
-/**
- * Validate that a magic-link token is not expired.
- * Returns `true` if valid, `false` if expired.
- *
- * Single-use enforcement (marking a token as consumed after first use)
- * is the server's responsibility — this function only checks `expiresAt`.
- */
-declare function isMagicLinkValid(linkToken: MagicLinkToken): boolean;
-/**
- * Build a stub `UnlockedKeyring` from the magic-link-derived KEK and
- * the viewer's DEK set.
- *
- * This is a thin wrapper for callers that have already:
- *   1. Called `deriveMagicLinkKEK()` to get the viewer KEK.
- *   2. Loaded the viewer's keyring from the adapter (which holds the DEKs
- *      wrapped with the magic-link KEK).
- *   3. Unwrapped the DEKs.
- *
- * The resulting keyring is always viewer-scoped. Callers who want to turn
- * it into a session token should call `createSession()` from
- * `@noy-db/hub/session`.
- */
-declare function buildMagicLinkKeyring(opts: {
-    viewerUserId: string;
-    displayName: string;
-    deks: Map<string, CryptoKey>;
-    kek: CryptoKey;
-    salt: Uint8Array;
-}): UnlockedKeyring;
-/**
- * Single grant within a batch magic-link issue. The grantor specifies
- * the tier + scope; the package handles the wrapping. `record` is
- * optional and narrows the grant to a single record id in the
- * collection (leave undefined for a whole-collection grant).
- */
-interface MagicLinkGrantSpec {
-    readonly toUser: string;
-    readonly tier: number;
-    readonly collection?: string;
-    readonly record?: string;
-    readonly until: Date | string;
-    readonly note?: string;
-}
-interface IssueMagicLinkDelegationOptions {
-    /**
-     * Server-held secret that gates access to the grant. Same value must
-     * be supplied at claim time — the server is the only party that
-     * knows it, so a leaked URL alone cannot unlock anything.
-     */
-    readonly serverSecret: string | Uint8Array<ArrayBuffer>;
-    /**
-     * One or more grants to persist under the same magic-link token.
-     * Single-element arrays cover the common "one collection to one
-     * user" case; multi-element arrays support scoped cross-collection
-     * delegations (e.g. client portal: invoices + payments + etax).
-     */
-    readonly grants: readonly MagicLinkGrantSpec[];
-    /**
-     * Magic-link TTL. Controls `link.expiresAt` (the URL freshness).
-     * Each grant's own `until` bounds the *delegation* lifetime — the
-     * claimant only receives DEKs for grants whose `until` is still
-     * future at claim time. Default 24 h.
-     */
-    readonly ttlMs?: number;
-    /**
-     * Optional override for the ULID embedded in the URL. Rarely useful
-     * outside deterministic tests.
-     */
-    readonly token?: string;
-}
-interface IssueMagicLinkDelegationResult {
-    /** URL-embeddable token metadata. Serialize `link.token` into the link. */
-    readonly link: MagicLinkToken;
-    /** One record per grant — mirrors the input array order. */
-    readonly grants: ReadonlyArray<{
-        readonly recordId: string;
-        readonly payload: MagicLinkGrantPayload;
-    }>;
-}
-/**
- * Issue a magic-link-bound delegation.
- *
- * Server-side workflow:
- *
- * ```ts
- * import { issueMagicLinkDelegation } from '@noy-db/on-magic-link'
- *
- * const { link, grants } = await issueMagicLinkDelegation(vault, {
- *   serverSecret: process.env.MAGIC_LINK_SECRET!,
- *   grants: [
- *     { toUser: 'auditor-bob', tier: 1, collection: 'invoices',
- *       until: new Date(Date.now() + 48*3600e3) },
- *   ],
- *   ttlMs: 48 * 3600 * 1000,
- * })
- *
- * // Embed link.token in an email URL. The grantee clicks → loads your
- * // client → calls claimMagicLinkDelegation() with the same serverSecret.
- * ```
- */
-declare function issueMagicLinkDelegation(vault: Vault, options: IssueMagicLinkDelegationOptions): Promise<IssueMagicLinkDelegationResult>;
-interface ClaimMagicLinkDelegationOptions {
-    readonly store: NoydbStore;
-    readonly vault: string;
-    readonly serverSecret: string | Uint8Array<ArrayBuffer>;
-    readonly token: string;
-    /**
-     * Reference clock used to evaluate grant expiry. Production callers
-     * leave this `undefined`; tests pass a fixed date.
-     */
-    readonly now?: Date;
-}
-interface ClaimedMagicLinkGrant {
-    readonly payload: MagicLinkGrantPayload;
-    /** Tier DEK, ready to insert into a keyring map. */
-    readonly dek: CryptoKey;
-    /** True when the grant's `until` has already passed. */
-    readonly expired: boolean;
-}
-interface ClaimMagicLinkDelegationResult {
-    /**
-     * False when the server secret is wrong, the vault is wrong, or
-     * every grant is malformed. A `true` with an empty `grants` array
-     * means the record was deleted (revoked) between issue and claim.
-     */
-    readonly valid: boolean;
-    readonly grants: readonly ClaimedMagicLinkGrant[];
-}
-/**
- * Client-side flow. Derives the same content key + KEK as the grantor,
- * loads every grant persisted under the token (primary + batch
- * entries), and returns the unwrapped tier DEKs.
- *
- * The caller decides what to do with them — typically inserting them
- * into a freshly-built `UnlockedKeyring` (see `buildMagicLinkKeyring`)
- * and opening a viewer session.
- */
-declare function claimMagicLinkDelegation(options: ClaimMagicLinkDelegationOptions): Promise<ClaimMagicLinkDelegationResult>;
-/**
- * Read (without unwrapping) the grants under a token — useful for an
- * audit UI that shows the grantor what's still live on a link.
- */
-declare function inspectMagicLinkDelegation(options: {
-    readonly store: NoydbStore;
-    readonly vault: string;
-    readonly serverSecret: string | Uint8Array<ArrayBuffer>;
-    readonly token: string;
-}): Promise<readonly MagicLinkGrantPayload[]>;
-/**
- * Delete every grant under a token. Idempotent — safe to call on an
- * already-revoked or never-existed token. Returns the number of
- * records removed.
- */
-declare function revokeMagicLinkDelegation(options: {
-    readonly store: NoydbStore;
-    readonly vault: string;
-    readonly token: string;
-}): Promise<number>;
-/**
- * Read a single grant by its full record id. Convenience for callers
- * that persisted `recordId` during issue and want to resolve just one.
- */
-declare function readMagicLinkGrant(options: {
-    readonly store: NoydbStore;
-    readonly vault: string;
-    readonly serverSecret: string | Uint8Array<ArrayBuffer>;
-    readonly token: string;
-    readonly recordId: string;
-}): Promise<MagicLinkGrantPayload | null>;
-
-export { type AcceptInviteOptions, type AcceptInviteResult, type ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, InviteAlreadyAcceptedError, type InviteAuditDoc, InviteAuditMissingError, InviteExpiredError, type InviteKind, type InvitePayload, InviteRevokedError, type IssueInviteOptions, type IssueInviteResult, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, type IssuePeerRecoveryOptions, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, acceptInvite, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, decodeInvitePayload, deriveMagicLinkKEK, encodeInvitePayload, inspectMagicLinkDelegation, isMagicLinkValid, issueInvite, issueMagicLinkDelegation, issuePeerRecovery, readMagicLinkGrant, revokeInvite, revokeMagicLinkDelegation };