@byok-sdk/keys 0.1.0

package/dist/registry.d.ts

@@ -0,0 +1,103 @@
+import { AnthropicMessagesClient } from './anthropic-client';
+import type { ProviderFetch } from './http';
+import { OpenAiCompatibleChatClient } from './openai-client';
+import type { ProviderProfileStore } from './profile-store';
+import { type ModelProviderAdapter, type ModelProviderId, type ProviderAuthMode } from './provider-profile';
+import { type ModelProviderSecretName, type SecretStore } from './secret-store';
+/** A transport client for whichever dialect the resolved profile declares. */
+export type ModelProviderClient = AnthropicMessagesClient | OpenAiCompatibleChatClient;
+/**
+ * What a caller supplies to {@link ProviderRegistry.configure}: the profile
+ * minus the fields the registry owns (`kind`, both timestamps) and minus the
+ * secret, which travels as a separate argument so it cannot be mistaken for
+ * persisted data.
+ */
+export interface ProviderConfiguration {
+    adapter: ModelProviderAdapter;
+    auth_mode: ProviderAuthMode;
+    base_url: string;
+    display_name: string;
+    /** Defaults to `true`: configuring a provider makes it the default. */
+    enabled?: boolean;
+    model: string;
+    provider_id: ModelProviderId;
+}
+/**
+ * The registry's outward projection of a profile.
+ *
+ * It reports **whether** a secret exists (`secret_configured`) and never the
+ * secret itself — the property `registry.golden.test.ts` asserts, mirroring
+ * `docs/researches/HANDOFF-byok-keys.md` §4.3's "status JSON contains no
+ * plaintext key".
+ */
+export interface ProviderStatus {
+    adapter: ModelProviderAdapter;
+    auth_mode: ProviderAuthMode;
+    base_url: string;
+    created_at: string;
+    display_name: string;
+    enabled: boolean;
+    model: string;
+    provider_id: ModelProviderId;
+    /** Whether the credential store currently holds this provider's key. */
+    secret_configured: boolean;
+    updated_at: string;
+}
+export interface ProviderRegistryOptions {
+    fetchImpl?: ProviderFetch;
+    /** Injected clock, so tests get deterministic timestamps. */
+    now?: () => Date;
+    profileStore: ProviderProfileStore;
+    secretStore: SecretStore<ModelProviderSecretName>;
+}
+/**
+ * The configure/resolve boundary, ported from `providers.ts:1180-1229`
+ * (`configure`) and `providers.ts:1331-1354` (`resolveDefaultModelProvider`).
+ *
+ * Both halves of a provider's configuration are written here and nowhere else:
+ * the non-secret profile goes to the injected {@link ProviderProfileStore}, the
+ * API key goes to the injected {@link SecretStore}. Splitting them is the whole
+ * point of the package, so the registry is the only place that knows both.
+ *
+ * Two departures from the source, both required by
+ * `docs/researches/HANDOFF-byok-keys.md` §4.5:
+ *
+ * - `resolveDefaultModelProvider` returns a transport client or `undefined`,
+ *   and throws on a broken configuration. The source returned an
+ *   `UnavailableNarrativeProvider` null-object carrying an error code, which is
+ *   a narrative-domain symbol that stays in aip-main-open — and a degradation
+ *   fallback this package's fail-closed rule does not permit. A caller that
+ *   wants aip's behaviour catches `ByokKeysError` and reads `.code`, which is
+ *   the same information the null-object carried.
+ * - The source's `#migrateLegacyModelSecret` is not ported (legacy secret
+ *   migration is out of scope per the plan).
+ */
+export declare class ProviderRegistry {
+    #private;
+    constructor(options: ProviderRegistryOptions);
+    close(): void;
+    /**
+     * Persist a provider's profile and, when supplied, its secret
+     * (`providers.ts:1180-1229`).
+     *
+     * Order matters and is the source's: write the secret first, then require
+     * that an authenticating profile actually has one, and only then save the
+     * profile. A profile is therefore never persisted in a state that claims
+     * authentication it cannot perform.
+     */
+    configure(configuration: ProviderConfiguration, secret?: string): Promise<ProviderStatus>;
+    /** Remove a provider's profile and its secret together. */
+    delete(providerId: ModelProviderId): Promise<boolean>;
+    get(providerId: ModelProviderId): Promise<ProviderStatus | undefined>;
+    list(): Promise<ProviderStatus[]>;
+    /**
+     * Build a client for the one enabled provider (`providers.ts:1331-1354`).
+     *
+     * `undefined` means "nothing is configured", which is a legitimate state a
+     * caller must handle. A configured-but-broken provider throws instead — a
+     * missing secret or an unusable profile is a fault, not an absence.
+     */
+    resolveDefaultModelProvider(): Promise<ModelProviderClient | undefined>;
+    /** Switch which configured provider is the default. */
+    setDefaultModelProvider(providerId: ModelProviderId): Promise<ProviderStatus>;
+}

