@agentuity/core 1.0.55 → 1.0.57

package/src/services/oauth/flow.ts

@@ -25,11 +25,28 @@ function resolveConfig(config?: OAuthFlowConfig) {
 		config?.userinfoUrl ??
 		getEnv('OAUTH_USERINFO_URL') ??
 		(issuer ? `${issuer}/userinfo` : undefined);
+	const revokeUrl =
+		config?.revokeUrl ?? getEnv('OAUTH_REVOKE_URL') ?? (issuer ? `${issuer}/revoke` : undefined);
+	const endSessionUrl =
+		config?.endSessionUrl ??
+		getEnv('OAUTH_END_SESSION_URL') ??
+		(issuer ? `${issuer}/end_session` : undefined);
 	const scopes = config?.scopes ?? getEnv('OAUTH_SCOPES') ?? 'openid profile email';
 
 	const prompt = config?.prompt;
 
-	return { clientId, clientSecret, issuer, authorizeUrl, tokenUrl, userinfoUrl, scopes, prompt };
+	return {
+		clientId,
+		clientSecret,
+		issuer,
+		authorizeUrl,
+		tokenUrl,
+		userinfoUrl,
+		revokeUrl,
+		endSessionUrl,
+		scopes,
+		prompt,
+	};
 }
 
 /**
@@ -118,9 +135,6 @@ export async function exchangeToken(
 		});
 	}
 
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
-
 	let response: Response;
 	try {
 		response = await fetch(resolved.tokenUrl, {
@@ -133,18 +147,16 @@ export async function exchangeToken(
 				client_id: resolved.clientId,
 				client_secret: resolved.clientSecret,
 			}),
-			signal: controller.signal,
+			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
 		});
 	} catch (err) {
-		clearTimeout(timer);
-		if (err instanceof DOMException && err.name === 'AbortError') {
+		if (err instanceof DOMException && err.name === 'TimeoutError') {
 			throw new OAuthResponseError({
 				message: `Token exchange timed out after ${DEFAULT_TIMEOUT_MS}ms`,
 			});
 		}
 		throw err;
 	}
-	clearTimeout(timer);
 
 	if (!response.ok) {
 		const error = await response.text();
@@ -157,6 +169,140 @@ export async function exchangeToken(
 	return OAuthTokenResponseSchema.parse(data);
 }
 
+/**
+ * Refresh an access token using a refresh token.
+ *
+ * @param refreshTokenValue - The refresh token obtained from a previous token exchange
+ * @param config - Optional OAuth configuration. Falls back to environment variables.
+ * @returns The token response including a new access_token, and optionally a new refresh_token
+ *
+ * @example
+ * ```typescript
+ * const newToken = await refreshToken(previousToken.refresh_token!);
+ * console.log(newToken.access_token);
+ * ```
+ */
+export async function refreshToken(
+	refreshTokenValue: string,
+	config?: OAuthFlowConfig
+): Promise<OAuthTokenResponse> {
+	const resolved = resolveConfig(config);
+
+	if (!resolved.tokenUrl) {
+		throw new OAuthResponseError({
+			message:
+				'No token URL configured. Set OAUTH_TOKEN_URL or OAUTH_ISSUER environment variable.',
+		});
+	}
+	if (!resolved.clientId) {
+		throw new OAuthResponseError({
+			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
+		});
+	}
+
+	const params = new URLSearchParams({
+		grant_type: 'refresh_token',
+		refresh_token: refreshTokenValue,
+		client_id: resolved.clientId,
+	});
+
+	if (resolved.clientSecret) {
+		params.set('client_secret', resolved.clientSecret);
+	}
+
+	let response: Response;
+	try {
+		response = await fetch(resolved.tokenUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+			body: params,
+			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+		});
+	} catch (err) {
+		if (err instanceof DOMException && err.name === 'TimeoutError') {
+			throw new OAuthResponseError({
+				message: `Token refresh timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+			});
+		}
+		throw err;
+	}
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new OAuthResponseError({
+			message: `Token refresh failed (${response.status}): ${error}`,
+		});
+	}
+
+	const data = await response.json();
+	return OAuthTokenResponseSchema.parse(data);
+}
+
+/**
+ * Revoke an OAuth token (access token or refresh token) to log the user out.
+ *
+ * Calls the token revocation endpoint (RFC 7009). The server will invalidate
+ * the token so it can no longer be used. Per the spec, the endpoint returns
+ * a success response even if the token was already invalid.
+ *
+ * @param token - The access token or refresh token to revoke
+ * @param config - Optional OAuth configuration. Falls back to environment variables.
+ *
+ * @example
+ * ```typescript
+ * // Revoke the refresh token to fully log out
+ * await logout(token.refresh_token!);
+ * ```
+ */
+export async function logout(token: string, config?: OAuthFlowConfig): Promise<void> {
+	const resolved = resolveConfig(config);
+
+	if (!resolved.revokeUrl) {
+		throw new OAuthResponseError({
+			message:
+				'No revoke URL configured. Set OAUTH_REVOKE_URL or OAUTH_ISSUER environment variable.',
+		});
+	}
+	if (!resolved.clientId) {
+		throw new OAuthResponseError({
+			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
+		});
+	}
+
+	const params = new URLSearchParams({
+		token,
+		client_id: resolved.clientId,
+	});
+
+	if (resolved.clientSecret) {
+		params.set('client_secret', resolved.clientSecret);
+	}
+
+	let response: Response;
+	try {
+		response = await fetch(resolved.revokeUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+			body: params,
+			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+		});
+	} catch (err) {
+		if (err instanceof DOMException && err.name === 'TimeoutError') {
+			throw new OAuthResponseError({
+				message: `Token revocation timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+			});
+		}
+		throw err;
+	}
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new OAuthResponseError({
+			message: `Token revocation failed (${response.status}): ${error}`,
+		});
+	}
+}
+
 /**
  * Fetch user information from the OIDC userinfo endpoint using an access token.
  *
@@ -183,25 +329,20 @@ export async function fetchUserInfo(
 		});
 	}
 
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
-
 	let response: Response;
 	try {
 		response = await fetch(resolved.userinfoUrl, {
 			headers: { Authorization: `Bearer ${accessToken}` },
-			signal: controller.signal,
+			signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
 		});
 	} catch (err) {
-		clearTimeout(timer);
-		if (err instanceof DOMException && err.name === 'AbortError') {
+		if (err instanceof DOMException && err.name === 'TimeoutError') {
 			throw new OAuthResponseError({
 				message: `Userinfo request timed out after ${DEFAULT_TIMEOUT_MS}ms`,
 			});
 		}
 		throw err;
 	}
-	clearTimeout(timer);
 
 	if (!response.ok) {
 		const error = await response.text();

package/src/services/oauth/index.ts

@@ -7,3 +7,4 @@ export * from './members.ts';
 export * from './keys.ts';
 export * from './util.ts';
 export * from './flow.ts';
+export * from './token-storage.ts';

package/src/services/oauth/token-storage.ts

@@ -0,0 +1,220 @@
+import type { KeyValueStorage } from '../keyvalue/service.ts';
+import type { OAuthFlowConfig, OAuthTokenResponse, StoredToken } from './types.ts';
+import { StoredTokenSchema } from './types.ts';
+import { refreshToken, logout } from './flow.ts';
+
+const DEFAULT_NAMESPACE = 'oauth-tokens';
+
+/**
+ * Check whether a stored token's access token has expired.
+ *
+ * @param token - The stored token to check
+ * @returns true if the token has an expires_at timestamp that is in the past
+ *
+ * @example
+ * ```typescript
+ * const token = await storage.get('user:123');
+ * if (token && isTokenExpired(token)) {
+ *   // Token is expired and auto-refresh wasn't available
+ * }
+ * ```
+ */
+export function isTokenExpired(token: StoredToken): boolean {
+	if (!token.expires_at) return false;
+	return Math.floor(Date.now() / 1000) >= token.expires_at;
+}
+
+/**
+ * Options for configuring a TokenStorage instance.
+ */
+export interface TokenStorageOptions {
+	/**
+	 * OAuth configuration for auto-refresh and token revocation.
+	 * If not provided, auto-refresh on get() and server-side revocation on invalidate() are disabled.
+	 */
+	config?: OAuthFlowConfig;
+
+	/**
+	 * KV namespace for storing tokens. Defaults to 'oauth-tokens'.
+	 */
+	namespace?: string;
+
+	/**
+	 * Key prefix prepended to all storage keys.
+	 * Useful for scoping tokens by application or tenant.
+	 */
+	prefix?: string;
+}
+
+/**
+ * Interface for storing, retrieving, and invalidating OAuth tokens.
+ *
+ * Implementations handle persistence and may support automatic token refresh
+ * on retrieval and server-side revocation on invalidation.
+ */
+export interface TokenStorage {
+	/**
+	 * Retrieve a stored token by key.
+	 *
+	 * If the token is expired and a refresh_token is available (and config is provided),
+	 * the token is automatically refreshed, stored, and the new token is returned.
+	 * If auto-refresh fails, the expired token is returned so the caller can decide
+	 * how to handle it (check with {@link isTokenExpired}).
+	 *
+	 * @param key - The storage key (e.g. a user ID or session ID)
+	 * @returns The stored token, or null if no token exists for the key
+	 */
+	get(key: string): Promise<StoredToken | null>;
+
+	/**
+	 * Store a token response from a token exchange or refresh.
+	 *
+	 * Automatically computes `expires_at` from `expires_in` if present.
+	 *
+	 * @param key - The storage key (e.g. a user ID or session ID)
+	 * @param token - The OAuth token response to store
+	 */
+	set(key: string, token: OAuthTokenResponse): Promise<void>;
+
+	/**
+	 * Invalidate a stored token: revoke it server-side and remove from storage.
+	 *
+	 * If config is provided, the refresh token (or access token as fallback)
+	 * is revoked via the token revocation endpoint. Revocation is best-effort —
+	 * the token is removed from storage regardless of whether revocation succeeds.
+	 *
+	 * @param key - The storage key to invalidate
+	 * @returns The token that was removed, or null if no token existed
+	 */
+	invalidate(key: string): Promise<StoredToken | null>;
+}
+
+/**
+ * Convert an OAuth token response to a StoredToken with computed expires_at.
+ */
+function toStoredToken(token: OAuthTokenResponse): StoredToken {
+	return {
+		access_token: token.access_token,
+		token_type: token.token_type,
+		refresh_token: token.refresh_token,
+		scope: token.scope,
+		id_token: token.id_token,
+		expires_at: token.expires_in ? Math.floor(Date.now() / 1000) + token.expires_in : undefined,
+	};
+}
+
+/**
+ * Token storage backed by Agentuity's Key-Value storage service.
+ *
+ * Stores tokens as JSON in a KV namespace. Supports automatic token refresh
+ * on retrieval when tokens expire (if OAuth config is provided).
+ *
+ * @example
+ * ```typescript
+ * import { KeyValueTokenStorage } from '@agentuity/core/oauth';
+ *
+ * // Create storage with auto-refresh enabled
+ * const storage = new KeyValueTokenStorage(ctx.kv, {
+ *   config: { issuer: 'https://auth.example.com' },
+ * });
+ *
+ * // Store a token after initial exchange
+ * await storage.set('user:123', tokenResponse);
+ *
+ * // Retrieve — auto-refreshes if expired
+ * const token = await storage.get('user:123');
+ *
+ * // Logout — revokes server-side and removes from storage
+ * await storage.invalidate('user:123');
+ * ```
+ */
+export class KeyValueTokenStorage implements TokenStorage {
+	#kv: KeyValueStorage;
+	#namespace: string;
+	#prefix: string;
+	#config?: OAuthFlowConfig;
+
+	constructor(kv: KeyValueStorage, options?: TokenStorageOptions) {
+		this.#kv = kv;
+		this.#namespace = options?.namespace ?? DEFAULT_NAMESPACE;
+		this.#prefix = options?.prefix ?? '';
+		this.#config = options?.config;
+	}
+
+	async get(key: string): Promise<StoredToken | null> {
+		const result = await this.#kv.get<StoredToken>(this.#namespace, this.#resolveKey(key));
+		if (!result.exists) return null;
+
+		const parsed = StoredTokenSchema.safeParse(result.data);
+		if (!parsed.success) return null;
+
+		const token = parsed.data;
+
+		// Auto-refresh if expired and refresh_token + config are available
+		if (isTokenExpired(token) && token.refresh_token && this.#config) {
+			try {
+				const newTokenResponse = await refreshToken(token.refresh_token, this.#config);
+				const newStored = toStoredToken(newTokenResponse);
+				await this.#store(key, newStored);
+				return newStored;
+			} catch {
+				// Refresh failed — return the expired token, caller can check isTokenExpired()
+				return token;
+			}
+		}
+
+		return token;
+	}
+
+	async set(key: string, token: OAuthTokenResponse): Promise<void> {
+		const stored = toStoredToken(token);
+		await this.#store(key, stored);
+	}
+
+	async invalidate(key: string): Promise<StoredToken | null> {
+		const resolvedKey = this.#resolveKey(key);
+		const result = await this.#kv.get<StoredToken>(this.#namespace, resolvedKey);
+
+		if (!result.exists) return null;
+
+		const parsed = StoredTokenSchema.safeParse(result.data);
+		const token = parsed.success ? parsed.data : null;
+
+		// Revoke server-side (best effort)
+		if (token && this.#config) {
+			const tokenToRevoke = token.refresh_token ?? token.access_token;
+			try {
+				await logout(tokenToRevoke, this.#config);
+			} catch {
+				// Best effort — continue with storage cleanup
+			}
+		}
+
+		// Remove from storage regardless of revocation result
+		await this.#kv.delete(this.#namespace, resolvedKey);
+
+		return token;
+	}
+
+	async #store(key: string, token: StoredToken): Promise<void> {
+		// Only set explicit TTL for tokens without a refresh_token.
+		// Tokens with refresh capability persist until explicitly invalidated
+		// (auto-refresh on get() will keep them fresh).
+		let ttl: number | undefined;
+		if (!token.refresh_token && token.expires_at) {
+			const remaining = token.expires_at - Math.floor(Date.now() / 1000);
+			if (remaining > 0) {
+				ttl = Math.max(remaining, 60); // KV minimum is 60 seconds
+			}
+		}
+
+		await this.#kv.set(this.#namespace, this.#resolveKey(key), token, {
+			ttl,
+			contentType: 'application/json',
+		});
+	}
+
+	#resolveKey(key: string): string {
+		return this.#prefix ? `${this.#prefix}${key}` : key;
+	}
+}

