@jezweb/oauth-token-manager 0.1.0

package/dist/storage/d1.js

@@ -0,0 +1,31 @@
+/**
+ * Cloudflare D1 Storage Adapter (Placeholder)
+ *
+ * D1 provides stronger consistency guarantees than KV and allows
+ * for more complex queries (e.g., find all tokens expiring soon).
+ *
+ * TODO: Implement full D1 adapter with migrations
+ */
+/**
+ * D1 Storage adapter for Cloudflare D1
+ *
+ * NOT YET IMPLEMENTED - Use KVStorage for now
+ */
+export class D1Storage {
+    constructor(_db, _encryptionKey) {
+        throw new Error('D1Storage is not yet implemented. Use KVStorage instead, or contribute an implementation!');
+    }
+    get(_userId, _provider) {
+        throw new Error('Not implemented');
+    }
+    set(_token) {
+        throw new Error('Not implemented');
+    }
+    delete(_userId, _provider) {
+        throw new Error('Not implemented');
+    }
+    list(_userId) {
+        throw new Error('Not implemented');
+    }
+}
+//# sourceMappingURL=d1.js.map

package/dist/storage/d1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"d1.js","sourceRoot":"","sources":["../../src/storage/d1.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;GAIG;AACH,MAAM,OAAO,SAAS;IACpB,YAAY,GAAe,EAAE,cAAsB;QACjD,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,OAAe,EAAE,SAAiB;QACpC,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAED,GAAG,CAAC,MAAmB;QACrB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,OAAe,EAAE,SAAiB;QACvC,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,OAAe;QAClB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;CACF"}

package/dist/storage/kv.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cloudflare KV Storage Adapter
+ *
+ * Key structure:
+ * - tokens:{userId}:{provider} → encrypted token data
+ * - token-index:{userId} → JSON array of provider IDs (for listing)
+ *
+ * Note: KV is eventually consistent. For strict consistency needs, use D1 adapter.
+ */
+import type { TokenStorage, StoredToken, ConnectedProvider } from '../types';
+export interface KVStorageOptions {
+    /** Cloudflare KV Namespace binding */
+    namespace: KVNamespace;
+    /** Encryption key for token data */
+    encryptionKey: string;
+    /** Optional key prefix (default: 'tokens') */
+    keyPrefix?: string;
+}
+/**
+ * KV Storage adapter for Cloudflare Workers KV
+ */
+export declare class KVStorage implements TokenStorage {
+    private readonly kv;
+    private readonly encryptionKey;
+    private readonly keyPrefix;
+    constructor(options: KVStorageOptions);
+    private tokenKey;
+    private indexKey;
+    get(userId: string, provider: string): Promise<StoredToken | null>;
+    set(token: StoredToken): Promise<void>;
+    delete(userId: string, provider: string): Promise<void>;
+    list(userId: string): Promise<ConnectedProvider[]>;
+    /**
+     * Update the provider index for a user
+     */
+    private updateIndex;
+}
+//# sourceMappingURL=kv.d.ts.map

package/dist/storage/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../../src/storage/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAyBlB,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,SAAS,EAAE,WAAW,CAAC;IACvB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,gBAAgB;IAMrC,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,QAAQ;IAIV,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAyBlE,GAAG,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCtC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IA8BxD;;OAEG;YACW,WAAW;CAyB1B"}

package/dist/storage/kv.js

