@theokit/sdk 4.10.0 → 4.11.0

package/dist/internal/auth/auth-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * M42 — shared auth contract types. A LEAF module: pure type declarations, NO runtime imports (no zod, no
+ * node:fs). Every auth module (`credential-store`, `oauth-engine`, `oauth-device`, `resolve-credential`)
+ * imports its cross-module types from here so the barrel's rollup-plugin-dts bundle sees a single canonical
+ * origin — the codebase's established "leaf-type-only deps" pattern (see tsup.config.ts), which sidesteps
+ * the rollup-dts cross-module resolution limitation that a value-module type export trips.
+ *
+ * @internal (re-exported from the package barrel as public)
+ */
+/**
+ * The flat bearer surface every consumer holds. `kind:'api'` is the classic API-key path; `kind:'oauth'` is
+ * an OAuth session whose `apiKey` is the CURRENT access token, so consumers keep passing a flat bearer
+ * string unchanged. `provider` is an open string (any registered provider name).
+ */
+export interface ResolvedCredential {
+    kind: "api" | "oauth";
+    provider: string;
+    /** The effective BEARER the transport sends — an API key, or (oauth) the current access token. */
+    apiKey: string;
+    /** Where it came from — an env var NAME or a file path. Never the value. */
+    source: string;
+    /** True when the provider was derived rather than declared. */
+    inferred: boolean;
+    /** oauth only: epoch ms the access token expires. Drives the refresh in the oauth engine. */
+    expiresAt?: number;
+}
+export interface StoredApiCredential {
+    type?: "api";
+    provider?: string;
+    api_key: string;
+}
+export interface StoredOAuthCredential {
+    type: "oauth";
+    provider: string;
+    access: string;
+    refresh: string;
+    /** Epoch ms the access token expires. */
+    expires: number;
+    account_id?: string;
+}
+export type StoredCredential = StoredApiCredential | StoredOAuthCredential;
+/** A provider's OAuth endpoints + client identity. Passed in (provider-agnostic, like OpenCode). */
+export interface OAuthProviderConfig {
+    provider: string;
+    authorizeEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    scopes: readonly string[];
+    redirectUri: string;
+}
+/** The token triple persisted to the store's oauth variant. */
+export interface OAuthTokens {
+    access: string;
+    refresh: string;
+    /** Epoch ms the access token expires. */
+    expires: number;
+    accountId?: string;
+}
+/** Injected HTTP + clock effects — deterministic in tests, real in production. */
+export interface HttpDeps {
+    fetch: typeof fetch;
+    now: () => number;
+}
+/** A device-grant config: the OAuth config plus the RFC 8628 device authorization endpoint. */
+export interface DeviceOAuthConfig extends OAuthProviderConfig {
+    /** RFC 8628 device authorization endpoint — returns device_code + user_code + verification_uri. */
+    deviceCodeEndpoint: string;
+}
+/** The device authorization the user acts on. Times/interval are SECONDS (RFC 8628). */
+export interface DeviceCodeGrant {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    /** Seconds between token polls (server-mandated minimum). */
+    interval: number;
+    /** Seconds until the device_code expires. */
+    expiresIn: number;
+}
+/** Injected effects for the device flow — deterministic in tests, real in production. */
+export interface DeviceDeps {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}
+/** The OpenAI two-step device config: usercode + poll endpoints return an authorization_code (not tokens). */
+export interface OpenAIDeviceConfig extends OAuthProviderConfig {
+    /** POST `{client_id}` here → `{device_auth_id, user_code, interval}`. */
+    deviceUsercodeEndpoint: string;
+    /** Poll `{device_auth_id, user_code}` here → 200 `{authorization_code, code_verifier}`; 403/404 = pending. */
+    devicePollEndpoint: string;
+    /** Verification URL the user opens to enter the code. */
+    verificationUri: string;
+}

package/dist/internal/auth/credential-store.d.ts

