@openkeyai/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,267 @@
+/**
+ * Shared types — kept in their own module so they can be imported without
+ * pulling the verifier / fetcher implementations into a tool's bundle.
+ *
+ * Mirrors the FROZEN claim contract in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/ARCHITECTURE.md#appendix-b
+ * Changes here require coordinated bumps across hub + SDK + every deployed
+ * tool.
+ */
+/** Scopes a tool may request and a JWT may carry. */
+type ToolJwtScope = "keys.read" | "user.read" | "billing.read";
+/** Decoded + verified claim payload. */
+type ToolJwtClaims = {
+    /** Always exactly "https://openkeyai.com". */
+    iss: "https://openkeyai.com";
+    /** Hub user_id (Supabase auth.users.id, UUID v4). */
+    sub: string;
+    /** Tool slug the token was minted for. Must match the calling tool's slug. */
+    aud: string;
+    /** Subset of the scope set above. */
+    scopes: ToolJwtScope[];
+    /** Whether the user has an active subscription at issuance time. */
+    subscription_active: boolean;
+    /** Unix seconds. */
+    iat: number;
+    /** Unix seconds. Tokens default to iat + 900 (15 min). */
+    exp: number;
+    /** Unique token id, used for future revocation. */
+    jti: string;
+};
+/**
+ * Provider slug as seen by the hub vault. Kept as a string union rather
+ * than an `unknown` so editor autocomplete is useful; the hub will reject
+ * any value not in its registry, regardless of what TS thinks.
+ */
+type ProviderSlug = "openai" | "anthropic" | "google" | "replicate" | "elevenlabs" | "fal" | (string & {});
+/**
+ * Optional overrides for any SDK call. All defaults match production.
+ */
+type HubCallOptions = {
+    /**
+     * Root URL of the hub. Defaults to `https://openkeyai.com`. Override only
+     * for staging or local-dev tools.
+     */
+    hubUrl?: string;
+    /**
+     * AbortSignal to cancel the call. SDK never sets a default timeout — use
+     * the caller's request signal.
+     */
+    signal?: AbortSignal;
+};
+
+/**
+ * `session.verify(jwt, opts?)`
+ *
+ * Verifies a hub-issued JWT against the hub's public JWKS, then validates
+ * the claim shape (`iss`, `sub`, `aud`, `scopes`, `subscription_active`).
+ *
+ * Returns the typed claims on success.
+ * Throws `BadTokenError` on any failure — signature, expiry, issuer,
+ * audience, missing/malformed custom claims.
+ * Throws `MissingTokenError` if `jwt` is empty / null.
+ *
+ * The verifier:
+ *   - fetches `${hubUrl}/.well-known/jwks.json` (cached per hub URL)
+ *   - re-fetches on `kid` rotation (jose handles this transparently)
+ *   - DOES NOT validate `aud` here — the caller specifies which audience
+ *     they expect (the tool's own slug, OR a wildcard for tools that
+ *     legitimately accept multiple audiences). `keys.get` validates
+ *     audience against the tool slug derived from the route.
+ *
+ * @param jwt The bearer token string (no `Bearer ` prefix).
+ * @param opts.hubUrl override the hub root (default: `https://openkeyai.com`)
+ * @param opts.expectedAudience tool slug the token must be addressed to.
+ *        When omitted, audience is not checked here — the caller MUST do it
+ *        themselves before granting any scope-derived privilege.
+ */
+declare function verify(jwt: string, opts?: HubCallOptions & {
+    expectedAudience?: string;
+}): Promise<ToolJwtClaims>;
+
+/**
+ * SecureKey — the only way the SDK hands a plaintext credential to a tool.
+ *
+ * Design goals (per docs/SECURITY.md in the hub repo):
+ *
+ *   1. The plaintext is reachable from EXACTLY ONE place: inside a callback
+ *      passed to `use(fn)`. Outside that callback, no public method or
+ *      property returns the value.
+ *
+ *   2. After the callback runs (or throws), the held reference is set to
+ *      null. Subsequent `use()` calls throw `SecureKeyConsumedError`. The
+ *      pattern is one-shot — get a fresh SecureKey for the next request.
+ *
+ *   3. `JSON.stringify`, `toString`, `console.log` (via util.inspect), and
+ *      template-literal coercion all return the literal string
+ *      `"[SecureKey]"` — never the underlying value, even by accident.
+ *
+ * #plaintext is a true private field (Stage 3 syntax) so it doesn't appear
+ * in `Object.keys()`, isn't accessible via bracket-notation, and is not
+ * enumerable for serialisation. The frozen overrides below cover the
+ * coercion paths.
+ *
+ * What we deliberately do NOT do:
+ *
+ *   - WeakRef + FinalizationRegistry. They're observable from the same realm,
+ *     and we have no useful action to take on GC. Single-use + manual null
+ *     is the simpler, more deterministic guarantee.
+ *
+ *   - Buffer.alloc + .fill(0) "zeroising". V8 and modern runtimes can keep
+ *     copies of strings in cache; we can't truly zeroise from JS. The
+ *     useful guarantee we CAN give is reference-clearing, which we do.
+ */
+declare class SecureKey {
+    #private;
+    /** Provider slug the key was fetched for. Public — not sensitive. */
+    readonly provider: string;
+    /** @internal — tools should use `keys.get()`, never construct directly. */
+    constructor(plaintext: string, provider: string);
+    /**
+     * Pass the plaintext into a callback. Returns whatever the callback
+     * returns. After the callback resolves (or throws), the SecureKey is
+     * consumed — subsequent calls throw `SecureKeyConsumedError`.
+     *
+     * @example
+     *   const k = await keys.get(jwt, "openai");
+     *   const response = await k.use((apiKey) => fetch("...", {
+     *     headers: { "Authorization": `Bearer ${apiKey}` },
+     *   }));
+     */
+    use<T>(fn: (plaintext: string) => T | Promise<T>): Promise<T>;
+    /** Returns true once `use()` has been called and the reference cleared. */
+    get isConsumed(): boolean;
+    /** Always `[SecureKey]`. Never the underlying value. */
+    toString(): string;
+    /** Always `[SecureKey]`. Catches `JSON.stringify` and friends. */
+    toJSON(): string;
+}
+
+/**
+ * `keys.get(jwt, provider, opts?)`
+ *
+ * Fetches a credential for the user identified by `jwt` and returns a
+ * single-use SecureKey. The hub:
+ *
+ *   1. Verifies the JWT (signature + iss + aud + exp)
+ *   2. Confirms `keys.read` scope, active subscription, and that the tool +
+ *      user are both subscribed to this provider
+ *   3. Decrypts the user's stored API key via KMS
+ *   4. Returns the plaintext, logged to the audit trail
+ *
+ * On the client side we:
+ *   - Decode (no verify) the JWT locally to read the `aud` claim — that's
+ *     the tool slug the hub will scope the lookup against
+ *   - Pre-check the `keys.read` scope so we can return a typed error
+ *     without a round-trip
+ *   - Issue the GET, map the hub's frozen error codes to typed exceptions
+ *   - Wrap the plaintext in a SecureKey and return
+ *
+ * IMPORTANT: a SecureKey is single-use. Don't call `.use()` more than once;
+ * call `keys.get` again for the next request. The audit trail records every
+ * fetch.
+ */
+declare function get(jwt: string, provider: ProviderSlug, opts?: HubCallOptions): Promise<SecureKey>;
+
+/**
+ * Typed errors.
+ *
+ * The error `code` strings are part of the FROZEN public contract — see the
+ * key-fetch endpoint's documentation in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/phases/05-tools-keyfetch.md
+ *
+ * Adding a new code is a minor-version bump. Renaming or removing one is a
+ * major (with 60-day notice).
+ *
+ * Tools catch these to surface precise UX:
+ *
+ *   try {
+ *     await keys.get(jwt, "openai");
+ *   } catch (e) {
+ *     if (e instanceof SubscriptionInactiveError) showPaywall();
+ *     else if (e instanceof RateLimitedError) showRetryToast(e.retryAfter);
+ *     else throw e;
+ *   }
+ */
+type HubSdkErrorCode = "missing_token" | "bad_token" | "missing_scope" | "subscription_inactive" | "tool_not_found" | "not_subscribed" | "provider_not_granted" | "rate_limited" | "key_not_found" | "internal" | "network" | "secure_key_consumed";
+/** Base class for every typed error in the SDK. */
+declare class HubSdkError extends Error {
+    readonly code: HubSdkErrorCode;
+    /** HTTP status from the hub, when applicable. 0 for client-only errors. */
+    readonly status: number;
+    constructor(code: HubSdkErrorCode, message: string, status?: number);
+}
+declare class MissingTokenError extends HubSdkError {
+    constructor();
+}
+declare class BadTokenError extends HubSdkError {
+    constructor(message?: string);
+}
+declare class MissingScopeError extends HubSdkError {
+    constructor(needed: string);
+}
+declare class SubscriptionInactiveError extends HubSdkError {
+    constructor();
+}
+declare class ToolNotFoundError extends HubSdkError {
+    constructor();
+}
+declare class NotSubscribedError extends HubSdkError {
+    constructor();
+}
+declare class ProviderNotGrantedError extends HubSdkError {
+    constructor(provider: string);
+}
+declare class RateLimitedError extends HubSdkError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number);
+}
+declare class KeyNotFoundError extends HubSdkError {
+    constructor(provider: string);
+}
+declare class InternalError extends HubSdkError {
+    constructor(status: number, message?: string);
+}
+declare class NetworkError extends HubSdkError {
+    constructor(cause: unknown);
+}
+declare class SecureKeyConsumedError extends HubSdkError {
+    constructor();
+}
+
+/**
+ * `@openkeyai/sdk` — public entry.
+ *
+ * Tools install this and import only from the package root:
+ *
+ *   import { session, keys, SecureKey, SubscriptionInactiveError } from "@openkeyai/sdk";
+ *
+ * The five-module surface (session / keys / user / billing / webhooks) is
+ * defined in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/TOOL_SDK.md
+ *
+ * Status by module in 0.1.0:
+ *   - session.verify ✓
+ *   - keys.get → SecureKey ✓
+ *   - user        — deferred until the hub ships /api/me (issue TBD)
+ *   - billing     — deferred until the hub ships /api/billing/status
+ *   - webhooks    — deferred until Phase 16 (the hub's webhook delivery layer)
+ *
+ * Internal helpers live under `_internal/`. They are NOT part of the
+ * public API and may change without notice — the tool-manifest scanner
+ * (Phase 9) treats `@openkeyai/sdk/_internal` imports as a CI failure.
+ */
+
+/** session module — JWT verification + (future) refresh. */
+declare const session: {
+    readonly verify: typeof verify;
+};
+/** keys module — credential fetch returning a single-use SecureKey. */
+declare const keys: {
+    readonly get: typeof get;
+};
+
+/** Bumped on each release. Tools log this on boot. */
+declare const SDK_VERSION = "0.1.0";
+
+export { BadTokenError, type HubCallOptions, HubSdkError, type HubSdkErrorCode, InternalError, KeyNotFoundError, MissingScopeError, MissingTokenError, NetworkError, NotSubscribedError, ProviderNotGrantedError, type ProviderSlug, RateLimitedError, SDK_VERSION, SecureKey, SecureKeyConsumedError, SubscriptionInactiveError, type ToolJwtClaims, type ToolJwtScope, ToolNotFoundError, keys, session };

