@noy-db/at-macos-keychain 0.2.0-pre.9 → 0.3.0-pre.1

package/README.md

@@ -57,7 +57,7 @@ const vault = db.vault('acme')
 macos-keychain:<service>/<account>
 ```
 
-E.g., `macos-keychain:com.acme.app/alice@acme.example`. This format is **frozen** per the [sealing pid stability rule](../../docs/subsystems/sealing-pid-stability.md) — once shipped, it never changes. The hub uses it as the dispatch key when reading an existing `_meta/sealed-passphrase` envelope.
+E.g., `macos-keychain:com.acme.app/alice@acme.example`. This format is **frozen** per the [sealing pid stability rule](https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/sealing-pid-stability.md) — once shipped, it never changes. The hub uses it as the dispatch key when reading an existing `_meta/sealed-passphrase` envelope.
 
 ## Touch ID
 
@@ -137,7 +137,7 @@ For real-Keychain integration tests on darwin CI runners, leave `entry` undefine
 - [`@noy-db/at-env`](../at-env) — env-var sealing for server / container deployments.
 - [`@noy-db/hub`](../hub) — the database core that consumes `SealingKeyProvider`.
 - [Foundation doc — at-* sealing dimension](../../docs/superpowers/specs/2026-05-23-sealing-at-dimension-foundation.md)
-- [Sealing pid stability rule](../../docs/subsystems/sealing-pid-stability.md)
+- [Sealing pid stability rule](https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/sealing-pid-stability.md)
 
 ## License
 

package/dist/index.d.ts

@@ -140,7 +140,7 @@ interface MacosKeychainSealingProviderOptions {
  *
  * Provider `id` format: `macos-keychain:{service}/{account}`. The
  * format is semver-frozen per the §11.9.1 stability rule; see
- * `docs/subsystems/sealing-pid-stability.md`.
+ * `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/sealing-pid-stability.md`.
  *
  * @throws Error at construction if `service` or `account` is empty,
  *   or on non-darwin platforms (with a pointer to platform-appropriate

package/dist/index.js

@@ -1,11 +1,6 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/index.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
 function macosKeychainSealingProvider(opts) {
   if (!opts.service || typeof opts.service !== "string") {
     throw new Error(
@@ -27,7 +22,7 @@ function macosKeychainSealingProvider(opts) {
     if (resolvedEntry) return resolvedEntry;
     let Entry;
     try {
-      const mod = __require("@napi-rs/keyring");
+      const mod = require2("@napi-rs/keyring");
       Entry = mod.Entry;
     } catch (err) {
       throw new Error(

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/at-macos-keychain** — macOS Keychain sealing key provider\n * for noy-db [managed-passphrase mode](https://github.com/vLannaAi/noy-db/issues/14).\n *\n * Desktop-app provider in the `at-*` family. Binds the sealing key to\n * the user's macOS login Keychain — accessible only to processes\n * running as the same user, optionally gated by Touch ID via Keychain\n * Access UI (a one-time per-entry toggle the user enables themselves;\n * this package does not gate that programmatically).\n *\n * ## When to use\n *\n * - Desktop apps where the user expects \"log into my Mac = open the\n *   vault.\" The Keychain entry persists across reboots, scoped to\n *   the user account.\n * - Apps where `at-env` is unsuitable — laptops or shared dev machines\n *   where other users with shell access can `echo $NOYDB_SEALING_KEY`\n *   and exfiltrate the key.\n *\n * ## When NOT to use\n *\n * - Server-side / containerized deployments — there is no Keychain\n *   there. Use `@noy-db/at-env` or `@noy-db/at-aws-kms` (when it\n *   ships).\n * - Browser apps — Keychain is a native OS feature, not exposed to\n *   browser sandboxes. Use `@noy-db/at-webauthn-prf` (when it ships).\n *\n * ## Setup\n *\n * ```bash\n * pnpm add @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring\n * ```\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { macosKeychainSealingProvider } from '@noy-db/at-macos-keychain'\n *\n * const db = await createNoydb({\n *   store,\n *   user: 'alice',\n *   passphraseMode: 'managed',\n *   sealingKey: macosKeychainSealingProvider({\n *     service: 'com.acme.app',         // your bundle id / app namespace\n *     account: 'alice@acme.example',   // per-user keychain item\n *   }),\n * })\n * ```\n *\n * First call generates a fresh 32-byte AES-256 key, stores it in the\n * Keychain under `(service, account)`, and uses it to seal the\n * hub-generated managed passphrase. Subsequent process launches\n * retrieve the same key and unseal transparently.\n *\n * ## Threat model\n *\n * The Keychain entry IS the security boundary. Strength bounded by:\n *\n * - **macOS user-account isolation.** Other processes running as the\n *   same user can read the entry. macOS App Sandboxing limits this\n *   for App Store apps; unsandboxed apps must trust co-resident\n *   processes.\n * - **Login keychain lock state.** When the user's login keychain\n *   is locked (default: never, unless explicitly configured), reads\n *   surface a prompt or fail. Apps that need to operate when the\n *   keychain is locked should consider explicit unlock UX.\n * - **Touch ID upgrade.** Users may add Touch ID gating to the\n *   Keychain entry via Keychain Access.app → right-click → Get Info\n *   → Access Control. This is opt-in per entry and out of band of\n *   this package's API.\n *\n * Does NOT protect against:\n *\n * - Malware running as the same user with Keychain access.\n * - A physically present attacker who knows the user's login\n *   password and can unlock the keychain.\n * - macOS itself being compromised below the Keychain Services\n *   layer.\n *\n * @packageDocumentation\n */\n\nimport type { SealingKeyProvider } from '@noy-db/hub'\n\n/**\n * Structural shape of `@napi-rs/keyring`'s `Entry` class.\n *\n * Defined here as a structural type rather than importing the\n * concrete class so that:\n *\n *   1. Test code can inject a memory-backed stub for cross-platform\n *      unit tests (the real Entry only works on darwin/win32/linux).\n *   2. We don't pin a specific version of `@napi-rs/keyring`'s\n *      exported types — the structural match is exact across 1.x.\n *\n * @public\n */\nexport interface KeychainEntry {\n  /** Returns the stored secret, or `null` when no entry exists. */\n  getPassword(): string | null\n  /** Persists the secret. Overwrites any existing value. */\n  setPassword(value: string): void\n  /** Removes the entry. Returns `true` if an entry was removed. */\n  deletePassword(): boolean\n}\n\n/**\n * Options for {@link macosKeychainSealingProvider}.\n *\n * The pair `(service, account)` becomes the Keychain lookup key. By\n * convention:\n *\n * - `service` is your app's bundle id or stable app namespace, e.g.\n *   `'com.acme.app'`. Stable across users; identifies the app.\n * - `account` is per-user, typically the user's email or stable\n *   user id, e.g. `'alice@acme.example'`. Different users = different\n *   Keychain entries.\n */\nexport interface MacosKeychainSealingProviderOptions {\n  /** Keychain service identifier — typically your app's bundle id. */\n  readonly service: string\n  /** Per-user account identifier inside the service. */\n  readonly account: string\n  /**\n   * Test-injection hook. Pass a pre-constructed `KeychainEntry`\n   * (e.g., a memory-backed stub) to bypass the real Keychain. The\n   * production code path defaults to `new Entry(service, account)`\n   * from `@napi-rs/keyring`.\n   *\n   * @internal — production callers should leave undefined.\n   */\n  readonly entry?: KeychainEntry\n}\n\n/**\n * Build a {@link SealingKeyProvider} backed by a macOS Keychain entry.\n *\n * The 32-byte AES-256-GCM sealing key is generated on first use and\n * persisted in the Keychain under `(service, account)`. Subsequent\n * calls (this process or any future process running as the same\n * user) retrieve the same key — the vault round-trips across\n * restarts.\n *\n * Provider `id` format: `macos-keychain:{service}/{account}`. The\n * format is semver-frozen per the §11.9.1 stability rule; see\n * `docs/subsystems/sealing-pid-stability.md`.\n *\n * @throws Error at construction if `service` or `account` is empty,\n *   or on non-darwin platforms (with a pointer to platform-appropriate\n *   providers).\n */\nexport function macosKeychainSealingProvider(\n  opts: MacosKeychainSealingProviderOptions,\n): SealingKeyProvider {\n  if (!opts.service || typeof opts.service !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `service` is required, must be a non-empty string. '\n      + 'Typically your app bundle id (e.g., \"com.acme.app\").',\n    )\n  }\n  if (!opts.account || typeof opts.account !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `account` is required, must be a non-empty string. '\n      + 'Typically the user\\'s email or stable user id (e.g., \"alice@acme.example\").',\n    )\n  }\n\n  // Hard platform check unless the caller supplied a test stub.\n  // Per §11.9.1 spec Q.3: fail loudly on the wrong platform.\n  if (opts.entry === undefined && process.platform !== 'darwin') {\n    throw new Error(\n      `@noy-db/at-macos-keychain: refusing to construct provider on `\n      + `platform \"${process.platform}\". This package only operates on `\n      + 'darwin (macOS). For other platforms use @noy-db/at-env (server), '\n      + '@noy-db/at-wincred (Windows desktop), @noy-db/at-libsecret (Linux desktop), '\n      + 'or @noy-db/at-webauthn-prf (browser).',\n    )\n  }\n\n  // Resolved lazily so that production callers don't pay the require\n  // cost (or fail loudly on wrong platform) until they actually invoke\n  // seal/unseal. Construction-site failure of new Entry() on unsupported\n  // platforms is caught and rethrown with a clearer message.\n  let resolvedEntry: KeychainEntry | undefined = opts.entry\n  const getEntry = (): KeychainEntry => {\n    if (resolvedEntry) return resolvedEntry\n    // Dynamic require so non-darwin imports don't crash on package load.\n    // The platform check above guards production callers; this branch\n    // only runs for production (opts.entry was undefined) on darwin.\n    /* eslint-disable @typescript-eslint/no-require-imports */\n    let Entry: new (service: string, account: string) => KeychainEntry\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const mod = require('@napi-rs/keyring') as { Entry: any }\n      Entry = mod.Entry\n    } catch (err) {\n      throw new Error(\n        '@noy-db/at-macos-keychain: failed to load `@napi-rs/keyring`. '\n        + 'Ensure it is installed (`pnpm add @napi-rs/keyring`) and that '\n        + 'the platform-specific binary for darwin is available. '\n        + 'Original error: '\n        + (err instanceof Error ? err.message : String(err)),\n      )\n    }\n    /* eslint-enable */\n    resolvedEntry = new Entry(opts.service, opts.account)\n    return resolvedEntry\n  }\n\n  // Cache the imported CryptoKey for the lifetime of this provider\n  // instance. Matches at-env's pattern; avoids a Keychain round-trip\n  // per seal/unseal operation in long-running processes.\n  let cachedKey: Promise<CryptoKey> | null = null\n  const getKey = (): Promise<CryptoKey> => {\n    if (!cachedKey) {\n      cachedKey = (async (): Promise<CryptoKey> => {\n        const entry = getEntry()\n        let stored = entry.getPassword()\n        if (stored === null) {\n          // First call ever for this (service, account) — generate a\n          // fresh 32-byte AES-256 key, base64-encode for string\n          // storage, persist.\n          const fresh = new Uint8Array(32)\n          globalThis.crypto.getRandomValues(fresh)\n          entry.setPassword(bytesToBase64(fresh))\n          stored = entry.getPassword()\n          if (stored === null) {\n            throw new Error(\n              '@noy-db/at-macos-keychain: setPassword succeeded but '\n              + 'getPassword returned null immediately after. '\n              + 'Keychain may be denying access or the entry was '\n              + 'deleted out from under us.',\n            )\n          }\n        }\n        const keyBytes = base64ToBytes(stored)\n        if (keyBytes.length !== 32) {\n          throw new Error(\n            `@noy-db/at-macos-keychain: stored key for service=\"${opts.service}\" `\n            + `account=\"${opts.account}\" decodes to ${keyBytes.length} bytes; `\n            + 'expected 32. The Keychain entry may have been tampered with — '\n            + 'delete the entry (Keychain Access.app → search → right-click → Delete) '\n            + 'and reopen the vault to regenerate.',\n          )\n        }\n        return globalThis.crypto.subtle.importKey(\n          'raw',\n          keyBytes as unknown as BufferSource,\n          'AES-GCM',\n          false,\n          ['encrypt', 'decrypt'],\n        )\n      })()\n    }\n    return cachedKey\n  }\n\n  return {\n    id: `macos-keychain:${opts.service}/${opts.account}`,\n\n    async seal(passphrase: Uint8Array): Promise<Uint8Array> {\n      const key = await getKey()\n      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))\n      const ciphertext = await globalThis.crypto.subtle.encrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        passphrase as unknown as BufferSource,\n      )\n      // Output format: [12-byte IV][ciphertext + 16-byte GCM tag]\n      // Identical wire layout to at-env, by design — the hub envelope\n      // dispatches on pid, not on per-provider format.\n      const out = new Uint8Array(12 + ciphertext.byteLength)\n      out.set(iv, 0)\n      out.set(new Uint8Array(ciphertext), 12)\n      return out\n    },\n\n    async unseal(sealed: Uint8Array): Promise<Uint8Array> {\n      // 12-byte IV + ≥ 16-byte GCM tag minimum.\n      if (sealed.length < 12 + 16) {\n        throw new Error(\n          `@noy-db/at-macos-keychain: sealed bytes too short (${sealed.length} < 28). `\n          + 'Input is not a valid at-macos-keychain-sealed envelope.',\n        )\n      }\n      const iv = sealed.subarray(0, 12)\n      const body = sealed.subarray(12)\n      const key = await getKey()\n      const plaintext = await globalThis.crypto.subtle.decrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        body as unknown as BufferSource,\n      )\n      return new Uint8Array(plaintext)\n    },\n  }\n}\n\n// ─── base64 helpers (browser + node compatible) ──────────────────────────\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!)\n  return btoa(binary)\n}\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {\n    throw new Error('input contains characters outside the base64 alphabet')\n  }\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\n  return out\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/at-macos-keychain** — macOS Keychain sealing key provider\n * for noy-db [managed-passphrase mode](https://github.com/vLannaAi/noy-db/issues/14).\n *\n * Desktop-app provider in the `at-*` family. Binds the sealing key to\n * the user's macOS login Keychain — accessible only to processes\n * running as the same user, optionally gated by Touch ID via Keychain\n * Access UI (a one-time per-entry toggle the user enables themselves;\n * this package does not gate that programmatically).\n *\n * ## When to use\n *\n * - Desktop apps where the user expects \"log into my Mac = open the\n *   vault.\" The Keychain entry persists across reboots, scoped to\n *   the user account.\n * - Apps where `at-env` is unsuitable — laptops or shared dev machines\n *   where other users with shell access can `echo $NOYDB_SEALING_KEY`\n *   and exfiltrate the key.\n *\n * ## When NOT to use\n *\n * - Server-side / containerized deployments — there is no Keychain\n *   there. Use `@noy-db/at-env` or `@noy-db/at-aws-kms` (when it\n *   ships).\n * - Browser apps — Keychain is a native OS feature, not exposed to\n *   browser sandboxes. Use `@noy-db/at-webauthn-prf` (when it ships).\n *\n * ## Setup\n *\n * ```bash\n * pnpm add @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring\n * ```\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { macosKeychainSealingProvider } from '@noy-db/at-macos-keychain'\n *\n * const db = await createNoydb({\n *   store,\n *   user: 'alice',\n *   passphraseMode: 'managed',\n *   sealingKey: macosKeychainSealingProvider({\n *     service: 'com.acme.app',         // your bundle id / app namespace\n *     account: 'alice@acme.example',   // per-user keychain item\n *   }),\n * })\n * ```\n *\n * First call generates a fresh 32-byte AES-256 key, stores it in the\n * Keychain under `(service, account)`, and uses it to seal the\n * hub-generated managed passphrase. Subsequent process launches\n * retrieve the same key and unseal transparently.\n *\n * ## Threat model\n *\n * The Keychain entry IS the security boundary. Strength bounded by:\n *\n * - **macOS user-account isolation.** Other processes running as the\n *   same user can read the entry. macOS App Sandboxing limits this\n *   for App Store apps; unsandboxed apps must trust co-resident\n *   processes.\n * - **Login keychain lock state.** When the user's login keychain\n *   is locked (default: never, unless explicitly configured), reads\n *   surface a prompt or fail. Apps that need to operate when the\n *   keychain is locked should consider explicit unlock UX.\n * - **Touch ID upgrade.** Users may add Touch ID gating to the\n *   Keychain entry via Keychain Access.app → right-click → Get Info\n *   → Access Control. This is opt-in per entry and out of band of\n *   this package's API.\n *\n * Does NOT protect against:\n *\n * - Malware running as the same user with Keychain access.\n * - A physically present attacker who knows the user's login\n *   password and can unlock the keychain.\n * - macOS itself being compromised below the Keychain Services\n *   layer.\n *\n * @packageDocumentation\n */\n\nimport { createRequire } from 'node:module'\n\nimport type { SealingKeyProvider } from '@noy-db/hub'\n\n// ESM has no ambient `require`. Synthesize one bound to this module's URL so\n// the native `@napi-rs/keyring` addon (a CJS-only N-API binary) can still be\n// lazily loaded on darwin. This package is Node/darwin-only by definition, so\n// node:module is always available here.\nconst require = createRequire(import.meta.url)\n\n/**\n * Structural shape of `@napi-rs/keyring`'s `Entry` class.\n *\n * Defined here as a structural type rather than importing the\n * concrete class so that:\n *\n *   1. Test code can inject a memory-backed stub for cross-platform\n *      unit tests (the real Entry only works on darwin/win32/linux).\n *   2. We don't pin a specific version of `@napi-rs/keyring`'s\n *      exported types — the structural match is exact across 1.x.\n *\n * @public\n */\nexport interface KeychainEntry {\n  /** Returns the stored secret, or `null` when no entry exists. */\n  getPassword(): string | null\n  /** Persists the secret. Overwrites any existing value. */\n  setPassword(value: string): void\n  /** Removes the entry. Returns `true` if an entry was removed. */\n  deletePassword(): boolean\n}\n\n/**\n * Options for {@link macosKeychainSealingProvider}.\n *\n * The pair `(service, account)` becomes the Keychain lookup key. By\n * convention:\n *\n * - `service` is your app's bundle id or stable app namespace, e.g.\n *   `'com.acme.app'`. Stable across users; identifies the app.\n * - `account` is per-user, typically the user's email or stable\n *   user id, e.g. `'alice@acme.example'`. Different users = different\n *   Keychain entries.\n */\nexport interface MacosKeychainSealingProviderOptions {\n  /** Keychain service identifier — typically your app's bundle id. */\n  readonly service: string\n  /** Per-user account identifier inside the service. */\n  readonly account: string\n  /**\n   * Test-injection hook. Pass a pre-constructed `KeychainEntry`\n   * (e.g., a memory-backed stub) to bypass the real Keychain. The\n   * production code path defaults to `new Entry(service, account)`\n   * from `@napi-rs/keyring`.\n   *\n   * @internal — production callers should leave undefined.\n   */\n  readonly entry?: KeychainEntry\n}\n\n/**\n * Build a {@link SealingKeyProvider} backed by a macOS Keychain entry.\n *\n * The 32-byte AES-256-GCM sealing key is generated on first use and\n * persisted in the Keychain under `(service, account)`. Subsequent\n * calls (this process or any future process running as the same\n * user) retrieve the same key — the vault round-trips across\n * restarts.\n *\n * Provider `id` format: `macos-keychain:{service}/{account}`. The\n * format is semver-frozen per the §11.9.1 stability rule; see\n * `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/sealing-pid-stability.md`.\n *\n * @throws Error at construction if `service` or `account` is empty,\n *   or on non-darwin platforms (with a pointer to platform-appropriate\n *   providers).\n */\nexport function macosKeychainSealingProvider(\n  opts: MacosKeychainSealingProviderOptions,\n): SealingKeyProvider {\n  if (!opts.service || typeof opts.service !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `service` is required, must be a non-empty string. '\n      + 'Typically your app bundle id (e.g., \"com.acme.app\").',\n    )\n  }\n  if (!opts.account || typeof opts.account !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `account` is required, must be a non-empty string. '\n      + 'Typically the user\\'s email or stable user id (e.g., \"alice@acme.example\").',\n    )\n  }\n\n  // Hard platform check unless the caller supplied a test stub.\n  // Per §11.9.1 spec Q.3: fail loudly on the wrong platform.\n  if (opts.entry === undefined && process.platform !== 'darwin') {\n    throw new Error(\n      `@noy-db/at-macos-keychain: refusing to construct provider on `\n      + `platform \"${process.platform}\". This package only operates on `\n      + 'darwin (macOS). For other platforms use @noy-db/at-env (server), '\n      + '@noy-db/at-wincred (Windows desktop), @noy-db/at-libsecret (Linux desktop), '\n      + 'or @noy-db/at-webauthn-prf (browser).',\n    )\n  }\n\n  // Resolved lazily so that production callers don't pay the require\n  // cost (or fail loudly on wrong platform) until they actually invoke\n  // seal/unseal. Construction-site failure of new Entry() on unsupported\n  // platforms is caught and rethrown with a clearer message.\n  let resolvedEntry: KeychainEntry | undefined = opts.entry\n  const getEntry = (): KeychainEntry => {\n    if (resolvedEntry) return resolvedEntry\n    // Dynamic require so non-darwin imports don't crash on package load.\n    // The platform check above guards production callers; this branch\n    // only runs for production (opts.entry was undefined) on darwin.\n    /* eslint-disable @typescript-eslint/no-require-imports */\n    let Entry: new (service: string, account: string) => KeychainEntry\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const mod = require('@napi-rs/keyring') as { Entry: any }\n      Entry = mod.Entry\n    } catch (err) {\n      throw new Error(\n        '@noy-db/at-macos-keychain: failed to load `@napi-rs/keyring`. '\n        + 'Ensure it is installed (`pnpm add @napi-rs/keyring`) and that '\n        + 'the platform-specific binary for darwin is available. '\n        + 'Original error: '\n        + (err instanceof Error ? err.message : String(err)),\n      )\n    }\n    /* eslint-enable */\n    resolvedEntry = new Entry(opts.service, opts.account)\n    return resolvedEntry\n  }\n\n  // Cache the imported CryptoKey for the lifetime of this provider\n  // instance. Matches at-env's pattern; avoids a Keychain round-trip\n  // per seal/unseal operation in long-running processes.\n  let cachedKey: Promise<CryptoKey> | null = null\n  const getKey = (): Promise<CryptoKey> => {\n    if (!cachedKey) {\n      cachedKey = (async (): Promise<CryptoKey> => {\n        const entry = getEntry()\n        let stored = entry.getPassword()\n        if (stored === null) {\n          // First call ever for this (service, account) — generate a\n          // fresh 32-byte AES-256 key, base64-encode for string\n          // storage, persist.\n          const fresh = new Uint8Array(32)\n          globalThis.crypto.getRandomValues(fresh)\n          entry.setPassword(bytesToBase64(fresh))\n          stored = entry.getPassword()\n          if (stored === null) {\n            throw new Error(\n              '@noy-db/at-macos-keychain: setPassword succeeded but '\n              + 'getPassword returned null immediately after. '\n              + 'Keychain may be denying access or the entry was '\n              + 'deleted out from under us.',\n            )\n          }\n        }\n        const keyBytes = base64ToBytes(stored)\n        if (keyBytes.length !== 32) {\n          throw new Error(\n            `@noy-db/at-macos-keychain: stored key for service=\"${opts.service}\" `\n            + `account=\"${opts.account}\" decodes to ${keyBytes.length} bytes; `\n            + 'expected 32. The Keychain entry may have been tampered with — '\n            + 'delete the entry (Keychain Access.app → search → right-click → Delete) '\n            + 'and reopen the vault to regenerate.',\n          )\n        }\n        return globalThis.crypto.subtle.importKey(\n          'raw',\n          keyBytes as unknown as BufferSource,\n          'AES-GCM',\n          false,\n          ['encrypt', 'decrypt'],\n        )\n      })()\n    }\n    return cachedKey\n  }\n\n  return {\n    id: `macos-keychain:${opts.service}/${opts.account}`,\n\n    async seal(passphrase: Uint8Array): Promise<Uint8Array> {\n      const key = await getKey()\n      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))\n      const ciphertext = await globalThis.crypto.subtle.encrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        passphrase as unknown as BufferSource,\n      )\n      // Output format: [12-byte IV][ciphertext + 16-byte GCM tag]\n      // Identical wire layout to at-env, by design — the hub envelope\n      // dispatches on pid, not on per-provider format.\n      const out = new Uint8Array(12 + ciphertext.byteLength)\n      out.set(iv, 0)\n      out.set(new Uint8Array(ciphertext), 12)\n      return out\n    },\n\n    async unseal(sealed: Uint8Array): Promise<Uint8Array> {\n      // 12-byte IV + ≥ 16-byte GCM tag minimum.\n      if (sealed.length < 12 + 16) {\n        throw new Error(\n          `@noy-db/at-macos-keychain: sealed bytes too short (${sealed.length} < 28). `\n          + 'Input is not a valid at-macos-keychain-sealed envelope.',\n        )\n      }\n      const iv = sealed.subarray(0, 12)\n      const body = sealed.subarray(12)\n      const key = await getKey()\n      const plaintext = await globalThis.crypto.subtle.decrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        body as unknown as BufferSource,\n      )\n      return new Uint8Array(plaintext)\n    },\n  }\n}\n\n// ─── base64 helpers (browser + node compatible) ──────────────────────────\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!)\n  return btoa(binary)\n}\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {\n    throw new Error('input contains characters outside the base64 alphabet')\n  }\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\n  return out\n}\n"],"mappings":"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","names":["require"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noy-db/at-macos-keychain",
-  "version": "0.2.0-pre.9",
+  "version": "0.3.0-pre.1",
   "description": "macOS Keychain sealing key provider for noy-db managed-passphrase mode — AES-256-GCM under a 32-byte key stored in the user's login Keychain. Desktop-app provider in the at-* family; pairs with Touch ID via Keychain Access UI.",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
