@alpacakit/core 0.1.0-beta.35 → 0.1.0-beta.37

package/README.md

@@ -16,3 +16,27 @@ Main exports: `createMapRegistry` / `createKeyedRegistry`,
 `createSchemaRuntimeCodec` and the `schema.ts` helpers, `makeBrandedId` /
 id factories, `produceImmutable` and the draft mutation helpers, and the
 shared empty-value defaults.
+
+## `@alpacakit/core/keyring`
+
+The ONE module in the workspace that talks to an OS keychain. `@alpacakit/agents`,
+`@alpacakit/integrations`, and the family convention packages above them all
+reach the keychain through this subpath, so the native peer, the
+absence-versus-failure rule, and the error type have a single owner.
+
+```ts
+import { keyringResolver, keyringSecretStore } from "@alpacakit/core/keyring";
+
+const store = keyringSecretStore({ service: "alpaca.agents" });
+await store.set("profile:judge-codex:api-key", secret);
+const resolver = keyringResolver({ service: "alpaca.agents" });
+```
+
+- `get` returns `null` for an absent (or empty) entry; anything the keychain
+  throws surfaces as `KeyringError` with `code: "operation_failed"` — absence
+  is never inferred from a failure.
+- `@napi-rs/keyring` is an **optional** peer, loaded lazily on first use. A
+  missing peer is `KeyringError` with `code: "peer_missing"`; both codes carry
+  the attempted `operation` (`read` / `write` / `delete`) and the `cause`.
+- `module` accepts a loader so tests exercise the whole path without touching
+  a real keychain.

package/dist/keyring/error.d.ts

@@ -0,0 +1,33 @@
+import type { ValueOf } from "../types.js";
+export declare const KEYRING_ERROR_CODE: {
+    /** The optional `@napi-rs/keyring` peer is absent or exports no `Entry`. */
+    readonly peerMissing: "peer_missing";
+    /** The OS keychain rejected or failed the operation — never "absent". */
+    readonly operationFailed: "operation_failed";
+};
+export type KeyringErrorCode = ValueOf<typeof KEYRING_ERROR_CODE>;
+export declare const KEYRING_OPERATION: {
+    readonly read: "read";
+    readonly write: "write";
+    readonly delete: "delete";
+};
+export type KeyringOperation = ValueOf<typeof KEYRING_OPERATION>;
+export type KeyringErrorOptions = {
+    readonly code: KeyringErrorCode;
+    readonly operation: KeyringOperation;
+    readonly message: string;
+    readonly cause?: unknown;
+};
+/**
+ * The single error type of the keychain boundary. `operation` records what
+ * was attempted (a missing peer is only ever discovered while attempting
+ * one), so a caller can report "could not write the secret" without
+ * re-deriving it from the call site.
+ */
+export declare class KeyringError extends Error {
+    readonly code: KeyringErrorCode;
+    readonly operation: KeyringOperation;
+    constructor(options: KeyringErrorOptions);
+}
+export declare function isKeyringError(value: unknown, code?: KeyringErrorCode): value is KeyringError;
+//# sourceMappingURL=error.d.ts.map

package/dist/keyring/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/keyring/error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,kBAAkB;IAC7B,4EAA4E;;IAE5E,yEAAyE;;CAEjE,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAElE,eAAO,MAAM,iBAAiB;;;;CAIpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAQF;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;gBAEzB,OAAO,EAAE,mBAAmB;CAazC;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,gBAAgB,GACtB,KAAK,IAAI,YAAY,CAUvB"}

package/dist/keyring/error.js

@@ -0,0 +1,45 @@
+export const KEYRING_ERROR_CODE = {
+    /** The optional `@napi-rs/keyring` peer is absent or exports no `Entry`. */
+    peerMissing: "peer_missing",
+    /** The OS keychain rejected or failed the operation — never "absent". */
+    operationFailed: "operation_failed",
+};
+export const KEYRING_OPERATION = {
+    read: "read",
+    write: "write",
+    delete: "delete",
+};
+const KEYRING_ERROR_NAME = "KeyringError";
+const KEYRING_ERROR_BRAND = Symbol.for("@alpacakit/core/keyring.KeyringError");
+const KEYRING_ERROR_FIELD = {
+    code: "code",
+};
+/**
+ * The single error type of the keychain boundary. `operation` records what
+ * was attempted (a missing peer is only ever discovered while attempting
+ * one), so a caller can report "could not write the secret" without
+ * re-deriving it from the call site.
+ */
+export class KeyringError extends Error {
+    code;
+    operation;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = KEYRING_ERROR_NAME;
+        this.code = options.code;
+        this.operation = options.operation;
+        Object.defineProperty(this, KEYRING_ERROR_BRAND, {
+            value: true,
+            enumerable: false,
+        });
+    }
+}
+export function isKeyringError(value, code) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    if (Reflect.get(value, KEYRING_ERROR_BRAND) !== true) {
+        return false;
+    }
+    return (code === undefined || Reflect.get(value, KEYRING_ERROR_FIELD.code) === code);
+}

package/dist/keyring/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The ONE place in the workspace that talks to an OS keychain. Every other
+ * package (agents, integrations, and the family conventions above them)
+ * reaches the keychain through this subpath, so the native peer, the
+ * absence-vs-failure rule, and the error type have a single owner.
+ */
+export type { KeyringErrorCode, KeyringErrorOptions, KeyringOperation, } from "./error.js";
+export { KEYRING_ERROR_CODE, KEYRING_OPERATION, KeyringError, isKeyringError, } from "./error.js";
+export type { KeyringModuleLoader, KeyringOptions, KeyringSecretStore, } from "./resolver.js";
+export { keyringResolver, keyringSecretStore } from "./resolver.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/keyring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/keyring/index.js