package/src/services/oauth/types.ts

@@ -268,6 +268,18 @@ export const OAuthFlowConfigSchema = z.object({
 		.string()
 		.optional()
 		.describe('UserInfo endpoint. Defaults to OAUTH_USERINFO_URL or {issuer}/userinfo'),
+	revokeUrl: z
+		.string()
+		.optional()
+		.describe(
+			'Token revocation endpoint (RFC 7009). Defaults to OAUTH_REVOKE_URL or {issuer}/revoke'
+		),
+	endSessionUrl: z
+		.string()
+		.optional()
+		.describe(
+			'OIDC end session endpoint. Defaults to OAUTH_END_SESSION_URL or {issuer}/end_session'
+		),
 	scopes: z
 		.string()
 		.optional()
@@ -305,3 +317,17 @@ export const OAuthUserInfoSchema = z
 	.catchall(z.unknown());
 
 export type OAuthUserInfo = z.infer<typeof OAuthUserInfoSchema>;
+
+export const StoredTokenSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional(),
+	id_token: z.string().optional(),
+	expires_at: z
+		.number()
+		.optional()
+		.describe('Unix timestamp (seconds) when the access token expires'),
+});
+
+export type StoredToken = z.infer<typeof StoredTokenSchema>;

package/src/services/sandbox/execute.ts