package/dist/secret-name.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Legal secret-entry names, 3 to 96 characters.
+ *
+ * The source (`aip-main-open@c6a5385`, `apps/local-agent/src/index.ts:258-268`)
+ * closed this set at compile time with the `KeychainSecretName` union, so it
+ * needed no runtime check. `SecretStore<TName extends string>` is open by
+ * design — aip's closed union stays in aip — so the closure moves to runtime.
+ *
+ * The exclusion that matters is `.`: every backend composes its storage key as
+ * `` `${servicePrefix}.${name}` `` and a scoped store appends
+ * `.scope.<namespace>` to that prefix. A name containing a dot could therefore
+ * spell out another scope's service string and read that scope's secret. The
+ * validator throws rather than sanitizing — a caller that mistyped a name must
+ * see the error, not silently address a different entry.
+ */
+export declare const SECRET_NAME_PATTERN: RegExp;
+/**
+ * Legal scope namespaces, 8 to 96 characters. Ported verbatim from the source's
+ * `normalizeSecretNamespace` (`index.ts:748-757`); the 8-character floor keeps
+ * a namespace from colliding with a short accidental value.
+ */
+export declare const SECRET_NAMESPACE_PATTERN: RegExp;
+/** Fail closed unless `name` matches {@link SECRET_NAME_PATTERN}. */
+export declare function assertSecretName<TName extends string>(name: TName): TName;
+/**
+ * Trim and validate a scope namespace, or throw. Trimming is the source's
+ * behavior and is safe because the pattern rejects every interior whitespace
+ * character anyway.
+ */
+export declare function assertSecretNamespace(value: string): string;

package/dist/secret-scope.d.ts

@@ -0,0 +1,59 @@
+import { type SecretStore } from './secret-store';
+/**
+ * Tenant identity a secret store is partitioned by. Ported from
+ * `aip-main-open@c6a5385` `apps/local-agent/src/local-data-scope.ts:19-22`
+ * (`LocalAccountDataScope`).
+ */
+export interface SecretScope {
+    account_id: string;
+    workspace_id: string;
+}
+/**
+ * Envelope marker, injectable so K4 can pass the source's
+ * `aiphabee-scoped-secrets-v1:` value (`local-data-scope.ts:30`).
+ */
+export declare const DEFAULT_SECRET_ENVELOPE_PREFIX = "byok-scoped-secrets-v1:";
+/**
+ * Derive the opaque namespace a scope's secrets live under
+ * (`local-data-scope.ts:32-37`). Hashing means the namespace never leaks a
+ * tenant identifier into a keychain service name a user can browse.
+ */
+export declare function secretScopeId(scope: SecretScope): string;
+/**
+ * Partition `store` by `scope` (`local-data-scope.ts:100-106`).
+ *
+ * The source read `store.scope?.(id) ?? new EnvelopeScopedSecretStore(...)`:
+ * when a store happened not to implement `scope`, it silently switched to a
+ * different storage layout. `SecretStore.scope` is required in this package, so
+ * that implicit substitution is gone — a caller who wants envelope semantics
+ * constructs {@link EnvelopeScopedSecretStore} on purpose.
+ */
+export declare function scopeSecretStore<TName extends string>(store: SecretStore<TName>, scope: SecretScope): SecretStore<TName>;
+/**
+ * Partition a store by keeping every scope's secret in one underlying entry,
+ * as a JSON map of scope id to secret.
+ *
+ * This is the layout to reach for when the backend cannot cheaply namespace its
+ * own key space. It costs a read-modify-write on every mutation and offers no
+ * cross-process locking, so prefer a backend's native `scope()` when it has
+ * one; this decorator exists for the backends that do not.
+ *
+ * Reads are fail-closed in a way the source's were not
+ * (`local-data-scope.ts:163-194`): the source mapped any unparseable stored
+ * value to `undefined`, which made a foreign value look like an absent secret
+ * and let the next `set()` overwrite it. Here a stored value that is not a
+ * well-formed envelope raises `SECRET_ENVELOPE_INVALID`.
+ */
+export declare class EnvelopeScopedSecretStore<TName extends string = string> implements SecretStore<TName> {
+    #private;
+    readonly providerLabel: string;
+    constructor(store: SecretStore<TName>, scopeId: string, options?: {
+        envelopePrefix?: string;
+    });
+    available(): Promise<boolean>;
+    delete(name: TName): Promise<boolean>;
+    get(name: TName): Promise<string | undefined>;
+    has(name: TName): Promise<boolean>;
+    scope(namespace: string): SecretStore<TName>;
+    set(name: TName, secret: string): Promise<void>;
+}

