@jini-ai/agent-runtime 0.1.0

package/dist/providers/oauth-callback-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-callback-server.js","sourceRoot":"","sources":["../../src/providers/oauth-callback-server.ts"],"names":[],"mappings":"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"}

package/dist/providers/oauth-credentials.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module providers/oauth-credentials
+ *
+ * Runtime credential resolver on top of `oauth-tokens.ts` +
+ * `oauth-provider.ts`: returns a fresh access token, automatically
+ * refreshing in place when the stored token is within the expiry skew
+ * window. Ported from OD's `integrations/xai-credentials.ts`, generalized
+ * to any {@link OAuthPkceProviderConfig} (the origin's `resolveXAIBearer`
+ * hardcoded the xAI refresh call and the `xai-tokens.json` filename).
+ *
+ * Refresh-on-read (lazy) is sufficient because OAuth bearer tokens are
+ * typically short-lived — every active call site naturally sees expiry
+ * often enough that a separate background refresher isn't needed.
+ */
+import { type OAuthPkceProviderConfig } from './oauth-provider.js';
+export interface ResolvedOAuthCredential {
+    accessToken: string;
+    /** Whether this came back unchanged from disk or was refreshed inline. */
+    source: 'stored' | 'refreshed';
+}
+/**
+ * Gets a usable bearer token for `config`'s provider, refreshing in place if
+ * the stored token is within the expiry skew window. Returns null when
+ * nothing is stored, the stored token has no refresh_token to renew with, or
+ * the refresh call fails. Callers should treat null as "no OAuth available,
+ * fall back to API key / re-login UI".
+ */
+export declare function resolveOAuthBearer(config: OAuthPkceProviderConfig, tokenFileName: string, dataDir: string, fetchImpl?: typeof fetch): Promise<ResolvedOAuthCredential | null>;
+//# sourceMappingURL=oauth-credentials.d.ts.map

package/dist/providers/oauth-credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-credentials.d.ts","sourceRoot":"","sources":["../../src/providers/oauth-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAyB,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAQ1F,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EAAE,QAAQ,GAAG,WAAW,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,uBAAuB,EAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CA0CzC"}

package/dist/providers/oauth-credentials.js

@@ -0,0 +1,70 @@
+/**
+ * @module providers/oauth-credentials
+ *
+ * Runtime credential resolver on top of `oauth-tokens.ts` +
+ * `oauth-provider.ts`: returns a fresh access token, automatically
+ * refreshing in place when the stored token is within the expiry skew
+ * window. Ported from OD's `integrations/xai-credentials.ts`, generalized
+ * to any {@link OAuthPkceProviderConfig} (the origin's `resolveXAIBearer`
+ * hardcoded the xAI refresh call and the `xai-tokens.json` filename).
+ *
+ * Refresh-on-read (lazy) is sufficient because OAuth bearer tokens are
+ * typically short-lived — every active call site naturally sees expiry
+ * often enough that a separate background refresher isn't needed.
+ */
+import { refreshOAuthPkceToken } from './oauth-provider.js';
+import { getStoredOAuthToken, isOAuthTokenExpired, setStoredOAuthToken, } from './oauth-tokens.js';
+/**
+ * Gets a usable bearer token for `config`'s provider, refreshing in place if
+ * the stored token is within the expiry skew window. Returns null when
+ * nothing is stored, the stored token has no refresh_token to renew with, or
+ * the refresh call fails. Callers should treat null as "no OAuth available,
+ * fall back to API key / re-login UI".
+ */
+export async function resolveOAuthBearer(config, tokenFileName, dataDir, fetchImpl) {
+    const stored = await getStoredOAuthToken(dataDir, tokenFileName);
+    if (!stored)
+        return null;
+    if (!isOAuthTokenExpired(stored)) {
+        return { accessToken: stored.accessToken, source: 'stored' };
+    }
+    // Within skew window — try a refresh. If there's no refresh_token (some
+    // auth servers don't issue one) the caller has to re-login; recovery
+    // isn't possible here.
+    if (!stored.refreshToken)
+        return null;
+    try {
+        const fresh = await refreshOAuthPkceToken({
+            config,
+            refreshToken: stored.refreshToken,
+            ...(fetchImpl ? { fetchImpl } : {}),
+        });
+        const next = {
+            accessToken: fresh.access_token,
+            tokenType: fresh.token_type ?? 'Bearer',
+            savedAt: Date.now(),
+        };
+        // Preserves the existing refresh_token when the token endpoint omits
+        // one in its response. RFC 6749 §6 lets a server skip refresh_token
+        // rotation and keep the old one valid; dropping it here would leave the
+        // next expiry with nothing to refresh against, forcing the user back
+        // through a full sign-in even though their grant is still good.
+        const carriedRefresh = fresh.refresh_token ?? stored.refreshToken;
+        if (carriedRefresh)
+            next.refreshToken = carriedRefresh;
+        if (typeof fresh.expires_in === 'number') {
+            next.expiresAt = Date.now() + fresh.expires_in * 1000;
+        }
+        if (fresh.scope)
+            next.scope = fresh.scope;
+        await setStoredOAuthToken(dataDir, tokenFileName, next);
+        return { accessToken: next.accessToken, source: 'refreshed' };
+    }
+    catch {
+        // Refresh failed (network blip, revoked refresh_token, server error).
+        // Return null so the caller falls through to API-key resolution and
+        // surfaces a re-login prompt if everything is empty.
+        return null;
+    }
+}
+//# sourceMappingURL=oauth-credentials.js.map

