@noy-db/at-macos-keychain 0.1.0-pre.16

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,144 @@
+# @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.
+
+The user never sees or types a passphrase. The 32-byte AES-256-GCM key lives in the Keychain; the vault opens only when the same OS user (and optionally same biometric) is present.
+
+## Install
+
+```bash
+pnpm add @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring
+# or: npm install @noy-db/hub @noy-db/at-macos-keychain @napi-rs/keyring
+```
+
+`@napi-rs/keyring` is a peer dependency — it ships the native binding to the macOS Security framework via `SecItem*` calls. Install it alongside this package.
+
+## Setup
+
+```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 app's bundle id
+    account: 'alice@acme.example',    // per-user keychain item
+  }),
+})
+
+const vault = db.vault('acme')
+// First open: provider generates a fresh 32-byte AES-256 key, stores it
+// in the Keychain, hub uses it to seal a random passphrase. Subsequent
+// opens (this process or any future process running as alice on this
+// Mac) retrieve the same key, unseal transparently. No passphrase
+// prompt ever appears.
+```
+
+## When to use this provider
+
+- ✅ Desktop apps where the user expects "I'm logged into my Mac, the vault should be available."
+- ✅ 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.
+- ✅ Apps that want optional Touch ID upgrade (see "Touch ID" below) without writing platform-specific UI code.
+
+## When NOT to use this provider
+
+- ❌ Server-side / containerized deployments — there is no Keychain in a container. Use [`@noy-db/at-env`](../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).
+- ❌ Cross-machine handover (where a SaaS hands a customer their bundle to open on their laptop). Keychain entries don't leave a Mac (except via iCloud Keychain sync between the same user's devices); this provider can't seal *for* an arbitrary recipient. Use a handover-capable cloud-KMS provider (`@noy-db/at-aws-kms` asymmetric, when it ships).
+
+## Provider id format
+
+```
+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.
+
+## Touch ID
+
+macOS lets users add Touch ID gating to a Keychain entry via **Keychain Access.app → search for the entry → right-click → Get Info → Access Control → Confirm before allowing access → "Ask for Touch ID"**. This is a one-time user-controlled action; this package does not gate it programmatically.
+
+After the user enables Touch ID on the entry, every subsequent `seal`/`unseal` call surfaces the system Touch ID prompt. The provider's API surface does not change; the gating is transparent.
+
+## Threat model
+
+The Keychain entry IS the security boundary. Strength is bounded by:
+
+- **macOS user-account isolation.** Processes running as a different OS user cannot read the entry. App Sandboxing (App Store apps) further restricts; unsandboxed apps must trust co-resident processes.
+- **Login keychain lock state.** When the user's login keychain is locked, reads surface a prompt or fail. Apps needing operation while locked should implement explicit unlock UX.
+- **Optional Touch ID per entry.** Users add this via Keychain Access UI as described above.
+
+**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.
+
+For full architectural background see the [at-* sealing dimension foundation doc](../../docs/superpowers/specs/2026-05-23-sealing-at-dimension-foundation.md), §11.2 (capability matrix) and §2 (threat-model honesty table).
+
+## API
+
+```ts
+function macosKeychainSealingProvider(opts: {
+  service: string                  // your app bundle id / namespace
+  account: string                  // per-user identifier
+  entry?: KeychainEntry            // internal test injection — leave undefined in production
+}): SealingKeyProvider
+```
+
+Returns a [`SealingKeyProvider`](../hub/src/team/managed-passphrase.ts) — the contract `@noy-db/hub`'s managed-passphrase mode consumes.
+
+Throws at construction when `service` or `account` is empty, or when running on a non-darwin platform without a test stub.
+
+The provider exposes only `SealingKeyProvider` — not `RecipientSealer`. By the [capability matrix](../../docs/superpowers/specs/2026-05-23-sealing-at-dimension-foundation.md#112-provider-capability-matrix), this provider is **self-targeted only**: it can seal and unseal locally, but cannot seal for an arbitrary recipient (no public-half to publish). Bundle-handover delivery to arbitrary recipients requires a handover-capable cloud-KMS provider.
+
+## Key lifecycle
+
+- **First call ever for a given `(service, account)`**: generates a fresh 32-byte AES-256 key via `crypto.getRandomValues`, base64-encodes it, stores in the Keychain. The `seal`/`unseal` operation then proceeds using that key.
+- **Subsequent calls (same process or any future process under the same OS user)**: read the stored base64, decode, import as a `CryptoKey`, perform AES-256-GCM.
+- **Different `(service, account)` → different Keychain entry → different key**. Sealed outputs from one pair cannot be unsealed by another.
+- **Cache**: the imported `CryptoKey` is cached for the lifetime of the provider instance. Long-running processes do not pay a Keychain round-trip per seal/unseal.
+
+If a vault is being retired, call `entry.deletePassword()` directly on `@napi-rs/keyring`. This package does not wrap that — the Keychain entry's lifecycle is decoupled from the vault's lifecycle, and the explicit `@napi-rs/keyring` call is the cleanest way to do it.
+
+## Testing
+
+For platform-independent unit tests, inject a memory-backed entry via the `entry` option:
+
+```ts
+import { macosKeychainSealingProvider, type KeychainEntry } from '@noy-db/at-macos-keychain'
+
+function memoryEntry(): KeychainEntry {
+  let stored: string | null = null
+  return {
+    getPassword: () => stored,
+    setPassword: (v) => { stored = v },
+    deletePassword: () => { const had = stored !== null; stored = null; return had },
+  }
+}
+
+const provider = macosKeychainSealingProvider({
+  service: 'com.acme.test',
+  account: 'test',
+  entry: memoryEntry(),
+})
+```
+
+The injected entry bypasses the real Keychain entirely. The seal/unseal AES-GCM pipeline is fully exercised; only the OS-Keychain integration is stubbed.
+
+For real-Keychain integration tests on darwin CI runners, leave `entry` undefined and ensure each test uses a unique `service` (e.g., `com.noydb.test-${randomUUID()}`) with cleanup in `afterEach` (`entry.deletePassword()`). Otherwise Keychain entries leak across runs.
+
+## Related
+
+- [`@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)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,142 @@
+"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

@@ -0,0 +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":[]}

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+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 };

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+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 };

package/dist/index.js

@@ -0,0 +1,124 @@
+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
+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;
+}
+export {
+  macosKeychainSealingProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@noy-db/at-macos-keychain",
+  "version": "0.1.0-pre.16",
+  "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>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/at-macos-keychain#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/at-macos-keychain"
+  },
+  "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"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@napi-rs/keyring": "^1.1.0",
+    "@noy-db/hub": "0.1.0-pre.16"
+  },
+  "peerDependenciesMeta": {
+    "@napi-rs/keyring": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@napi-rs/keyring": "^1.1.0",
+    "@types/node": "^22.0.0",
+    "@noy-db/to-memory": "0.1.0-pre.16",
+    "@noy-db/hub": "0.1.0-pre.16"
+  },
+  "keywords": [
+    "noy-db",
+    "at-macos-keychain",
+    "sealing-key-provider",
+    "managed-passphrase",
+    "macos",
+    "keychain",
+    "aes-256-gcm",
+    "rubber-hose-resistant",
+    "encryption",
+    "zero-knowledge"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}