package/dist/secret-store.d.ts

@@ -0,0 +1,103 @@
+import type { ModelProviderId } from './provider-profile';
+/**
+ * Storage contract for a single secret entry in an operating-system credential
+ * store.
+ *
+ * Ported from `aip-main-open@c6a5385` `apps/local-agent/src/index.ts:261-269`
+ * with two deliberate changes:
+ *
+ * 1. `TName` is a generic parameter rather than aip's closed
+ *    `KeychainSecretName` union. aip's union names device keys, refresh tokens,
+ *    and market-data entries that this package has no business knowing about,
+ *    so it stays in aip and consumers pin their own union. The compile-time
+ *    closure it provided is replaced at runtime by {@link assertSecretName},
+ *    which every implementation must apply on every name it receives.
+ * 2. `scope()` is required, not optional. The source made it optional and its
+ *    `scopeLocalAgentSecretStore` silently substituted an envelope
+ *    implementation when a store did not provide one. Scope-envelope prefixing
+ *    has no installed base, so this package removes the implicit substitution:
+ *    every store scopes itself, and {@link EnvelopeScopedSecretStore} is a
+ *    decorator a caller applies on purpose.
+ */
+export interface SecretStore<TName extends string = string> {
+    /** Human-readable backend name, safe to show a user. Never contains a secret. */
+    readonly providerLabel: string;
+    /** Whether this backend can be used on the current machine. Must not throw. */
+    available(): Promise<boolean>;
+    /** Remove `name`; `false` when it was already absent. */
+    delete(name: TName): Promise<boolean>;
+    /** Read `name`, or `undefined` when it is absent. */
+    get(name: TName): Promise<string | undefined>;
+    /** Whether `name` currently holds a secret. */
+    has(name: TName): Promise<boolean>;
+    /** A view of this store isolated under `namespace`. */
+    scope(namespace: string): SecretStore<TName>;
+    /** Write `secret` at `name`, replacing any existing value. */
+    set(name: TName, secret: string): Promise<void>;
+}
+/**
+ * Default service prefix for this package's own entries. `servicePrefix` is a
+ * constructor option on both OS backends, so K4's aip-main-open swap passes its
+ * `com.aiphabee.local-agent` value and keeps existing installs byte-compatible.
+ */
+export declare const DEFAULT_SECRET_SERVICE_PREFIX = "com.byok.keys";
+/**
+ * Credential-store entry name per model provider, ported verbatim from
+ * `providers.ts:1624-1632`. The names carry no vendor branding — the branding
+ * lives in the service prefix — so they travel unchanged and K4 needs no
+ * migration.
+ */
+export declare const MODEL_PROVIDER_SECRET_NAMES: {
+    readonly anthropic: 'model-anthropic-api-key';
+    readonly custom: 'model-custom-api-key';
+    readonly deepseek: 'model-deepseek-api-key';
+    readonly openai: 'model-openai-api-key';
+};
+export type ModelProviderSecretName = (typeof MODEL_PROVIDER_SECRET_NAMES)[keyof typeof MODEL_PROVIDER_SECRET_NAMES];
+/** Resolve a provider id to the credential-store entry holding its API key. */
+export declare function modelProviderSecretName(providerId: ModelProviderId): ModelProviderSecretName;
+/**
+ * The secret-shape invariant both OS backends share. Their size ceilings differ
+ * in both magnitude and unit (macOS counts 16384 characters, Windows counts
+ * 2560 UTF-8 bytes) and each reports its own error code, so those checks stay
+ * in the backends; only the empty/control-character rule is common.
+ */
+export declare function assertSharedSecretValue(secret: string): void;
+/**
+ * Decode base64 to UTF-8 text, or return `undefined` — never a repaired
+ * approximation.
+ *
+ * Both decode paths in Node are lenient in ways that matter here: `Buffer.from`
+ * silently drops characters outside the base64 alphabet (so `"a!G@k="` would
+ * decode to `"hi"`), and `Buffer#toString('utf8')` substitutes U+FFFD for
+ * invalid byte sequences. A credential store that "successfully" returns a
+ * silently-mangled secret is worse than one that fails, so the alphabet, the
+ * canonical padding, and the UTF-8 round trip are all checked explicitly.
+ */
+export declare function decodeStrictBase64Utf8(encoded: string): string | undefined;
+/**
+ * A {@link SecretStore} held in process memory, for tests and for embedders
+ * that supply their own persistence.
+ *
+ * It keys entries by the same `` `${servicePrefix}.${name}` `` string the OS
+ * backends use, and `scope()` extends that prefix exactly as they do, so a test
+ * written against this store exercises the same isolation arithmetic as
+ * production. It applies the name validator and the shared secret-shape rule;
+ * the platform size ceilings deliberately are not simulated, since they differ
+ * per backend.
+ */
+export declare class InMemorySecretStore<TName extends string = string> implements SecretStore<TName> {
+    #private;
+    readonly providerLabel = "in-memory";
+    constructor(options?: {
+        /** Shared backing map; a scoped view keeps the parent's map. */
+        entries?: Map<string, string>;
+        servicePrefix?: string;
+    });
+    available(): Promise<boolean>;
+    delete(name: TName): Promise<boolean>;
+    get(name: TName): Promise<string | undefined>;
+    has(name: TName): Promise<boolean>;
+    scope(namespace: string): SecretStore<TName>;
+    set(name: TName, secret: string): Promise<void>;
+}

