@cloudflare/workers-auth 0.4.1 → 0.5.0

package/dist/keyring-preference-DMsAtawt.d.mts

@@ -0,0 +1,189 @@
+import { l as OAuthConsentPages, F as FileFormat, b as OAuthFlowContext, C as CredentialStore, d as LoginOrRefreshResult, U as UserAuthConfig } from './file-format-CWtMNfzC.mjs';
+import { ApiCredentials, ComplianceConfig } from '@cloudflare/workers-utils';
+
+/** Minimal shape of the interactive `select` prompt's options for account selection. */
+interface AccountSelectOptions {
+    choices: {
+        title: string;
+        value: string;
+    }[];
+}
+/**
+ * Dependency-injection surface for {@link createCloudflareAuth}.
+ *
+ * Everything here is a consumer primitive that genuinely can't live in this
+ * package: the logger, the interactive prompts (`prompt` / `select`, whose
+ * implementations live in the consuming CLI, e.g. wrangler's `dialogs.ts`), and
+ * the User-Agent string. All the auth *logic* lives in the package and is
+ * parameterised by the {@link CliDescriptor} descriptor instead.
+ */
+interface AuthContext {
+    /** The consumer's logger (drop-in for wrangler's logger singleton). */
+    logger: OAuthFlowContext["logger"];
+    /**
+     * User-Agent header sent with the account/membership REST calls
+     * (e.g. `wrangler/<version>` or `cf/<version>`).
+     */
+    userAgent: string;
+    /** The interactive text prompt, used for the temporary-preview-account terms. */
+    prompt: (question: string) => Promise<string>;
+    /** The interactive selection prompt. */
+    select: (text: string, options: AccountSelectOptions) => Promise<string>;
+    /**
+     * Whether the given error is the "no default value / non-interactive" signal
+     * thrown by {@link AuthContext.select} (wrangler's `NoDefaultValueProvided`).
+     */
+    isNoDefaultValueProvidedError: (error: unknown) => boolean;
+}
+/**
+ * Everything that varies between the Cloudflare CLIs that share this auth layer
+ * (wrangler, cf, …). The CLI-agnostic {@link createCloudflareAuth} factory
+ * reads every consumer-specific value from here, so a new CLI is a descriptor
+ * rather than a fork of the factory.
+ */
+interface CliDescriptor {
+    /** CLI name used in user-facing messaging and keyring install-dir scoping (e.g. `"wrangler"`). */
+    cliName: string;
+    /** Commands surfaced in auth guidance. */
+    commands: {
+        login: string;
+        whoami: string;
+        createProfile?: string;
+    };
+    /**
+     * OS-keyring service identifier. Becomes the `-s` arg to macOS `security`,
+     * the `service` attribute for Linux `secret-tool`, and the `service` arg to
+     * `@napi-rs/keyring` on Windows. Distinct per CLI so credentials don't collide.
+     */
+    keyringServiceName: string;
+    /** The CLI's registered OAuth app client ID (or a lazy env-driven resolver). */
+    clientId: string | (() => string);
+    /** The CLI's branded OAuth consent pages. */
+    consent: OAuthConsentPages;
+    /** The `redirect_uri` registered on the CLI's OAuth app; also the local callback URL. */
+    redirectUri: string;
+    /**
+     * Whether Cloudflare Global API Key + email credentials are accepted.
+     * Defaults to `true`.
+     */
+    allowGlobalAuthKey?: boolean;
+    /** The CLI's global config directory, resolved lazily (re-read per call for tests). */
+    getConfigPath: () => string;
+    /** Absolute path to the temporary-preview-account cache file. */
+    getTemporaryAccountConfigPath: () => string;
+    /** On-disk file format for credentials / temporary-account / profile files. */
+    fileFormat: FileFormat;
+    /**
+     * Filename prefix for the cached account selection in the config cache
+     * (e.g. `"wrangler-account"` → `wrangler-account.json`). Always JSON.
+     */
+    accountCachePrefix: string;
+    /**
+     * Namespace for the config-cache directory, isolating each CLI's cache so
+     * one CLI's login/logout purge never wipes another's. Omit to use wrangler's
+     * shared cache dir (the historical default).
+     */
+    cacheNamespace?: string;
+    /**
+     * Label for the CLI's config file, used in "set `account_id` in your <file>"
+     * hints. A getter so it can reflect runtime config state (wrangler resolves
+     * this from `configFileName(undefined)`).
+     */
+    getConfigFileLabel: () => string;
+    /** The live default OAuth scope keys (a getter so any reassignment of the mutable `DefaultScopeKeys` binding is observed). */
+    getDefaultScopeKeys: () => string[];
+}
+
+/** Details for one of the user's accounts. */
+type Account = {
+    id: string;
+    name: string;
+};
+/** The config surface {@link CloudflareAuth.requireAuth} needs: compliance settings plus an optional `account_id`. */
+type RequireAuthConfig = ComplianceConfig & {
+    account_id?: string;
+};
+/** Overrides accepted by {@link CloudflareAuth.login} / {@link CloudflareAuth.loginOrRefreshIfRequired}. */
+interface CloudflareLoginProps {
+    scopes?: string[];
+    browser?: boolean;
+    callbackHost?: string;
+    callbackPort?: number;
+    profile?: string;
+}
+/** A Cloudflare CLI's auth layer, returned by {@link createCloudflareAuth}. */
+interface CloudflareAuth {
+    /** Set the active auth profile for all subsequent credential lookups. */
+    setProfile: (profile: string) => void;
+    /** Return the active auth profile name. */
+    getActiveProfile: () => string;
+    /** The currently-active credential store for the active profile. */
+    getCredentialStore: () => CredentialStore;
+    /** Mark whether `--temporary` is permitted for the current invocation. */
+    setTemporaryAllowed: (allowed: boolean) => void;
+    /** Resolve API credentials (env / temporary account / stored OAuth token). */
+    getAPIToken: () => ApiCredentials | undefined;
+    /** Throw an error if there is no API token available. */
+    requireApiToken: () => ApiCredentials;
+    /** Open the browser, complete the OAuth login, and persist the token. */
+    login: (complianceConfig: ComplianceConfig, props?: CloudflareLoginProps) => Promise<boolean>;
+    /** Revoke and delete the stored OAuth token. */
+    logout: (profile?: string) => Promise<void>;
+    /** Ensure the user is authenticated, refreshing or prompting as needed. */
+    loginOrRefreshIfRequired: (complianceConfig: ComplianceConfig, props?: CloudflareLoginProps) => Promise<LoginOrRefreshResult>;
+    /** Read the OAuth access token from local state, refreshing first if needed. */
+    getOAuthTokenFromLocalState: () => Promise<string | undefined>;
+    /** Scopes granted to the stored OAuth token, or `undefined` when not OAuth-logged-in. */
+    getScopes: () => string[] | undefined;
+    /** Read stored OAuth credentials via the active credential store. */
+    readAuthCredentials: () => UserAuthConfig | undefined;
+    /** Persist OAuth credentials via the active credential store. */
+    writeAuthCredentials: (config: UserAuthConfig) => void;
+    /** Returns the active account ID without side effects (config → env → cache). */
+    getActiveAccountId: (config: {
+        account_id?: string;
+    }) => string | undefined;
+    /** Resolve the account ID to use for API requests (fetching / prompting if needed). */
+    getOrSelectAccountId: (config: RequireAuthConfig) => Promise<string>;
+    /** Retrieve the cached account for the active profile, if any. */
+    getAccountFromCache: () => Account | undefined;
+    /** Fetch the accounts the current login auth can actually use. */
+    fetchAllAccounts: (complianceConfig: ComplianceConfig, options?: {
+        throwOnEmpty?: boolean;
+    }) => Promise<Account[]>;
+    /** Ensure the user is logged in and resolve a valid account ID. */
+    requireAuth: (config: RequireAuthConfig) => Promise<string>;
+}
+
+/**
+ * Persistent, user-level preferences for the authentication subsystem.
+ *
+ * Stored as `<global-config-path>/preferences.json` (always JSON, regardless of
+ * the CLI's credential file format). The preference is only consulted when
+ * the `CLOUDFLARE_AUTH_USE_KEYRING` environment variable is unset.
+ */
+interface UserPreferences {
+    /**
+     * When `true`, OAuth credentials are stored in the OS keychain rather than
+     * the plaintext file. Set by `<cli> login --use-keyring` and cleared by
+     * `<cli> login --no-use-keyring`.
+     */
+    keyring_enabled?: boolean;
+}
+
+/**
+ * Result of {@link KeyringPreference.setKeyringPreference}: the preference
+ * actually persisted, which can differ from the requested value when enabling
+ * was rolled back because the keyring backend isn't usable on this host.
+ */
+interface SetKeyringPreferenceResult {
+    enabled: boolean;
+}
+/** Consumer primitives {@link KeyringPreference.setKeyringPreference} needs. */
+interface KeyringPreferenceContext {
+    logger: OAuthFlowContext["logger"];
+    /** The currently-active credential store for the active profile. */
+    getCredentialStore: () => CredentialStore;
+}
+
+export type { AuthContext as A, CliDescriptor as C, KeyringPreferenceContext as K, SetKeyringPreferenceResult as S, UserPreferences as U, CloudflareAuth as a, CloudflareLoginProps as b };