@@ -0,0 +1,143 @@
+/**
+ * Cloudflare KV Storage Adapter
+ *
+ * Key structure:
+ * - tokens:{userId}:{provider} → encrypted token data
+ * - token-index:{userId} → JSON array of provider IDs (for listing)
+ *
+ * Note: KV is eventually consistent. For strict consistency needs, use D1 adapter.
+ */
+import { StorageError } from '../errors';
+import { encrypt, decrypt } from '../crypto';
+const KEY_PREFIX = 'tokens';
+const INDEX_PREFIX = 'token-index';
+/**
+ * KV Storage adapter for Cloudflare Workers KV
+ */
+export class KVStorage {
+    kv;
+    encryptionKey;
+    keyPrefix;
+    constructor(options) {
+        this.kv = options.namespace;
+        this.encryptionKey = options.encryptionKey;
+        this.keyPrefix = options.keyPrefix ?? KEY_PREFIX;
+    }
+    tokenKey(userId, provider) {
+        return `${this.keyPrefix}:${userId}:${provider}`;
+    }
+    indexKey(userId) {
+        return `${INDEX_PREFIX}:${userId}`;
+    }
+    async get(userId, provider) {
+        try {
+            const key = this.tokenKey(userId, provider);
+            const data = await this.kv.get(key, 'json');
+            if (!data) {
+                return null;
+            }
+            // Decrypt sensitive fields
+            const accessToken = await decrypt(data.accessToken, this.encryptionKey);
+            const refreshToken = data.refreshToken
+                ? await decrypt(data.refreshToken, this.encryptionKey)
+                : undefined;
+            return {
+                ...data,
+                accessToken,
+                refreshToken,
+            };
+        }
+        catch (error) {
+            throw new StorageError('get', error instanceof Error ? error : undefined);
+        }
+    }
+    async set(token) {
+        try {
+            const key = this.tokenKey(token.userId, token.provider);
+            // Encrypt sensitive fields
+            const encryptedAccessToken = await encrypt(token.accessToken, this.encryptionKey);
+            const encryptedRefreshToken = token.refreshToken
+                ? await encrypt(token.refreshToken, this.encryptionKey)
+                : undefined;
+            const data = {
+                userId: token.userId,
+                provider: token.provider,
+                accessToken: encryptedAccessToken,
+                refreshToken: encryptedRefreshToken,
+                expiresAt: token.expiresAt,
+                scopes: token.scopes,
+                createdAt: token.createdAt,
+                updatedAt: token.updatedAt,
+            };
+            // Store the token
+            await this.kv.put(key, JSON.stringify(data));
+            // Update the index
+            await this.updateIndex(token.userId, token.provider, 'add');
+        }
+        catch (error) {
+            throw new StorageError('set', error instanceof Error ? error : undefined);
+        }
+    }
+    async delete(userId, provider) {
+        try {
+            const key = this.tokenKey(userId, provider);
+            await this.kv.delete(key);
+            await this.updateIndex(userId, provider, 'remove');
+        }
+        catch (error) {
+            throw new StorageError('delete', error instanceof Error ? error : undefined);
+        }
+    }
+    async list(userId) {
+        try {
+            const indexKey = this.indexKey(userId);
+            const providers = await this.kv.get(indexKey, 'json');
+            if (!providers || providers.length === 0) {
+                return [];
+            }
+            // Fetch each provider's token data
+            const results = [];
+            for (const provider of providers) {
+                const token = await this.get(userId, provider);
+                if (token) {
+                    results.push({
+                        provider: token.provider,
+                        scopes: token.scopes,
+                        connectedAt: token.createdAt,
+                        expiresAt: token.expiresAt,
+                    });
+                }
+            }
+            return results;
+        }
+        catch (error) {
+            throw new StorageError('list', error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Update the provider index for a user
+     */
+    async updateIndex(userId, provider, action) {
+        const indexKey = this.indexKey(userId);
+        const current = (await this.kv.get(indexKey, 'json')) ?? [];
+        let updated;
+        if (action === 'add') {
+            if (!current.includes(provider)) {
+                updated = [...current, provider];
+            }
+            else {
+                return; // Already in index
+            }
+        }
+        else {
+            updated = current.filter((p) => p !== provider);
+        }
+        if (updated.length === 0) {
+            await this.kv.delete(indexKey);
+        }
+        else {
+            await this.kv.put(indexKey, JSON.stringify(updated));
+        }
+    }
+}
+//# sourceMappingURL=kv.js.map

package/dist/storage/kv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.js","sourceRoot":"","sources":["../../src/storage/kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,UAAU,GAAG,QAAQ,CAAC;AAC5B,MAAM,YAAY,GAAG,aAAa,CAAC;AA6BnC;;GAEG;AACH,MAAM,OAAO,SAAS;IACH,EAAE,CAAc;IAChB,aAAa,CAAS;IACtB,SAAS,CAAS;IAEnC,YAAY,OAAyB;QACnC,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAC3C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC;IACnD,CAAC;IAEO,QAAQ,CAAC,MAAc,EAAE,QAAgB;QAC/C,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;IACnD,CAAC;IAEO,QAAQ,CAAC,MAAc;QAC7B,OAAO,GAAG,YAAY,IAAI,MAAM,EAAE,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,QAAgB;QACxC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAuB,GAAG,EAAE,MAAM,CAAC,CAAC;YAElE,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO,IAAI,CAAC;YACd,CAAC;YAED,2BAA2B;YAC3B,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;YACxE,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY;gBACpC,CAAC,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC;gBACtD,CAAC,CAAC,SAAS,CAAC;YAEd,OAAO;gBACL,GAAG,IAAI;gBACP,WAAW;gBACX,YAAY;aACb,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAkB;QAC1B,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YAExD,2BAA2B;YAC3B,MAAM,oBAAoB,GAAG,MAAM,OAAO,CACxC,KAAK,CAAC,WAAW,EACjB,IAAI,CAAC,aAAa,CACnB,CAAC;YACF,MAAM,qBAAqB,GAAG,KAAK,CAAC,YAAY;gBAC9C,CAAC,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC,aAAa,CAAC;gBACvD,CAAC,CAAC,SAAS,CAAC;YAEd,MAAM,IAAI,GAAyB;gBACjC,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW,EAAE,oBAAoB;gBACjC,YAAY,EAAE,qBAAqB;gBACnC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,SAAS,EAAE,KAAK,CAAC,SAAS;aAC3B,CAAC;YAEF,kBAAkB;YAClB,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAE7C,mBAAmB;YACnB,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,QAAgB;QAC3C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC5C,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC1B,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAW,QAAQ,EAAE,MAAM,CAAC,CAAC;YAEhE,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzC,OAAO,EAAE,CAAC;YACZ,CAAC;YAED,mCAAmC;YACnC,MAAM,OAAO,GAAwB,EAAE,CAAC;YAExC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAC/C,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,CAAC,IAAI,CAAC;wBACX,QAAQ,EAAE,KAAK,CAAC,QAAQ;wBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;wBACpB,WAAW,EAAE,KAAK,CAAC,SAAS;wBAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;qBAC3B,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,YAAY,CAAC,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7E,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,WAAW,CACvB,MAAc,EACd,QAAgB,EAChB,MAAwB;QAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAW,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAEtE,IAAI,OAAiB,CAAC;QACtB,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACrB,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,OAAO,GAAG,CAAC,GAAG,OAAO,EAAE,QAAQ,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,mBAAmB;YAC7B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACjC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;CACF"}

package/dist/storage/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Storage adapter types
+ *
+ * Re-export from main types for convenience
+ */
+export type { TokenStorage, StoredToken, ConnectedProvider } from '../types';
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/storage/types.js

@@ -0,0 +1,7 @@
+/**
+ * Storage adapter types
+ *
+ * Re-export from main types for convenience
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/token-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * OAuth Token Manager
+ *
+ * Main entry point for storing, retrieving, and refreshing OAuth tokens
+ * for downstream API access in Cloudflare Workers.
+ */
+import type { TokenManagerConfig, TokenProvider, TokenData, StoreTokenOptions, GetTokenOptions, ListTokensOptions, ConnectedProvider, RevokeTokenOptions } from './types';
+/**
+ * OAuth Token Manager
+ *
+ * Manages OAuth tokens for downstream API access:
+ * - Stores tokens encrypted at rest
+ * - Automatically refreshes expired tokens
+ * - Validates required scopes
+ * - Supports Google, Microsoft, and GitHub out of the box
+ *
+ * @example
+ * ```typescript
+ * const tokens = new TokenManager({
+ *   storage: new KVStorage({ namespace: env.TOKEN_KV, encryptionKey: env.TOKEN_KEY }),
+ *   encryptionKey: env.TOKEN_KEY,
+ *   providers: {
+ *     google: {
+ *       clientId: env.GOOGLE_CLIENT_ID,
+ *       clientSecret: env.GOOGLE_CLIENT_SECRET,
+ *     },
+ *   },
+ * });
+ *
+ * // Store token after OAuth callback
+ * await tokens.store({ userId, provider: 'google', accessToken, refreshToken, expiresAt, scopes });
+ *
+ * // Get valid token (auto-refreshes if needed)
+ * const { accessToken } = await tokens.get({ userId, provider: 'google' });
+ * ```
+ */
+export declare class TokenManager {
+    private readonly storage;
+    private readonly providers;
+    private readonly defaultRefreshBuffer;
+    constructor(config: TokenManagerConfig);
+    /**
+     * Store a new token or update an existing one
+     *
+     * Call this after a successful OAuth callback to store the user's tokens.
+     */
+    store(options: StoreTokenOptions): Promise<void>;
+    /**
+     * Get a valid access token for API calls
+     *
+     * - Returns the current token if still valid
+     * - Automatically refreshes if expired or expiring soon
+     * - Validates required scopes if specified
+     *
+     * @throws TokenNotFoundError - User hasn't connected this provider
+     * @throws TokenExpiredError - Token expired and refresh failed
+     * @throws InsufficientScopesError - Token missing required scopes
+     * @throws ProviderNotConfiguredError - Provider not in config (for refresh)
+     */
+    get(options: GetTokenOptions): Promise<TokenData>;
+    /**
+     * List all connected providers for a user
+     */
+    list(options: ListTokensOptions): Promise<ConnectedProvider[]>;
+    /**
+     * Revoke/delete a token
+     *
+     * Note: This only removes the token from storage. For providers that
+     * support token revocation (e.g., GitHub), you may want to also call
+     * the provider's revocation endpoint.
+     */
+    revoke(options: RevokeTokenOptions): Promise<void>;
+    /**
+     * Check if a user has a token for a provider (without retrieving it)
+     */
+    has(userId: string, provider: string): Promise<boolean>;
+    /**
+     * Refresh an expired token
+     */
+    private refreshToken;
+    /**
+     * Register a custom provider implementation
+     *
+     * Use this to add support for providers beyond Google/Microsoft/GitHub
+     */
+    static registerProvider(provider: TokenProvider): void;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,aAAa,EAGb,SAAS,EACT,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAyBjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAElC,MAAM,EAAE,kBAAkB;IAMtC;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBtD;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IA0CvD;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAIpE;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxD;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7D;;OAEG;YACW,YAAY;IAuD1B;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;CAGvD"}

package/dist/token-manager.js

@@ -0,0 +1,199 @@
+/**
+ * OAuth Token Manager
+ *
+ * Main entry point for storing, retrieving, and refreshing OAuth tokens
+ * for downstream API access in Cloudflare Workers.
+ */
+import { TokenNotFoundError, TokenExpiredError, InsufficientScopesError, ProviderNotConfiguredError, } from './errors';
+import { GoogleProvider } from './providers/google';
+import { MicrosoftProvider } from './providers/microsoft';
+import { GitHubProvider } from './providers/github';
+// Default refresh buffer: 5 minutes before expiry
+const DEFAULT_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+/**
+ * Built-in provider instances
+ */
+const builtInProviders = {
+    google: new GoogleProvider(),
+    microsoft: new MicrosoftProvider(),
+    github: new GitHubProvider(),
+};
+/**
+ * OAuth Token Manager
+ *
+ * Manages OAuth tokens for downstream API access:
+ * - Stores tokens encrypted at rest
+ * - Automatically refreshes expired tokens
+ * - Validates required scopes
+ * - Supports Google, Microsoft, and GitHub out of the box
+ *
+ * @example
+ * ```typescript
+ * const tokens = new TokenManager({
+ *   storage: new KVStorage({ namespace: env.TOKEN_KV, encryptionKey: env.TOKEN_KEY }),
+ *   encryptionKey: env.TOKEN_KEY,
+ *   providers: {
+ *     google: {
+ *       clientId: env.GOOGLE_CLIENT_ID,
+ *       clientSecret: env.GOOGLE_CLIENT_SECRET,
+ *     },
+ *   },
+ * });
+ *
+ * // Store token after OAuth callback
+ * await tokens.store({ userId, provider: 'google', accessToken, refreshToken, expiresAt, scopes });
+ *
+ * // Get valid token (auto-refreshes if needed)
+ * const { accessToken } = await tokens.get({ userId, provider: 'google' });
+ * ```
+ */
+export class TokenManager {
+    storage;
+    providers;
+    defaultRefreshBuffer;
+    constructor(config) {
+        this.storage = config.storage;
+        this.providers = new Map(Object.entries(config.providers).filter(([, v]) => v !== undefined));
+        this.defaultRefreshBuffer = config.defaultRefreshBuffer ?? DEFAULT_REFRESH_BUFFER_MS;
+    }
+    /**
+     * Store a new token or update an existing one
+     *
+     * Call this after a successful OAuth callback to store the user's tokens.
+     */
+    async store(options) {
+        const now = Date.now();
+        // Check if token already exists (update vs create)
+        const existing = await this.storage.get(options.userId, options.provider);
+        const token = {
+            userId: options.userId,
+            provider: options.provider,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            expiresAt: options.expiresAt,
+            scopes: options.scopes,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await this.storage.set(token);
+    }
+    /**
+     * Get a valid access token for API calls
+     *
+     * - Returns the current token if still valid
+     * - Automatically refreshes if expired or expiring soon
+     * - Validates required scopes if specified
+     *
+     * @throws TokenNotFoundError - User hasn't connected this provider
+     * @throws TokenExpiredError - Token expired and refresh failed
+     * @throws InsufficientScopesError - Token missing required scopes
+     * @throws ProviderNotConfiguredError - Provider not in config (for refresh)
+     */
+    async get(options) {
+        const { userId, provider, requiredScopes, refreshBuffer } = options;
+        // Fetch stored token
+        const stored = await this.storage.get(userId, provider);
+        if (!stored) {
+            throw new TokenNotFoundError(userId, provider);
+        }
+        // Check required scopes
+        if (requiredScopes && requiredScopes.length > 0) {
+            const hasAllScopes = requiredScopes.every((scope) => stored.scopes.includes(scope));
+            if (!hasAllScopes) {
+                throw new InsufficientScopesError(userId, provider, requiredScopes, stored.scopes);
+            }
+        }
+        // Check if token needs refresh
+        const bufferMs = refreshBuffer ?? this.defaultRefreshBuffer;
+        const needsRefresh = stored.expiresAt && Date.now() + bufferMs >= stored.expiresAt;
+        if (needsRefresh) {
+            return await this.refreshToken(stored);
+        }
+        return {
+            accessToken: stored.accessToken,
+            refreshToken: stored.refreshToken,
+            expiresAt: stored.expiresAt,
+            scopes: stored.scopes,
+        };
+    }
+    /**
+     * List all connected providers for a user
+     */
+    async list(options) {
+        return this.storage.list(options.userId);
+    }
+    /**
+     * Revoke/delete a token
+     *
+     * Note: This only removes the token from storage. For providers that
+     * support token revocation (e.g., GitHub), you may want to also call
+     * the provider's revocation endpoint.
+     */
+    async revoke(options) {
+        await this.storage.delete(options.userId, options.provider);
+    }
+    /**
+     * Check if a user has a token for a provider (without retrieving it)
+     */
+    async has(userId, provider) {
+        const token = await this.storage.get(userId, provider);
+        return token !== null;
+    }
+    /**
+     * Refresh an expired token
+     */
+    async refreshToken(stored) {
+        const { userId, provider, refreshToken } = stored;
+        // Check for refresh token
+        if (!refreshToken) {
+            throw new TokenExpiredError(userId, provider, 'no_refresh_token');
+        }
+        // Get provider config
+        const providerConfig = this.providers.get(provider);
+        if (!providerConfig) {
+            throw new ProviderNotConfiguredError(provider);
+        }
+        // Get provider implementation
+        const providerImpl = builtInProviders[provider];
+        if (!providerImpl) {
+            // For custom providers without built-in implementation,
+            // we can't refresh - user needs to re-authenticate
+            throw new TokenExpiredError(userId, provider, 'refresh_failed');
+        }
+        // Check if provider supports refresh
+        if (!providerImpl.supportsRefresh) {
+            // Provider tokens don't expire (e.g., GitHub)
+            // If we got here, the token must be invalid
+            throw new TokenExpiredError(userId, provider, 'refresh_failed');
+        }
+        // Attempt refresh
+        const refreshed = await providerImpl.refresh(refreshToken, providerConfig);
+        if (!refreshed) {
+            throw new TokenExpiredError(userId, provider, 'refresh_failed');
+        }
+        // Update stored token with new values
+        const updatedToken = {
+            ...stored,
+            accessToken: refreshed.accessToken,
+            refreshToken: refreshed.refreshToken ?? stored.refreshToken,
+            expiresAt: refreshed.expiresAt,
+            updatedAt: Date.now(),
+        };
+        await this.storage.set(updatedToken);
+        return {
+            accessToken: updatedToken.accessToken,
+            refreshToken: updatedToken.refreshToken,
+            expiresAt: updatedToken.expiresAt,
+            scopes: updatedToken.scopes,
+        };
+    }
+    /**
+     * Register a custom provider implementation
+     *
+     * Use this to add support for providers beyond Google/Microsoft/GitHub
+     */
+    static registerProvider(provider) {
+        builtInProviders[provider.id] = provider;
+    }
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/token-manager.js.map

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