import * as Config from "effect/Config";
import * as ConfigProvider from "effect/ConfigProvider";
import * as Context from "effect/Context";
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>()("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>()("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<EnvironmentVariable>): 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<EnvironmentVariable>) =>
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<ProviderDetailLine>;
}
/**
* One input a provider's flag-driven (non-interactive) configuration
* accepts — the machine-readable half of `alchemy profile edit --add
* <provider> --method <m> --set <name>=<value>`.
*/
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<ConfigureField>;
}
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<Config>;
configure(
profileName: string,
currentConfig?: Config,
): Effect.Effect<Config, AuthError, R | Interaction>;
/**
* 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<string, string>;
},
): Effect.Effect<Config, AuthError, R | Interaction>;
/**
* 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<ConfigureMethod>;
/**
* 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<void, AuthError>,
reload?: Effect.Effect<Config, AuthError>,
): Effect.Effect<Config | void, AuthError, R | Interaction>;
logout(profileName: string, config: Config): Effect.Effect<void, AuthError, R | Interaction>;
/**
* 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<void, AuthError>,
): Effect.Effect<ProviderDetails, AuthError | NeedsReauth, R | Interaction>;
/**
* 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<void, AuthError>,
): Effect.Effect<Credentials, AuthError | NeedsReauth, R>;
/**
* Resolve credentials directly from the process environment for CI.
* This never creates, selects, or mutates an Alchemy profile.
*/
readonly readEnvironment?: Effect.Effect<Credentials, AuthError, R>;
/**
* 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<EnvironmentVariable>;
}
export interface AuthProvider<
Config extends { method: string } = { method: string },
Credentials = unknown,
> extends Omit<AuthProviderImpl<Config, Credentials>, "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<E>(
profileName: string,
loadConfig: Effect.Effect<Config, E>,
updateConfig?: (config: Config) => Effect.Effect<void, AuthError>,
): Effect.Effect<Credentials, E | AuthError | NeedsReauth>;
/**
* {@link AuthProviderImpl.details} under the profile's credentials lock,
* with `loadConfig` run inside the lock, since details may refresh.
*/
details<E>(
profileName: string,
loadConfig: Effect.Effect<Config, E>,
updateConfig?: (config: Config) => Effect.Effect<void, AuthError>,
): Effect.Effect<ProviderDetails, E | AuthError | NeedsReauth, Interaction>;
/** Log each environment contract once per built provider layer. */
readonly logEnvironmentCredentials: (used: ReadonlyArray<string>) => Effect.Effect<void>;
/**
* The provider's declared CI environment contract. Empty when the
* provider does not support environment credentials.
*/
readonly environment: ReadonlyArray<EnvironmentVariable>;
/**
* 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<Config, AuthError>;
}
export const AuthProvider =
<Config extends { method: string }, Credentials>() =>
<R = never, ImplReq = never>(
name: string,
impl:
| AuthProviderImpl<Config, Credentials, R>
| Effect.Effect<AuthProviderImpl<Config, Credentials, R>, never, ImplReq>,
) =>
Effect.gen(function* () {
// FileSystem/Path 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<R, … Exclude<R, Interaction>>` 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 | R | ImplReq>(),
) as Context.Context<FileSystem.FileSystem | Path.Path | 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;
const service = yield* Effect.isEffect(impl) ? impl : Effect.succeed(impl);
// 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<Config, Credentials> = {
logEnvironmentCredentials: yield* cachedFunction(
(used: ReadonlyArray<string>) =>
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<string, string>;
},
) =>
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 =
<Config extends { method: string }, Credentials>() =>
<R = never, ImplReq = never>(
name: string,
impl:
| AuthProviderImpl<Config, Credentials, R>
| Effect.Effect<AuthProviderImpl<Config, Credentials, R>, never, ImplReq>,
) =>
Layer.effectDiscard(AuthProvider<Config, Credentials>()<R, ImplReq>(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<AuthProvider<Config, Credentials>, 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<Config, Credentials>,
),
);