@@ -17,17 +17,10 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -39,11 +32,11 @@
     "darwin"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
     "@napi-rs/keyring": "^1.1.0",
-    "@noy-db/hub": "0.2.0-pre.9"
+    "@noy-db/hub": "0.3.0-pre.1"
   },
   "peerDependenciesMeta": {
     "@napi-rs/keyring": {
@@ -53,9 +46,9 @@
   "devDependencies": {
     "@napi-rs/keyring": "^1.1.0",
     "@types/node": "^22.0.0",
-    "@noy-db/on-shamir": "0.2.0-pre.9",
-    "@noy-db/hub": "0.2.0-pre.9",
-    "@noy-db/to-memory": "0.2.0-pre.9"
+    "@noy-db/on-shamir": "0.3.0-pre.1",
+    "@noy-db/hub": "0.3.0-pre.1",
+    "@noy-db/to-memory": "0.3.0-pre.1"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,142 +0,0 @@
-"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, {
-  macosKeychainSealingProvider: () => macosKeychainSealingProvider
-});
-module.exports = __toCommonJS(index_exports);
-function macosKeychainSealingProvider(opts) {
-  if (!opts.service || typeof opts.service !== "string") {
-    throw new Error(
-      '@noy-db/at-macos-keychain: `service` is required, must be a non-empty string. Typically your app bundle id (e.g., "com.acme.app").'
-    );
-  }
-  if (!opts.account || typeof opts.account !== "string") {
-    throw new Error(
-      '@noy-db/at-macos-keychain: `account` is required, must be a non-empty string. Typically the user\'s email or stable user id (e.g., "alice@acme.example").'
-    );
-  }
-  if (opts.entry === void 0 && process.platform !== "darwin") {
-    throw new Error(
-      `@noy-db/at-macos-keychain: refusing to construct provider on platform "${process.platform}". This package only operates on darwin (macOS). For other platforms use @noy-db/at-env (server), @noy-db/at-wincred (Windows desktop), @noy-db/at-libsecret (Linux desktop), or @noy-db/at-webauthn-prf (browser).`
-    );
-  }
-  let resolvedEntry = opts.entry;
-  const getEntry = () => {
-    if (resolvedEntry) return resolvedEntry;
-    let Entry;
-    try {
-      const mod = require("@napi-rs/keyring");
-      Entry = mod.Entry;
-    } catch (err) {
-      throw new Error(
-        "@noy-db/at-macos-keychain: failed to load `@napi-rs/keyring`. Ensure it is installed (`pnpm add @napi-rs/keyring`) and that the platform-specific binary for darwin is available. Original error: " + (err instanceof Error ? err.message : String(err))
-      );
-    }
-    resolvedEntry = new Entry(opts.service, opts.account);
-    return resolvedEntry;
-  };
-  let cachedKey = null;
-  const getKey = () => {
-    if (!cachedKey) {
-      cachedKey = (async () => {
-        const entry = getEntry();
-        let stored = entry.getPassword();
-        if (stored === null) {
-          const fresh = new Uint8Array(32);
-          globalThis.crypto.getRandomValues(fresh);
-          entry.setPassword(bytesToBase64(fresh));
-          stored = entry.getPassword();
-          if (stored === null) {
-            throw new Error(
-              "@noy-db/at-macos-keychain: setPassword succeeded but getPassword returned null immediately after. Keychain may be denying access or the entry was deleted out from under us."
-            );
-          }
-        }
-        const keyBytes = base64ToBytes(stored);
-        if (keyBytes.length !== 32) {
-          throw new Error(
-            `@noy-db/at-macos-keychain: stored key for service="${opts.service}" account="${opts.account}" decodes to ${keyBytes.length} bytes; expected 32. The Keychain entry may have been tampered with \u2014 delete the entry (Keychain Access.app \u2192 search \u2192 right-click \u2192 Delete) and reopen the vault to regenerate.`
-          );
-        }
-        return globalThis.crypto.subtle.importKey(
-          "raw",
-          keyBytes,
-          "AES-GCM",
-          false,
-          ["encrypt", "decrypt"]
-        );
-      })();
-    }
-    return cachedKey;
-  };
-  return {
-    id: `macos-keychain:${opts.service}/${opts.account}`,
-    async seal(passphrase) {
-      const key = await getKey();
-      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
-      const ciphertext = await globalThis.crypto.subtle.encrypt(
-        { name: "AES-GCM", iv },
-        key,
-        passphrase
-      );
-      const out = new Uint8Array(12 + ciphertext.byteLength);
-      out.set(iv, 0);
-      out.set(new Uint8Array(ciphertext), 12);
-      return out;
-    },
-    async unseal(sealed) {
-      if (sealed.length < 12 + 16) {
-        throw new Error(
-          `@noy-db/at-macos-keychain: sealed bytes too short (${sealed.length} < 28). Input is not a valid at-macos-keychain-sealed envelope.`
-        );
-      }
-      const iv = sealed.subarray(0, 12);
-      const body = sealed.subarray(12);
-      const key = await getKey();
-      const plaintext = await globalThis.crypto.subtle.decrypt(
-        { name: "AES-GCM", iv },
-        key,
-        body
-      );
-      return new Uint8Array(plaintext);
-    }
-  };
-}
-function bytesToBase64(bytes) {
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-  return btoa(binary);
-}
-function base64ToBytes(b64) {
-  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {
-    throw new Error("input contains characters outside the base64 alphabet");
-  }
-  const binary = atob(b64);
-  const out = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
-  return out;
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  macosKeychainSealingProvider
-});
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/at-macos-keychain** — macOS Keychain sealing key provider\n * for noy-db [managed-passphrase mode](https://github.com/vLannaAi/noy-db/issues/14).\n *\n * Desktop-app provider in the `at-*` family. Binds the sealing key to\n * the user's macOS login Keychain — accessible only to processes\n * running as the same user, optionally gated by Touch ID via Keychain\n * Access UI (a one-time per-entry toggle the user enables themselves;\n * this package does not gate that programmatically).\n *\n * ## When to use\n *\n * - Desktop apps where the user expects \"log into my Mac = open the\n *   vault.\" The Keychain entry persists across reboots, scoped to\n *   the user account.\n * - Apps where `at-env` is unsuitable — laptops or shared dev machines\n *   where other users with shell access can `echo $NOYDB_SEALING_KEY`\n *   and exfiltrate the key.\n *\n * ## When NOT to use\n *\n * - Server-side / containerized deployments — there is no Keychain\n *   there. Use `@noy-db/at-env` or `@noy-db/at-aws-kms` (when it\n *   ships).\n * - Browser apps — Keychain is a native OS feature, not exposed to\n *   browser sandboxes. Use `@noy-db/at-webauthn-prf` (when it ships).\n *\n * ## Setup\n *\n * ```bash\n * pnpm add @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring\n * ```\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { macosKeychainSealingProvider } from '@noy-db/at-macos-keychain'\n *\n * const db = await createNoydb({\n *   store,\n *   user: 'alice',\n *   passphraseMode: 'managed',\n *   sealingKey: macosKeychainSealingProvider({\n *     service: 'com.acme.app',         // your bundle id / app namespace\n *     account: 'alice@acme.example',   // per-user keychain item\n *   }),\n * })\n * ```\n *\n * First call generates a fresh 32-byte AES-256 key, stores it in the\n * Keychain under `(service, account)`, and uses it to seal the\n * hub-generated managed passphrase. Subsequent process launches\n * retrieve the same key and unseal transparently.\n *\n * ## Threat model\n *\n * The Keychain entry IS the security boundary. Strength bounded by:\n *\n * - **macOS user-account isolation.** Other processes running as the\n *   same user can read the entry. macOS App Sandboxing limits this\n *   for App Store apps; unsandboxed apps must trust co-resident\n *   processes.\n * - **Login keychain lock state.** When the user's login keychain\n *   is locked (default: never, unless explicitly configured), reads\n *   surface a prompt or fail. Apps that need to operate when the\n *   keychain is locked should consider explicit unlock UX.\n * - **Touch ID upgrade.** Users may add Touch ID gating to the\n *   Keychain entry via Keychain Access.app → right-click → Get Info\n *   → Access Control. This is opt-in per entry and out of band of\n *   this package's API.\n *\n * Does NOT protect against:\n *\n * - Malware running as the same user with Keychain access.\n * - A physically present attacker who knows the user's login\n *   password and can unlock the keychain.\n * - macOS itself being compromised below the Keychain Services\n *   layer.\n *\n * @packageDocumentation\n */\n\nimport type { SealingKeyProvider } from '@noy-db/hub'\n\n/**\n * Structural shape of `@napi-rs/keyring`'s `Entry` class.\n *\n * Defined here as a structural type rather than importing the\n * concrete class so that:\n *\n *   1. Test code can inject a memory-backed stub for cross-platform\n *      unit tests (the real Entry only works on darwin/win32/linux).\n *   2. We don't pin a specific version of `@napi-rs/keyring`'s\n *      exported types — the structural match is exact across 1.x.\n *\n * @public\n */\nexport interface KeychainEntry {\n  /** Returns the stored secret, or `null` when no entry exists. */\n  getPassword(): string | null\n  /** Persists the secret. Overwrites any existing value. */\n  setPassword(value: string): void\n  /** Removes the entry. Returns `true` if an entry was removed. */\n  deletePassword(): boolean\n}\n\n/**\n * Options for {@link macosKeychainSealingProvider}.\n *\n * The pair `(service, account)` becomes the Keychain lookup key. By\n * convention:\n *\n * - `service` is your app's bundle id or stable app namespace, e.g.\n *   `'com.acme.app'`. Stable across users; identifies the app.\n * - `account` is per-user, typically the user's email or stable\n *   user id, e.g. `'alice@acme.example'`. Different users = different\n *   Keychain entries.\n */\nexport interface MacosKeychainSealingProviderOptions {\n  /** Keychain service identifier — typically your app's bundle id. */\n  readonly service: string\n  /** Per-user account identifier inside the service. */\n  readonly account: string\n  /**\n   * Test-injection hook. Pass a pre-constructed `KeychainEntry`\n   * (e.g., a memory-backed stub) to bypass the real Keychain. The\n   * production code path defaults to `new Entry(service, account)`\n   * from `@napi-rs/keyring`.\n   *\n   * @internal — production callers should leave undefined.\n   */\n  readonly entry?: KeychainEntry\n}\n\n/**\n * Build a {@link SealingKeyProvider} backed by a macOS Keychain entry.\n *\n * The 32-byte AES-256-GCM sealing key is generated on first use and\n * persisted in the Keychain under `(service, account)`. Subsequent\n * calls (this process or any future process running as the same\n * user) retrieve the same key — the vault round-trips across\n * restarts.\n *\n * Provider `id` format: `macos-keychain:{service}/{account}`. The\n * format is semver-frozen per the §11.9.1 stability rule; see\n * `docs/subsystems/sealing-pid-stability.md`.\n *\n * @throws Error at construction if `service` or `account` is empty,\n *   or on non-darwin platforms (with a pointer to platform-appropriate\n *   providers).\n */\nexport function macosKeychainSealingProvider(\n  opts: MacosKeychainSealingProviderOptions,\n): SealingKeyProvider {\n  if (!opts.service || typeof opts.service !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `service` is required, must be a non-empty string. '\n      + 'Typically your app bundle id (e.g., \"com.acme.app\").',\n    )\n  }\n  if (!opts.account || typeof opts.account !== 'string') {\n    throw new Error(\n      '@noy-db/at-macos-keychain: `account` is required, must be a non-empty string. '\n      + 'Typically the user\\'s email or stable user id (e.g., \"alice@acme.example\").',\n    )\n  }\n\n  // Hard platform check unless the caller supplied a test stub.\n  // Per §11.9.1 spec Q.3: fail loudly on the wrong platform.\n  if (opts.entry === undefined && process.platform !== 'darwin') {\n    throw new Error(\n      `@noy-db/at-macos-keychain: refusing to construct provider on `\n      + `platform \"${process.platform}\". This package only operates on `\n      + 'darwin (macOS). For other platforms use @noy-db/at-env (server), '\n      + '@noy-db/at-wincred (Windows desktop), @noy-db/at-libsecret (Linux desktop), '\n      + 'or @noy-db/at-webauthn-prf (browser).',\n    )\n  }\n\n  // Resolved lazily so that production callers don't pay the require\n  // cost (or fail loudly on wrong platform) until they actually invoke\n  // seal/unseal. Construction-site failure of new Entry() on unsupported\n  // platforms is caught and rethrown with a clearer message.\n  let resolvedEntry: KeychainEntry | undefined = opts.entry\n  const getEntry = (): KeychainEntry => {\n    if (resolvedEntry) return resolvedEntry\n    // Dynamic require so non-darwin imports don't crash on package load.\n    // The platform check above guards production callers; this branch\n    // only runs for production (opts.entry was undefined) on darwin.\n    /* eslint-disable @typescript-eslint/no-require-imports */\n    let Entry: new (service: string, account: string) => KeychainEntry\n    try {\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      const mod = require('@napi-rs/keyring') as { Entry: any }\n      Entry = mod.Entry\n    } catch (err) {\n      throw new Error(\n        '@noy-db/at-macos-keychain: failed to load `@napi-rs/keyring`. '\n        + 'Ensure it is installed (`pnpm add @napi-rs/keyring`) and that '\n        + 'the platform-specific binary for darwin is available. '\n        + 'Original error: '\n        + (err instanceof Error ? err.message : String(err)),\n      )\n    }\n    /* eslint-enable */\n    resolvedEntry = new Entry(opts.service, opts.account)\n    return resolvedEntry\n  }\n\n  // Cache the imported CryptoKey for the lifetime of this provider\n  // instance. Matches at-env's pattern; avoids a Keychain round-trip\n  // per seal/unseal operation in long-running processes.\n  let cachedKey: Promise<CryptoKey> | null = null\n  const getKey = (): Promise<CryptoKey> => {\n    if (!cachedKey) {\n      cachedKey = (async (): Promise<CryptoKey> => {\n        const entry = getEntry()\n        let stored = entry.getPassword()\n        if (stored === null) {\n          // First call ever for this (service, account) — generate a\n          // fresh 32-byte AES-256 key, base64-encode for string\n          // storage, persist.\n          const fresh = new Uint8Array(32)\n          globalThis.crypto.getRandomValues(fresh)\n          entry.setPassword(bytesToBase64(fresh))\n          stored = entry.getPassword()\n          if (stored === null) {\n            throw new Error(\n              '@noy-db/at-macos-keychain: setPassword succeeded but '\n              + 'getPassword returned null immediately after. '\n              + 'Keychain may be denying access or the entry was '\n              + 'deleted out from under us.',\n            )\n          }\n        }\n        const keyBytes = base64ToBytes(stored)\n        if (keyBytes.length !== 32) {\n          throw new Error(\n            `@noy-db/at-macos-keychain: stored key for service=\"${opts.service}\" `\n            + `account=\"${opts.account}\" decodes to ${keyBytes.length} bytes; `\n            + 'expected 32. The Keychain entry may have been tampered with — '\n            + 'delete the entry (Keychain Access.app → search → right-click → Delete) '\n            + 'and reopen the vault to regenerate.',\n          )\n        }\n        return globalThis.crypto.subtle.importKey(\n          'raw',\n          keyBytes as unknown as BufferSource,\n          'AES-GCM',\n          false,\n          ['encrypt', 'decrypt'],\n        )\n      })()\n    }\n    return cachedKey\n  }\n\n  return {\n    id: `macos-keychain:${opts.service}/${opts.account}`,\n\n    async seal(passphrase: Uint8Array): Promise<Uint8Array> {\n      const key = await getKey()\n      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))\n      const ciphertext = await globalThis.crypto.subtle.encrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        passphrase as unknown as BufferSource,\n      )\n      // Output format: [12-byte IV][ciphertext + 16-byte GCM tag]\n      // Identical wire layout to at-env, by design — the hub envelope\n      // dispatches on pid, not on per-provider format.\n      const out = new Uint8Array(12 + ciphertext.byteLength)\n      out.set(iv, 0)\n      out.set(new Uint8Array(ciphertext), 12)\n      return out\n    },\n\n    async unseal(sealed: Uint8Array): Promise<Uint8Array> {\n      // 12-byte IV + ≥ 16-byte GCM tag minimum.\n      if (sealed.length < 12 + 16) {\n        throw new Error(\n          `@noy-db/at-macos-keychain: sealed bytes too short (${sealed.length} < 28). `\n          + 'Input is not a valid at-macos-keychain-sealed envelope.',\n        )\n      }\n      const iv = sealed.subarray(0, 12)\n      const body = sealed.subarray(12)\n      const key = await getKey()\n      const plaintext = await globalThis.crypto.subtle.decrypt(\n        { name: 'AES-GCM', iv: iv as BufferSource },\n        key,\n        body as unknown as BufferSource,\n      )\n      return new Uint8Array(plaintext)\n    },\n  }\n}\n\n// ─── base64 helpers (browser + node compatible) ──────────────────────────\n\nfunction bytesToBase64(bytes: Uint8Array): string {\n  let binary = ''\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]!)\n  return btoa(binary)\n}\n\nfunction base64ToBytes(b64: string): Uint8Array {\n  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(b64.trim())) {\n    throw new Error('input contains characters outside the base64 alphabet')\n  }\n  const binary = atob(b64)\n  const out = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i)\n  return out\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -1,151 +0,0 @@
-import { SealingKeyProvider } from '@noy-db/hub';
-
-/**
- * **@noy-db/at-macos-keychain** — macOS Keychain sealing key provider
- * for noy-db [managed-passphrase mode](https://github.com/vLannaAi/noy-db/issues/14).
- *
- * Desktop-app provider in the `at-*` family. Binds the sealing key to
- * the user's macOS login Keychain — accessible only to processes
- * running as the same user, optionally gated by Touch ID via Keychain
- * Access UI (a one-time per-entry toggle the user enables themselves;
- * this package does not gate that programmatically).
- *
- * ## When to use
- *
- * - Desktop apps where the user expects "log into my Mac = open the
- *   vault." The Keychain entry persists across reboots, scoped to
- *   the user account.
- * - Apps where `at-env` is unsuitable — laptops or shared dev machines
- *   where other users with shell access can `echo $NOYDB_SEALING_KEY`
- *   and exfiltrate the key.
- *
- * ## When NOT to use
- *
- * - Server-side / containerized deployments — there is no Keychain
- *   there. Use `@noy-db/at-env` or `@noy-db/at-aws-kms` (when it
- *   ships).
- * - Browser apps — Keychain is a native OS feature, not exposed to
- *   browser sandboxes. Use `@noy-db/at-webauthn-prf` (when it ships).
- *
- * ## Setup
- *
- * ```bash
- * pnpm add @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring
- * ```
- *
- * ```ts
- * import { createNoydb } from '@noy-db/hub'
- * import { macosKeychainSealingProvider } from '@noy-db/at-macos-keychain'
- *
- * const db = await createNoydb({
- *   store,
- *   user: 'alice',
- *   passphraseMode: 'managed',
- *   sealingKey: macosKeychainSealingProvider({
- *     service: 'com.acme.app',         // your bundle id / app namespace
- *     account: 'alice@acme.example',   // per-user keychain item
- *   }),
- * })
- * ```
- *
- * First call generates a fresh 32-byte AES-256 key, stores it in the
- * Keychain under `(service, account)`, and uses it to seal the
- * hub-generated managed passphrase. Subsequent process launches
- * retrieve the same key and unseal transparently.
- *
- * ## Threat model
- *
- * The Keychain entry IS the security boundary. Strength bounded by:
- *
- * - **macOS user-account isolation.** Other processes running as the
- *   same user can read the entry. macOS App Sandboxing limits this
- *   for App Store apps; unsandboxed apps must trust co-resident
- *   processes.
- * - **Login keychain lock state.** When the user's login keychain
- *   is locked (default: never, unless explicitly configured), reads
- *   surface a prompt or fail. Apps that need to operate when the
- *   keychain is locked should consider explicit unlock UX.
- * - **Touch ID upgrade.** Users may add Touch ID gating to the
- *   Keychain entry via Keychain Access.app → right-click → Get Info
- *   → Access Control. This is opt-in per entry and out of band of
- *   this package's API.
- *
- * Does NOT protect against:
- *
- * - Malware running as the same user with Keychain access.
- * - A physically present attacker who knows the user's login
- *   password and can unlock the keychain.
- * - macOS itself being compromised below the Keychain Services
- *   layer.
- *
- * @packageDocumentation
- */
-
-/**
- * Structural shape of `@napi-rs/keyring`'s `Entry` class.
- *
- * Defined here as a structural type rather than importing the
- * concrete class so that:
- *
- *   1. Test code can inject a memory-backed stub for cross-platform
- *      unit tests (the real Entry only works on darwin/win32/linux).
- *   2. We don't pin a specific version of `@napi-rs/keyring`'s
- *      exported types — the structural match is exact across 1.x.
- *
- * @public
- */
-interface KeychainEntry {
-    /** Returns the stored secret, or `null` when no entry exists. */
-    getPassword(): string | null;
-    /** Persists the secret. Overwrites any existing value. */
-    setPassword(value: string): void;
-    /** Removes the entry. Returns `true` if an entry was removed. */
-    deletePassword(): boolean;
-}
-/**
- * Options for {@link macosKeychainSealingProvider}.
- *
- * The pair `(service, account)` becomes the Keychain lookup key. By
- * convention:
- *
- * - `service` is your app's bundle id or stable app namespace, e.g.
- *   `'com.acme.app'`. Stable across users; identifies the app.
- * - `account` is per-user, typically the user's email or stable
- *   user id, e.g. `'alice@acme.example'`. Different users = different
- *   Keychain entries.
- */
-interface MacosKeychainSealingProviderOptions {
-    /** Keychain service identifier — typically your app's bundle id. */
-    readonly service: string;
-    /** Per-user account identifier inside the service. */
-    readonly account: string;
-    /**
-     * Test-injection hook. Pass a pre-constructed `KeychainEntry`
-     * (e.g., a memory-backed stub) to bypass the real Keychain. The
-     * production code path defaults to `new Entry(service, account)`
-     * from `@napi-rs/keyring`.
-     *
-     * @internal — production callers should leave undefined.
-     */
-    readonly entry?: KeychainEntry;
-}
-/**
- * Build a {@link SealingKeyProvider} backed by a macOS Keychain entry.
- *
- * The 32-byte AES-256-GCM sealing key is generated on first use and
- * persisted in the Keychain under `(service, account)`. Subsequent
- * calls (this process or any future process running as the same
- * user) retrieve the same key — the vault round-trips across
- * restarts.
- *
- * Provider `id` format: `macos-keychain:{service}/{account}`. The
- * format is semver-frozen per the §11.9.1 stability rule; see
- * `docs/subsystems/sealing-pid-stability.md`.
- *
- * @throws Error at construction if `service` or `account` is empty,
- *   or on non-darwin platforms (with a pointer to platform-appropriate
- *   providers).
- */
-declare function macosKeychainSealingProvider(opts: MacosKeychainSealingProviderOptions): SealingKeyProvider;
-
-export { type KeychainEntry, type MacosKeychainSealingProviderOptions, macosKeychainSealingProvider };