@noy-db/on-magic-link 0.1.0-pre.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @noy-db/on-magic-link
+
+[![npm](https://img.shields.io/npm/v/%40noy-db/on-magic-link.svg)](https://www.npmjs.com/package/@noy-db/on-magic-link)
+
+> Magic-link unlock for noy-db
+
+Part of [**`@noy-db/hub`**](https://www.npmjs.com/package/@noy-db/hub) — the zero-knowledge, offline-first, encrypted document store.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/on-magic-link
+```
+
+## What it is
+
+Magic-link unlock for noy-db — one-time URL that opens a vault in a viewer-scoped session without a passphrase. Part of the @noy-db/on-* authentication family.
+
+## Status
+
+**Pre-release** (`0.1.0-pre.1`). API may change before `1.0`.
+
+## Documentation
+
+See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
+
+- Source — [`packages/on-magic-link`](https://github.com/vLannaAi/noy-db/tree/main/packages/on-magic-link)
+- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
+
+## License
+
+[MIT](./LICENSE) © vLannaAi

package/dist/index.cjs

@@ -0,0 +1,173 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MAGIC_LINK_DEFAULT_TTL_MS: () => MAGIC_LINK_DEFAULT_TTL_MS,
+  MAGIC_LINK_GRANTS_COLLECTION: () => import_hub.MAGIC_LINK_GRANTS_COLLECTION,
+  buildMagicLinkKeyring: () => buildMagicLinkKeyring,
+  claimMagicLinkDelegation: () => claimMagicLinkDelegation,
+  createMagicLinkToken: () => createMagicLinkToken,
+  deriveMagicLinkContentKey: () => import_hub.deriveMagicLinkContentKey,
+  deriveMagicLinkKEK: () => deriveMagicLinkKEK,
+  inspectMagicLinkDelegation: () => inspectMagicLinkDelegation,
+  isMagicLinkValid: () => isMagicLinkValid,
+  issueMagicLinkDelegation: () => issueMagicLinkDelegation,
+  readMagicLinkGrant: () => readMagicLinkGrant,
+  revokeMagicLinkDelegation: () => revokeMagicLinkDelegation
+});
+module.exports = __toCommonJS(index_exports);
+var import_hub = require("@noy-db/hub");
+var MAGIC_LINK_INFO_PREFIX = "noydb-magic-link-v1:";
+var MAGIC_LINK_DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+async function deriveMagicLinkKEK(serverSecret, token, vault) {
+  const subtle = globalThis.crypto.subtle;
+  const ikmBytes = serverSecret instanceof Uint8Array ? serverSecret : new TextEncoder().encode(serverSecret);
+  const tokenBytes = new TextEncoder().encode(token);
+  const saltBuffer = await subtle.digest("SHA-256", tokenBytes);
+  const info = new TextEncoder().encode(MAGIC_LINK_INFO_PREFIX + vault);
+  const ikm = await subtle.importKey("raw", ikmBytes, "HKDF", false, ["deriveKey"]);
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: saltBuffer,
+      info
+    },
+    ikm,
+    { name: "AES-KW", length: 256 },
+    false,
+    ["wrapKey", "unwrapKey"]
+  );
+}
+function createMagicLinkToken(vault, options = {}) {
+  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS;
+  return {
+    token: (0, import_hub.generateULID)(),
+    vault,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    role: "viewer"
+  };
+}
+function isMagicLinkValid(linkToken) {
+  return Date.now() <= new Date(linkToken.expiresAt).getTime();
+}
+function buildMagicLinkKeyring(opts) {
+  return {
+    userId: opts.viewerUserId,
+    displayName: opts.displayName,
+    role: "viewer",
+    permissions: {},
+    deks: opts.deks,
+    kek: opts.kek,
+    salt: opts.salt
+  };
+}
+async function issueMagicLinkDelegation(vault, options) {
+  if (options.grants.length === 0) {
+    throw new Error("@noy-db/on-magic-link: grants[] must be non-empty");
+  }
+  const token = options.token ?? (0, import_hub.generateULID)();
+  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS;
+  const link = {
+    token,
+    vault: vault.name,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    role: "viewer"
+  };
+  const contentKey = await (0, import_hub.deriveMagicLinkContentKey)(options.serverSecret, token, vault.name);
+  const grantKek = await deriveMagicLinkKEK(options.serverSecret, token, vault.name);
+  const grants = [];
+  for (let i = 0; i < options.grants.length; i += 1) {
+    const spec = options.grants[i];
+    const recordId = (0, import_hub.magicLinkGrantRecordId)(token, i);
+    const issueOpts = {
+      toUser: spec.toUser,
+      tier: spec.tier,
+      ...spec.collection !== void 0 && { collection: spec.collection },
+      ...spec.record !== void 0 && { record: spec.record },
+      until: spec.until,
+      ...spec.note !== void 0 && { note: spec.note }
+    };
+    const record = await vault.writeMagicLinkGrant(contentKey, grantKek, recordId, issueOpts);
+    grants.push({ recordId: record.recordId, payload: record.payload });
+  }
+  return { link, grants };
+}
+async function claimMagicLinkDelegation(options) {
+  const { store, vault, token, serverSecret } = options;
+  const contentKey = await (0, import_hub.deriveMagicLinkContentKey)(serverSecret, token, vault);
+  const grantKek = await deriveMagicLinkKEK(serverSecret, token, vault);
+  const payloads = await (0, import_hub.listMagicLinkGrants)(store, vault, contentKey, token);
+  if (payloads.length === 0) {
+    return { valid: false, grants: [] };
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const claimed = [];
+  for (const payload of payloads) {
+    let dek;
+    try {
+      dek = await (0, import_hub.unwrapMagicLinkGrant)(payload, grantKek);
+    } catch {
+      continue;
+    }
+    claimed.push({
+      payload,
+      dek,
+      expired: (0, import_hub.isMagicLinkGrantExpired)(payload, now)
+    });
+  }
+  return { valid: true, grants: claimed };
+}
+async function inspectMagicLinkDelegation(options) {
+  const contentKey = await (0, import_hub.deriveMagicLinkContentKey)(
+    options.serverSecret,
+    options.token,
+    options.vault
+  );
+  return (0, import_hub.listMagicLinkGrants)(options.store, options.vault, contentKey, options.token);
+}
+async function revokeMagicLinkDelegation(options) {
+  return (0, import_hub.revokeMagicLinkGrant)(options.store, options.vault, options.token);
+}
+async function readMagicLinkGrant(options) {
+  const contentKey = await (0, import_hub.deriveMagicLinkContentKey)(
+    options.serverSecret,
+    options.token,
+    options.vault
+  );
+  return (0, import_hub.readMagicLinkGrantRecord)(options.store, options.vault, contentKey, options.recordId);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MAGIC_LINK_DEFAULT_TTL_MS,
+  MAGIC_LINK_GRANTS_COLLECTION,
+  buildMagicLinkKeyring,
+  claimMagicLinkDelegation,
+  createMagicLinkToken,
+  deriveMagicLinkContentKey,
+  deriveMagicLinkKEK,
+  inspectMagicLinkDelegation,
+  isMagicLinkValid,
+  issueMagicLinkDelegation,
+  readMagicLinkGrant,
+  revokeMagicLinkDelegation
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-magic-link** — one-time-link viewer unlock for noy-db.\n *\n * A magic link is a single-use URL that opens a vault in a read-only,\n * viewer-scoped session WITHOUT entering a passphrase. The link\n * expires after use or after a configurable TTL; the resulting\n * session is strictly limited to the `viewer` role.\n *\n * Part of the `@noy-db/on-*` authentication family. Sibling packages:\n * `@noy-db/on-oidc` (federated login), `@noy-db/on-webauthn` (passkey\n * / biometric). All follow the same shape: enrol once, produce a\n * short-lived token, unwrap a viewer keyring at unlock.\n *\n * ## Security model\n *\n * The viewer KEK is derived via:\n *\n * ```\n * HKDF-SHA256(\n *   ikm   = serverSecret,\n *   salt  = sha256(token),\n *   info  = \"noydb-magic-link-v1:\" + vaultId,\n * )\n * ```\n *\n * - `serverSecret` is a server-held secret that the SERVER knows but\n *   is NOT embedded in the link. If the link is intercepted, the\n *   attacker cannot derive the KEK without the server secret.\n * - `token` is a ULID embedded in the URL. It is single-use at the\n *   application layer (the server marks it consumed after first use).\n * - `vaultId` binds the derived key to a specific vault — a token for\n *   vault A cannot be used to unlock vault B.\n *\n * The resulting keyring is ALWAYS viewer-scoped (`role: 'viewer'`).\n * The DEKs available to the viewer are only the collections in the\n * viewer-specific subset, determined by the admin who created the link.\n *\n * ## What this package is NOT\n *\n * This module provides the CRYPTO layer only — it does not:\n *   - Issue HTTP tokens or send emails (that's the application layer)\n *   - Mark tokens as consumed (that's the server's responsibility)\n *   - Store viewer keyrings in the adapter (callers do this via `grant()`)\n *\n * ## Usage\n *\n * ```ts\n * import {\n *   createMagicLinkToken,\n *   deriveMagicLinkKEK,\n *   isMagicLinkValid,\n *   buildMagicLinkKeyring,\n * } from '@noy-db/on-magic-link'\n *\n * // SERVER — mint a token + grant the viewer keyring\n * const token = createMagicLinkToken('company-a', { ttlMs: 24 * 60 * 60 * 1000 })\n * const kek = await deriveMagicLinkKEK(serverSecret, token.token, 'company-a')\n * // ... use kek + db.grant(...) to create a viewer keyring entry ...\n *\n * // Email the link, e.g. https://app.example.com/view?t=<token.token>\n *\n * // CLIENT — derive the same KEK and unlock\n * if (!isMagicLinkValid(token)) throw new Error('expired')\n * const sameKek = await deriveMagicLinkKEK(serverSecret, token.token, token.vault)\n * const keyring = buildMagicLinkKeyring({ ... })\n * ```\n *\n * @packageDocumentation\n */\n\nimport {\n  generateULID,\n  deriveMagicLinkContentKey,\n  readMagicLinkGrantRecord,\n  listMagicLinkGrants,\n  unwrapMagicLinkGrant,\n  revokeMagicLinkGrant,\n  magicLinkGrantRecordId,\n  isMagicLinkGrantExpired,\n  MAGIC_LINK_GRANTS_COLLECTION,\n} from '@noy-db/hub'\nimport type {\n  Role,\n  UnlockedKeyring,\n  Vault,\n  NoydbStore,\n  MagicLinkGrantPayload,\n  IssueMagicLinkGrantOptions,\n} from '@noy-db/hub'\n\n// HKDF info string — version-namespaced so future schemes are distinguishable.\nconst MAGIC_LINK_INFO_PREFIX = 'noydb-magic-link-v1:'\n\n/** Default magic-link TTL: 24 hours. */\nexport const MAGIC_LINK_DEFAULT_TTL_MS = 24 * 60 * 60 * 1000\n\n// ─── Types ──────────────────────────────────────────────────────────────\n\n/**\n * The serializable metadata describing a magic link.\n * Embed `token` in the link URL as a query parameter or path segment.\n */\nexport interface MagicLinkToken {\n  /** Unique one-time token (ULID). Embed this in the URL. */\n  readonly token: string\n  /** The vault this link unlocks (viewer-only). */\n  readonly vault: string\n  /** ISO timestamp after which the link is invalid. */\n  readonly expiresAt: string\n  /** Role of the resulting session. Always `'viewer'` for magic links. */\n  readonly role: 'viewer'\n}\n\n/** Options for `createMagicLinkToken()`. */\nexport interface CreateMagicLinkOptions {\n  /** Link lifetime in milliseconds. Default: 24 hours. */\n  ttlMs?: number\n}\n\n// ─── KEK derivation ─────────────────────────────────────────────────────\n\n/**\n * Derive a viewer KEK from the server secret and the magic-link token.\n *\n * Both the server (at grant time) and the client (at unlock time) call\n * this with the same inputs to get the same key. The key is used to:\n *   - Server: derive the KEK, call `db.grant()` to create a viewer keyring.\n *   - Client: derive the KEK, call `db.openVault()` / `loadKeyring()` with\n *     this KEK directly (bypassing PBKDF2) to unlock the viewer session.\n *\n * @param serverSecret - Server-held secret (never sent to the client).\n * @param token - The ULID from the magic-link URL.\n * @param vault - The vault ID this link is for.\n */\nexport async function deriveMagicLinkKEK(\n  serverSecret: string | Uint8Array<ArrayBuffer>,\n  token: string,\n  vault: string,\n): Promise<CryptoKey> {\n  const subtle = globalThis.crypto.subtle\n\n  // IKM: the server secret\n  const ikmBytes =\n    serverSecret instanceof Uint8Array\n      ? serverSecret\n      : new TextEncoder().encode(serverSecret)\n\n  // Salt: SHA-256(token). Hashing the token prevents the salt from being\n  // trivially guessable if the token format is known (ULID has predictable\n  // structure — hashing removes that structure from the HKDF salt).\n  const tokenBytes = new TextEncoder().encode(token)\n  const saltBuffer = await subtle.digest('SHA-256', tokenBytes)\n\n  // Info: \"noydb-magic-link-v1:\" + vaultId — binds the key to a specific\n  // vault so a token for vault A cannot unlock vault B.\n  const info = new TextEncoder().encode(MAGIC_LINK_INFO_PREFIX + vault)\n\n  const ikm = await subtle.importKey('raw', ikmBytes, 'HKDF', false, ['deriveKey'])\n\n  return subtle.deriveKey(\n    {\n      name: 'HKDF',\n      hash: 'SHA-256',\n      salt: saltBuffer,\n      info,\n    },\n    ikm,\n    { name: 'AES-KW', length: 256 },\n    false,\n    ['wrapKey', 'unwrapKey'],\n  )\n}\n\n// ─── Link creation (server-side) ────────────────────────────────────────\n\n/**\n * Generate a magic-link token (server-side).\n *\n * Returns a `MagicLinkToken` whose `token` field should be embedded in\n * the URL sent to the viewer. The server must store the token metadata\n * (or reconstruct it from the URL) so it can:\n *   1. Validate that the token has not expired or been used.\n *   2. Call `deriveMagicLinkKEK()` to create the viewer keyring.\n *\n * @param vault - The vault to grant viewer access to.\n * @param options - Optional TTL configuration.\n */\nexport function createMagicLinkToken(\n  vault: string,\n  options: CreateMagicLinkOptions = {},\n): MagicLinkToken {\n  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS\n  return {\n    token: generateULID(),\n    vault,\n    expiresAt: new Date(Date.now() + ttlMs).toISOString(),\n    role: 'viewer',\n  }\n}\n\n/**\n * Validate that a magic-link token is not expired.\n * Returns `true` if valid, `false` if expired.\n *\n * Single-use enforcement (marking a token as consumed after first use)\n * is the server's responsibility — this function only checks `expiresAt`.\n */\nexport function isMagicLinkValid(linkToken: MagicLinkToken): boolean {\n  return Date.now() <= new Date(linkToken.expiresAt).getTime()\n}\n\n/**\n * Build a stub `UnlockedKeyring` from the magic-link-derived KEK and\n * the viewer's DEK set.\n *\n * This is a thin wrapper for callers that have already:\n *   1. Called `deriveMagicLinkKEK()` to get the viewer KEK.\n *   2. Loaded the viewer's keyring from the adapter (which holds the DEKs\n *      wrapped with the magic-link KEK).\n *   3. Unwrapped the DEKs.\n *\n * The resulting keyring is always viewer-scoped. Callers who want to turn\n * it into a session token should call `createSession()` from\n * `@noy-db/hub/session`.\n */\nexport function buildMagicLinkKeyring(opts: {\n  viewerUserId: string\n  displayName: string\n  deks: Map<string, CryptoKey>\n  kek: CryptoKey\n  salt: Uint8Array\n}): UnlockedKeyring {\n  return {\n    userId: opts.viewerUserId,\n    displayName: opts.displayName,\n    role: 'viewer' as Role,\n    permissions: {},\n    deks: opts.deks,\n    kek: opts.kek,\n    salt: opts.salt,\n  }\n}\n\n// ─── Delegation bridge ─────────────────────────────────────\n\n/**\n * Single grant within a batch magic-link issue. The grantor specifies\n * the tier + scope; the package handles the wrapping. `record` is\n * optional and narrows the grant to a single record id in the\n * collection (leave undefined for a whole-collection grant).\n */\nexport interface MagicLinkGrantSpec {\n  readonly toUser: string\n  readonly tier: number\n  readonly collection?: string\n  readonly record?: string\n  readonly until: Date | string\n  readonly note?: string\n}\n\nexport interface IssueMagicLinkDelegationOptions {\n  /**\n   * Server-held secret that gates access to the grant. Same value must\n   * be supplied at claim time — the server is the only party that\n   * knows it, so a leaked URL alone cannot unlock anything.\n   */\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  /**\n   * One or more grants to persist under the same magic-link token.\n   * Single-element arrays cover the common \"one collection to one\n   * user\" case; multi-element arrays support scoped cross-collection\n   * delegations (e.g. client portal: invoices + payments + etax).\n   */\n  readonly grants: readonly MagicLinkGrantSpec[]\n  /**\n   * Magic-link TTL. Controls `link.expiresAt` (the URL freshness).\n   * Each grant's own `until` bounds the *delegation* lifetime — the\n   * claimant only receives DEKs for grants whose `until` is still\n   * future at claim time. Default 24 h.\n   */\n  readonly ttlMs?: number\n  /**\n   * Optional override for the ULID embedded in the URL. Rarely useful\n   * outside deterministic tests.\n   */\n  readonly token?: string\n}\n\nexport interface IssueMagicLinkDelegationResult {\n  /** URL-embeddable token metadata. Serialize `link.token` into the link. */\n  readonly link: MagicLinkToken\n  /** One record per grant — mirrors the input array order. */\n  readonly grants: ReadonlyArray<{\n    readonly recordId: string\n    readonly payload: MagicLinkGrantPayload\n  }>\n}\n\n/**\n * Issue a magic-link-bound delegation.\n *\n * Server-side workflow:\n *\n * ```ts\n * import { issueMagicLinkDelegation } from '@noy-db/on-magic-link'\n *\n * const { link, grants } = await issueMagicLinkDelegation(vault, {\n *   serverSecret: process.env.MAGIC_LINK_SECRET!,\n *   grants: [\n *     { toUser: 'auditor-bob', tier: 1, collection: 'invoices',\n *       until: new Date(Date.now() + 48*3600e3) },\n *   ],\n *   ttlMs: 48 * 3600 * 1000,\n * })\n *\n * // Embed link.token in an email URL. The grantee clicks → loads your\n * // client → calls claimMagicLinkDelegation() with the same serverSecret.\n * ```\n */\nexport async function issueMagicLinkDelegation(\n  vault: Vault,\n  options: IssueMagicLinkDelegationOptions,\n): Promise<IssueMagicLinkDelegationResult> {\n  if (options.grants.length === 0) {\n    throw new Error('@noy-db/on-magic-link: grants[] must be non-empty')\n  }\n  const token = options.token ?? generateULID()\n  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS\n  const link: MagicLinkToken = {\n    token,\n    vault: vault.name,\n    expiresAt: new Date(Date.now() + ttlMs).toISOString(),\n    role: 'viewer',\n  }\n  const contentKey = await deriveMagicLinkContentKey(options.serverSecret, token, vault.name)\n  const grantKek = await deriveMagicLinkKEK(options.serverSecret, token, vault.name)\n\n  const grants: Array<{ recordId: string; payload: MagicLinkGrantPayload }> = []\n  for (let i = 0; i < options.grants.length; i += 1) {\n    const spec = options.grants[i]!\n    const recordId = magicLinkGrantRecordId(token, i)\n    const issueOpts: IssueMagicLinkGrantOptions = {\n      toUser: spec.toUser,\n      tier: spec.tier,\n      ...(spec.collection !== undefined && { collection: spec.collection }),\n      ...(spec.record !== undefined && { record: spec.record }),\n      until: spec.until,\n      ...(spec.note !== undefined && { note: spec.note }),\n    }\n    const record = await vault.writeMagicLinkGrant(contentKey, grantKek, recordId, issueOpts)\n    grants.push({ recordId: record.recordId, payload: record.payload })\n  }\n  return { link, grants }\n}\n\nexport interface ClaimMagicLinkDelegationOptions {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n  /**\n   * Reference clock used to evaluate grant expiry. Production callers\n   * leave this `undefined`; tests pass a fixed date.\n   */\n  readonly now?: Date\n}\n\nexport interface ClaimedMagicLinkGrant {\n  readonly payload: MagicLinkGrantPayload\n  /** Tier DEK, ready to insert into a keyring map. */\n  readonly dek: CryptoKey\n  /** True when the grant's `until` has already passed. */\n  readonly expired: boolean\n}\n\nexport interface ClaimMagicLinkDelegationResult {\n  /**\n   * False when the server secret is wrong, the vault is wrong, or\n   * every grant is malformed. A `true` with an empty `grants` array\n   * means the record was deleted (revoked) between issue and claim.\n   */\n  readonly valid: boolean\n  readonly grants: readonly ClaimedMagicLinkGrant[]\n}\n\n/**\n * Client-side flow. Derives the same content key + KEK as the grantor,\n * loads every grant persisted under the token (primary + batch\n * entries), and returns the unwrapped tier DEKs.\n *\n * The caller decides what to do with them — typically inserting them\n * into a freshly-built `UnlockedKeyring` (see `buildMagicLinkKeyring`)\n * and opening a viewer session.\n */\nexport async function claimMagicLinkDelegation(\n  options: ClaimMagicLinkDelegationOptions,\n): Promise<ClaimMagicLinkDelegationResult> {\n  const { store, vault, token, serverSecret } = options\n  const contentKey = await deriveMagicLinkContentKey(serverSecret, token, vault)\n  const grantKek = await deriveMagicLinkKEK(serverSecret, token, vault)\n\n  const payloads = await listMagicLinkGrants(store, vault, contentKey, token)\n  if (payloads.length === 0) {\n    // Could be wrong secret / wrong vault / revoked — all indistinguishable.\n    return { valid: false, grants: [] }\n  }\n  const now = options.now ?? new Date()\n  const claimed: ClaimedMagicLinkGrant[] = []\n  for (const payload of payloads) {\n    let dek: CryptoKey\n    try {\n      dek = await unwrapMagicLinkGrant(payload, grantKek)\n    } catch {\n      // Malformed wrappedDek — skip this record but keep the others.\n      continue\n    }\n    claimed.push({\n      payload,\n      dek,\n      expired: isMagicLinkGrantExpired(payload, now),\n    })\n  }\n  return { valid: true, grants: claimed }\n}\n\n/**\n * Read (without unwrapping) the grants under a token — useful for an\n * audit UI that shows the grantor what's still live on a link.\n */\nexport async function inspectMagicLinkDelegation(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n}): Promise<readonly MagicLinkGrantPayload[]> {\n  const contentKey = await deriveMagicLinkContentKey(\n    options.serverSecret,\n    options.token,\n    options.vault,\n  )\n  return listMagicLinkGrants(options.store, options.vault, contentKey, options.token)\n}\n\n/**\n * Delete every grant under a token. Idempotent — safe to call on an\n * already-revoked or never-existed token. Returns the number of\n * records removed.\n */\nexport async function revokeMagicLinkDelegation(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly token: string\n}): Promise<number> {\n  return revokeMagicLinkGrant(options.store, options.vault, options.token)\n}\n\n/**\n * Read a single grant by its full record id. Convenience for callers\n * that persisted `recordId` during issue and want to resolve just one.\n */\nexport async function readMagicLinkGrant(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n  readonly recordId: string\n}): Promise<MagicLinkGrantPayload | null> {\n  const contentKey = await deriveMagicLinkContentKey(\n    options.serverSecret,\n    options.token,\n    options.vault,\n  )\n  return readMagicLinkGrantRecord(options.store, options.vault, contentKey, options.recordId)\n}\n\n// Re-exports so callers don't need a separate @noy-db/hub import for\n// these helpers.\nexport { MAGIC_LINK_GRANTS_COLLECTION, deriveMagicLinkContentKey }\nexport type { MagicLinkGrantPayload }\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,292 @@
+import { NoydbStore, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
+export { MAGIC_LINK_GRANTS_COLLECTION, MagicLinkGrantPayload, deriveMagicLinkContentKey } from '@noy-db/hub';
+
+/**
+ * **@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 ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, deriveMagicLinkKEK, inspectMagicLinkDelegation, isMagicLinkValid, issueMagicLinkDelegation, readMagicLinkGrant, revokeMagicLinkDelegation };

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+import { NoydbStore, MagicLinkGrantPayload, UnlockedKeyring, Vault } from '@noy-db/hub';
+export { MAGIC_LINK_GRANTS_COLLECTION, MagicLinkGrantPayload, deriveMagicLinkContentKey } from '@noy-db/hub';
+
+/**
+ * **@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 ClaimMagicLinkDelegationOptions, type ClaimMagicLinkDelegationResult, type ClaimedMagicLinkGrant, type CreateMagicLinkOptions, type IssueMagicLinkDelegationOptions, type IssueMagicLinkDelegationResult, MAGIC_LINK_DEFAULT_TTL_MS, type MagicLinkGrantSpec, type MagicLinkToken, buildMagicLinkKeyring, claimMagicLinkDelegation, createMagicLinkToken, deriveMagicLinkKEK, inspectMagicLinkDelegation, isMagicLinkValid, issueMagicLinkDelegation, readMagicLinkGrant, revokeMagicLinkDelegation };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/index.ts
+import {
+  generateULID,
+  deriveMagicLinkContentKey,
+  readMagicLinkGrantRecord,
+  listMagicLinkGrants,
+  unwrapMagicLinkGrant,
+  revokeMagicLinkGrant,
+  magicLinkGrantRecordId,
+  isMagicLinkGrantExpired,
+  MAGIC_LINK_GRANTS_COLLECTION
+} from "@noy-db/hub";
+var MAGIC_LINK_INFO_PREFIX = "noydb-magic-link-v1:";
+var MAGIC_LINK_DEFAULT_TTL_MS = 24 * 60 * 60 * 1e3;
+async function deriveMagicLinkKEK(serverSecret, token, vault) {
+  const subtle = globalThis.crypto.subtle;
+  const ikmBytes = serverSecret instanceof Uint8Array ? serverSecret : new TextEncoder().encode(serverSecret);
+  const tokenBytes = new TextEncoder().encode(token);
+  const saltBuffer = await subtle.digest("SHA-256", tokenBytes);
+  const info = new TextEncoder().encode(MAGIC_LINK_INFO_PREFIX + vault);
+  const ikm = await subtle.importKey("raw", ikmBytes, "HKDF", false, ["deriveKey"]);
+  return subtle.deriveKey(
+    {
+      name: "HKDF",
+      hash: "SHA-256",
+      salt: saltBuffer,
+      info
+    },
+    ikm,
+    { name: "AES-KW", length: 256 },
+    false,
+    ["wrapKey", "unwrapKey"]
+  );
+}
+function createMagicLinkToken(vault, options = {}) {
+  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS;
+  return {
+    token: generateULID(),
+    vault,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    role: "viewer"
+  };
+}
+function isMagicLinkValid(linkToken) {
+  return Date.now() <= new Date(linkToken.expiresAt).getTime();
+}
+function buildMagicLinkKeyring(opts) {
+  return {
+    userId: opts.viewerUserId,
+    displayName: opts.displayName,
+    role: "viewer",
+    permissions: {},
+    deks: opts.deks,
+    kek: opts.kek,
+    salt: opts.salt
+  };
+}
+async function issueMagicLinkDelegation(vault, options) {
+  if (options.grants.length === 0) {
+    throw new Error("@noy-db/on-magic-link: grants[] must be non-empty");
+  }
+  const token = options.token ?? generateULID();
+  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS;
+  const link = {
+    token,
+    vault: vault.name,
+    expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+    role: "viewer"
+  };
+  const contentKey = await deriveMagicLinkContentKey(options.serverSecret, token, vault.name);
+  const grantKek = await deriveMagicLinkKEK(options.serverSecret, token, vault.name);
+  const grants = [];
+  for (let i = 0; i < options.grants.length; i += 1) {
+    const spec = options.grants[i];
+    const recordId = magicLinkGrantRecordId(token, i);
+    const issueOpts = {
+      toUser: spec.toUser,
+      tier: spec.tier,
+      ...spec.collection !== void 0 && { collection: spec.collection },
+      ...spec.record !== void 0 && { record: spec.record },
+      until: spec.until,
+      ...spec.note !== void 0 && { note: spec.note }
+    };
+    const record = await vault.writeMagicLinkGrant(contentKey, grantKek, recordId, issueOpts);
+    grants.push({ recordId: record.recordId, payload: record.payload });
+  }
+  return { link, grants };
+}
+async function claimMagicLinkDelegation(options) {
+  const { store, vault, token, serverSecret } = options;
+  const contentKey = await deriveMagicLinkContentKey(serverSecret, token, vault);
+  const grantKek = await deriveMagicLinkKEK(serverSecret, token, vault);
+  const payloads = await listMagicLinkGrants(store, vault, contentKey, token);
+  if (payloads.length === 0) {
+    return { valid: false, grants: [] };
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const claimed = [];
+  for (const payload of payloads) {
+    let dek;
+    try {
+      dek = await unwrapMagicLinkGrant(payload, grantKek);
+    } catch {
+      continue;
+    }
+    claimed.push({
+      payload,
+      dek,
+      expired: isMagicLinkGrantExpired(payload, now)
+    });
+  }
+  return { valid: true, grants: claimed };
+}
+async function inspectMagicLinkDelegation(options) {
+  const contentKey = await deriveMagicLinkContentKey(
+    options.serverSecret,
+    options.token,
+    options.vault
+  );
+  return listMagicLinkGrants(options.store, options.vault, contentKey, options.token);
+}
+async function revokeMagicLinkDelegation(options) {
+  return revokeMagicLinkGrant(options.store, options.vault, options.token);
+}
+async function readMagicLinkGrant(options) {
+  const contentKey = await deriveMagicLinkContentKey(
+    options.serverSecret,
+    options.token,
+    options.vault
+  );
+  return readMagicLinkGrantRecord(options.store, options.vault, contentKey, options.recordId);
+}
+export {
+  MAGIC_LINK_DEFAULT_TTL_MS,
+  MAGIC_LINK_GRANTS_COLLECTION,
+  buildMagicLinkKeyring,
+  claimMagicLinkDelegation,
+  createMagicLinkToken,
+  deriveMagicLinkContentKey,
+  deriveMagicLinkKEK,
+  inspectMagicLinkDelegation,
+  isMagicLinkValid,
+  issueMagicLinkDelegation,
+  readMagicLinkGrant,
+  revokeMagicLinkDelegation
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/on-magic-link** — one-time-link viewer unlock for noy-db.\n *\n * A magic link is a single-use URL that opens a vault in a read-only,\n * viewer-scoped session WITHOUT entering a passphrase. The link\n * expires after use or after a configurable TTL; the resulting\n * session is strictly limited to the `viewer` role.\n *\n * Part of the `@noy-db/on-*` authentication family. Sibling packages:\n * `@noy-db/on-oidc` (federated login), `@noy-db/on-webauthn` (passkey\n * / biometric). All follow the same shape: enrol once, produce a\n * short-lived token, unwrap a viewer keyring at unlock.\n *\n * ## Security model\n *\n * The viewer KEK is derived via:\n *\n * ```\n * HKDF-SHA256(\n *   ikm   = serverSecret,\n *   salt  = sha256(token),\n *   info  = \"noydb-magic-link-v1:\" + vaultId,\n * )\n * ```\n *\n * - `serverSecret` is a server-held secret that the SERVER knows but\n *   is NOT embedded in the link. If the link is intercepted, the\n *   attacker cannot derive the KEK without the server secret.\n * - `token` is a ULID embedded in the URL. It is single-use at the\n *   application layer (the server marks it consumed after first use).\n * - `vaultId` binds the derived key to a specific vault — a token for\n *   vault A cannot be used to unlock vault B.\n *\n * The resulting keyring is ALWAYS viewer-scoped (`role: 'viewer'`).\n * The DEKs available to the viewer are only the collections in the\n * viewer-specific subset, determined by the admin who created the link.\n *\n * ## What this package is NOT\n *\n * This module provides the CRYPTO layer only — it does not:\n *   - Issue HTTP tokens or send emails (that's the application layer)\n *   - Mark tokens as consumed (that's the server's responsibility)\n *   - Store viewer keyrings in the adapter (callers do this via `grant()`)\n *\n * ## Usage\n *\n * ```ts\n * import {\n *   createMagicLinkToken,\n *   deriveMagicLinkKEK,\n *   isMagicLinkValid,\n *   buildMagicLinkKeyring,\n * } from '@noy-db/on-magic-link'\n *\n * // SERVER — mint a token + grant the viewer keyring\n * const token = createMagicLinkToken('company-a', { ttlMs: 24 * 60 * 60 * 1000 })\n * const kek = await deriveMagicLinkKEK(serverSecret, token.token, 'company-a')\n * // ... use kek + db.grant(...) to create a viewer keyring entry ...\n *\n * // Email the link, e.g. https://app.example.com/view?t=<token.token>\n *\n * // CLIENT — derive the same KEK and unlock\n * if (!isMagicLinkValid(token)) throw new Error('expired')\n * const sameKek = await deriveMagicLinkKEK(serverSecret, token.token, token.vault)\n * const keyring = buildMagicLinkKeyring({ ... })\n * ```\n *\n * @packageDocumentation\n */\n\nimport {\n  generateULID,\n  deriveMagicLinkContentKey,\n  readMagicLinkGrantRecord,\n  listMagicLinkGrants,\n  unwrapMagicLinkGrant,\n  revokeMagicLinkGrant,\n  magicLinkGrantRecordId,\n  isMagicLinkGrantExpired,\n  MAGIC_LINK_GRANTS_COLLECTION,\n} from '@noy-db/hub'\nimport type {\n  Role,\n  UnlockedKeyring,\n  Vault,\n  NoydbStore,\n  MagicLinkGrantPayload,\n  IssueMagicLinkGrantOptions,\n} from '@noy-db/hub'\n\n// HKDF info string — version-namespaced so future schemes are distinguishable.\nconst MAGIC_LINK_INFO_PREFIX = 'noydb-magic-link-v1:'\n\n/** Default magic-link TTL: 24 hours. */\nexport const MAGIC_LINK_DEFAULT_TTL_MS = 24 * 60 * 60 * 1000\n\n// ─── Types ──────────────────────────────────────────────────────────────\n\n/**\n * The serializable metadata describing a magic link.\n * Embed `token` in the link URL as a query parameter or path segment.\n */\nexport interface MagicLinkToken {\n  /** Unique one-time token (ULID). Embed this in the URL. */\n  readonly token: string\n  /** The vault this link unlocks (viewer-only). */\n  readonly vault: string\n  /** ISO timestamp after which the link is invalid. */\n  readonly expiresAt: string\n  /** Role of the resulting session. Always `'viewer'` for magic links. */\n  readonly role: 'viewer'\n}\n\n/** Options for `createMagicLinkToken()`. */\nexport interface CreateMagicLinkOptions {\n  /** Link lifetime in milliseconds. Default: 24 hours. */\n  ttlMs?: number\n}\n\n// ─── KEK derivation ─────────────────────────────────────────────────────\n\n/**\n * Derive a viewer KEK from the server secret and the magic-link token.\n *\n * Both the server (at grant time) and the client (at unlock time) call\n * this with the same inputs to get the same key. The key is used to:\n *   - Server: derive the KEK, call `db.grant()` to create a viewer keyring.\n *   - Client: derive the KEK, call `db.openVault()` / `loadKeyring()` with\n *     this KEK directly (bypassing PBKDF2) to unlock the viewer session.\n *\n * @param serverSecret - Server-held secret (never sent to the client).\n * @param token - The ULID from the magic-link URL.\n * @param vault - The vault ID this link is for.\n */\nexport async function deriveMagicLinkKEK(\n  serverSecret: string | Uint8Array<ArrayBuffer>,\n  token: string,\n  vault: string,\n): Promise<CryptoKey> {\n  const subtle = globalThis.crypto.subtle\n\n  // IKM: the server secret\n  const ikmBytes =\n    serverSecret instanceof Uint8Array\n      ? serverSecret\n      : new TextEncoder().encode(serverSecret)\n\n  // Salt: SHA-256(token). Hashing the token prevents the salt from being\n  // trivially guessable if the token format is known (ULID has predictable\n  // structure — hashing removes that structure from the HKDF salt).\n  const tokenBytes = new TextEncoder().encode(token)\n  const saltBuffer = await subtle.digest('SHA-256', tokenBytes)\n\n  // Info: \"noydb-magic-link-v1:\" + vaultId — binds the key to a specific\n  // vault so a token for vault A cannot unlock vault B.\n  const info = new TextEncoder().encode(MAGIC_LINK_INFO_PREFIX + vault)\n\n  const ikm = await subtle.importKey('raw', ikmBytes, 'HKDF', false, ['deriveKey'])\n\n  return subtle.deriveKey(\n    {\n      name: 'HKDF',\n      hash: 'SHA-256',\n      salt: saltBuffer,\n      info,\n    },\n    ikm,\n    { name: 'AES-KW', length: 256 },\n    false,\n    ['wrapKey', 'unwrapKey'],\n  )\n}\n\n// ─── Link creation (server-side) ────────────────────────────────────────\n\n/**\n * Generate a magic-link token (server-side).\n *\n * Returns a `MagicLinkToken` whose `token` field should be embedded in\n * the URL sent to the viewer. The server must store the token metadata\n * (or reconstruct it from the URL) so it can:\n *   1. Validate that the token has not expired or been used.\n *   2. Call `deriveMagicLinkKEK()` to create the viewer keyring.\n *\n * @param vault - The vault to grant viewer access to.\n * @param options - Optional TTL configuration.\n */\nexport function createMagicLinkToken(\n  vault: string,\n  options: CreateMagicLinkOptions = {},\n): MagicLinkToken {\n  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS\n  return {\n    token: generateULID(),\n    vault,\n    expiresAt: new Date(Date.now() + ttlMs).toISOString(),\n    role: 'viewer',\n  }\n}\n\n/**\n * Validate that a magic-link token is not expired.\n * Returns `true` if valid, `false` if expired.\n *\n * Single-use enforcement (marking a token as consumed after first use)\n * is the server's responsibility — this function only checks `expiresAt`.\n */\nexport function isMagicLinkValid(linkToken: MagicLinkToken): boolean {\n  return Date.now() <= new Date(linkToken.expiresAt).getTime()\n}\n\n/**\n * Build a stub `UnlockedKeyring` from the magic-link-derived KEK and\n * the viewer's DEK set.\n *\n * This is a thin wrapper for callers that have already:\n *   1. Called `deriveMagicLinkKEK()` to get the viewer KEK.\n *   2. Loaded the viewer's keyring from the adapter (which holds the DEKs\n *      wrapped with the magic-link KEK).\n *   3. Unwrapped the DEKs.\n *\n * The resulting keyring is always viewer-scoped. Callers who want to turn\n * it into a session token should call `createSession()` from\n * `@noy-db/hub/session`.\n */\nexport function buildMagicLinkKeyring(opts: {\n  viewerUserId: string\n  displayName: string\n  deks: Map<string, CryptoKey>\n  kek: CryptoKey\n  salt: Uint8Array\n}): UnlockedKeyring {\n  return {\n    userId: opts.viewerUserId,\n    displayName: opts.displayName,\n    role: 'viewer' as Role,\n    permissions: {},\n    deks: opts.deks,\n    kek: opts.kek,\n    salt: opts.salt,\n  }\n}\n\n// ─── Delegation bridge ─────────────────────────────────────\n\n/**\n * Single grant within a batch magic-link issue. The grantor specifies\n * the tier + scope; the package handles the wrapping. `record` is\n * optional and narrows the grant to a single record id in the\n * collection (leave undefined for a whole-collection grant).\n */\nexport interface MagicLinkGrantSpec {\n  readonly toUser: string\n  readonly tier: number\n  readonly collection?: string\n  readonly record?: string\n  readonly until: Date | string\n  readonly note?: string\n}\n\nexport interface IssueMagicLinkDelegationOptions {\n  /**\n   * Server-held secret that gates access to the grant. Same value must\n   * be supplied at claim time — the server is the only party that\n   * knows it, so a leaked URL alone cannot unlock anything.\n   */\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  /**\n   * One or more grants to persist under the same magic-link token.\n   * Single-element arrays cover the common \"one collection to one\n   * user\" case; multi-element arrays support scoped cross-collection\n   * delegations (e.g. client portal: invoices + payments + etax).\n   */\n  readonly grants: readonly MagicLinkGrantSpec[]\n  /**\n   * Magic-link TTL. Controls `link.expiresAt` (the URL freshness).\n   * Each grant's own `until` bounds the *delegation* lifetime — the\n   * claimant only receives DEKs for grants whose `until` is still\n   * future at claim time. Default 24 h.\n   */\n  readonly ttlMs?: number\n  /**\n   * Optional override for the ULID embedded in the URL. Rarely useful\n   * outside deterministic tests.\n   */\n  readonly token?: string\n}\n\nexport interface IssueMagicLinkDelegationResult {\n  /** URL-embeddable token metadata. Serialize `link.token` into the link. */\n  readonly link: MagicLinkToken\n  /** One record per grant — mirrors the input array order. */\n  readonly grants: ReadonlyArray<{\n    readonly recordId: string\n    readonly payload: MagicLinkGrantPayload\n  }>\n}\n\n/**\n * Issue a magic-link-bound delegation.\n *\n * Server-side workflow:\n *\n * ```ts\n * import { issueMagicLinkDelegation } from '@noy-db/on-magic-link'\n *\n * const { link, grants } = await issueMagicLinkDelegation(vault, {\n *   serverSecret: process.env.MAGIC_LINK_SECRET!,\n *   grants: [\n *     { toUser: 'auditor-bob', tier: 1, collection: 'invoices',\n *       until: new Date(Date.now() + 48*3600e3) },\n *   ],\n *   ttlMs: 48 * 3600 * 1000,\n * })\n *\n * // Embed link.token in an email URL. The grantee clicks → loads your\n * // client → calls claimMagicLinkDelegation() with the same serverSecret.\n * ```\n */\nexport async function issueMagicLinkDelegation(\n  vault: Vault,\n  options: IssueMagicLinkDelegationOptions,\n): Promise<IssueMagicLinkDelegationResult> {\n  if (options.grants.length === 0) {\n    throw new Error('@noy-db/on-magic-link: grants[] must be non-empty')\n  }\n  const token = options.token ?? generateULID()\n  const ttlMs = options.ttlMs ?? MAGIC_LINK_DEFAULT_TTL_MS\n  const link: MagicLinkToken = {\n    token,\n    vault: vault.name,\n    expiresAt: new Date(Date.now() + ttlMs).toISOString(),\n    role: 'viewer',\n  }\n  const contentKey = await deriveMagicLinkContentKey(options.serverSecret, token, vault.name)\n  const grantKek = await deriveMagicLinkKEK(options.serverSecret, token, vault.name)\n\n  const grants: Array<{ recordId: string; payload: MagicLinkGrantPayload }> = []\n  for (let i = 0; i < options.grants.length; i += 1) {\n    const spec = options.grants[i]!\n    const recordId = magicLinkGrantRecordId(token, i)\n    const issueOpts: IssueMagicLinkGrantOptions = {\n      toUser: spec.toUser,\n      tier: spec.tier,\n      ...(spec.collection !== undefined && { collection: spec.collection }),\n      ...(spec.record !== undefined && { record: spec.record }),\n      until: spec.until,\n      ...(spec.note !== undefined && { note: spec.note }),\n    }\n    const record = await vault.writeMagicLinkGrant(contentKey, grantKek, recordId, issueOpts)\n    grants.push({ recordId: record.recordId, payload: record.payload })\n  }\n  return { link, grants }\n}\n\nexport interface ClaimMagicLinkDelegationOptions {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n  /**\n   * Reference clock used to evaluate grant expiry. Production callers\n   * leave this `undefined`; tests pass a fixed date.\n   */\n  readonly now?: Date\n}\n\nexport interface ClaimedMagicLinkGrant {\n  readonly payload: MagicLinkGrantPayload\n  /** Tier DEK, ready to insert into a keyring map. */\n  readonly dek: CryptoKey\n  /** True when the grant's `until` has already passed. */\n  readonly expired: boolean\n}\n\nexport interface ClaimMagicLinkDelegationResult {\n  /**\n   * False when the server secret is wrong, the vault is wrong, or\n   * every grant is malformed. A `true` with an empty `grants` array\n   * means the record was deleted (revoked) between issue and claim.\n   */\n  readonly valid: boolean\n  readonly grants: readonly ClaimedMagicLinkGrant[]\n}\n\n/**\n * Client-side flow. Derives the same content key + KEK as the grantor,\n * loads every grant persisted under the token (primary + batch\n * entries), and returns the unwrapped tier DEKs.\n *\n * The caller decides what to do with them — typically inserting them\n * into a freshly-built `UnlockedKeyring` (see `buildMagicLinkKeyring`)\n * and opening a viewer session.\n */\nexport async function claimMagicLinkDelegation(\n  options: ClaimMagicLinkDelegationOptions,\n): Promise<ClaimMagicLinkDelegationResult> {\n  const { store, vault, token, serverSecret } = options\n  const contentKey = await deriveMagicLinkContentKey(serverSecret, token, vault)\n  const grantKek = await deriveMagicLinkKEK(serverSecret, token, vault)\n\n  const payloads = await listMagicLinkGrants(store, vault, contentKey, token)\n  if (payloads.length === 0) {\n    // Could be wrong secret / wrong vault / revoked — all indistinguishable.\n    return { valid: false, grants: [] }\n  }\n  const now = options.now ?? new Date()\n  const claimed: ClaimedMagicLinkGrant[] = []\n  for (const payload of payloads) {\n    let dek: CryptoKey\n    try {\n      dek = await unwrapMagicLinkGrant(payload, grantKek)\n    } catch {\n      // Malformed wrappedDek — skip this record but keep the others.\n      continue\n    }\n    claimed.push({\n      payload,\n      dek,\n      expired: isMagicLinkGrantExpired(payload, now),\n    })\n  }\n  return { valid: true, grants: claimed }\n}\n\n/**\n * Read (without unwrapping) the grants under a token — useful for an\n * audit UI that shows the grantor what's still live on a link.\n */\nexport async function inspectMagicLinkDelegation(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n}): Promise<readonly MagicLinkGrantPayload[]> {\n  const contentKey = await deriveMagicLinkContentKey(\n    options.serverSecret,\n    options.token,\n    options.vault,\n  )\n  return listMagicLinkGrants(options.store, options.vault, contentKey, options.token)\n}\n\n/**\n * Delete every grant under a token. Idempotent — safe to call on an\n * already-revoked or never-existed token. Returns the number of\n * records removed.\n */\nexport async function revokeMagicLinkDelegation(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly token: string\n}): Promise<number> {\n  return revokeMagicLinkGrant(options.store, options.vault, options.token)\n}\n\n/**\n * Read a single grant by its full record id. Convenience for callers\n * that persisted `recordId` during issue and want to resolve just one.\n */\nexport async function readMagicLinkGrant(options: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly serverSecret: string | Uint8Array<ArrayBuffer>\n  readonly token: string\n  readonly recordId: string\n}): Promise<MagicLinkGrantPayload | null> {\n  const contentKey = await deriveMagicLinkContentKey(\n    options.serverSecret,\n    options.token,\n    options.vault,\n  )\n  return readMagicLinkGrantRecord(options.store, options.vault, contentKey, options.recordId)\n}\n\n// Re-exports so callers don't need a separate @noy-db/hub import for\n// these helpers.\nexport { MAGIC_LINK_GRANTS_COLLECTION, deriveMagicLinkContentKey }\nexport type { MagicLinkGrantPayload }\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@noy-db/on-magic-link",
+  "version": "0.1.0-pre.3",
+  "description": "Magic-link unlock for noy-db — one-time URL that opens a vault in a viewer-scoped session without a passphrase. Part of the @noy-db/on-* authentication family.",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/on-magic-link#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/on-magic-link"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "devDependencies": {
+    "@noy-db/hub": "0.1.0-pre.3"
+  },
+  "keywords": [
+    "noy-db",
+    "auth",
+    "on-magic-link",
+    "magic-link",
+    "passwordless",
+    "viewer-portal",
+    "one-time-token",
+    "encryption",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}