package/dist/providers/oauth-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-credentials.js","sourceRoot":"","sources":["../../src/providers/oauth-credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,qBAAqB,EAAgC,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAQ3B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAA+B,EAC/B,aAAqB,EACrB,OAAe,EACf,SAAwB;IAExB,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACjE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAC/D,CAAC;IAED,wEAAwE;IACxE,qEAAqE;IACrE,uBAAuB;IACvB,IAAI,CAAC,MAAM,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC;YACxC,MAAM;YACN,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,IAAI,GAAqB;YAC7B,WAAW,EAAE,KAAK,CAAC,YAAY;YAC/B,SAAS,EAAE,KAAK,CAAC,UAAU,IAAI,QAAQ;YACvC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;SACpB,CAAC;QACF,qEAAqE;QACrE,oEAAoE;QACpE,wEAAwE;QACxE,qEAAqE;QACrE,gEAAgE;QAChE,MAAM,cAAc,GAAG,KAAK,CAAC,aAAa,IAAI,MAAM,CAAC,YAAY,CAAC;QAClE,IAAI,cAAc;YAAE,IAAI,CAAC,YAAY,GAAG,cAAc,CAAC;QACvD,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YACzC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC;QACxD,CAAC;QACD,IAAI,KAAK,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1C,MAAM,mBAAmB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,CAAC,CAAC;QACxD,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,oEAAoE;QACpE,qDAAqD;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/providers/oauth-provider.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @module providers/oauth-provider
+ *
+ * Generic OAuth Authorization Code + PKCE provider dance (begin / complete /
+ * refresh), parameterized over any fixed-issuer OAuth server — no Dynamic
+ * Client Registration or MCP-resource discovery involved (that's
+ * `mcp-oauth.ts`'s separate, unported concern; see `pkce.ts`'s doc comment).
+ *
+ * Ported from OD's `integrations/xai-oauth.ts`, generalized: the origin
+ * hardcoded xAI's issuer/endpoints/client_id/scope/redirect port directly
+ * into module-level constants and function names (`beginXAIAuth`,
+ * `XAI_OAUTH_CLIENT_ID`, ...) because it only ever needed to talk to one
+ * OAuth server. That shape doesn't generalize to "any BYOK provider that
+ * happens to use OAuth+PKCE instead of a bare API key" — the actual
+ * generic-provider-material classification this task asked for — so the
+ * dance is now a config-driven `beginOAuthPkce`/`completeOAuthPkce`/
+ * `refreshOAuthPkceToken` triad taking an {@link OAuthPkceProviderConfig},
+ * with `XAI_OAUTH_PROVIDER_CONFIG` kept as the one concrete preset the
+ * origin actually shipped (same pattern this package already uses for
+ * `RuntimeAgentDef` — a generic contract type plus concrete `defs/*`
+ * instances).
+ */
+import { type OAuthTokenResponse, type PendingAuthCache } from './pkce.js';
+export interface OAuthPkceProviderConfig {
+    /** Stable id used to key the token in any per-provider cache and to guard against state/provider mismatch. */
+    providerId: string;
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    clientId: string;
+    scope: string;
+}
+export interface BeginOAuthPkceInput {
+    config: OAuthPkceProviderConfig;
+    pending: PendingAuthCache;
+    redirectUri: string;
+}
+export interface BeginOAuthPkceResult {
+    authorizeUrl: string;
+    state: string;
+}
+/**
+ * Pre-redirect half of the OAuth dance. Mints a PKCE verifier/challenge,
+ * builds the authorize URL, and stashes the pending state in `pending`.
+ *
+ * The caller is responsible for sending the user's browser to
+ * `authorizeUrl` and receiving the callback at `redirectUri`. When the
+ * callback arrives, pass `state` and `code` to {@link completeOAuthPkce}.
+ */
+export declare function beginOAuthPkce(input: BeginOAuthPkceInput): BeginOAuthPkceResult;
+export interface CompleteOAuthPkceInput {
+    config: OAuthPkceProviderConfig;
+    pending: PendingAuthCache;
+    state: string;
+    code: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Post-callback half of the OAuth dance. Looks up `state` in `pending`,
+ * validates it (one-shot, TTL-checked by {@link PendingAuthCache}), and
+ * exchanges `code` for tokens. Throws if `state` is unknown, expired,
+ * already consumed, or was issued for a different provider.
+ */
+export declare function completeOAuthPkce(input: CompleteOAuthPkceInput): Promise<OAuthTokenResponse>;
+export interface RefreshOAuthPkceInput {
+    config: OAuthPkceProviderConfig;
+    refreshToken: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Refreshes an existing access token. The refresh_token is bound to the
+ * client_id that originally received it (RFC 6749 §6); since the same fixed
+ * client_id is always used, it doesn't need to be persisted per-token.
+ */
+export declare function refreshOAuthPkceToken(input: RefreshOAuthPkceInput): Promise<OAuthTokenResponse>;
+/** Stable provider id used to key an xAI token in any per-provider cache. */
+export declare const XAI_OAUTH_PROVIDER_ID = "xai";
+export declare const XAI_OAUTH_REDIRECT_HOST = "127.0.0.1";
+export declare const XAI_OAUTH_REDIRECT_PORT = 56121;
+export declare const XAI_OAUTH_REDIRECT_PATH = "/callback";
+/**
+ * xAI Grok OAuth 2.0 + PKCE provider config. xAI doesn't speak MCP and
+ * doesn't expose Dynamic Client Registration, so the issuer / endpoints /
+ * client_id / scope are hardcoded rather than discovered — same as the
+ * origin.
+ *
+ * `clientId` is a proof-of-concept id reused from NousResearch/hermes-agent
+ * (xAI does not publish a public application-registration flow); a
+ * consumer that provisions its own client_id with xAI should override this
+ * field rather than edit the constant.
+ */
+export declare const XAI_OAUTH_PROVIDER_CONFIG: OAuthPkceProviderConfig;
+/** The fixed loopback redirect URI xAI's client_id is registered against. */
+export declare function xaiOAuthRedirectUri(): string;
+//# sourceMappingURL=oauth-provider.d.ts.map

package/dist/providers/oauth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.d.ts","sourceRoot":"","sources":["../../src/providers/oauth-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAQL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EAEtB,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,uBAAuB;IACtC,8GAA8G;IAC9G,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,uBAAuB,CAAC;IAChC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAUD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,oBAAoB,CA4B/E;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,uBAAuB,CAAC;IAChC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAoB7B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,uBAAuB,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAS7B;AAMD,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,eAAO,MAAM,uBAAuB,cAAc,CAAC;AACnD,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAC7C,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,uBAOvC,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/providers/oauth-provider.js

@@ -0,0 +1,130 @@
+/**
+ * @module providers/oauth-provider
+ *
+ * Generic OAuth Authorization Code + PKCE provider dance (begin / complete /
+ * refresh), parameterized over any fixed-issuer OAuth server — no Dynamic
+ * Client Registration or MCP-resource discovery involved (that's
+ * `mcp-oauth.ts`'s separate, unported concern; see `pkce.ts`'s doc comment).
+ *
+ * Ported from OD's `integrations/xai-oauth.ts`, generalized: the origin
+ * hardcoded xAI's issuer/endpoints/client_id/scope/redirect port directly
+ * into module-level constants and function names (`beginXAIAuth`,
+ * `XAI_OAUTH_CLIENT_ID`, ...) because it only ever needed to talk to one
+ * OAuth server. That shape doesn't generalize to "any BYOK provider that
+ * happens to use OAuth+PKCE instead of a bare API key" — the actual
+ * generic-provider-material classification this task asked for — so the
+ * dance is now a config-driven `beginOAuthPkce`/`completeOAuthPkce`/
+ * `refreshOAuthPkceToken` triad taking an {@link OAuthPkceProviderConfig},
+ * with `XAI_OAUTH_PROVIDER_CONFIG` kept as the one concrete preset the
+ * origin actually shipped (same pattern this package already uses for
+ * `RuntimeAgentDef` — a generic contract type plus concrete `defs/*`
+ * instances).
+ */
+import { buildAuthorizeUrl, deriveCodeChallenge, exchangeCodeForToken, generateCodeVerifier, generateState, refreshAccessToken, } from './pkce.js';
+function authServerMetadata(config) {
+    return {
+        issuer: config.issuer,
+        authorization_endpoint: config.authorizationEndpoint,
+        token_endpoint: config.tokenEndpoint,
+    };
+}
+/**
+ * Pre-redirect half of the OAuth dance. Mints a PKCE verifier/challenge,
+ * builds the authorize URL, and stashes the pending state in `pending`.
+ *
+ * The caller is responsible for sending the user's browser to
+ * `authorizeUrl` and receiving the callback at `redirectUri`. When the
+ * callback arrives, pass `state` and `code` to {@link completeOAuthPkce}.
+ */
+export function beginOAuthPkce(input) {
+    const { config, pending, redirectUri } = input;
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = deriveCodeChallenge(codeVerifier);
+    const state = generateState();
+    const authorizeUrl = buildAuthorizeUrl({
+        authServer: authServerMetadata(config),
+        clientId: config.clientId,
+        redirectUri,
+        state,
+        codeChallenge,
+        scope: config.scope,
+    });
+    const pendingState = {
+        serverId: config.providerId,
+        authServerIssuer: config.issuer,
+        tokenEndpoint: config.tokenEndpoint,
+        clientId: config.clientId,
+        redirectUri,
+        codeVerifier,
+        scope: config.scope,
+        createdAt: Date.now(),
+    };
+    pending.put(state, pendingState);
+    return { authorizeUrl, state };
+}
+/**
+ * Post-callback half of the OAuth dance. Looks up `state` in `pending`,
+ * validates it (one-shot, TTL-checked by {@link PendingAuthCache}), and
+ * exchanges `code` for tokens. Throws if `state` is unknown, expired,
+ * already consumed, or was issued for a different provider.
+ */
+export async function completeOAuthPkce(input) {
+    const consumed = input.pending.consume(input.state);
+    if (!consumed) {
+        throw new Error(`${input.config.providerId} OAuth state not found or expired`);
+    }
+    if (consumed.serverId !== input.config.providerId) {
+        throw new Error(`${input.config.providerId} OAuth state mismatch: expected serverId=${input.config.providerId}, got ${consumed.serverId}`);
+    }
+    return exchangeCodeForToken({
+        tokenEndpoint: consumed.tokenEndpoint,
+        clientId: consumed.clientId,
+        redirectUri: consumed.redirectUri,
+        code: input.code,
+        codeVerifier: consumed.codeVerifier,
+    }, input.fetchImpl ?? fetch);
+}
+/**
+ * Refreshes an existing access token. The refresh_token is bound to the
+ * client_id that originally received it (RFC 6749 §6); since the same fixed
+ * client_id is always used, it doesn't need to be persisted per-token.
+ */
+export async function refreshOAuthPkceToken(input) {
+    return refreshAccessToken({
+        tokenEndpoint: input.config.tokenEndpoint,
+        clientId: input.config.clientId,
+        refreshToken: input.refreshToken,
+    }, input.fetchImpl ?? fetch);
+}
+// ---------------------------------------------------------------------------
+// Concrete preset: the one OAuth+PKCE provider the origin actually shipped.
+// ---------------------------------------------------------------------------
+/** Stable provider id used to key an xAI token in any per-provider cache. */
+export const XAI_OAUTH_PROVIDER_ID = 'xai';
+export const XAI_OAUTH_REDIRECT_HOST = '127.0.0.1';
+export const XAI_OAUTH_REDIRECT_PORT = 56121;
+export const XAI_OAUTH_REDIRECT_PATH = '/callback';
+/**
+ * xAI Grok OAuth 2.0 + PKCE provider config. xAI doesn't speak MCP and
+ * doesn't expose Dynamic Client Registration, so the issuer / endpoints /
+ * client_id / scope are hardcoded rather than discovered — same as the
+ * origin.
+ *
+ * `clientId` is a proof-of-concept id reused from NousResearch/hermes-agent
+ * (xAI does not publish a public application-registration flow); a
+ * consumer that provisions its own client_id with xAI should override this
+ * field rather than edit the constant.
+ */
+export const XAI_OAUTH_PROVIDER_CONFIG = {
+    providerId: XAI_OAUTH_PROVIDER_ID,
+    issuer: 'https://auth.x.ai',
+    authorizationEndpoint: 'https://auth.x.ai/oauth2/authorize',
+    tokenEndpoint: 'https://auth.x.ai/oauth2/token',
+    clientId: 'b1a00492-073a-47ea-816f-4c329264a828',
+    scope: 'openid profile email offline_access grok-cli:access api:access',
+};
+/** The fixed loopback redirect URI xAI's client_id is registered against. */
+export function xaiOAuthRedirectUri() {
+    return `http://${XAI_OAUTH_REDIRECT_HOST}:${XAI_OAUTH_REDIRECT_PORT}${XAI_OAUTH_REDIRECT_PATH}`;
+}
+//# sourceMappingURL=oauth-provider.js.map

package/dist/providers/oauth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-provider.js","sourceRoot":"","sources":["../../src/providers/oauth-provider.ts"],"names":[],"mappings":"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"}

package/dist/providers/oauth-tokens.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stored OAuth token. Mirrors the relevant subset of an OAuth 2.0
+ * token-endpoint response (RFC 6749 §5.1). `client_id`, `redirect_uri`, and
+ * `issuer` aren't persisted because they're constants in the provider's own
+ * `OAuthPkceProviderConfig`.
+ */
+export interface StoredOAuthToken {
+    /** The bearer token to send as `Authorization: Bearer ...`. */
+    accessToken: string;
+    /** Refresh token (RFC 6749 §6) if the auth server issued one. */
+    refreshToken?: string;
+    /** Absolute epoch ms at which `accessToken` expires. Optional — some providers never expire. */
+    expiresAt?: number;
+    /** RFC 6749 §5.1 token_type. Almost always `Bearer`. */
+    tokenType: string;
+    /** Space-separated scopes granted (verbatim from the token response). */
+    scope?: string;
+    /** Wall-clock epoch ms when this record was first persisted. */
+    savedAt: number;
+}
+export interface OAuthTokenFile {
+    token?: StoredOAuthToken;
+}
+/** Coerces a freeform JSON blob into the typed shape, dropping anything that doesn't deserialize cleanly. Used both at read time and as a defensive pass when third-party tooling has hand-edited the file. */
+export declare function sanitizeOAuthTokenFile(raw: unknown): OAuthTokenFile;
+export declare function readOAuthTokenFile(dataDir: string, fileName: string): Promise<OAuthTokenFile>;
+/** Gets the current stored OAuth token for `fileName`, or null when none is stored (or the persisted entry is malformed). */
+export declare function getStoredOAuthToken(dataDir: string, fileName: string): Promise<StoredOAuthToken | null>;
+/** Atomically replaces the stored OAuth token for `fileName`. */
+export declare function setStoredOAuthToken(dataDir: string, fileName: string, token: StoredOAuthToken): Promise<void>;
+/** Atomically deletes the stored OAuth token for `fileName`. No-op when absent. */
+export declare function clearStoredOAuthToken(dataDir: string, fileName: string): Promise<void>;
+/** True when the stored token is past its `expiresAt` (or within `skew` milliseconds of expiring). Returns false when no `expiresAt` is recorded — some providers issue non-expiring tokens. */
+export declare function isOAuthTokenExpired(token: StoredOAuthToken, now?: number, skew?: number): boolean;
+//# sourceMappingURL=oauth-tokens.d.ts.map

package/dist/providers/oauth-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-tokens.d.ts","sourceRoot":"","sources":["../../src/providers/oauth-tokens.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAYD,+MAA+M;AAC/M,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAInE;AAkCD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAanG;AA2CD,6HAA6H;AAC7H,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAGlC;AAED,iEAAiE;AACjE,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,mFAAmF;AACnF,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5F;AAED,gMAAgM;AAChM,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EACvB,GAAG,GAAE,MAAmB,EACxB,IAAI,GAAE,MAAgB,GACrB,OAAO,CAGT"}

package/dist/providers/oauth-tokens.js

@@ -0,0 +1,136 @@
+/**
+ * @module providers/oauth-tokens
+ *
+ * Persistent OAuth token storage: atomic write + per-file in-memory mutex +
+ * best-effort `chmod 0600`. Ported from OD's `integrations/xai-tokens.ts`,
+ * generalized: the origin hardcoded the on-disk filename (`xai-tokens.json`)
+ * and type names (`StoredXAIToken`) for xAI's single-account case. Since a
+ * host may want this same single-token-per-provider storage shape for any
+ * OAuth+PKCE provider (not just xAI), the file name is now a caller-supplied
+ * parameter and the types are provider-neutral. The on-disk layout is still
+ * `{ token: ... }` (room for a future multi-account schema without breaking
+ * existing files) and the write path is unchanged.
+ */
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+const EMPTY = {};
+function tokenFilePath(dataDir, fileName) {
+    return path.join(dataDir, fileName);
+}
+function isPlainObject(v) {
+    return Boolean(v) && typeof v === 'object' && !Array.isArray(v);
+}
+/** Coerces a freeform JSON blob into the typed shape, dropping anything that doesn't deserialize cleanly. Used both at read time and as a defensive pass when third-party tooling has hand-edited the file. */
+export function sanitizeOAuthTokenFile(raw) {
+    if (!isPlainObject(raw))
+        return {};
+    const tok = sanitizeToken(raw.token);
+    return tok ? { token: tok } : {};
+}
+function sanitizeToken(raw) {
+    if (!isPlainObject(raw))
+        return null;
+    const accessToken = typeof raw.accessToken === 'string' ? raw.accessToken.trim() : '';
+    if (!accessToken)
+        return null;
+    const tokenType = typeof raw.tokenType === 'string' && raw.tokenType.trim()
+        ? raw.tokenType.trim()
+        : 'Bearer';
+    const refreshToken = typeof raw.refreshToken === 'string' && raw.refreshToken.trim()
+        ? raw.refreshToken.trim()
+        : undefined;
+    const scope = typeof raw.scope === 'string' && raw.scope.trim()
+        ? raw.scope.trim()
+        : undefined;
+    const expiresAt = typeof raw.expiresAt === 'number' && Number.isFinite(raw.expiresAt)
+        ? raw.expiresAt
+        : undefined;
+    const savedAt = typeof raw.savedAt === 'number' && Number.isFinite(raw.savedAt)
+        ? raw.savedAt
+        : Date.now();
+    const out = { accessToken, tokenType, savedAt };
+    if (refreshToken)
+        out.refreshToken = refreshToken;
+    if (scope)
+        out.scope = scope;
+    if (expiresAt !== undefined)
+        out.expiresAt = expiresAt;
+    return out;
+}
+export async function readOAuthTokenFile(dataDir, fileName) {
+    try {
+        const raw = await readFile(tokenFilePath(dataDir, fileName), 'utf8');
+        return sanitizeOAuthTokenFile(JSON.parse(raw));
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            return { ...EMPTY };
+        if (e.name === 'SyntaxError') {
+            console.error('[oauth-tokens] Corrupted JSON, returning empty:', e.message);
+            return { ...EMPTY };
+        }
+        throw err;
+    }
+}
+const writeLocks = new Map();
+async function withLock(lockKey, fn) {
+    const prev = writeLocks.get(lockKey) ?? Promise.resolve();
+    const task = prev.catch(() => { }).then(fn);
+    writeLocks.set(lockKey, task);
+    try {
+        return await task;
+    }
+    finally {
+        if (writeLocks.get(lockKey) === task)
+            writeLocks.delete(lockKey);
+    }
+}
+async function writeTokenFile(dataDir, fileName, next) {
+    const file = tokenFilePath(dataDir, fileName);
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = file + '.' + randomBytes(4).toString('hex') + '.tmp';
+    await writeFile(tmp, JSON.stringify(next, null, 2), 'utf8');
+    await rename(tmp, file);
+    // Best-effort lockdown of file mode. A bearer token grants API access on
+    // the user's behalf, so restrict to owner-only read/write where the OS
+    // supports it.
+    try {
+        await chmod(file, 0o600);
+    }
+    catch (err) {
+        const e = err;
+        if (e.code !== 'ENOTSUP' && e.code !== 'EPERM') {
+            console.warn('[oauth-tokens] could not chmod 0600', file, e.message ?? err);
+        }
+    }
+    return next;
+}
+/** Gets the current stored OAuth token for `fileName`, or null when none is stored (or the persisted entry is malformed). */
+export async function getStoredOAuthToken(dataDir, fileName) {
+    const file = await readOAuthTokenFile(dataDir, fileName);
+    return file.token ?? null;
+}
+/** Atomically replaces the stored OAuth token for `fileName`. */
+export async function setStoredOAuthToken(dataDir, fileName, token) {
+    await withLock(`${dataDir}\0${fileName}`, async () => {
+        await writeTokenFile(dataDir, fileName, { token });
+    });
+}
+/** Atomically deletes the stored OAuth token for `fileName`. No-op when absent. */
+export async function clearStoredOAuthToken(dataDir, fileName) {
+    await withLock(`${dataDir}\0${fileName}`, async () => {
+        const file = await readOAuthTokenFile(dataDir, fileName);
+        if (!file.token)
+            return;
+        await writeTokenFile(dataDir, fileName, {});
+    });
+}
+/** True when the stored token is past its `expiresAt` (or within `skew` milliseconds of expiring). Returns false when no `expiresAt` is recorded — some providers issue non-expiring tokens. */
+export function isOAuthTokenExpired(token, now = Date.now(), skew = 120_000) {
+    if (typeof token.expiresAt !== 'number')
+        return false;
+    return token.expiresAt - skew <= now;
+}
+//# sourceMappingURL=oauth-tokens.js.map

package/dist/providers/oauth-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-tokens.js","sourceRoot":"","sources":["../../src/providers/oauth-tokens.ts"],"names":[],"mappings":"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"}