@agentuity/core 2.0.0-beta.0 → 2.0.0

package/src/services/oauth/index.ts

@@ -6,3 +6,5 @@ export * from './scopes.ts';
 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

@@ -19,6 +19,7 @@ export const OAuthClientSchema = z.object({
 	refresh_token_lifetime_seconds: z.number().optional(),
 	id_token_lifetime_seconds: z.number().optional(),
 	allowed_user_ids: z.array(z.string()),
+	internal: z.boolean().optional().default(false),
 	created_at: z.string(),
 	updated_at: z.string(),
 });
@@ -154,6 +155,8 @@ export const OAuthPermissionLevelSchema = z.object({
 	label: z.string(),
 	value: z.string(),
 	scopes: z.array(z.string()),
+	warning: z.boolean().optional(),
+	warningTitle: z.string().optional(),
 });
 
 export type OAuthPermissionLevel = z.infer<typeof OAuthPermissionLevelSchema>;
@@ -238,3 +241,95 @@ export type OAuthUserConsentRevokeResponse = z.infer<typeof OAuthUserConsentRevo
 export type OAuthScopesResponse = z.infer<typeof OAuthScopesResponseSchema>;
 export type OAuthOrgMembersResponse = z.infer<typeof OAuthOrgMembersResponseSchema>;
 export type OAuthKeysRotateResponse = z.infer<typeof OAuthKeysRotateResponseSchema>;
+
+// ============================================================================
+// OAuth 2.0 Authorization Code Flow Types
+// ============================================================================
+
+export const OAuthFlowConfigSchema = z.object({
+	clientId: z.string().optional().describe('OAuth client ID. Defaults to OAUTH_CLIENT_ID env var'),
+	clientSecret: z
+		.string()
+		.optional()
+		.describe('OAuth client secret. Defaults to OAUTH_CLIENT_SECRET env var'),
+	issuer: z
+		.string()
+		.optional()
+		.describe(
+			'OIDC issuer base URL. Defaults to OAUTH_ISSUER env var. Used to derive authorize/token/userinfo URLs'
+		),
+	authorizeUrl: z
+		.string()
+		.optional()
+		.describe('Authorization endpoint. Defaults to OAUTH_AUTHORIZE_URL or {issuer}/authorize'),
+	tokenUrl: z
+		.string()
+		.optional()
+		.describe('Token endpoint. Defaults to OAUTH_TOKEN_URL or {issuer}/oauth/token'),
+	userinfoUrl: z
+		.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()
+		.describe('Space-separated scopes. Defaults to OAUTH_SCOPES or "openid profile email"'),
+	prompt: z
+		.enum(['none', 'login', 'consent', 'select_account'])
+		.optional()
+		.describe(
+			'OIDC prompt parameter. Controls authentication UX: "login" forces re-auth, "consent" forces consent screen, "none" fails if not authenticated, "select_account" lets user pick an account'
+		),
+});
+
+export type OAuthFlowConfig = z.infer<typeof OAuthFlowConfigSchema>;
+
+export const OAuthTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string().optional(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional(),
+	id_token: z.string().optional(),
+});
+
+export type OAuthTokenResponse = z.infer<typeof OAuthTokenResponseSchema>;
+
+export const OAuthUserInfoSchema = z
+	.object({
+		sub: z.string(),
+		name: z.string().optional(),
+		given_name: z.string().optional(),
+		family_name: z.string().optional(),
+		email: z.string().optional(),
+		email_verified: z.boolean().optional(),
+	})
+	.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/project/get.ts

@@ -16,9 +16,18 @@ export const ProjectSchema = z.object({
 	orgId: z.string().describe('the organization id'),
 	cloudRegion: z.string().nullable().optional().describe('the cloud region'),
 	vanityHostname: z.string().nullable().optional().describe('the vanity hostname'),
+	domains: z.array(z.string()).nullable().optional().describe('custom domains for the project'),
 	api_key: z.string().optional().describe('the SDK api key for the project'),
 	env: z.record(z.string(), z.string()).optional().describe('the environment key/values'),
 	secrets: z.record(z.string(), z.string()).optional().describe('the secrets key/values'),
+	urls: z
+		.object({
+			dashboard: z.string().describe('the dashboard URL for the project'),
+			app: z.string().describe('the public URL for the latest deployment'),
+			custom: z.array(z.string()).describe('custom domain URLs'),
+		})
+		.optional()
+		.describe('project URLs'),
 });
 
 export const ProjectGetResponseSchema = APIResponseSchema(ProjectSchema);