package/dist/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Shared types — kept in their own module so they can be imported without
+ * pulling the verifier / fetcher implementations into a tool's bundle.
+ *
+ * Mirrors the FROZEN claim contract in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/ARCHITECTURE.md#appendix-b
+ * Changes here require coordinated bumps across hub + SDK + every deployed
+ * tool.
+ */
+/** Scopes a tool may request and a JWT may carry. */
+type ToolJwtScope = "keys.read" | "user.read" | "billing.read";
+/** Decoded + verified claim payload. */
+type ToolJwtClaims = {
+    /** Always exactly "https://openkeyai.com". */
+    iss: "https://openkeyai.com";
+    /** Hub user_id (Supabase auth.users.id, UUID v4). */
+    sub: string;
+    /** Tool slug the token was minted for. Must match the calling tool's slug. */
+    aud: string;
+    /** Subset of the scope set above. */
+    scopes: ToolJwtScope[];
+    /** Whether the user has an active subscription at issuance time. */
+    subscription_active: boolean;
+    /** Unix seconds. */
+    iat: number;
+    /** Unix seconds. Tokens default to iat + 900 (15 min). */
+    exp: number;
+    /** Unique token id, used for future revocation. */
+    jti: string;
+};
+/**
+ * Provider slug as seen by the hub vault. Kept as a string union rather
+ * than an `unknown` so editor autocomplete is useful; the hub will reject
+ * any value not in its registry, regardless of what TS thinks.
+ */
+type ProviderSlug = "openai" | "anthropic" | "google" | "replicate" | "elevenlabs" | "fal" | (string & {});
+/**
+ * Optional overrides for any SDK call. All defaults match production.
+ */
+type HubCallOptions = {
+    /**
+     * Root URL of the hub. Defaults to `https://openkeyai.com`. Override only
+     * for staging or local-dev tools.
+     */
+    hubUrl?: string;
+    /**
+     * AbortSignal to cancel the call. SDK never sets a default timeout — use
+     * the caller's request signal.
+     */
+    signal?: AbortSignal;
+};
+
+/**
+ * `session.verify(jwt, opts?)`
+ *
+ * Verifies a hub-issued JWT against the hub's public JWKS, then validates
+ * the claim shape (`iss`, `sub`, `aud`, `scopes`, `subscription_active`).
+ *
+ * Returns the typed claims on success.
+ * Throws `BadTokenError` on any failure — signature, expiry, issuer,
+ * audience, missing/malformed custom claims.
+ * Throws `MissingTokenError` if `jwt` is empty / null.
+ *
+ * The verifier:
+ *   - fetches `${hubUrl}/.well-known/jwks.json` (cached per hub URL)
+ *   - re-fetches on `kid` rotation (jose handles this transparently)
+ *   - DOES NOT validate `aud` here — the caller specifies which audience
+ *     they expect (the tool's own slug, OR a wildcard for tools that
+ *     legitimately accept multiple audiences). `keys.get` validates
+ *     audience against the tool slug derived from the route.
+ *
+ * @param jwt The bearer token string (no `Bearer ` prefix).
+ * @param opts.hubUrl override the hub root (default: `https://openkeyai.com`)
+ * @param opts.expectedAudience tool slug the token must be addressed to.
+ *        When omitted, audience is not checked here — the caller MUST do it
+ *        themselves before granting any scope-derived privilege.
+ */
+declare function verify(jwt: string, opts?: HubCallOptions & {
+    expectedAudience?: string;
+}): Promise<ToolJwtClaims>;
+
+/**
+ * SecureKey — the only way the SDK hands a plaintext credential to a tool.
+ *
+ * Design goals (per docs/SECURITY.md in the hub repo):
+ *
+ *   1. The plaintext is reachable from EXACTLY ONE place: inside a callback
+ *      passed to `use(fn)`. Outside that callback, no public method or
+ *      property returns the value.
+ *
+ *   2. After the callback runs (or throws), the held reference is set to
+ *      null. Subsequent `use()` calls throw `SecureKeyConsumedError`. The
+ *      pattern is one-shot — get a fresh SecureKey for the next request.
+ *
+ *   3. `JSON.stringify`, `toString`, `console.log` (via util.inspect), and
+ *      template-literal coercion all return the literal string
+ *      `"[SecureKey]"` — never the underlying value, even by accident.
+ *
+ * #plaintext is a true private field (Stage 3 syntax) so it doesn't appear
+ * in `Object.keys()`, isn't accessible via bracket-notation, and is not
+ * enumerable for serialisation. The frozen overrides below cover the
+ * coercion paths.
+ *
+ * What we deliberately do NOT do:
+ *
+ *   - WeakRef + FinalizationRegistry. They're observable from the same realm,
+ *     and we have no useful action to take on GC. Single-use + manual null
+ *     is the simpler, more deterministic guarantee.
+ *
+ *   - Buffer.alloc + .fill(0) "zeroising". V8 and modern runtimes can keep
+ *     copies of strings in cache; we can't truly zeroise from JS. The
+ *     useful guarantee we CAN give is reference-clearing, which we do.
+ */
+declare class SecureKey {
+    #private;
+    /** Provider slug the key was fetched for. Public — not sensitive. */
+    readonly provider: string;
+    /** @internal — tools should use `keys.get()`, never construct directly. */
+    constructor(plaintext: string, provider: string);
+    /**
+     * Pass the plaintext into a callback. Returns whatever the callback
+     * returns. After the callback resolves (or throws), the SecureKey is
+     * consumed — subsequent calls throw `SecureKeyConsumedError`.
+     *
+     * @example
+     *   const k = await keys.get(jwt, "openai");
+     *   const response = await k.use((apiKey) => fetch("...", {
+     *     headers: { "Authorization": `Bearer ${apiKey}` },
+     *   }));
+     */
+    use<T>(fn: (plaintext: string) => T | Promise<T>): Promise<T>;
+    /** Returns true once `use()` has been called and the reference cleared. */
+    get isConsumed(): boolean;
+    /** Always `[SecureKey]`. Never the underlying value. */
+    toString(): string;
+    /** Always `[SecureKey]`. Catches `JSON.stringify` and friends. */
+    toJSON(): string;
+}
+
+/**
+ * `keys.get(jwt, provider, opts?)`
+ *
+ * Fetches a credential for the user identified by `jwt` and returns a
+ * single-use SecureKey. The hub:
+ *
+ *   1. Verifies the JWT (signature + iss + aud + exp)
+ *   2. Confirms `keys.read` scope, active subscription, and that the tool +
+ *      user are both subscribed to this provider
+ *   3. Decrypts the user's stored API key via KMS
+ *   4. Returns the plaintext, logged to the audit trail
+ *
+ * On the client side we:
+ *   - Decode (no verify) the JWT locally to read the `aud` claim — that's
+ *     the tool slug the hub will scope the lookup against
+ *   - Pre-check the `keys.read` scope so we can return a typed error
+ *     without a round-trip
+ *   - Issue the GET, map the hub's frozen error codes to typed exceptions
+ *   - Wrap the plaintext in a SecureKey and return
+ *
+ * IMPORTANT: a SecureKey is single-use. Don't call `.use()` more than once;
+ * call `keys.get` again for the next request. The audit trail records every
+ * fetch.
+ */
+declare function get(jwt: string, provider: ProviderSlug, opts?: HubCallOptions): Promise<SecureKey>;
+
+/**
+ * Typed errors.
+ *
+ * The error `code` strings are part of the FROZEN public contract — see the
+ * key-fetch endpoint's documentation in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/phases/05-tools-keyfetch.md
+ *
+ * Adding a new code is a minor-version bump. Renaming or removing one is a
+ * major (with 60-day notice).
+ *
+ * Tools catch these to surface precise UX:
+ *
+ *   try {
+ *     await keys.get(jwt, "openai");
+ *   } catch (e) {
+ *     if (e instanceof SubscriptionInactiveError) showPaywall();
+ *     else if (e instanceof RateLimitedError) showRetryToast(e.retryAfter);
+ *     else throw e;
+ *   }
+ */
+type HubSdkErrorCode = "missing_token" | "bad_token" | "missing_scope" | "subscription_inactive" | "tool_not_found" | "not_subscribed" | "provider_not_granted" | "rate_limited" | "key_not_found" | "internal" | "network" | "secure_key_consumed";
+/** Base class for every typed error in the SDK. */
+declare class HubSdkError extends Error {
+    readonly code: HubSdkErrorCode;
+    /** HTTP status from the hub, when applicable. 0 for client-only errors. */
+    readonly status: number;
+    constructor(code: HubSdkErrorCode, message: string, status?: number);
+}
+declare class MissingTokenError extends HubSdkError {
+    constructor();
+}
+declare class BadTokenError extends HubSdkError {
+    constructor(message?: string);
+}
+declare class MissingScopeError extends HubSdkError {
+    constructor(needed: string);
+}
+declare class SubscriptionInactiveError extends HubSdkError {
+    constructor();
+}
+declare class ToolNotFoundError extends HubSdkError {
+    constructor();
+}
+declare class NotSubscribedError extends HubSdkError {
+    constructor();
+}
+declare class ProviderNotGrantedError extends HubSdkError {
+    constructor(provider: string);
+}
+declare class RateLimitedError extends HubSdkError {
+    readonly retryAfter: number;
+    constructor(retryAfter: number);
+}
+declare class KeyNotFoundError extends HubSdkError {
+    constructor(provider: string);
+}
+declare class InternalError extends HubSdkError {
+    constructor(status: number, message?: string);
+}
+declare class NetworkError extends HubSdkError {
+    constructor(cause: unknown);
+}
+declare class SecureKeyConsumedError extends HubSdkError {
+    constructor();
+}
+
+/**
+ * `@openkeyai/sdk` — public entry.
+ *
+ * Tools install this and import only from the package root:
+ *
+ *   import { session, keys, SecureKey, SubscriptionInactiveError } from "@openkeyai/sdk";
+ *
+ * The five-module surface (session / keys / user / billing / webhooks) is
+ * defined in
+ * https://github.com/Scott-Builds-AI/hub/blob/main/docs/TOOL_SDK.md
+ *
+ * Status by module in 0.1.0:
+ *   - session.verify ✓
+ *   - keys.get → SecureKey ✓
+ *   - user        — deferred until the hub ships /api/me (issue TBD)
+ *   - billing     — deferred until the hub ships /api/billing/status
+ *   - webhooks    — deferred until Phase 16 (the hub's webhook delivery layer)
+ *
+ * Internal helpers live under `_internal/`. They are NOT part of the
+ * public API and may change without notice — the tool-manifest scanner
+ * (Phase 9) treats `@openkeyai/sdk/_internal` imports as a CI failure.
+ */
+
+/** session module — JWT verification + (future) refresh. */
+declare const session: {
+    readonly verify: typeof verify;
+};
+/** keys module — credential fetch returning a single-use SecureKey. */
+declare const keys: {
+    readonly get: typeof get;
+};
+
+/** Bumped on each release. Tools log this on boot. */
+declare const SDK_VERSION = "0.1.0";
+
+export { BadTokenError, type HubCallOptions, HubSdkError, type HubSdkErrorCode, InternalError, KeyNotFoundError, MissingScopeError, MissingTokenError, NetworkError, NotSubscribedError, ProviderNotGrantedError, type ProviderSlug, RateLimitedError, SDK_VERSION, SecureKey, SecureKeyConsumedError, SubscriptionInactiveError, type ToolJwtClaims, type ToolJwtScope, ToolNotFoundError, keys, session };