package/dist/sqlite-profile-store.d.ts

@@ -0,0 +1,35 @@
+import { type ProviderProfileStore } from './profile-store';
+import { type ModelProviderId, type ModelProviderProfile } from './provider-profile';
+export interface SqliteProviderProfileStoreOptions {
+    /**
+     * Database file path. `:memory:` exercises the SQLite code path without a
+     * temp file, but defeats the point of this store (restart-safety) exactly as
+     * it does for `@byok/server`'s `SqliteTaskStore`.
+     */
+    path: string;
+}
+/**
+ * SQLite-backed {@link ProviderProfileStore}, following `@byok/server`'s
+ * `SqliteTaskStore` shape. Holds no secret: the API key lives in the injected
+ * `SecretStore`, and `registry.golden.test.ts` asserts the plaintext key never
+ * appears in this file's bytes.
+ */
+export declare class SqliteProviderProfileStore implements ProviderProfileStore {
+    #private;
+    constructor(options: SqliteProviderProfileStoreOptions);
+    /**
+     * Idempotent, as {@link ProviderProfileStore.close} requires: `node:sqlite`
+     * throws "database is not open" on a second `close()`, and a store is
+     * routinely closed both by the code that finished with it and by a test's
+     * teardown.
+     */
+    close(): void;
+    delete(providerId: ModelProviderId): boolean;
+    get(providerId: ModelProviderId): ModelProviderProfile | undefined;
+    getEnabled(): ModelProviderProfile | undefined;
+    list(): ModelProviderProfile[];
+    save(profile: ModelProviderProfile): ModelProviderProfile;
+    setEnabled(providerId: ModelProviderId): ModelProviderProfile;
+}
+/** Exported for the store's own tests to enumerate the CHECK-constrained ids. */
+export declare const SQLITE_PROFILE_PROVIDER_IDS: readonly ["openai", "deepseek", "anthropic", "custom"];

package/dist/sqlite-support.d.ts