@@ -1,7 +1,7 @@
 import type { ExecuteOptions, Execution, ExecutionStatus } from './types.ts';
 import { z } from 'zod';
 import type { APIClient } from '../api.ts';
-import { SandboxBusyError, throwSandboxError } from './util.ts';
+import { SandboxBusyError, SandboxNotFoundError, throwSandboxError } from './util.ts';
 
 export const ExecuteRequestSchema = z
 	.object({
@@ -114,23 +114,37 @@ export async function sandboxExecute(
 			signal ?? options.signal
 		);
 	} catch (error: unknown) {
-		// Detect 409 Conflict (sandbox busy) and throw a specific error.
-		// The sandbox API client is configured with maxRetries: 0 to fail fast
-		// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
-		// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
 		if (
 			error &&
 			typeof error === 'object' &&
 			'_tag' in error &&
 			(error as { _tag: string })._tag === 'APIErrorResponse' &&
-			'status' in error &&
-			(error as { status: number }).status === 409
+			'status' in error
 		) {
-			throw new SandboxBusyError({
-				message:
-					'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
-				sandboxId,
-			});
+			const status = (error as { status: number }).status;
+
+			// Detect 404 Not Found — sandbox may not exist or may still be initializing.
+			// The server normally handles the creating→idle wait transparently, but this
+			// provides a clear typed error if a 404 reaches the SDK for any reason.
+			if (status === 404) {
+				throw new SandboxNotFoundError({
+					message:
+						'Sandbox not found. If you just created this sandbox, it may still be initializing. The server should handle this automatically — if this persists, the sandbox may have been destroyed.',
+					sandboxId,
+				});
+			}
+
+			// Detect 409 Conflict (sandbox busy) and throw a specific error.
+			// The sandbox API client is configured with maxRetries: 0 to fail fast
+			// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
+			// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
+			if (status === 409) {
+				throw new SandboxBusyError({
+					message:
+						'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
+					sandboxId,
+				});
+			}
 		}
 		throw error;
 	}