veryfront 0.1.1186 → 0.1.1190

package/esm/src/oauth/handlers/init-handler.js

@@ -2,11 +2,22 @@ import { logger as baseLogger } from "../../utils/index.js";
 import { getEnvironmentConfig, } from "../../config/environment-config.js";
 import { getEnv } from "../../platform/compat/process.js";
 import { OAuthService } from "../providers/base.js";
-import { memoryTokenStore } from "../token-store/memory.js";
+import { buildOAuthCallbackUrl, createOAuthJsonResponse, createOAuthRedirect, resolveOAuthApplicationUrl, } from "../url-utils.js";
+import { isRefreshCapableTokenStore, normalizeStoredOAuthTokens } from "../token-utils.js";
+import { normalizeOAuthUserId } from "../state-utils.js";
+import { normalizeOAuthScopeSet } from "../scope-utils.js";
+import { RESERVED_AUTHORIZATION_PARAMETERS, snapshotOAuthParameterRecord, } from "../config-validation.js";
+import { snapshotOwnDataProperties } from "../data-properties.js";
+import { resolveOAuthHandlerTokenStore } from "./token-store-policy.js";
 const logger = baseLogger.component("o-auth");
-const DEFAULT_APP_URL = "http://localhost:3000";
 function createUnauthorizedResponse() {
-    return Response.json({ error: "Unauthorized" }, { status: 401 });
+    return createOAuthJsonResponse({ error: "Unauthorized" }, { status: 401 });
+}
+function createMethodNotAllowedResponse(allow) {
+    return createOAuthJsonResponse({ error: "Method not allowed" }, { status: 405, headers: { Allow: allow } });
+}
+function createForbiddenResponse() {
+    return createOAuthJsonResponse({ error: "Forbidden" }, { status: 403 });
 }
 async function isRequestUnauthorized(req, isAuthenticated) {
     return isAuthenticated ? !(await isAuthenticated(req)) : false;
@@ -23,112 +34,184 @@ async function resolveUserId(req, getUserId) {
     if (!getUserId)
         return null;
     const result = await getUserId(req);
-    if (!result)
-        return null; // null, undefined, or empty string all fail.
-    return result;
-}
-function resolveAppUrl(baseUrl, env) {
-    const appUrl = baseUrl ?? env.appUrl;
-    if (appUrl)
-        return appUrl;
-    // Fail closed in production: never silently redirect OAuth callbacks to
-    // localhost. Require APP_URL (or an explicit baseUrl) to be configured.
-    if (env.nodeEnv === "production" || env.veryfrontEnv === "production") {
-        throw new Error("OAuth callback base URL not configured: set APP_URL (or pass baseUrl) in production.");
-    }
-    return DEFAULT_APP_URL;
+    const normalized = normalizeOAuthUserId(result);
+    return normalized !== null && normalized === result ? normalized : null;
 }
-function createNotConfiguredResponse(config) {
+function createNotConfiguredResponse(service) {
     // SEC-009: Do NOT leak internal env var names in the HTTP response body.
     // Operators still need the diagnostic, so log the missing env var names
     // server-side via the existing logger.
     logger.error("OAuth provider not configured", {
-        serviceId: config.serviceId,
-        displayName: config.displayName,
-        missingVars: [config.clientIdEnvVar, config.clientSecretEnvVar],
+        serviceId: service.serviceId,
+        displayName: service.displayName,
+        missingVars: service.credentialEnvironmentVariables,
     });
-    return Response.json({ error: `${config.displayName} OAuth not configured` }, { status: 503 });
+    return createOAuthJsonResponse({ error: `${service.displayName} OAuth not configured` }, { status: 503 });
 }
 function createInitErrorResponse() {
     // SEC-009: do NOT leak internal error details (file paths, library
     // internals) to the client. The caller already logs the full error
     // server-side; return a generic message here.
-    return Response.json({ error: "Failed to initiate OAuth flow" }, { status: 500 });
+    return createOAuthJsonResponse({ error: "Failed to initiate OAuth flow" }, { status: 500 });
 }
 /** Handler for create oauth init. */
 export function createOAuthInitHandler(config, options) {
-    const { tokenStore = memoryTokenStore, baseUrl, authOptions = {}, env = getEnvironmentConfig(), envReader = getEnv, isAuthenticated, getUserId, } = options ?? {};
+    const { tokenStore: configuredTokenStore, baseUrl, callbackRouteId, authOptions: rawAuthOptions = {}, env = getEnvironmentConfig(), envReader = getEnv, isAuthenticated, getUserId, } = options ?? {};
+    const tokenStore = resolveOAuthHandlerTokenStore(configuredTokenStore, env);
+    const service = new OAuthService(config, tokenStore, envReader);
+    const handlerUsesPkce = service.pkceMode !== "unsupported";
+    const authOptions = snapshotOwnDataProperties(rawAuthOptions, [
+        "scopes",
+        "state",
+        "usePkce",
+        "additionalParams",
+        "redirectUri",
+    ]);
+    if (!authOptions) {
+        throw new Error("OAuth init handler authOptions must use plain data properties");
+    }
+    if (authOptions.state !== undefined) {
+        throw new Error("OAuth init handler state is generated internally and must not be configured through authOptions");
+    }
+    if (authOptions.redirectUri !== undefined) {
+        throw new Error("OAuth init handler redirectUri is derived from the configured application URL");
+    }
+    const scopes = authOptions.scopes === undefined ? undefined : normalizeOAuthScopeSet(authOptions.scopes, service.scopeSeparator);
+    if (authOptions.scopes !== undefined && !scopes) {
+        throw new Error("OAuth init handler scopes are invalid");
+    }
+    const additionalParams = snapshotOAuthParameterRecord(authOptions.additionalParams, RESERVED_AUTHORIZATION_PARAMETERS);
+    const additionalParamsIssue = additionalParams.issues[0];
+    if (additionalParamsIssue) {
+        throw new Error(`Invalid OAuth authorization parameter configuration: ${additionalParamsIssue.message}`);
+    }
+    if (authOptions.usePkce !== undefined && authOptions.usePkce !== handlerUsesPkce) {
+        throw new Error(handlerUsesPkce
+            ? "OAuth init handler requires PKCE with the S256 challenge method"
+            : "OAuth provider does not support PKCE");
+    }
+    const authorizationOptions = {
+        ...(scopes ? { scopes } : {}),
+        ...(additionalParams.snapshot === undefined
+            ? {}
+            : { additionalParams: additionalParams.snapshot }),
+        usePkce: handlerUsesPkce,
+    };
+    const appUrl = resolveOAuthApplicationUrl(baseUrl, env);
+    const redirectUri = buildOAuthCallbackUrl(appUrl, callbackRouteId === undefined ? service.serviceId : callbackRouteId);
     return async function handler(req) {
-        if (await isRequestUnauthorized(req, isAuthenticated)) {
-            return createUnauthorizedResponse();
-        }
-        const userId = await resolveUserId(req, getUserId);
-        if (!userId)
-            return createUnauthorizedResponse();
-        const service = new OAuthService(config, tokenStore, envReader);
-        if (!service.isConfigured()) {
-            return createNotConfiguredResponse(config);
-        }
-        const appUrl = resolveAppUrl(baseUrl, env);
-        const redirectUri = `${appUrl}/api/auth/${config.serviceId}/callback`;
+        if (req.method !== "GET")
+            return createMethodNotAllowedResponse("GET");
         try {
-            const { url, state } = await service.createAuthorizationUrl({ ...authOptions, redirectUri });
+            if (await isRequestUnauthorized(req, isAuthenticated)) {
+                return createUnauthorizedResponse();
+            }
+            const userId = await resolveUserId(req, getUserId);
+            if (!userId)
+                return createUnauthorizedResponse();
+            if (!service.isConfigured()) {
+                return createNotConfiguredResponse(service);
+            }
+            const { url, state } = await service.createAuthorizationUrl({
+                ...authorizationOptions,
+                redirectUri,
+            });
+            if (handlerUsesPkce && !state.codeVerifier) {
+                throw new Error("OAuth provider did not return the required PKCE verifier state");
+            }
             await tokenStore.setState(state.state, {
                 userId,
-                serviceId: config.serviceId,
-                codeVerifier: state.codeVerifier,
+                serviceId: service.serviceId,
                 redirectUri: state.redirectUri,
                 scopes: state.scopes,
                 createdAt: state.createdAt,
+                ...(state.codeVerifier === undefined ? {} : { codeVerifier: state.codeVerifier }),
                 metadata: state.metadata,
             });
-            return Response.redirect(url);
+            return createOAuthRedirect(url);
         }
         catch (error) {
-            logger.error("Init error", { serviceId: config.serviceId }, error);
+            logger.error("Init error", { serviceId: service.serviceId }, error);
             return createInitErrorResponse();
         }
     };
 }
 /** Handler for create oauth status. */
 export function createOAuthStatusHandler(config, options) {
-    const { tokenStore = memoryTokenStore, envReader = getEnv, isAuthenticated, getUserId, } = options ?? {};
+    const { tokenStore: configuredTokenStore, env = getEnvironmentConfig(), envReader = getEnv, isAuthenticated, getUserId, } = options ?? {};
+    const tokenStore = resolveOAuthHandlerTokenStore(configuredTokenStore, env);
+    const service = new OAuthService(config, tokenStore, envReader);
     return async function handler(req) {
-        if (await isRequestUnauthorized(req, isAuthenticated)) {
-            return createUnauthorizedResponse();
+        if (req.method !== "GET")
+            return createMethodNotAllowedResponse("GET");
+        try {
+            if (await isRequestUnauthorized(req, isAuthenticated)) {
+                return createUnauthorizedResponse();
+            }
+            const userId = await resolveUserId(req, getUserId);
+            if (!userId)
+                return createUnauthorizedResponse();
+            const storedTokens = await tokenStore.getTokens(service.serviceId, userId);
+            const tokens = storedTokens === null ? null : normalizeStoredOAuthTokens(storedTokens);
+            if (storedTokens !== null && !tokens) {
+                throw new Error("TokenStore returned an invalid OAuth token row");
+            }
+            const isConnected = !!tokens?.accessToken;
+            const isExpired = tokens?.expiresAt !== undefined ? Date.now() >= tokens.expiresAt : false;
+            const hasRefreshToken = !!tokens?.refreshToken;
+            const refreshCapable = isRefreshCapableTokenStore(tokenStore);
+            const configured = service.isConfigured();
+            return createOAuthJsonResponse({
+                service: service.serviceId,
+                displayName: service.displayName,
+                connected: isConnected &&
+                    (!isExpired || (hasRefreshToken && refreshCapable && configured)),
+                configured,
+                expiresAt: tokens?.expiresAt,
+                hasRefreshToken,
+                refreshCapable,
+            });
+        }
+        catch (error) {
+            logger.error("OAuth status lookup failed", { serviceId: service.serviceId }, error);
+            return createOAuthJsonResponse({ error: "Failed to read OAuth status" }, { status: 500 });
         }
-        const userId = await resolveUserId(req, getUserId);
-        if (!userId)
-            return createUnauthorizedResponse();
-        const tokens = await tokenStore.getTokens(config.serviceId, userId);
-        const isConnected = !!tokens?.accessToken;
-        const isExpired = tokens?.expiresAt ? Date.now() > tokens.expiresAt : false;
-        const hasRefreshToken = !!tokens?.refreshToken;
-        return Response.json({
-            service: config.serviceId,
-            displayName: config.displayName,
-            connected: isConnected && (!isExpired || hasRefreshToken),
-            configured: !!(envReader(config.clientIdEnvVar) && envReader(config.clientSecretEnvVar)),
-            expiresAt: tokens?.expiresAt,
-            hasRefreshToken,
-        });
     };
 }
 /** Handler for create oauth disconnect. */
 export function createOAuthDisconnectHandler(config, options) {
-    const { tokenStore = memoryTokenStore, isAuthenticated, getUserId } = options ??
+    const { tokenStore: configuredTokenStore, env = getEnvironmentConfig(), baseUrl, isAuthenticated, getUserId, } = options ??
         {};
+    const tokenStore = resolveOAuthHandlerTokenStore(configuredTokenStore, env);
+    const service = new OAuthService(config, tokenStore);
+    const appUrl = resolveOAuthApplicationUrl(baseUrl, env);
     return async function handler(req) {
-        if (await isRequestUnauthorized(req, isAuthenticated)) {
-            return createUnauthorizedResponse();
+        if (req.method !== "POST")
+            return createMethodNotAllowedResponse("POST");
+        const origin = req.headers.get("Origin");
+        try {
+            if (!origin || new URL(origin).origin !== appUrl.origin)
+                return createForbiddenResponse();
+        }
+        catch {
+            return createForbiddenResponse();
+        }
+        try {
+            if (await isRequestUnauthorized(req, isAuthenticated)) {
+                return createUnauthorizedResponse();
+            }
+            const userId = await resolveUserId(req, getUserId);
+            if (!userId)
+                return createUnauthorizedResponse();
+            await tokenStore.clearTokens(service.serviceId, userId);
+            return createOAuthJsonResponse({
+                success: true,
+                message: `Removed locally stored ${service.displayName} OAuth tokens`,
+            });
+        }
+        catch (error) {
+            logger.error("OAuth disconnect failed", { serviceId: service.serviceId }, error);
+            return createOAuthJsonResponse({ error: "Failed to disconnect OAuth provider" }, { status: 500 });
         }
-        const userId = await resolveUserId(req, getUserId);
-        if (!userId)
-            return createUnauthorizedResponse();
-        await tokenStore.clearTokens(config.serviceId, userId);
-        return Response.json({
-            success: true,
-            message: `Disconnected from ${config.displayName}`,
-        });
     };
 }

package/esm/src/oauth/handlers/token-store-policy.d.ts

@@ -0,0 +1,5 @@
+import type { EnvironmentConfig } from "../../config/environment-config.js";
+import type { TokenStore } from "../types.js";
+/** Resolve the handler store without silently using process-local state in deployments. */
+export declare function resolveOAuthHandlerTokenStore(tokenStore: TokenStore | undefined, env: EnvironmentConfig): TokenStore;
+//# sourceMappingURL=token-store-policy.d.ts.map

package/esm/src/oauth/handlers/token-store-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-store-policy.d.ts","sourceRoot":"","sources":["../../../../src/src/oauth/handlers/token-store-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,2FAA2F;AAC3F,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,GAAG,EAAE,iBAAiB,GACrB,UAAU,CAMZ"}

package/esm/src/oauth/handlers/token-store-policy.js

@@ -0,0 +1,10 @@
+import { memoryTokenStore } from "../token-store/memory.js";
+import { isExplicitLocalOAuthEnvironment } from "../url-utils.js";
+/** Resolve the handler store without silently using process-local state in deployments. */
+export function resolveOAuthHandlerTokenStore(tokenStore, env) {
+    if (tokenStore)
+        return tokenStore;
+    if (isExplicitLocalOAuthEnvironment(env))
+        return memoryTokenStore;
+    throw new Error("OAuth handlers require an explicit shared TokenStore outside development/test");
+}

package/esm/src/oauth/index.d.ts

@@ -9,21 +9,26 @@
  * ```typescript
  * // Create OAuth routes with pre-configured providers
  * import { createOAuthInitHandler, createOAuthCallbackHandler, gmailConfig } from "veryfront/oauth";
+ * import { tokenStore } from "./persistent-token-store.ts";
  *
  * // app/api/auth/gmail/route.ts
- * export const GET = createOAuthInitHandler(gmailConfig);
+ * export const GET = createOAuthInitHandler(gmailConfig, {
+ *   tokenStore,
+ *   getUserId: (request) => getSessionUserId(request),
+ * });
  *
  * // app/api/auth/gmail/callback/route.ts
- * export const GET = createOAuthCallbackHandler(gmailConfig);
+ * export const GET = createOAuthCallbackHandler(gmailConfig, { tokenStore });
  * ```
  *
  * @module oauth
  */
 import "../../_dnt.polyfills.js";
-export type { AuthorizationUrlOptions, OAuthProviderConfig, OAuthServiceConfig, OAuthState, OAuthTokens, TokenExchangeOptions, TokenExchangeResult, TokenStore, } from "./types.js";
+export type { AuthorizationUrlOptions, OAuthProviderConfig, OAuthServiceConfig, OAuthState, OAuthTokens, OAuthTokenSnapshot, RefreshCapableTokenStore, StoredOAuthState, TokenExchangeOptions, TokenExchangeResult, TokenStore, } from "./types.js";
 export { OAuthProvider, OAuthService } from "./providers/base.js";
-export { airtableConfig, asanaConfig, bitbucketConfig, boxConfig, calendarConfig, clickupConfig, confluenceConfig, driveConfig, figmaConfig, freshdeskConfig, githubConfig, gitlabConfig, gmailConfig, hubspotConfig, intercomConfig, jiraConfig, linearConfig, mailchimpConfig, mondayConfig, notionConfig, oneDriveConfig, outlookConfig, pipedriveConfig, quickbooksConfig, salesforceConfig, sharePointConfig, sheetsConfig, shopifyConfig, slackConfig, teamsConfig, trelloConfig, twitterConfig, webexConfig, xeroConfig, zoomConfig, } from "./providers/index.js";
+export { AuthorizationUrlOptionsSchema, getAuthorizationUrlOptionsSchema, getOAuthProviderConfigSchema, getOAuthServiceConfigSchema, getOAuthStateSchema, getOAuthTokensSchema, getTokenExchangeOptionsSchema, getTokenExchangeResultSchema, OAuthProviderConfigSchema, OAuthServiceConfigSchema, OAuthStateSchema, OAuthTokensSchema, TokenExchangeOptionsSchema, TokenExchangeResultSchema, } from "./schemas/index.js";
+export { airtableConfig, asanaConfig, bitbucketConfig, boxConfig, calendarConfig, clickupConfig, confluenceConfig, docsGoogleConfig, driveConfig, figmaConfig, freshdeskConfig, githubConfig, gitlabConfig, gmailConfig, hubspotConfig, intercomConfig, jiraConfig, linearConfig, mailchimpConfig, mondayConfig, notionConfig, oneDriveConfig, outlookConfig, pipedriveConfig, quickbooksConfig, salesforceConfig, sharePointConfig, sheetsConfig, shopifyConfig, slackConfig, teamsConfig, trelloConfig, twitterConfig, webexConfig, xeroConfig, zoomConfig, } from "./providers/index.js";
 export { MemoryTokenStore } from "./token-store/index.js";
 export type { MemoryTokenStoreOptions } from "./token-store/index.js";
-export { createOAuthCallbackHandler, createOAuthDisconnectHandler, createOAuthInitHandler, createOAuthStatusHandler, type OAuthCallbackHandlerOptions, type OAuthInitHandlerOptions, } from "./handlers/index.js";
+export { createOAuthCallbackDispatcher, createOAuthCallbackHandler, createOAuthDisconnectHandler, createOAuthInitHandler, createOAuthStatusHandler, type GetUserIdFn, type OAuthCallbackDispatcherOptions, type OAuthCallbackHandlerOptions, type OAuthDisconnectHandlerOptions, type OAuthInitHandlerOptions, type OAuthStatusHandlerOptions, } from "./handlers/index.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/oauth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EACL,cAAc,EACd,WAAW,EACX,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,2BAA2B,EAChC,KAAK,uBAAuB,GAC7B,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/oauth/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,yBAAyB,CAAC;AAGjC,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,4BAA4B,EAC5B,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,6BAA6B,EAC7B,4BAA4B,EAC5B,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,cAAc,EACd,WAAW,EACX,eAAe,EACf,SAAS,EACT,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,wBAAwB,EACxB,KAAK,WAAW,EAChB,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,GAC/B,MAAM,qBAAqB,CAAC"}

package/esm/src/oauth/index.js

@@ -9,18 +9,23 @@
  * ```typescript
  * // Create OAuth routes with pre-configured providers
  * import { createOAuthInitHandler, createOAuthCallbackHandler, gmailConfig } from "veryfront/oauth";
+ * import { tokenStore } from "./persistent-token-store.ts";
  *
  * // app/api/auth/gmail/route.ts
- * export const GET = createOAuthInitHandler(gmailConfig);
+ * export const GET = createOAuthInitHandler(gmailConfig, {
+ *   tokenStore,
+ *   getUserId: (request) => getSessionUserId(request),
+ * });
  *
  * // app/api/auth/gmail/callback/route.ts
- * export const GET = createOAuthCallbackHandler(gmailConfig);
+ * export const GET = createOAuthCallbackHandler(gmailConfig, { tokenStore });
  * ```
  *
  * @module oauth
  */
 import "../../_dnt.polyfills.js";
 export { OAuthProvider, OAuthService } from "./providers/base.js";
-export { airtableConfig, asanaConfig, bitbucketConfig, boxConfig, calendarConfig, clickupConfig, confluenceConfig, driveConfig, figmaConfig, freshdeskConfig, githubConfig, gitlabConfig, gmailConfig, hubspotConfig, intercomConfig, jiraConfig, linearConfig, mailchimpConfig, mondayConfig, notionConfig, oneDriveConfig, outlookConfig, pipedriveConfig, quickbooksConfig, salesforceConfig, sharePointConfig, sheetsConfig, shopifyConfig, slackConfig, teamsConfig, trelloConfig, twitterConfig, webexConfig, xeroConfig, zoomConfig, } from "./providers/index.js";
+export { AuthorizationUrlOptionsSchema, getAuthorizationUrlOptionsSchema, getOAuthProviderConfigSchema, getOAuthServiceConfigSchema, getOAuthStateSchema, getOAuthTokensSchema, getTokenExchangeOptionsSchema, getTokenExchangeResultSchema, OAuthProviderConfigSchema, OAuthServiceConfigSchema, OAuthStateSchema, OAuthTokensSchema, TokenExchangeOptionsSchema, TokenExchangeResultSchema, } from "./schemas/index.js";
+export { airtableConfig, asanaConfig, bitbucketConfig, boxConfig, calendarConfig, clickupConfig, confluenceConfig, docsGoogleConfig, driveConfig, figmaConfig, freshdeskConfig, githubConfig, gitlabConfig, gmailConfig, hubspotConfig, intercomConfig, jiraConfig, linearConfig, mailchimpConfig, mondayConfig, notionConfig, oneDriveConfig, outlookConfig, pipedriveConfig, quickbooksConfig, salesforceConfig, sharePointConfig, sheetsConfig, shopifyConfig, slackConfig, teamsConfig, trelloConfig, twitterConfig, webexConfig, xeroConfig, zoomConfig, } from "./providers/index.js";
 export { MemoryTokenStore } from "./token-store/index.js";
-export { createOAuthCallbackHandler, createOAuthDisconnectHandler, createOAuthInitHandler, createOAuthStatusHandler, } from "./handlers/index.js";
+export { createOAuthCallbackDispatcher, createOAuthCallbackHandler, createOAuthDisconnectHandler, createOAuthInitHandler, createOAuthStatusHandler, } from "./handlers/index.js";

package/esm/src/oauth/limits.d.ts

@@ -0,0 +1,48 @@
+/** Maximum OAuth authorization-code length accepted at the HTTP boundary. */
+export declare const MAX_OAUTH_AUTHORIZATION_CODE_LENGTH = 4096;
+/**
+ * Cross-runtime upper bound for outbound OAuth request timeouts.
+ *
+ * Ten minutes is intentionally far above the normal 30-second default while
+ * remaining operationally bounded and portable across Deno and Node.
+ */
+export declare const MAX_OAUTH_REQUEST_TIMEOUT_MS: number;
+/** Maximum token-endpoint response body accepted by a provider config. */
+export declare const MAX_OAUTH_TOKEN_RESPONSE_BYTES = 1048576;
+/** Maximum provider API response body accepted by a service config. */
+export declare const MAX_OAUTH_API_RESPONSE_BYTES: number;
+/** Maximum opaque token-store revision length accepted across the boundary. */
+export declare const MAX_OAUTH_TOKEN_REVISION_LENGTH = 256;
+/** Maximum serialized size of optional data-only OAuth transaction metadata. */
+export declare const MAX_OAUTH_STATE_METADATA_BYTES: number;
+/** Maximum logical services admitted by one shared callback dispatcher. */
+export declare const MAX_OAUTH_CALLBACK_SERVICE_COUNT = 100;
+/** Maximum distinct refresh leaders retained for one token-store instance. */
+export declare const MAX_OAUTH_REFRESH_INFLIGHT_COUNT = 10000;
+/** Bounds each configured OAuth scope token and the complete scope set. */
+export declare const MAX_OAUTH_SCOPE_TOKEN_LENGTH = 256;
+export declare const MAX_OAUTH_SCOPE_COUNT = 100;
+export declare const MAX_OAUTH_SCOPE_WIRE_LENGTH = 4096;
+/** Bounds public identifiers used in persistent-store keys. */
+export declare const MAX_OAUTH_PROVIDER_ID_LENGTH = 128;
+export declare const MAX_OAUTH_SERVICE_ID_LENGTH = 128;
+export declare const MAX_OAUTH_USER_ID_LENGTH = 1024;
+export declare const MAX_OAUTH_PROJECT_ID_LENGTH = 256;
+/** Bounds configuration-controlled names and wire values. */
+export declare const MAX_OAUTH_DISPLAY_NAME_LENGTH = 256;
+export declare const MAX_OAUTH_ENV_VAR_NAME_LENGTH = 128;
+export declare const MAX_OAUTH_CREDENTIAL_LENGTH = 16384;
+export declare const MAX_OAUTH_CONFIG_PARAMETER_COUNT = 100;
+export declare const MAX_OAUTH_CONFIG_PARAMETER_NAME_LENGTH = 128;
+export declare const MAX_OAUTH_CONFIG_PARAMETER_VALUE_LENGTH = 4096;
+export declare const MAX_OAUTH_STATIC_HEADER_COUNT = 64;
+export declare const MAX_OAUTH_STATIC_HEADER_NAME_LENGTH = 128;
+export declare const MAX_OAUTH_STATIC_HEADER_VALUE_LENGTH = 8192;
+export declare const MAX_OAUTH_TOKEN_MAPPING_FIELD_LENGTH = 128;
+export declare const MAX_OAUTH_URL_LENGTH = 8192;
+export declare const MAX_OAUTH_TOKEN_VALUE_LENGTH = 65536;
+export declare const MAX_OAUTH_TOKEN_TYPE_LENGTH = 256;
+/** Bounds machine-readable exchange errors and optional operator-safe detail. */
+export declare const MAX_OAUTH_ERROR_LENGTH = 128;
+export declare const MAX_OAUTH_ERROR_DESCRIPTION_LENGTH = 4096;
+//# sourceMappingURL=limits.d.ts.map

package/esm/src/oauth/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../../src/src/oauth/limits.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,QAAc,CAAC;AAExD,0EAA0E;AAC1E,eAAO,MAAM,8BAA8B,UAAY,CAAC;AAExD,uEAAuE;AACvE,eAAO,MAAM,4BAA4B,QAAiB,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,gFAAgF;AAChF,eAAO,MAAM,8BAA8B,QAAa,CAAC;AAEzD,2EAA2E;AAC3E,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,8EAA8E;AAC9E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,+DAA+D;AAC/D,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAC9C,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,6DAA6D;AAC7D,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,6BAA6B,MAAM,CAAC;AACjD,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAClD,eAAO,MAAM,gCAAgC,MAAM,CAAC;AACpD,eAAO,MAAM,sCAAsC,MAAM,CAAC;AAC1D,eAAO,MAAM,uCAAuC,OAAQ,CAAC;AAC7D,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,mCAAmC,MAAM,CAAC;AACvD,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAC1D,eAAO,MAAM,oCAAoC,MAAM,CAAC;AACxD,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAC1C,eAAO,MAAM,4BAA4B,QAAS,CAAC;AACnD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,eAAO,MAAM,kCAAkC,OAAQ,CAAC"}

package/esm/src/oauth/limits.js

@@ -0,0 +1,47 @@
+/** Maximum OAuth authorization-code length accepted at the HTTP boundary. */
+export const MAX_OAUTH_AUTHORIZATION_CODE_LENGTH = 4_096;
+/**
+ * Cross-runtime upper bound for outbound OAuth request timeouts.
+ *
+ * Ten minutes is intentionally far above the normal 30-second default while
+ * remaining operationally bounded and portable across Deno and Node.
+ */
+export const MAX_OAUTH_REQUEST_TIMEOUT_MS = 10 * 60_000;
+/** Maximum token-endpoint response body accepted by a provider config. */
+export const MAX_OAUTH_TOKEN_RESPONSE_BYTES = 1_048_576;
+/** Maximum provider API response body accepted by a service config. */
+export const MAX_OAUTH_API_RESPONSE_BYTES = 10 * 1_048_576;
+/** Maximum opaque token-store revision length accepted across the boundary. */
+export const MAX_OAUTH_TOKEN_REVISION_LENGTH = 256;
+/** Maximum serialized size of optional data-only OAuth transaction metadata. */
+export const MAX_OAUTH_STATE_METADATA_BYTES = 16 * 1_024;
+/** Maximum logical services admitted by one shared callback dispatcher. */
+export const MAX_OAUTH_CALLBACK_SERVICE_COUNT = 100;
+/** Maximum distinct refresh leaders retained for one token-store instance. */
+export const MAX_OAUTH_REFRESH_INFLIGHT_COUNT = 10_000;
+/** Bounds each configured OAuth scope token and the complete scope set. */
+export const MAX_OAUTH_SCOPE_TOKEN_LENGTH = 256;
+export const MAX_OAUTH_SCOPE_COUNT = 100;
+export const MAX_OAUTH_SCOPE_WIRE_LENGTH = 4_096;
+/** Bounds public identifiers used in persistent-store keys. */
+export const MAX_OAUTH_PROVIDER_ID_LENGTH = 128;
+export const MAX_OAUTH_SERVICE_ID_LENGTH = 128;
+export const MAX_OAUTH_USER_ID_LENGTH = 1_024;
+export const MAX_OAUTH_PROJECT_ID_LENGTH = 256;
+/** Bounds configuration-controlled names and wire values. */
+export const MAX_OAUTH_DISPLAY_NAME_LENGTH = 256;
+export const MAX_OAUTH_ENV_VAR_NAME_LENGTH = 128;
+export const MAX_OAUTH_CREDENTIAL_LENGTH = 16_384;
+export const MAX_OAUTH_CONFIG_PARAMETER_COUNT = 100;
+export const MAX_OAUTH_CONFIG_PARAMETER_NAME_LENGTH = 128;
+export const MAX_OAUTH_CONFIG_PARAMETER_VALUE_LENGTH = 4_096;
+export const MAX_OAUTH_STATIC_HEADER_COUNT = 64;
+export const MAX_OAUTH_STATIC_HEADER_NAME_LENGTH = 128;
+export const MAX_OAUTH_STATIC_HEADER_VALUE_LENGTH = 8_192;
+export const MAX_OAUTH_TOKEN_MAPPING_FIELD_LENGTH = 128;
+export const MAX_OAUTH_URL_LENGTH = 8_192;
+export const MAX_OAUTH_TOKEN_VALUE_LENGTH = 65_536;
+export const MAX_OAUTH_TOKEN_TYPE_LENGTH = 256;
+/** Bounds machine-readable exchange errors and optional operator-safe detail. */
+export const MAX_OAUTH_ERROR_LENGTH = 128;
+export const MAX_OAUTH_ERROR_DESCRIPTION_LENGTH = 4_096;

package/esm/src/oauth/providers/atlassian.d.ts

@@ -19,6 +19,15 @@ export declare const atlassianServices: {
         additionalAuthParams?: Record<string, string> | undefined;
         additionalTokenParams?: Record<string, string> | undefined;
         useBasicAuth?: boolean | undefined;
+        pkceMode?: string | undefined;
+        runtimeSupport?: string | undefined;
+        tokenRequestFormat?: string | undefined;
+        tokenRequestHeaders?: Record<string, string> | undefined;
+        apiHeaders?: Record<string, string> | undefined;
+        scopeSeparator?: string | undefined;
+        requestTimeoutMs?: number | undefined;
+        maxTokenResponseBytes?: number | undefined;
+        maxApiResponseBytes?: number | undefined;
         tokenResponseMapping?: Partial<import("../../extensions/schema/schema-validator.js").InferShape<{
             accessToken: import("../../internal-agents/schema.js").Schema<string | undefined>;
             refreshToken: import("../../internal-agents/schema.js").Schema<string | undefined>;
@@ -44,6 +53,15 @@ export declare const atlassianServices: {
         additionalAuthParams?: Record<string, string> | undefined;
         additionalTokenParams?: Record<string, string> | undefined;
         useBasicAuth?: boolean | undefined;
+        pkceMode?: string | undefined;
+        runtimeSupport?: string | undefined;
+        tokenRequestFormat?: string | undefined;
+        tokenRequestHeaders?: Record<string, string> | undefined;
+        apiHeaders?: Record<string, string> | undefined;
+        scopeSeparator?: string | undefined;
+        requestTimeoutMs?: number | undefined;
+        maxTokenResponseBytes?: number | undefined;
+        maxApiResponseBytes?: number | undefined;
         tokenResponseMapping?: Partial<import("../../extensions/schema/schema-validator.js").InferShape<{
             accessToken: import("../../internal-agents/schema.js").Schema<string | undefined>;
             refreshToken: import("../../internal-agents/schema.js").Schema<string | undefined>;
@@ -69,6 +87,15 @@ export declare const atlassianServices: {
         additionalAuthParams?: Record<string, string> | undefined;
         additionalTokenParams?: Record<string, string> | undefined;
         useBasicAuth?: boolean | undefined;
+        pkceMode?: string | undefined;
+        runtimeSupport?: string | undefined;
+        tokenRequestFormat?: string | undefined;
+        tokenRequestHeaders?: Record<string, string> | undefined;
+        apiHeaders?: Record<string, string> | undefined;
+        scopeSeparator?: string | undefined;
+        requestTimeoutMs?: number | undefined;
+        maxTokenResponseBytes?: number | undefined;
+        maxApiResponseBytes?: number | undefined;
         tokenResponseMapping?: Partial<import("../../extensions/schema/schema-validator.js").InferShape<{
             accessToken: import("../../internal-agents/schema.js").Schema<string | undefined>;
             refreshToken: import("../../internal-agents/schema.js").Schema<string | undefined>;

package/esm/src/oauth/providers/atlassian.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atlassian.d.ts","sourceRoot":"","sources":["../../../../src/src/oauth/providers/atlassian.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAgBtD,kCAAkC;AAClC,eAAO,MAAM,UAAU,EAAE,kBAWxB,CAAC;AAEF,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,EAAE,kBAe9B,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAE,kBAiB7B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIpB,CAAC"}
+{"version":3,"file":"atlassian.d.ts","sourceRoot":"","sources":["../../../../src/src/oauth/providers/atlassian.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAkBtD,kCAAkC;AAClC,eAAO,MAAM,UAAU,EAAE,kBAYxB,CAAC;AAEF,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,EAAE,kBAgB9B,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,eAAe,EAAE,kBAkB7B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIpB,CAAC"}

package/esm/src/oauth/providers/atlassian.js

@@ -10,10 +10,13 @@ const atlassianBase = {
         audience: "api.atlassian.com",
         prompt: "consent",
     },
+    tokenRequestFormat: "json",
+    pkceMode: "unsupported",
 };
 /** Configuration used by jira. */
 export const jiraConfig = {
     ...atlassianBase,
+    additionalAuthParams: { ...atlassianBase.additionalAuthParams },
     serviceId: "jira",
     displayName: "Jira",
     apiBaseUrl: "https://api.atlassian.com/ex/jira",
@@ -27,6 +30,7 @@ export const jiraConfig = {
 /** Configuration used by confluence. */
 export const confluenceConfig = {
     ...atlassianBase,
+    additionalAuthParams: { ...atlassianBase.additionalAuthParams },
     serviceId: "confluence",
     displayName: "Confluence",
     apiBaseUrl: "https://api.atlassian.com/ex/confluence",
@@ -52,11 +56,12 @@ export const bitbucketConfig = {
     clientSecretEnvVar: "BITBUCKET_CLIENT_SECRET",
     apiBaseUrl: "https://api.bitbucket.org/2.0",
     additionalAuthParams: {},
+    tokenRequestFormat: "form",
+    useBasicAuth: true,
     defaultScopes: [
         "repository",
-        "repository:write",
-        "pullrequest",
         "pullrequest:write",
+        "issue",
         "account",
     ],
 };

package/esm/src/oauth/providers/base.d.ts

@@ -2,18 +2,28 @@ import type { AuthorizationUrlOptions, OAuthProviderConfig, OAuthServiceConfig,
 export type EnvReader = (key: string) => string | undefined;
 /** Implement oauth provider. */
 export declare class OAuthProvider {
-    protected config: OAuthProviderConfig;
-    protected envReader: EnvReader;
+    protected readonly config: OAuthProviderConfig;
+    protected readonly envReader: EnvReader;
     constructor(config: OAuthProviderConfig, envReader?: EnvReader);
     getClientId(): string | null;
     getClientSecret(): string | null;
     isConfigured(): boolean;
+    /** Declared PKCE behavior for this provider (`supported` by default). */
+    get pkceMode(): "required" | "supported" | "unsupported";
+    /** Separator used to serialize the provider's configured scope set. */
+    get scopeSeparator(): " " | ",";
     createAuthorizationUrl(options?: AuthorizationUrlOptions & {
         defaultScopes?: string[];
     }): Promise<{
         url: string;
         state: OAuthState;
     }>;
+    /**
+     * Headers for a client-authenticated request to the provider's auth server.
+     * `useBasicAuth` providers carry the client credentials here; every other
+     * provider carries them in the body via {@link buildClientCredentialsParams}.
+     */
+    private buildClientAuthHeaders;
     private buildTokenHeaders;
     /**
      * Parse a successful token-endpoint body into {@link OAuthTokens}.
@@ -28,16 +38,19 @@ export declare class OAuthProvider {
     private postTokenRequest;
     private buildClientCredentialsParams;
     private exchangeToken;
-    exchangeCode(options: TokenExchangeOptions): Promise<TokenExchangeResult>;
-    refreshTokens(refreshToken: string): Promise<TokenExchangeResult>;
-    revokeToken(token: string): Promise<boolean>;
+    exchangeCode(options: TokenExchangeOptions, signal?: AbortSignal): Promise<TokenExchangeResult>;
+    refreshTokens(refreshToken: string, signal?: AbortSignal): Promise<TokenExchangeResult>;
+    revokeToken(token: string, callerSignal?: AbortSignal): Promise<boolean>;
 }
 /** Implement oauth service. */
 export declare class OAuthService extends OAuthProvider {
-    protected serviceConfig: OAuthServiceConfig;
+    protected readonly serviceConfig: OAuthServiceConfig;
     protected tokenStore?: TokenStore;
     constructor(config: OAuthServiceConfig, tokenStore?: TokenStore, envReader?: EnvReader);
     get serviceId(): string;
+    get displayName(): string;
+    /** Detached credential variable names for operator-only diagnostics. */
+    get credentialEnvironmentVariables(): readonly [string, string];
     get apiBaseUrl(): string;
     createAuthorizationUrl(options?: AuthorizationUrlOptions): Promise<{
         url: string;
@@ -50,8 +63,10 @@ export declare class OAuthService extends OAuthProvider {
      * prevent one user's OAuth completion from overwriting another user's
      * tokens. See VULN-AUTH-2.
      */
-    getAccessToken(userId: string): Promise<string | null>;
+    getAccessToken(userId: string, signal?: AbortSignal): Promise<string | null>;
     private refreshAndStoreAccessToken;
+    private readTokenSnapshot;
+    private readCurrentUnexpiredAccessToken;
     /**
      * Resolve `endpoint` against `apiBaseUrl`, validating that absolute URLs
      * share the configured origin.