@@ -0,0 +1,8 @@
+/**
+ * The ONE place in the workspace that talks to an OS keychain. Every other
+ * package (agents, integrations, and the family conventions above them)
+ * reaches the keychain through this subpath, so the native peer, the
+ * absence-vs-failure rule, and the error type have a single owner.
+ */
+export { KEYRING_ERROR_CODE, KEYRING_OPERATION, KeyringError, isKeyringError, } from "./error.js";
+export { keyringResolver, keyringSecretStore } from "./resolver.js";

package/dist/keyring/resolver.d.ts

@@ -0,0 +1,16 @@
+import type { SecretResolver } from "../ports.js";
+/** Injection seam: tests supply a fake module instead of touching a keychain. */
+export type KeyringModuleLoader = () => Promise<unknown>;
+export type KeyringOptions = {
+    readonly service: string;
+    readonly module?: KeyringModuleLoader;
+};
+/** Read/write/delete of one OS keychain service. Absence is `null`, not a throw. */
+export interface KeyringSecretStore {
+    get(id: string): Promise<string | null>;
+    set(id: string, value: string): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export declare function keyringResolver(options: KeyringOptions): SecretResolver;
+export declare function keyringSecretStore(options: KeyringOptions): KeyringSecretStore;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/keyring/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/keyring/resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgClD,iFAAiF;AACjF,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CACvC,CAAC;AAEF,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAKD,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAGvE;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,GACtB,kBAAkB,CAEpB"}

package/dist/keyring/resolver.js

@@ -0,0 +1,93 @@
+import { KEYRING_ERROR_CODE, KEYRING_OPERATION, KeyringError, } from "./error.js";
+const KEYRING_PEER_PACKAGE = "@napi-rs/keyring";
+const KEYRING_ENTRY_EXPORT = "Entry";
+const EMPTY_SECRET_VALUE = "";
+const KEYRING_OPERATION_VERB = {
+    [KEYRING_OPERATION.read]: "read",
+    [KEYRING_OPERATION.write]: "written",
+    [KEYRING_OPERATION.delete]: "deleted",
+};
+const KEYRING_ERROR_MESSAGE = {
+    peerMissing: `Keyring peer "${KEYRING_PEER_PACKAGE}" is not installed`,
+    operationFailed: (id, operation) => `Keyring secret "${id}" could not be ${KEYRING_OPERATION_VERB[operation]}`,
+};
+const defaultKeyringModuleLoader = () => import(KEYRING_PEER_PACKAGE);
+export function keyringResolver(options) {
+    const open = openKeyring(options);
+    return { resolve: (id) => open.get(id) };
+}
+export function keyringSecretStore(options) {
+    return openKeyring(options);
+}
+function openKeyring(options) {
+    const loader = options.module ?? defaultKeyringModuleLoader;
+    const service = options.service;
+    // Only a SUCCESSFUL load is cached: caching the rejection would replay one
+    // operation's `peer_missing` (with its stale `operation`) forever, even
+    // after the peer is installed.
+    let loaded = null;
+    const entry = async (id, operation) => {
+        loaded ??= await loadKeyringModule(loader, operation);
+        return new loaded.Entry(service, id);
+    };
+    return {
+        get: async (id) => {
+            const target = await entry(id, KEYRING_OPERATION.read);
+            // Absent entries are the `null` return (`Entry.getPassword():
+            // string | null` in @napi-rs/keyring); anything thrown is a real
+            // keychain failure, never "missing secret".
+            return await run(id, KEYRING_OPERATION.read, async () => {
+                const value = await target.getPassword();
+                return value === EMPTY_SECRET_VALUE ? null : value;
+            });
+        },
+        set: async (id, value) => {
+            const target = await entry(id, KEYRING_OPERATION.write);
+            await run(id, KEYRING_OPERATION.write, async () => await target.setPassword(value));
+        },
+        delete: async (id) => {
+            const target = await entry(id, KEYRING_OPERATION.delete);
+            await run(id, KEYRING_OPERATION.delete, async () => {
+                await target.deletePassword();
+            });
+        },
+    };
+}
+async function run(id, operation, operate) {
+    try {
+        return await operate();
+    }
+    catch (error) {
+        throw new KeyringError({
+            code: KEYRING_ERROR_CODE.operationFailed,
+            operation,
+            message: KEYRING_ERROR_MESSAGE.operationFailed(id, operation),
+            cause: error,
+        });
+    }
+}
+async function loadKeyringModule(loader, operation) {
+    let loaded;
+    try {
+        loaded = await loader();
+    }
+    catch (error) {
+        throw peerMissing(operation, error);
+    }
+    if (typeof loaded !== "object" || loaded === null) {
+        throw peerMissing(operation, null);
+    }
+    const entry = Reflect.get(loaded, KEYRING_ENTRY_EXPORT);
+    if (typeof entry !== "function") {
+        throw peerMissing(operation, null);
+    }
+    return { Entry: entry };
+}
+function peerMissing(operation, cause) {
+    return new KeyringError({
+        code: KEYRING_ERROR_CODE.peerMissing,
+        operation,
+        message: KEYRING_ERROR_MESSAGE.peerMissing,
+        cause,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpacakit/core",
-  "version": "0.1.0-beta.35",
+  "version": "0.1.0-beta.37",
   "description": "Architecture-neutral kernel primitives: branded ids, ports, registries, pipelines, payload codecs, and immutable mutation helpers.",
   "license": "MIT",
   "type": "module",
@@ -8,6 +8,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./keyring": {
+      "types": "./dist/keyring/index.d.ts",
+      "import": "./dist/keyring/index.js"
     }
   },
   "types": "./dist/index.d.ts",
@@ -29,6 +33,14 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
+  "peerDependencies": {
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@napi-rs/keyring": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",