@@ -0,0 +1,19 @@
+/** The store directory, honoring an optional `homeEnvVar` override. */
+export declare function credentialHome(config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/** The credential file path inside the (possibly overridden) store directory. */
+export declare function authFilePath(config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/** A credential problem the caller can act on. Never carries the key value. */
+export declare class CredentialError extends Error {
+    constructor(message: string);
+}
+export declare function readAuthFile(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredCredential | undefined;
+/**
+ * Read the stored OAuth credential (with its refresh token), or `undefined` when the store is absent or
+ * holds an api credential. The oauth engine needs the refresh token, which the resolved bearer does not
+ * carry. Enforces the same 0600/0700 gates as every other read.
+ */
+export declare function readStoredOAuth(config: CredentialStoreConfig, env?: Record<string, string | undefined>): StoredOAuthCredential | undefined;
+export declare function writeCredential(cred: {
+    provider: string;
+    apiKey: string;
+} | StoredOAuthCredential, config: CredentialStoreConfig, env?: Record<string, string | undefined>): string;

package/dist/internal/auth/oauth-device.d.ts

@@ -0,0 +1,55 @@
+import type { DeviceCodeGrant, DeviceDeps, DeviceOAuthConfig, OAuthTokens, OpenAIDeviceConfig } from "./auth-types.js";
+/** Step 1 — request a device code. POSTs `{client_id, scope}` to the device endpoint. */
+export declare function requestDeviceCode(config: DeviceOAuthConfig, deps: Pick<DeviceDeps, "fetch">): Promise<DeviceCodeGrant>;
+/**
+ * Step 2 — poll the token endpoint until the user approves (or the code expires). Handles RFC 8628
+ * `authorization_pending` (keep waiting) and `slow_down` (back off), with an expiry deadline so it cannot
+ * spin forever.
+ */
+export declare function pollDeviceToken(config: DeviceOAuthConfig, grant: DeviceCodeGrant, deps: DeviceDeps): Promise<OAuthTokens>;
+/**
+ * The full device login: request a code, hand the user the verification URL + user code via `onPrompt`
+ * (never printed here — the caller renders it, keeping this module output-free), then poll to completion.
+ */
+export declare function deviceLogin(config: DeviceOAuthConfig, deps: DeviceDeps, hooks: {
+    onPrompt: (p: {
+        userCode: string;
+        verificationUri: string;
+        expiresIn: number;
+    }) => void;
+}): Promise<OAuthTokens>;
+/** The OpenAI two-step device config: usercode + poll endpoints return an authorization_code (not tokens). */
+/** Step 1 (OpenAI) — request the user code. */
+export declare function requestOpenAIUsercode(config: OpenAIDeviceConfig, deps: Pick<DeviceDeps, "fetch">): Promise<{
+    deviceAuthId: string;
+    userCode: string;
+    interval: number;
+}>;
+/**
+ * Step 2+3 (OpenAI) — poll for the authorization code (200 = ready; 403/404 = pending; else fail), then
+ * exchange it for tokens at the standard `/oauth/token` endpoint (reuses `exchangeCode`).
+ */
+export declare function openaiDeviceLogin(config: OpenAIDeviceConfig, deps: DeviceDeps, hooks: {
+    onPrompt: (p: {
+        userCode: string;
+        verificationUri: string;
+    }) => void;
+}): Promise<OAuthTokens>;
+/** JWT id/access-token claims we read to attribute an account. Adapted from OpenCode's codex plugin. */
+interface IdTokenClaims {
+    chatgpt_account_id?: string;
+    organizations?: Array<{
+        id: string;
+    }>;
+    "https://api.openai.com/auth"?: {
+        chatgpt_account_id?: string;
+    };
+}
+/** Decode a JWT's claim set (no signature verification — used only to read a self-reported account id). */
+export declare function parseJwtClaims(token: string): IdTokenClaims | undefined;
+/** Best-effort account id from an id/access token's claims (OpenAI/ChatGPT shape). Adapted from OpenCode. */
+export declare function extractAccountId(tokens: {
+    id_token?: string;
+    access_token?: string;
+}): string | undefined;
+export {};

package/dist/internal/auth/oauth-engine.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialStoreConfig, HttpDeps, OAuthProviderConfig, OAuthTokens, ResolvedCredential } from "./auth-types.js";
+/** Exchange an authorization `code` (+ PKCE verifier) for the token pair. */
+export declare function exchangeCode(config: OAuthProviderConfig, input: {
+    code: string;
+    verifier: string;
+}, deps: HttpDeps): Promise<OAuthTokens>;
+/** Swap a refresh token for a fresh access (and possibly rotated refresh) token. */
+export declare function refreshOAuthTokens(config: OAuthProviderConfig, refresh: string, deps: HttpDeps): Promise<OAuthTokens>;
+/** Persist a token triple to the store's oauth variant through the hardened 0600 writer. */
+export declare function persistOAuthTokens(provider: string, tokens: OAuthTokens, store: CredentialStoreConfig, env?: Record<string, string | undefined>): string;
+/**
+ * Return a credential guaranteed fresh enough to use. An `api` credential passes through untouched. An
+ * `oauth` credential still valid (beyond the skew window) passes through; an expired one is refreshed,
+ * re-persisted 0600, and returned with the new access token. Concurrent refreshes of the same store are
+ * coalesced (single-use refresh tokens); the rejected promise is evicted so a failure is not cached-poison.
+ */
+export declare function ensureFreshCredential(resolved: ResolvedCredential, opts: {
+    config: OAuthProviderConfig;
+    store: CredentialStoreConfig;
+    env?: Record<string, string | undefined>;
+}, deps: HttpDeps): Promise<ResolvedCredential>;

package/dist/internal/auth/resolve-credential.d.ts

@@ -0,0 +1,16 @@
+export interface ResolveCredentialOptions {
+    /** The provider whose stored credential to resolve. */
+    provider: string;
+    /** Where the credential store lives. */
+    store: CredentialStoreConfig;
+    /** Env for the store's optional `homeEnvVar` override. Never an ambient read. */
+    env?: Record<string, string | undefined>;
+    /** Required to refresh an oauth credential; omit for an api-only store. */
+    oauth?: OAuthProviderConfig;
+    /** Injected HTTP + clock for deterministic tests; default globals. */
+    deps?: {
+        fetch?: typeof fetch;
+        now?: () => number;
+    };
+}
+export declare function resolveCredential(opts: ResolveCredentialOptions): Promise<ResolvedCredential | undefined>;

package/dist/internal/providers/types.d.ts

@@ -8,4 +8,4 @@
  *
  * @public
  */
-export type { ApiMode, AuthType, ProviderProfile, } from "../../types/provider-profile.js";
+export type { ApiMode, AuthType, ProviderProfile, ProviderTransform, ProviderTransformContext, } from "../../types/provider-profile.js";

package/dist/types/provider-profile.d.ts

@@ -34,7 +34,12 @@ export interface ProviderTransformContext {
  * @public
  */
 export interface ProviderTransform {
-    /** Dynamic per-request headers, merged OVER the profile's static `extraHeaders`. */
+    /**
+     * Dynamic per-request headers, merged OVER the profile's static `extraHeaders`, and spread AFTER the
+     * transport's base `authorization`/`content-type`. A provider that owns its auth MAY intentionally set
+     * `authorization` here to override the resolved bearer — but a stray `authorization`/`content-type` key
+     * will silently replace the base header, so return only the headers you mean to add.
+     */
     headers?(ctx: ProviderTransformContext): Record<string, string>;
     /** A fetch to use for this provider's requests (refresh-aware / fully provider-controlled). */
     fetch?(ctx: ProviderTransformContext): typeof fetch;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.10.0",
-  "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
+  "version": "4.11.0",
+  "description": "TypeScript SDK for the Theo agent harness \u2014 same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheodev/theokit-sdk#readme",
   "bugs": "https://github.com/usetheodev/theokit-sdk/issues",
@@ -218,6 +218,16 @@
         "default": "./dist/sanitize/index.cjs"
       }
     },
+    "./auth": {
+      "import": {
+        "types": "./dist/auth/index.d.ts",
+        "default": "./dist/auth/index.js"
+      },
+      "require": {
+        "types": "./dist/auth/index.d.cts",
+        "default": "./dist/auth/index.cjs"
+      }
+    },
     "./internal/persistence": {
       "import": {
         "types": "./dist/internal/persistence/index.d.ts",