@cloudflare/workers-auth 0.1.1 → 0.3.0

package/dist/index.d.mts

@@ -1,4 +1,21 @@
-import { UserError, ComplianceConfig } from '@cloudflare/workers-utils';
+import { ApiCredentials, ComplianceConfig } from '@cloudflare/workers-utils';
+
+/**
+ * Pluggable persistence for a typed config blob
+ */
+interface ConfigStorage<T> {
+    /**
+     * Read and parse the stored config.
+     * @throws if the backing store is missing or cannot be parsed.
+     */
+    read(): T;
+    /** Serialize and persist the config. */
+    write(config: T): void;
+    /** Remove the backing store; returns whether anything existed beforehand. */
+    clear(): boolean;
+    /** Human-readable location of the backing store, for display and warnings. */
+    path(): string;
+}
 
 /**
  * The data that may be read from the on-disk user auth config file.
@@ -11,29 +28,24 @@ interface UserAuthConfig {
     /** @deprecated - this field was only provided by the deprecated v1 `wrangler config` command. */
     api_token?: string;
 }
+type AuthConfigStorage = ConfigStorage<UserAuthConfig>;
+
 /**
- * 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;
+ * A short-lived "temporary preview account"
+ */
+type TemporaryPreviewAccount = {
+    account: {
+        id: string;
+        name: string;
+        apiToken: string;
+        expiresAt: string;
+    };
+    claim: {
+        url: string;
+        expiresAt: string;
+    };
+};
+type TemporaryAccountStorage = ConfigStorage<TemporaryPreviewAccount>;
 
 interface GenerateAuthUrlProps {
     authUrl: string;
@@ -41,8 +53,8 @@ interface GenerateAuthUrlProps {
     scopes: string[];
     stateQueryParam: string;
     codeChallenge: string;
+    redirectUri: string;
 }
-declare const OAUTH_CALLBACK_URL = "http://localhost:8976/oauth/callback";
 /**
  * Build the OAuth 2.0 authorize URL for the Cloudflare auth endpoint.
  *
@@ -50,7 +62,7 @@ declare const OAUTH_CALLBACK_URL = "http://localhost:8976/oauth/callback";
  * 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;
+declare const generateAuthUrl: ({ authUrl, clientId, scopes, stateQueryParam, codeChallenge, redirectUri, }: GenerateAuthUrlProps) => string;
 
 /**
  * Generates random state to be passed for anti-csrf.
@@ -61,6 +73,38 @@ declare const generateAuthUrl: ({ authUrl, clientId, scopes, stateQueryParam, co
  */
 declare function generateRandomState(lengthOfState: number): string;
 
+/**
+ * The dependencies the OAuth flow needs to mint/reuse a short-lived "temporary
+ * preview account"
+ */
+interface OAuthFlowTemporaryContext {
+    /** Persistence backend for the cached temporary preview account. */
+    storage: TemporaryAccountStorage;
+    /**
+     * Hook to customise the terms-acceptance interactive prompt
+     *  - question: the question to ask a user in interactive mode.
+     *    return answer === "yes" (must be the literal string)
+     *  - notice: the notice to print on stderr if in non-interactive mode
+     *    always return true
+     */
+    prompt: (question: string, notice: string) => Promise<boolean>;
+}
+/**
+ * The branded OAuth consent pages the provider redirects the browser to after
+ * the user grants or denies consent.
+ */
+interface OAuthConsentPages {
+    /** Redirect target shown after the user grants consent. */
+    granted: {
+        url: string;
+    };
+    /** Redirect target shown after the user denies consent, plus the error
+     * surfaced to the terminal. */
+    denied: {
+        url: string;
+        error: string;
+    };
+}
 /**
  * Subset of the wrangler `logger` singleton used by the OAuth flow.
  * Consumers pass in an implementation that maps to their own logging surface.
@@ -107,6 +151,36 @@ interface OAuthFlowContext {
      * cache).
      */
     purgeOnLoginOrLogout?: () => void;
+    /**
+     * The OAuth client ID identifying the consuming CLI to the Cloudflare OAuth
+     * server. Consumer-specific (each CLI registers its own OAuth app), so it is
+     * required. Pass a function to resolve it lazily — e.g. so an env-var read at
+     * call time can switch between production and staging apps.
+     */
+    clientId: string | (() => string);
+    /**
+     * The branded consent pages the provider redirects to after the user grants
+     * or denies consent.
+     */
+    consent: OAuthConsentPages;
+    /**
+     * The `redirect_uri` registered on the consumer's OAuth app
+     */
+    redirectUri: string;
+    /**
+     * Persistence backend for the stored auth config.
+     */
+    storage: AuthConfigStorage;
+    /**
+     * Whether the flow's credential resolvers (`getAPIToken` / `requireApiToken`)
+     * should honour the global API key + email pair in addition to scoped API
+     * tokens.
+     */
+    allowGlobalAuthKey: boolean;
+    /**
+     * Dependencies for minting/reusing a temporary preview account.
+     */
+    temporary: OAuthFlowTemporaryContext | undefined;
     /**
      * Override the OAuth authorize URL generator. Used by tests to produce a
      * deterministic URL for snapshot testing. Defaults to the standard
@@ -121,6 +195,35 @@ interface OAuthFlowContext {
     generateRandomState?: typeof generateRandomState;
 }
 
+/** `CLOUDFLARE_API_TOKEN` (legacy alias `CF_API_TOKEN`): a scoped API token. */
+declare const getCloudflareAPITokenFromEnv: () => string | undefined;
+/** `CLOUDFLARE_API_KEY` (legacy alias `CF_API_KEY`): the global API key. */
+declare const getCloudflareGlobalAuthKeyFromEnv: () => string | undefined;
+/** `CLOUDFLARE_EMAIL` (legacy alias `CF_EMAIL`): the account email, paired with
+ * the global API key. */
+declare const getCloudflareGlobalAuthEmailFromEnv: () => string | undefined;
+interface GetAuthFromEnvOptions {
+    /**
+     * Whether to honour the global API key + email pair
+     * (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`, surfaced as
+     * `X-Auth-Key`/`X-Auth-Email`). Defaults to `true` (Wrangler's behaviour).
+     * CLIs that only support scoped API tokens / OAuth should pass `false`.
+     */
+    allowGlobalAuthKey?: boolean;
+}
+/**
+ * Resolve Cloudflare API credentials from environment variables.
+ *
+ * Priority (highest to lowest), matching Wrangler's historical order:
+ *   1. Global API key + email (`CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`) —
+ *      only when `allowGlobalAuthKey` is `true`.
+ *   2. API token (`CLOUDFLARE_API_TOKEN`).
+ *
+ * @returns the resolved credentials, or `undefined` when no env credentials
+ * are present.
+ */
+declare function getAuthFromEnv(options?: GetAuthFromEnvOptions): ApiCredentials | undefined;
+
 /**
  * Clear internal caches. Exported for use in tests only.
  */
@@ -152,37 +255,7 @@ 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.
@@ -192,132 +265,33 @@ declare const getAuthDomainFromEnv: () => string;
  * `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.
- *
- * Instances may carry the structured details from the OAuth provider's
- * `error`, `error_description` and `error_uri` query parameters (RFC 6749
- * §4.1.2.1) so callers can render them — see {@link toErrorClass}.
- */
-declare class ErrorOAuth2 extends UserError {
-    /** The OAuth `error` code returned by the provider (e.g. `invalid_scope`). */
-    code?: string;
-    /** The OAuth `error_description` returned by the provider, if any. */
-    description?: string;
-    /** The OAuth `error_uri` returned by the provider, if any. */
-    uri?: string;
-    toString(): string;
-}
-declare class ErrorUnknown extends ErrorOAuth2 {
-    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.
+ * Reason why {@link OAuthFlowAPI.loginOrRefreshIfRequired} could not
+ * authenticate the user.
  */
-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;
-}
+type LoginOrRefreshFailureReason = 
+/** no stored credentials and the environment is non-interactive (CI, piped stdin, etc.) so a browser login cannot be started. */
+"no-credentials-non-interactive"
+/** stored credentials and the interactive login attempt was unsuccessful (user cancelled, etc.). */
+ | "no-credentials-login-failed"
+/** the stored token has expired, refresh failed, and the environment is non-interactive so a browser login cannot be started. */
+ | "token-expired-non-interactive"
+/** the stored token has expired, refresh failed, and the interactive login attempt was unsuccessful. */
+ | "token-expired-login-failed";
 /**
- * Translate an OAuth error response from the provider into one of our error
- * classes. The `error_description` and `error_uri` parameters (RFC 6749
- * §4.1.2.1) are included in the message when present so the user sees the
- * specific reason for the failure rather than just the bare error code, and
- * are also attached as structured fields so the HTTP callback handler can
- * render them on the browser-facing error page.
+ * Discriminated union returned by {@link OAuthFlowAPI.loginOrRefreshIfRequired}.
+ *
+ * When `loggedIn` is `true` the caller can proceed. When `false`, `reason`
+ * describes why authentication failed so the caller can surface a
+ * targeted error message.
  */
-declare function toErrorClass(rawError: string, description?: string, uri?: string): ErrorOAuth2 | ErrorUnknown;
-
+type LoginOrRefreshResult = {
+    loggedIn: true;
+} | {
+    loggedIn: false;
+    reason: LoginOrRefreshFailureReason;
+};
 /**
  * Options for an interactive OAuth login.
  */
@@ -369,11 +343,12 @@ interface OAuthFlowAPI {
      * 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).
+     * @returns `{ loggedIn: true }` when the user is authenticated (or env
+     * credentials are present). When authentication fails, returns
+     * `{ loggedIn: false, reason }` describing why — see
+     * {@link LoginOrRefreshFailureReason}.
      */
-    loginOrRefreshIfRequired(props: LoginProps): Promise<boolean>;
+    loginOrRefreshIfRequired(props: LoginProps): Promise<LoginOrRefreshResult>;
     /**
      * Read the OAuth access token from local state, refreshing it first if
      * needed. Returns `undefined` when there is no stored OAuth token or the
@@ -384,17 +359,45 @@ interface OAuthFlowAPI {
      */
     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.
+     * Resolve API credentials, preferring an active temporary preview account
+     * (when one has been latched via {@link activateTemporaryAccount}) over the
+     * env / stored-OAuth resolution performed by the shared credential resolver.
+     *
+     * Returns `undefined` when no credentials are available.
+     */
+    getAPIToken(): ApiCredentials | undefined;
+    /**
+     * Like {@link getAPIToken}, but throws a `UserError` when no credentials are
+     * available.
+     */
+    requireApiToken(): ApiCredentials;
+    /**
+     * Establish whether `--temporary` is permitted for this invocation. Called
+     * once at command dispatch by the consumer. Also drops any temporary account
+     * latched by a previous dispatch, so that — when multiple commands share a
+     * process (e.g. in tests) — each invocation starts a fresh temporary session.
+     * No-op when the flow was created without a `temporary` context.
+     */
+    setTemporaryAllowed(allowed: boolean): void;
+    /**
+     * Whether `--temporary` is permitted for this invocation (see
+     * {@link setTemporaryAllowed}). Always `false` without a `temporary` context.
      */
-    isRefreshNeeded(): boolean;
+    isTemporaryAllowed(): boolean;
     /**
-     * Trigger an OAuth refresh-token rotation. Persists the new access/refresh
-     * tokens to disk on success. Returns `false` on any failure.
+     * The temporary preview account latched for this invocation, or `undefined`.
+     * Only set after {@link activateTemporaryAccount} has run.
      */
-    refreshToken(): Promise<boolean>;
+    getActiveTemporaryAccount(): TemporaryPreviewAccount | undefined;
+    /**
+     * The sole creator of the temporary-account latch: mint a fresh temporary
+     * preview account (or reuse a cached one), latch it for this invocation, and
+     * return it. Requires a `temporary` context.
+     */
+    activateTemporaryAccount(): Promise<{
+        account: TemporaryPreviewAccount;
+        cached: boolean;
+    }>;
 }
 /**
  * Build an instance of the OAuth flow bound to the given context.
@@ -405,35 +408,13 @@ interface OAuthFlowAPI {
  */
 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;
+declare const TEMPORARY_TERMS_PROMPT: string;
+declare const TEMPORARY_TERMS_NOTICE: string;
+
 /**
  * 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;
@@ -442,18 +423,6 @@ 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
@@ -481,10 +450,14 @@ interface StoredAuthState {
  * @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.
+ * @param options.storage the persistence backend to read from, injected by the
+ * consumer (e.g. wrangler's TOML-file-on-disk storage under the global Wrangler
+ * config directory).
  */
-declare function readStoredAuthState(options?: {
+declare function readStoredAuthState(options: {
     configOverride?: UserAuthConfig;
     warningLogger?: Pick<OAuthFlowLogger, "warn">;
+    storage: AuthConfigStorage;
 }): 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 };
+export { type AuthConfigStorage, type ConfigStorage, type LoginOrRefreshFailureReason, type LoginOrRefreshResult, type LoginProps, PKCE_CHARSET, TEMPORARY_TERMS_NOTICE, TEMPORARY_TERMS_PROMPT, type TemporaryPreviewAccount, type UserAuthConfig, clearAccessCaches, createOAuthFlow, domainUsesAccess, generateAuthUrl, generateRandomState, getAccessHeaders, getAuthFromEnv, getAuthUrlFromEnv, getCloudflareAPITokenFromEnv, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, readStoredAuthState };