import * as Config from "effect/Config"; import * as ConfigProvider from "effect/ConfigProvider"; import * as Context from "effect/Context"; import * as SecureRandom from "effect/crypto/SecureRandom"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; import * as Option from "effect/Option"; import * as Path from "effect/Path"; import * as Schema from "effect/Schema"; import * as Semaphore from "effect/Semaphore"; import { Interaction } from "../Interaction.ts"; import { UserFacingError } from "../UserFacingError.ts"; import { cachedFunction } from "../Util/cached-function.ts"; import { globalLogs } from "../Util/LogRecord.ts"; import { withProfileCredentialsLock } from "./Lock.ts"; import { AuthProviders } from "./Registry.ts"; /** * Canonical web host for OAuth provider-agnostic landing pages * (`/auth/success`, `/auth/error`). The CLI's loopback server 302s the * browser to one of these after handling the OAuth callback. Centralized * here so the redirect target lives in exactly one place across all * provider OAuth clients. */ export const AUTH_LANDING_HOST = "https://alchemy.run"; export const AUTH_SUCCESS_URL = `${AUTH_LANDING_HOST}/auth/success`; export const AUTH_ERROR_URL = `${AUTH_LANDING_HOST}/auth/error`; /** * Methods that may drive an interactive flow (prompts, browser-based * OAuth, etc.). A process-wide mutex serializes these across providers * so that, e.g., Cloudflare's `configure` finishes its prompt sequence * before Planetscale's begins — even when the two auth provider Layers * are built in parallel as part of a single `providers()` Layer. * * The interactive renderer enforces per-prompt serialization; this mutex * enforces per-flow serialization so the user sees one provider's prompts * grouped together rather than interleaved. */ const interactiveMutex = Semaphore.makeUnsafe(1); export class AuthError extends Schema.TaggedError()("AuthError", { message: Schema.String, cause: Schema.optional(Schema.Defect()), }) { readonly [UserFacingError] = true; } /** * Stored credentials exist (or are expected) but cannot be used until the * user re-authenticates: missing values, an expired/rotated * token, or a session the provider can no longer refresh silently. The * profile UI renders this as "needs re-login" instead of a generic error, * and callers match it with `Effect.catchTag("NeedsReauth", ...)` — never * by inspecting the message. */ export class NeedsReauth extends Schema.TaggedError()("NeedsReauth", { provider: Schema.String, profile: Schema.String, message: Schema.String, cause: Schema.optional(Schema.Defect()), }) { readonly [UserFacingError] = true; } /** * Standard remediation hint appended to stored-credential errors * ("credentials not found", "refresh failed", ...). Deliberately generic — * the explicit command is correct from any surface, including inside the * profile dashboard (where `r` is merely the shortcut for it). Centralized * so the phrasing lives in one place; surface-aware wording can layer on * top later without touching call sites. */ export const refreshHint = (provider: string, profileName: string): string => `Run \`alchemy profile refresh --profile ${profileName} --provider ${provider}\`.`; /** {@link refreshHint}'s sibling for reconfiguration. */ export const reconfigureHint = (provider: string, profileName: string): string => `Run \`alchemy profile edit --profile ${profileName} --reconfigure ${provider}\` to reconfigure.`; export { AuthProviders, AuthProvidersLive } from "./Registry.ts"; /** * Declares one environment variable a provider's {@link AuthProviderImpl.readEnvironment} * consumes. Profiles are not available in CI — environment variables are the * only CI credential source — so this metadata is the machine-readable * contract for "what must CI set": rendered in docs, surfaced by the CLI, * and available to tooling through the {@link AuthProviders} registry. */ export const EnvironmentVariable = Schema.Struct({ /** Environment variable name, e.g. `CLOUDFLARE_API_TOKEN`. */ name: Schema.String, /** What the variable configures and when it applies. */ description: Schema.optional(Schema.String), /** * Whether credential resolution fails when neither this variable nor one * of its {@link alternatives} is set. Use `description` to explain * conditional requirements (e.g. "required unless X is set"). */ required: Schema.Boolean, /** Holds a secret — display surfaces must redact its value. */ secret: Schema.optional(Schema.Boolean), /** * Alternative variable names that satisfy the same requirement, in * precedence order after {@link name} (e.g. `AWS_DEFAULT_REGION` for * `AWS_REGION`). */ alternatives: Schema.String.pipe(Schema.Array, Schema.optional), }); export type EnvironmentVariable = typeof EnvironmentVariable.Type; const EnvironmentVariables = Schema.Array(EnvironmentVariable); /** Render a one-line summary of a provider's environment contract. */ export const describeEnvironment = (environment: ReadonlyArray): string => environment .map((v) => { const names = [v.name, ...(v.alternatives ?? [])].join(" | "); return v.required ? names : `[${names}]`; }) .join(", "); /** * The variable names a provider's environment resolution would consume, or * `undefined` when the declared contract is not fully satisfied (some * required variable has no non-empty value). Reads through the ambient * `ConfigProvider` — the process environment plus `.env` / `--env-file` — * so it sees exactly what `readEnvironment` will. Environment credentials * take precedence over any profile, CI or not; the returned names tell the * user exactly which keys won. */ export const presentEnvironment = (environment: ReadonlyArray) => Effect.gen(function* () { const used: string[] = []; for (const variable of environment) { let found: string | undefined; for (const name of [variable.name, ...(variable.alternatives ?? [])]) { const value = yield* Config.option(Config.String(name)); if (Option.isSome(value) && value.value !== "") { found = name; break; } } if (found !== undefined) used.push(found); else if (variable.required) return undefined; } return used.length > 0 ? used : undefined; }); /** * One rendered line of a provider's credential details: `key: value`. * Values must arrive pre-redacted (see `displayRedacted`) — the display * layer renders them verbatim. */ export interface ProviderDetailLine { readonly key: string; readonly value: string; } /** * Structured result of {@link AuthProviderImpl.details} — what * `alchemy profile show` and the dashboard render for a connected * provider. Replaces the old `prettyPrint` Console-capture contract. */ export interface ProviderDetails { readonly lines: ReadonlyArray; } /** * One input a provider's flag-driven (non-interactive) configuration * accepts — the machine-readable half of `alchemy profile edit --add * --method --set =`. */ export interface ConfigureField { /** `--set` key and, for stored-credential providers, the stored JSON property. */ readonly name: string; /** Human prompt label, e.g. "Cloudflare API Token". */ readonly label: string; /** Secondary guidance shown beneath the interactive input. */ readonly description?: string; /** Masked during prompts and redacted in details. @default false */ readonly secret?: boolean; /** May be omitted. @default false */ readonly optional?: boolean; readonly placeholder?: string; readonly defaultValue?: string; /** Return an error message for an invalid value, undefined when valid. */ readonly validate?: (value: string) => string | undefined; } /** * The flag-driven configuration contract a provider exposes per method: * which `--method` names are accepted and which `--set` fields each one * takes. Interactive-only methods (browser OAuth, SSO) simply don't * appear here. */ export interface ConfigureMethod { /** * `--method` value. Always the same literal the provider persists as the * config's `method` (`"stored"`, `"sso"`, `"local"`, `"env"`), so the * flag and the credentials file speak one vocabulary. */ readonly method: string; readonly fields: ReadonlyArray; } export interface AuthProviderImpl< Config extends { method: string } = { method: string }, Credentials = unknown, R = never, > { /** * Schema for the provider-owned `values` object ({@link Config}). Stored * entries are user-editable JSON that may also come from a newer or * older alchemy, so every load decodes against this schema — an invalid * entry fails with a reconfigure hint instead of reaching provider code * that matches exhaustively on `method`. */ readonly configSchema: Schema.Codec; configure( profileName: string, currentConfig?: Config, ): Effect.Effect; /** * Flag-driven configuration for scripts and agents: validated `--set` * values for one of the methods declared in {@link configureMethods}. * Optional — interactive-only providers omit it. */ configureWith?( profileName: string, input: { readonly method: string; readonly values: Record; }, ): Effect.Effect; /** * The methods {@link configureWith} accepts and their fields. Required * whenever `configureWith` is implemented so the CLI can validate and * document the flags. */ readonly configureMethods?: ReadonlyArray; /** * Re-authenticate, silently refreshing when the stored credentials allow. * Returns the new config for the caller to save, or nothing when the * provider already saved it through `updateConfig` (a silent refresh saves * under the credentials lock, so the caller must not write it again). * `reload` reads the stored config; run it under the lock before * refreshing, since refresh tokens can be single-use. */ login( profileName: string, config: Config, updateConfig?: (config: Config) => Effect.Effect, reload?: Effect.Effect, ): Effect.Effect; logout(profileName: string, config: Config): Effect.Effect; /** * Structured credential details for display. Fails with * {@link NeedsReauth} when stored credentials exist but require * re-authentication, so the UI can render "needs re-login" instead of a * generic error. */ details( profileName: string, config: Config, updateConfig?: (config: Config) => Effect.Effect, ): Effect.Effect; /** * Resolve credentials from the profile values, silently refreshing when the * provider supports it. MUST be non-interactive — this is the only method * (with {@link readEnvironment}) that child processes exercise, and their * graphs carry no interaction services. When re-authentication is needed, * fail with {@link NeedsReauth} instead of prompting. */ read( profileName: string, config: Config, updateConfig?: (config: Config) => Effect.Effect, ): Effect.Effect; /** * Resolve credentials directly from the process environment for CI. * This never creates, selects, or mutates an Alchemy profile. */ readonly readEnvironment?: Effect.Effect; /** * The environment variables {@link readEnvironment} consumes. Required * whenever `readEnvironment` is implemented — profiles do not exist in CI, * so this list is the provider's entire CI configuration contract. Names * only, never values. */ readonly environment?: ReadonlyArray; } // TODO(typescript>7.1.0): microsoft/TypeScript#64757 infers `R` through // `Effect>` as just `Interaction`, dropping the impl's // own requirements (e.g. `ChildProcessSpawner`). `AuthProvider` and // `AuthProviderLayer` therefore infer the whole `Impl` and read `R` back with // this type. To revert, restore `(name, impl: // AuthProviderImpl | Effect.Effect, never, ImplReq>)` on both, drop this type and the // `service` cast below, and check that `pnpm exec tsrs -b` passes the // Cloudflare, GCP, PlanetScale and Railway `AuthProvider.ts` files. /** * The services an {@link AuthProviderImpl}'s methods require. */ export type AuthProviderImplRequirements = Impl extends AuthProviderImpl ? R : never; export interface AuthProvider< Config extends { method: string } = { method: string }, Credentials = unknown, > extends Omit, "read" | "details"> { readonly kind: "AuthProvider"; readonly name: string; /** * {@link AuthProviderImpl.read} under the profile's credentials lock, with * `loadConfig` run inside the lock. A silent refresh spends a single-use * refresh token, so config loaded before the lock can hold a token that * another process, or an earlier resolve in this one, already rotated. */ read( profileName: string, loadConfig: Effect.Effect, updateConfig?: (config: Config) => Effect.Effect, ): Effect.Effect; /** * {@link AuthProviderImpl.details} under the profile's credentials lock, * with `loadConfig` run inside the lock, since details may refresh. */ details( profileName: string, loadConfig: Effect.Effect, updateConfig?: (config: Config) => Effect.Effect, ): Effect.Effect; /** Log each environment contract once per built provider layer. */ readonly logEnvironmentCredentials: (used: ReadonlyArray) => Effect.Effect; /** * The provider's declared CI environment contract. Empty when the * provider does not support environment credentials. */ readonly environment: ReadonlyArray; /** * Decode raw provider values against {@link AuthProviderImpl.configSchema}. * Fails with an {@link AuthError} carrying the reconfigure hint, so every * consumer of stored configuration reports invalid entries the same way. */ decodeConfig(profileName: string, config: unknown): Effect.Effect; } export const AuthProvider = () => < // TODO(typescript>7.1.0): see AuthProviderImplRequirements. Impl extends AuthProviderImpl, ImplReq = never, R = AuthProviderImplRequirements, >( name: string, impl: Impl | Effect.Effect, ) => Effect.gen(function* () { // FileSystem/Path/SecureRandom back the cross-process credentials lock that wraps // `logout`/`read`/`details` below, so capture them with the impl's own services. // // `Effect.context()` snapshots the ENTIRE fiber context (the type // parameter only narrows the type), and `Effect.provideContext` makes // the provided side win — so an Interaction that happens to be // ambient at REGISTRATION would silently shadow whatever the caller // provides at call time, making the interactive methods' declared // `Interaction` requirement a dead letter. Omit it from the snapshot: // interactive flows resolve Interaction from the caller, exactly as // their signatures promise (a scripted test Interaction, a // browser-driven Alchemist login). // SAFETY: the assertion restores the pre-omit type — tsc cannot reduce // `Exclude>` over the generic R. It only // over-promises Interaction, which every registered method signature // re-declares as a requirement anyway, so no call site can rely on the // capture satisfying it. const ctx = Context.omit(Interaction)( yield* Effect.context< FileSystem.FileSystem | Path.Path | SecureRandom.SecureRandom | R | ImplReq >(), ) as Context.Context< FileSystem.FileSystem | Path.Path | SecureRandom.SecureRandom | R | ImplReq >; // `read` and `readEnvironment` resolve credentials for a caller that // has already chosen its ConfigProvider (`resolveProviderConfig` // checks `presentEnvironment` under it), so they read through that // one, not the one ambient at REGISTRATION. The profile-command // methods keep the snapshot: they run under the process environment, // and `--env-file` reaches them only through it. // SAFETY: as above, the assertion only restores the pre-omit type. const resolveCtx = Context.omit(ConfigProvider.ConfigProvider)(ctx) as typeof ctx; const providers = yield* AuthProviders; // TODO(typescript>7.1.0): see AuthProviderImplRequirements; the cast // goes with the `Impl` signature. // SAFETY: `R` is read back from `Impl` (see AuthProviderImplRequirements), // so this only restores the requirement the constraint's `any` erased. const service = (yield* Effect.isEffect(impl) ? impl : Effect.succeed(impl)) as AuthProviderImpl; // Validate the declared environment contract at registration so a // malformed declaration fails at layer build (programmer error), not // when a CI run tries to render it. const environment = service.environment === undefined ? [] : yield* Schema.decodeEffect(EnvironmentVariables)(service.environment).pipe( Effect.orDie, ); if (service.readEnvironment !== undefined && environment.length === 0) { return yield* Effect.die( `AuthProvider '${name}' implements readEnvironment but does not ` + "declare its `environment` variables. Declare every variable " + "readEnvironment consumes so CI requirements are discoverable.", ); } if ( service.configureWith !== undefined && (service.configureMethods === undefined || service.configureMethods.length === 0) ) { return yield* Effect.die( `AuthProvider '${name}' implements configureWith but does not ` + "declare `configureMethods`. Declare each accepted --method and " + "its --set fields so the CLI can validate and document them.", ); } // Auth and credentials are account-level: every method's logs go to // the global run log, not the project's. const provider: AuthProvider = { logEnvironmentCredentials: yield* cachedFunction( (used: ReadonlyArray) => Effect.logInfo(`${name}: using environment variables (${used.join(", ")}).`), { key: ([used]) => JSON.stringify(used.toSorted()) }, ), kind: "AuthProvider", name, // configure/login can wait minutes on a browser grant, so they hold // only the process-level interactive mutex — never the per-profile // credentials lock, which would starve every concurrent `read` (its // waiters time out at ~120s). Providers whose login path performs a // rotate-on-use silent refresh wrap that read-refresh-persist // section (and only it) in `withProfileCredentialsLock` themselves; // a post-browser persist is a benign whole-file swap where the last // grant wins. configure: (profileName, currentConfig) => Semaphore.withPermits( interactiveMutex, 1, )( service .configure(profileName, currentConfig) .pipe(Effect.provideContext(ctx), globalLogs), ), login: (profileName, config, updateConfig, reload) => Semaphore.withPermits( interactiveMutex, 1, )( service .login(profileName, config, updateConfig, reload) .pipe(Effect.provideContext(ctx), globalLogs), ), logout: (profileName, config) => withProfileCredentialsLock(profileName, service.logout(profileName, config)).pipe( Effect.provideContext(ctx), globalLogs, ), details: (profileName, loadConfig, updateConfig) => withProfileCredentialsLock( profileName, Effect.flatMap(loadConfig, (config) => service.details(profileName, config, updateConfig), ), ).pipe(Effect.provideContext(ctx), globalLogs), ...(service.configureWith === undefined ? {} : { configureWith: ( profileName: string, input: { readonly method: string; readonly values: Record; }, ) => service.configureWith!(profileName, input).pipe( Effect.provideContext(ctx), globalLogs, ), configureMethods: service.configureMethods, }), read: (profileName, loadConfig, updateConfig) => withProfileCredentialsLock( profileName, Effect.flatMap(loadConfig, (config) => service.read(profileName, config, updateConfig)), ).pipe(Effect.provideContext(resolveCtx), globalLogs), readEnvironment: service.readEnvironment?.pipe( Effect.provideContext(resolveCtx), globalLogs, ), environment, configSchema: service.configSchema, decodeConfig: (profileName, config) => Schema.decodeUnknownEffect(service.configSchema)(config).pipe( Effect.mapError((cause) => AuthError.make({ message: `Stored ${name} configuration in profile '${profileName}' is not valid ` + `for this version of alchemy. ` + `${reconfigureHint(name, profileName)}`, cause, }), ), ), }; providers[name] = provider; }); /** * Build a Layer that registers an AuthProvider into the {@link AuthProviders} * registry when its parent layer is built. Use this from a provider's * top-level `providers()` Layer so that the alchemy CLI can discover the * provider via the registry without forcing credential resolution. */ export const AuthProviderLayer = () => < // TODO(typescript>7.1.0): see AuthProviderImplRequirements. Impl extends AuthProviderImpl, ImplReq = never, R = AuthProviderImplRequirements, >( name: string, impl: Impl | Effect.Effect, ) => Layer.effectDiscard(AuthProvider()(name, impl)); /** * Look up a registered {@link AuthProvider} by name. Fails with * {@link AuthError} if the provider hasn't been registered (typically because * its layer hasn't been built). */ export const getAuthProvider = < Config extends { method: string } = { method: string }, Credentials = unknown, >( name: string, ): Effect.Effect, AuthError, AuthProviders> => AuthProviders.use((registry) => registry[name] == null ? Effect.fail( AuthError.make({ message: `AuthProvider '${name}' is not registered. Install the package that provides it.`, }), ) : Effect.succeed( // SAFETY: registration erases provider-specific generic parameters; // callers restore the contract associated with the requested name. registry[name] as AuthProvider, ), );