@cloudflare/workers-auth 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# @cloudflare/workers-auth
+
+Internal OAuth 2.0 + PKCE flow for Cloudflare CLIs (wrangler and friends).
+
+> **Not intended for external use.** APIs may change without notice. This package
+> is consumed only by other packages inside this monorepo.
+
+## What's in this package
+
+- OAuth 2.0 Authorization Code flow with PKCE (RFC 6749 + RFC 7636)
+- Cloudflare-flavored OAuth endpoints (`dash.cloudflare.com` / staging / `WRANGLER_*` overrides)
+- Cloudflare Access detection + service-token / `cloudflared` integration for staging auth domains
+- Persistent auth state stored as TOML in `<globalWranglerConfigPath>/config/<env>.toml`
+- `login`, `logout`, `loginOrRefreshIfRequired`, `getOauthToken`, `getOAuthTokenFromLocalState`
+
+What's **not** here (lives in wrangler):
+
+- yargs `login` / `logout` / `whoami` / `auth token` commands
+- Environment-based credential resolution (`CLOUDFLARE_API_TOKEN`, etc.)
+- Cloudflare account selection (`requireAuth`, `getOrSelectAccountId`)
+- The scope catalog (passed in as `string[]`)
+- `whoami` / account fetching
+
+## Attribution
+
+Portions of this package are derived from
+[BitySA/oauth2-auth-code-pkce](https://github.com/BitySA/oauth2-auth-code-pkce),
+licensed under the Apache License 2.0. See the individual file headers for
+the attribution and `LICENSE` for the full text.
+
+The rest of the package is MIT-licensed.

package/dist/chunk-PAWJFY3S.mjs

@@ -0,0 +1,6 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export { __name };
+//# sourceMappingURL=chunk-PAWJFY3S.mjs.map
+//# sourceMappingURL=chunk-PAWJFY3S.mjs.map

package/dist/chunk-PAWJFY3S.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-PAWJFY3S.mjs"}

package/dist/index.d.mts

@@ -0,0 +1,475 @@
+import { UserError, ComplianceConfig } from '@cloudflare/workers-utils';
+
+/**
+ * The data that may be read from the on-disk user auth config file.
+ */
+interface UserAuthConfig {
+    oauth_token?: string;
+    refresh_token?: string;
+    expiration_time?: string;
+    scopes?: string[];
+    /** @deprecated - this field was only provided by the deprecated v1 `wrangler config` command. */
+    api_token?: string;
+}
+/**
+ * Returns the absolute path to the auth config TOML file.
+ *
+ * The file lives under the global Wrangler config directory and is named
+ * `default.toml` in production, or `<environment>.toml` for the staging /
+ * other Cloudflare API environments.
+ */
+declare function getAuthConfigFilePath(): string;
+/**
+ * Writes the user auth config to disk.
+ *
+ * No in-memory cache to invalidate — auth state is read on demand by every call
+ * site that needs it. Callers are responsible for any consumer-side cache
+ * purging (e.g. via the {@link OAuthFlowContext.purgeOnLoginOrLogout} hook).
+ */
+declare function writeAuthConfigFile(config: UserAuthConfig): void;
+/**
+ * Reads the user auth config from disk.
+ *
+ * @throws if the file does not exist or cannot be parsed as TOML. Callers
+ * typically catch this and treat the failure as "not logged in via local OAuth".
+ */
+declare function readAuthConfigFile(): UserAuthConfig;
+
+interface GenerateAuthUrlProps {
+    authUrl: string;
+    clientId: string;
+    scopes: string[];
+    stateQueryParam: string;
+    codeChallenge: string;
+}
+declare const OAUTH_CALLBACK_URL = "http://localhost:8976/oauth/callback";
+/**
+ * Build the OAuth 2.0 authorize URL for the Cloudflare auth endpoint.
+ *
+ * Extracted from the rest of the OAuth flow so consumers (or tests) can
+ * substitute a deterministic implementation when a stable URL is needed
+ * (e.g. for snapshot testing).
+ */
+declare const generateAuthUrl: ({ authUrl, clientId, scopes, stateQueryParam, codeChallenge, }: GenerateAuthUrlProps) => string;
+
+/**
+ * Generates random state to be passed for anti-csrf.
+ *
+ * Extracted from the rest of the OAuth flow so consumers (or tests) can
+ * substitute a deterministic implementation when a stable state value is
+ * needed (e.g. for snapshot testing).
+ */
+declare function generateRandomState(lengthOfState: number): string;
+
+/**
+ * Subset of the wrangler `logger` singleton used by the OAuth flow.
+ * Consumers pass in an implementation that maps to their own logging surface.
+ */
+interface OAuthFlowLogger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    log(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Dependency-injection surface for {@link createOAuthFlow}.
+ *
+ * The OAuth flow only talks to OAuth endpoints (`/oauth2/auth`, `/oauth2/token`,
+ * `/oauth2/revoke`) using `undici`'s `fetch` directly — there is no Cloudflare
+ * API client wired into this context.
+ */
+interface OAuthFlowContext {
+    logger: OAuthFlowLogger;
+    /**
+     * Whether the process should not prompt the user. The OAuth flow uses this to
+     * decide whether to short-circuit interactive login attempts.
+     */
+    isNonInteractiveOrCI: () => boolean;
+    /**
+     * Open the given URL in the user's default browser. Called during the
+     * interactive OAuth login flow with the authorize URL.
+     */
+    openInBrowser: (url: string) => Promise<void>;
+    /**
+     * Whether environment-based credentials are present. When `true`, the OAuth
+     * flow short-circuits because the env credentials take priority over stored
+     * OAuth tokens:
+     *   - `login` refuses to start
+     *   - `logout` is a no-op (it cannot revoke env credentials)
+     *   - the refresh check returns `false` so an expired stored OAuth token does
+     *     not trigger a needless refresh attempt
+     */
+    hasEnvCredentials: () => boolean;
+    /**
+     * Called after a successful `login` or `logout` so the consumer can invalidate
+     * any caches that depend on the active token (e.g. wrangler's selected-account
+     * cache).
+     */
+    purgeOnLoginOrLogout?: () => void;
+    /**
+     * Override the OAuth authorize URL generator. Used by tests to produce a
+     * deterministic URL for snapshot testing. Defaults to the standard
+     * implementation.
+     */
+    generateAuthUrl?: typeof generateAuthUrl;
+    /**
+     * Override the random state generator. Used by tests to produce a
+     * deterministic state value for snapshot testing. Defaults to the standard
+     * implementation.
+     */
+    generateRandomState?: typeof generateRandomState;
+}
+
+/**
+ * Clear internal caches. Exported for use in tests only.
+ */
+declare function clearAccessCaches(): void;
+/**
+ * Probe a domain to detect whether it is sitting behind Cloudflare Access.
+ *
+ * A 302 to `cloudflareaccess.com` is the canonical signal. Service-auth-only
+ * Access applications return a hard 403 instead and are therefore not detected
+ * here — see {@link getAccessHeaders} for how this is handled.
+ */
+declare function domainUsesAccess(domain: string, logger: OAuthFlowLogger): Promise<boolean>;
+/**
+ * Get the headers needed to authenticate with an Access-protected domain.
+ *
+ * @param domain The hostname of the Access-protected domain (e.g. `"example.com"`).
+ * @param options logger + an `isNonInteractiveOrCI` predicate used to
+ *   produce an actionable error in CI; both default to no-op / `false`.
+ * @returns
+ * - Service token headers (`CF-Access-Client-Id` + `CF-Access-Client-Secret`) if env vars are set
+ * - A `Cookie: CF_Authorization=...` header if obtained via `cloudflared` (interactive only)
+ * - An empty object if the domain is not behind Access
+ * @throws {UserError} If the response does not contain a `CF_Authorization` cookie,
+ *   indicating the service token is invalid, expired, or lacks a Service Auth policy.
+ *   Also throws in non-interactive environments when the domain is behind Access
+ *   but no service token credentials are configured.
+ */
+declare function getAccessHeaders(domain: string, options: {
+    logger: OAuthFlowLogger;
+    isNonInteractiveOrCI: () => boolean;
+}): Promise<Record<string, string>>;
+/**
+ * Get headers needed to authenticate with the Cloudflare OAuth auth domain
+ * (the OAuth `WRANGLER_AUTH_DOMAIN`, which is `dash.cloudflare.com` by default
+ * and `dash.staging.cloudflare.com` in staging).
+ *
+ * Checks `WRANGLER_CF_AUTHORIZATION_TOKEN` first, then falls back to
+ * {@link getAccessHeaders} against the configured auth domain.
+ */
+declare function getCloudflareAccessHeaders(options: {
+    logger: OAuthFlowLogger;
+    isNonInteractiveOrCI: () => boolean;
+}): Promise<Record<string, string>>;
+
+/**
+ * `WRANGLER_CLIENT_ID` is a UUID that is used to identify Wrangler
+ * to the Cloudflare APIs.
+ *
+ * Normally you should not need to set this explicitly.
+ * If you want to switch to the staging environment set the
+ * `WRANGLER_API_ENVIRONMENT=staging` environment variable instead.
+ */
+declare const getClientIdFromEnv: () => string;
+/**
+ * `WRANGLER_AUTH_DOMAIN` is the URL base domain that is used
+ * to access OAuth URLs for the Cloudflare APIs.
+ *
+ * Normally you should not need to set this explicitly.
+ * If you want to switch to the staging environment set the
+ * `WRANGLER_API_ENVIRONMENT=staging` environment variable instead.
+ */
+declare const getAuthDomainFromEnv: () => string;
+/**
+ * `WRANGLER_AUTH_URL` is the path that is used to access OAuth
+ * for the Cloudflare APIs.
+ *
+ * Normally you should not need to set this explicitly.
+ * If you want to switch to the staging environment set the
+ * `WRANGLER_API_ENVIRONMENT=staging` environment variable instead.
+ */
+declare const getAuthUrlFromEnv: () => string;
+/**
+ * `WRANGLER_TOKEN_URL` is the path that is used to exchange an OAuth
+ * token for an API token.
+ *
+ * Normally you should not need to set this explicitly.
+ * If you want to switch to the staging environment set the
+ * `WRANGLER_API_ENVIRONMENT=staging` environment variable instead.
+ */
+declare const getTokenUrlFromEnv: () => string;
+/**
+ * `WRANGLER_REVOKE_URL` is the path that is used to exchange an OAuth
+ * refresh token for a new OAuth token.
+ *
+ * Normally you should not need to set this explicitly.
+ * If you want to switch to the staging environment set the
+ * `WRANGLER_API_ENVIRONMENT=staging` environment variable instead.
+ */
+declare const getRevokeUrlFromEnv: () => string;
+/**
+ * `CLOUDFLARE_ACCESS_CLIENT_ID` is the Client ID of a Cloudflare Access Service Token.
+ * Used together with `CLOUDFLARE_ACCESS_CLIENT_SECRET` to authenticate with
+ * Access-protected domains in non-interactive environments (e.g. CI).
+ *
+ * @see https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/
+ */
+declare const getAccessClientIdFromEnv: () => string | undefined;
+/**
+ * `CLOUDFLARE_ACCESS_CLIENT_SECRET` is the Client Secret of a Cloudflare Access Service Token.
+ * Used together with `CLOUDFLARE_ACCESS_CLIENT_ID` to authenticate with
+ * Access-protected domains in non-interactive environments (e.g. CI).
+ *
+ * @see https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/
+ */
+declare const getAccessClientSecretFromEnv: () => string | undefined;
+/**
+ * `WRANGLER_CF_AUTHORIZATION_TOKEN` is an explicit `CF_Authorization` cookie value
+ * used to authenticate against the OAuth auth domain when it is Access-protected
+ * (typically staging). When set, the OAuth flow skips Access detection and uses
+ * this token directly.
+ */
+declare const getCfAuthorizationTokenFromEnv: () => string | undefined;
+
+/**
+ * A list of OAuth2AuthCodePKCE errors.
+ */
+declare class ErrorOAuth2 extends UserError {
+    toString(): string;
+}
+declare class ErrorUnknown extends UserError {
+    toString(): string;
+}
+declare class ErrorNoAuthCode extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidReturnedStateParam extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidJson extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidScope extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidRequest extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidToken extends ErrorOAuth2 {
+    toString(): string;
+}
+/**
+ * Possible authorization grant errors given by the redirection from the
+ * authorization server.
+ */
+declare class ErrorAuthenticationGrant extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorUnauthorizedClient extends ErrorAuthenticationGrant {
+    toString(): string;
+}
+declare class ErrorAccessDenied extends ErrorAuthenticationGrant {
+    toString(): string;
+}
+declare class ErrorUnsupportedResponseType extends ErrorAuthenticationGrant {
+    toString(): string;
+}
+declare class ErrorServerError extends ErrorAuthenticationGrant {
+    toString(): string;
+}
+declare class ErrorTemporarilyUnavailable extends ErrorAuthenticationGrant {
+    toString(): string;
+}
+/**
+ * A list of possible access token response errors.
+ */
+declare class ErrorAccessTokenResponse extends ErrorOAuth2 {
+    toString(): string;
+}
+declare class ErrorInvalidClient extends ErrorAccessTokenResponse {
+    toString(): string;
+}
+declare class ErrorInvalidGrant extends ErrorAccessTokenResponse {
+    toString(): string;
+}
+declare class ErrorUnsupportedGrantType extends ErrorAccessTokenResponse {
+    toString(): string;
+}
+/**
+ * Translate the raw error strings returned from the server into error classes.
+ */
+declare function toErrorClass(rawError: string): ErrorOAuth2 | ErrorUnknown;
+
+/**
+ * Options for an interactive OAuth login.
+ */
+interface LoginProps {
+    complianceConfig: ComplianceConfig;
+    /**
+     * The OAuth scopes to request. The catalog of valid scope keys is
+     * consumer-defined; this package treats scopes as opaque strings.
+     */
+    scopes: string[];
+    /**
+     * Whether to open the authorize URL in a browser. Defaults to `true`.
+     * When `false` the URL is printed for the user to copy/paste.
+     */
+    browser?: boolean;
+    /** Host the local callback server listens on. Defaults to `localhost`. */
+    callbackHost?: string;
+    /** Port the local callback server listens on. Defaults to `8976`. */
+    callbackPort?: number;
+}
+/**
+ * Public surface returned by {@link createOAuthFlow}.
+ */
+interface OAuthFlowAPI {
+    /**
+     * Open the authorize URL in the user's browser, wait for the callback to be
+     * hit on the local HTTP server, exchange the code for an access token, and
+     * persist the result to disk.
+     *
+     * Refuses to start when `ctx.hasEnvCredentials()` returns `true`.
+     * Refuses to start when the compliance region is `fedramp_high`.
+     *
+     * @returns `true` on success, `false` when env credentials are present.
+     */
+    login(props: LoginProps): Promise<boolean>;
+    /**
+     * Revoke the stored refresh token at the Cloudflare OAuth endpoint and
+     * delete the on-disk auth config file.
+     *
+     * No-op when `ctx.hasEnvCredentials()` returns `true` (env credentials
+     * cannot be revoked).
+     */
+    logout(): Promise<void>;
+    /**
+     * If the user has no stored OAuth token, attempt an interactive login.
+     * If they have one but it is expired, attempt a refresh; if refresh fails,
+     * fall back to an interactive login.
+     *
+     * Scopes are required in case an interactive login is triggered — the
+     * consumer's scope catalog lives outside this package.
+     *
+     * @returns `true` when the user is logged in (or env credentials are
+     * present), `false` when interactive login was needed but skipped (e.g.
+     * non-interactive environment).
+     */
+    loginOrRefreshIfRequired(props: LoginProps): Promise<boolean>;
+    /**
+     * Read the OAuth access token from local state, refreshing it first if
+     * needed. Returns `undefined` when there is no stored OAuth token or the
+     * refresh fails.
+     *
+     * This intentionally does NOT consult env credentials — callers that want
+     * env-or-OAuth resolution should check env first themselves.
+     */
+    getOAuthTokenFromLocalState(): Promise<string | undefined>;
+    /**
+     * Whether the stored OAuth access token has expired and a refresh is
+     * required before it can be used. Returns `false` when env credentials are
+     * present (per `ctx.hasEnvCredentials`), because the stored OAuth state is
+     * not consulted in that case.
+     */
+    isRefreshNeeded(): boolean;
+    /**
+     * Trigger an OAuth refresh-token rotation. Persists the new access/refresh
+     * tokens to disk on success. Returns `false` on any failure.
+     */
+    refreshToken(): Promise<boolean>;
+}
+/**
+ * Build an instance of the OAuth flow bound to the given context.
+ *
+ * The returned object owns module-private state (the transient OAuth flow
+ * state and the deprecated-v1 warning latch). In practice consumers create
+ * exactly one instance per process.
+ */
+declare function createOAuthFlow(ctx: OAuthFlowContext): OAuthFlowAPI;
+
+/**
+ * The maximum length for a code verifier for the best security we can offer.
+ * Please note the NOTE section of RFC 7636 § 4.1 - the length must be >= 43,
+ * but <= 128, **after** base64 url encoding. This means 32 code verifier bytes
+ * encoded will be 43 bytes, or 96 bytes encoded will be 128 bytes. So 96 bytes
+ * is the highest valid value that can be used.
+ */
+declare const RECOMMENDED_CODE_VERIFIER_LENGTH = 96;
+/**
+ * A sensible length for the state's length, for anti-csrf.
+ */
+declare const RECOMMENDED_STATE_LENGTH = 32;
+/**
+ * Character set to generate code verifier defined in rfc7636.
+ */
+declare const PKCE_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+interface PKCECodes {
+    codeChallenge: string;
+    codeVerifier: string;
+}
+/**
+ * Implements *base64url-encode* (RFC 4648 § 5) without padding, which is NOT
+ * the same as regular base64 encoding.
+ */
+declare function base64urlEncode(value: string): string;
+/**
+ * Generates a code_verifier and code_challenge, as specified in rfc7636.
+ */
+declare function generatePKCECodes(): Promise<PKCECodes>;
+
+interface RefreshToken {
+    value: string;
+}
+interface AccessToken {
+    value: string;
+    expiry: string;
+}
+/**
+ * Transient state that is shared across the steps of a single OAuth login flow
+ * within one Wrangler command. This state is not file-backed; it lives only for
+ * the duration of an interactive login.
+ */
+interface OAuthFlowState {
+    authorizationCode?: string;
+    codeChallenge?: string;
+    codeVerifier?: string;
+    hasAuthCodeBeenExchangedForAccessToken?: boolean;
+    stateQueryParam?: string;
+}
+/**
+ * The auth state that is stored on disk in the user auth config file (TOML).
+ * Read on demand by {@link readStoredAuthState} — never cached at module scope
+ * so that environment variables loaded after import (e.g. from `.env`) take
+ * priority correctly.
+ */
+interface StoredAuthState {
+    accessToken?: AccessToken;
+    refreshToken?: RefreshToken;
+    scopes?: string[];
+    /** @deprecated - this field was only provided by the deprecated v1 `wrangler config` command. */
+    deprecatedApiToken?: string;
+}
+/**
+ * Read the on-disk auth state. Called on demand from every site that needs the
+ * stored OAuth tokens or the deprecated v1 `api_token`, rather than being
+ * cached at module scope, so that environment-based credentials loaded after
+ * module import are honoured by the rest of wrangler.
+ *
+ * @return an empty object when no auth config file exists or the file cannot
+ * be parsed — the caller treats this as "not logged in via local OAuth".
+ *
+ * @param options.configOverride seed the state from an in-memory config (used by
+ * the OAuth login flow before it writes to disk).
+ * @param options.warningLogger if provided, a one-time warning is emitted when a
+ * deprecated v1 `api_token` is found on disk. Pass the consumer's logger (e.g.
+ * wrangler's logger singleton) to surface this to the user.
+ */
+declare function readStoredAuthState(options?: {
+    configOverride?: UserAuthConfig;
+    warningLogger?: Pick<OAuthFlowLogger, "warn">;
+}): StoredAuthState;
+
+export { type AccessToken, ErrorAccessDenied, ErrorAccessTokenResponse, ErrorAuthenticationGrant, ErrorInvalidClient, ErrorInvalidGrant, ErrorInvalidJson, ErrorInvalidRequest, ErrorInvalidReturnedStateParam, ErrorInvalidScope, ErrorInvalidToken, ErrorNoAuthCode, ErrorOAuth2, ErrorServerError, ErrorTemporarilyUnavailable, ErrorUnauthorizedClient, ErrorUnknown, ErrorUnsupportedGrantType, ErrorUnsupportedResponseType, type LoginProps, OAUTH_CALLBACK_URL, type OAuthFlowAPI, type OAuthFlowContext, type OAuthFlowLogger, type OAuthFlowState, type PKCECodes, PKCE_CHARSET, RECOMMENDED_CODE_VERIFIER_LENGTH, RECOMMENDED_STATE_LENGTH, type RefreshToken, type StoredAuthState, type UserAuthConfig, base64urlEncode, clearAccessCaches, createOAuthFlow, domainUsesAccess, generateAuthUrl, generatePKCECodes, generateRandomState, getAccessClientIdFromEnv, getAccessClientSecretFromEnv, getAccessHeaders, getAuthConfigFilePath, getAuthDomainFromEnv, getAuthUrlFromEnv, getCfAuthorizationTokenFromEnv, getClientIdFromEnv, getCloudflareAccessHeaders, getRevokeUrlFromEnv, getTokenUrlFromEnv, readAuthConfigFile, readStoredAuthState, toErrorClass, writeAuthConfigFile };