@cloudflare/workers-auth 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { UserError, ComplianceConfig } from '@cloudflare/workers-utils';
+import { ApiCredentials, UserError, ComplianceConfig } from '@cloudflare/workers-utils';
 
 /**
  * The data that may be read from the on-disk user auth config file.
@@ -12,28 +12,29 @@ interface UserAuthConfig {
     api_token?: string;
 }
 /**
- * Returns the absolute path to the auth config TOML file.
+ * Pluggable persistence for the user auth config.
  *
- * 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;
+ * This package does not ship a default implementation — the consumer injects
+ * one via {@link OAuthFlowContext.storage} (and into {@link getAPIToken} /
+ * {@link readStoredAuthState}). Wrangler's default reads/writes a TOML file
+ * under the global Wrangler config directory; other CLIs can use a different
+ * location and/or serialization format (e.g. a JSONC file under a different
+ * CLI's XDG config directory).
+ */
+interface AuthConfigStorage {
+    /**
+     * Read and parse the stored auth config.
+     * @throws if the backing store is missing or cannot be parsed. Callers treat
+     * a throw as "not logged in via local OAuth".
+     */
+    read(): UserAuthConfig;
+    /** Serialize and persist the auth config. */
+    write(config: UserAuthConfig): void;
+    /** Remove the backing store (used on logout). */
+    clear(): void;
+    /** Human-readable location of the backing store, for display and warnings. */
+    path(): string;
+}
 
 interface GenerateAuthUrlProps {
     authUrl: string;
@@ -41,8 +42,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 +51,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 +62,22 @@ declare const generateAuthUrl: ({ authUrl, clientId, scopes, stateQueryParam, co
  */
 declare function generateRandomState(lengthOfState: number): string;
 
+/**
+ * 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 +124,26 @@ 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;
     /**
      * Override the OAuth authorize URL generator. Used by tests to produce a
      * deterministic URL for snapshot testing. Defaults to the standard
@@ -121,6 +158,60 @@ 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;
+interface GetAPITokenOptions extends GetAuthFromEnvOptions {
+    /** Persistence backend for the stored OAuth token.  */
+    storage: AuthConfigStorage;
+    /** Logger used to surface the one-time deprecated-v1-`api_token` warning. */
+    warningLogger?: Pick<OAuthFlowLogger, "warn">;
+}
+/**
+ * Resolve Cloudflare API credentials from the environment, falling back to the
+ * locally-stored OAuth token.
+ *
+ * Resolution order (highest to lowest):
+ *   1. {@link getAuthFromEnv} (env credentials).
+ *   2. The deprecated v1 `api_token` on disk (with a one-time warning).
+ *   3. The stored OAuth access token (from a previous interactive login).
+ *
+ * Note: this does NOT refresh an expired OAuth token. Callers that need a
+ * guaranteed-valid OAuth token should use the flow's
+ * `getOAuthTokenFromLocalState()` instead.
+ */
+declare function getAPIToken(options: GetAPITokenOptions): ApiCredentials | undefined;
+/**
+ * Like {@link getAPIToken}, but throws a {@link UserError} when no credentials
+ * are available.
+ */
+declare function requireApiToken(options: GetAPITokenOptions): ApiCredentials;
+
 /**
  * Clear internal caches. Exported for use in tests only.
  */
@@ -165,15 +256,6 @@ declare function getCloudflareAccessHeaders(options: {
     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.
@@ -318,6 +400,32 @@ declare class ErrorUnsupportedGrantType extends ErrorAccessTokenResponse {
  */
 declare function toErrorClass(rawError: string, description?: string, uri?: string): ErrorOAuth2 | ErrorUnknown;
 
+/**
+ * Reason why {@link OAuthFlowAPI.loginOrRefreshIfRequired} could not
+ * authenticate the user.
+ */
+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";
+/**
+ * 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.
+ */
+type LoginOrRefreshResult = {
+    loggedIn: true;
+} | {
+    loggedIn: false;
+    reason: LoginOrRefreshFailureReason;
+};
 /**
  * Options for an interactive OAuth login.
  */
@@ -369,11 +477,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
@@ -481,10 +590,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 AccessToken, type AuthConfigStorage, ErrorAccessDenied, ErrorAccessTokenResponse, ErrorAuthenticationGrant, ErrorInvalidClient, ErrorInvalidGrant, ErrorInvalidJson, ErrorInvalidRequest, ErrorInvalidReturnedStateParam, ErrorInvalidScope, ErrorInvalidToken, ErrorNoAuthCode, ErrorOAuth2, ErrorServerError, ErrorTemporarilyUnavailable, ErrorUnauthorizedClient, ErrorUnknown, ErrorUnsupportedGrantType, ErrorUnsupportedResponseType, type GetAPITokenOptions, type GetAuthFromEnvOptions, type LoginOrRefreshFailureReason, type LoginOrRefreshResult, type LoginProps, type OAuthConsentPages, 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, getAPIToken, getAccessClientIdFromEnv, getAccessClientSecretFromEnv, getAccessHeaders, getAuthDomainFromEnv, getAuthFromEnv, getAuthUrlFromEnv, getCfAuthorizationTokenFromEnv, getCloudflareAPITokenFromEnv, getCloudflareAccessHeaders, getCloudflareGlobalAuthEmailFromEnv, getCloudflareGlobalAuthKeyFromEnv, getRevokeUrlFromEnv, getTokenUrlFromEnv, readStoredAuthState, requireApiToken, toErrorClass };