@@ -0,0 +1,50 @@
+import type { DatabaseSync, DatabaseSyncOptions } from 'node:sqlite';
+interface SqliteModule {
+    DatabaseSync: new (path: string, options?: DatabaseSyncOptions) => DatabaseSync;
+}
+/**
+ * Load `node:sqlite`, or fail with a `ByokKeysError` that says why.
+ *
+ * `node:sqlite` shipped in Node.js 22.5.0 and stays marked experimental (an
+ * `ExperimentalWarning` on stderr is expected and harmless). Following
+ * `@byok/server`'s `sqlite-support.ts`, the SQLite-backed store here depends on
+ * nothing else — no `better-sqlite3`, no native module — because zero native
+ * dependencies is what keeps this package trivially packageable. The tradeoff
+ * is that {@link SqliteProviderProfileStore} does not work below Node 22.5, and
+ * this error says so instead of letting a cryptic `Cannot find module` surface
+ * from deep inside a query.
+ */
+export declare function loadSqliteModule(): SqliteModule;
+/**
+ * Whether `node:sqlite` can ACTUALLY be loaded right now.
+ *
+ * Same predicate as `@byok/server`'s `sqlite-support.ts`, and it exists for the
+ * same reason: this package's `engines.node` is `>=20` and CI runs the matrix
+ * on 20 and 22, but `node:sqlite` shipped in 22.5 and stayed behind
+ * `--experimental-sqlite` for part of the 22.x line. A version-number
+ * comparison would therefore be wrong in both directions, so this attempts the
+ * real require via {@link loadSqliteModule} and reports whether it succeeded.
+ *
+ * Callers use it to skip a SQLite-backed path rather than fail it — the
+ * package's own SQLite-backed suites gate on it — and anything else should call
+ * it before assuming a {@link SqliteProviderProfileStore} can be constructed.
+ */
+export declare function isSqliteAvailable(): boolean;
+/**
+ * Open a database, creating its parent directory owner-only first. `:memory:`
+ * skips every filesystem step, which is how the shared contract suite exercises
+ * the SQLite code path without leaving anything on disk.
+ */
+export declare function openSqliteDatabase(path: string, options?: DatabaseSyncOptions): DatabaseSync;
+/**
+ * Restrict `databasePath` and its WAL/SHM siblings to owner-only read/write.
+ *
+ * The profile table holds no secret — that is the whole point of splitting the
+ * key into the OS credential store — but it does hold every provider endpoint
+ * this machine talks to, and the source locked the file down
+ * (`providers.ts:158`), so the port keeps that. Call after the schema exists,
+ * so the lazily-created WAL/SHM files are already there; a sibling that does
+ * not exist is skipped rather than treated as an error. No-op for `:memory:`.
+ */
+export declare function secureSqliteFilePermissions(databasePath: string): void;
+export {};

package/dist/url.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalize a provider base URL, fail-closed.
+ *
+ * Ported from `aip-main-open@c6a5385` `providers.ts:1558-1588` plus the two
+ * host predicates at `:2216-2242`. Rules, unchanged:
+ * - must be an absolute URL;
+ * - no embedded credentials, no fragment, no query string;
+ * - HTTPS only, except that HTTP is allowed for loopback hosts;
+ * - private-network literals are rejected unless they are loopback;
+ * - one trailing slash is stripped.
+ */
+export declare function normalizeProviderUrl(value: string): string;
+/** Whether an already-parseable provider URL points at a loopback host. */
+export declare function isLoopbackProviderUrl(value: string): boolean;
+export declare function isLoopbackHost(hostname: string): boolean;
+/**
+ * Conservative private-network literal check. Any IPv6 literal counts as
+ * private (the `:` branch), matching the source: the guard cannot cheaply
+ * classify IPv6 ranges, so it refuses all of them and lets hostnames through.
+ */
+export declare function isPrivateNetworkLiteral(hostname: string): boolean;

package/dist/windows-credential-manager.d.ts

@@ -0,0 +1,31 @@
+import { type CommandRunner } from './command-runner';
+import { type SecretStore } from './secret-store';
+export interface WindowsCredentialManagerSecretStoreOptions {
+    account?: string;
+    commandRunner?: CommandRunner;
+    platform?: NodeJS.Platform;
+    servicePrefix?: string;
+}
+/**
+ * Windows Credential Manager backend (`index.ts:568-712`).
+ *
+ * As on macOS there is no plaintext fallback — off win32 every operation throws
+ * `CREDENTIAL_MANAGER_UNAVAILABLE`.
+ */
+export declare class WindowsCredentialManagerSecretStore<TName extends string = string> implements SecretStore<TName> {
+    #private;
+    readonly providerLabel = "Windows Credential Manager";
+    constructor(options?: WindowsCredentialManagerSecretStoreOptions);
+    available(): Promise<boolean>;
+    /**
+     * Delete, then read back. The source verifies rather than trusting the
+     * delete's exit code (`index.ts:651-679`): a credential that survives a
+     * "successful" delete is a security failure, so it is reported as one instead
+     * of being returned as `true`.
+     */
+    delete(name: TName): Promise<boolean>;
+    get(name: TName): Promise<string | undefined>;
+    has(name: TName): Promise<boolean>;
+    scope(namespace: string): SecretStore<TName>;
+    set(name: TName, secret: string): Promise<void>;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@byok-sdk/keys",
+  "version": "0.1.0",
+  "description": "BYOK SDK key management: provider profiles, credential-backed auth headers, and direct provider transports",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ancienttwo/byok-sdk.git",
+    "directory": "packages/keys"
+  },
+  "bugs": {
+    "url": "https://github.com/Ancienttwo/byok-sdk/issues"
+  },
+  "homepage": "https://github.com/Ancienttwo/byok-sdk#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}