/**
* The credential-demand seam for credential-free `alchemy dev`.
*
* A dev run whose plan is entirely local must never touch (or prompt for)
* cloud credentials. When the plan DOES need the cloud — a resource opted
* out of local emulation via `Alchemy.remote()`, a local Worker binding
* that proxies to a remote resource (`dev: { remote: true }`), or the
* deletion of a row that was last reconciled live — credentials are
* validated up front, BEFORE apply begins: the gate resolves each demanded
* provider's credentials through the same precedence the run will use. The
* seam never starts a login flow: missing credentials fail with the typed
* {@link CredentialsRequired} error naming the demanding resources and
* pointing at `alchemy profile edit` — the profile command is the only
* place logins happen.
*
* How deep the up-front resolution goes is PROVIDER-DEPENDENT — it runs
* the provider's `read`, no more:
*
* - Cloudflare's `read` eagerly checks OAuth expiry, silently refreshes,
* and persists under the profile lock — so a dead refresh token fails
* here as a typed `NeedsReauth`, and child processes (which only ever
* read what a parent persisted) start with a warm token.
* - AWS's `read` returns a credentials RECIPE whose inner effect stays
* unevaluated (SSO tokens are loaded lazily by consumers), so an
* expired SSO token passes the gate and still surfaces mid-run. Local-mode
* AWS providers carry a floci-scoped environment of their own (see
* `AWS/Local/FlociServices.ts`) and ensure the emulator there.
*
* The demand scan keys on provider MODE, not plan action — noop live rows
* still demand (their runtime proxies need live credentials to serve), so
* a watch restart re-runs this resolution even for an unchanged plan.
*
* Non-dev runs (`alchemy deploy` / `destroy`) never enter this seam:
* state-store init and live providers drive the pre-existing lazy
* credential-resolution flow unchanged.
*/
import * as Config from "effect/Config";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Result from "effect/Result";
import * as Schema from "effect/Schema";
import type { BindingNode, Plan } from "../Plan.ts";
import { UserFacingError } from "../UserFacingError.ts";
import { profileCommandHint } from "../Util/interactive.ts";
import { AuthError, AuthProviders, NeedsReauth, presentEnvironment } from "./AuthProvider.ts";
import {
ALCHEMY_PROFILE,
DEFAULT_PROFILE_NAME,
ProfileStore,
SuppressMissingProviderConfig,
} from "./Profile.ts";
import { CredentialsUnavailable, resolveProviderConfig } from "./Resolve.ts";
/** Why a plan row demands live (cloud) credentials during a dev run. */
export type CredentialDemandReason =
/** The resource's resolved provider mode is `"live"` (`Alchemy.remote()`). */
| "remote"
/** Binding data carries a truthy `devRemote` entry — the local runtime proxies this binding to the real cloud. */
| "remote-binding"
/** The plan deletes a row stamped `providerMode: "live"` — the live provider must run to delete it. */
| "live-delete";
export interface DemandingResource {
/** FQN of the demanding resource within the stack. */
readonly fqn: string;
readonly reason: CredentialDemandReason;
}
/**
* All the resources of one cloud provider that demand live credentials.
* `provider` is the auth-provider name, derived from the resource Type's
* leading namespace segment (`"AWS.S3.Bucket"` → `"AWS"`, matching the
* name the cloud's auth provider registers under).
*/
export interface CredentialDemand {
readonly provider: string;
readonly resources: readonly DemandingResource[];
}
/**
* A dev-mode plan needs cloud credentials and none are configured for the
* active profile. The message names the demanding resources and the exact
* `alchemy profile edit` invocation that fixes it.
*/
export class CredentialsRequired extends Data.TaggedError("CredentialsRequired")<{
message: string;
/** Auth-provider name whose credentials are missing (e.g. `"AWS"`). */
provider: string;
/** FQNs of the resources demanding the credentials. */
resources: string[];
/** Short summary of why the credentials are needed. */
reason: string;
}> {
readonly [UserFacingError] = true;
}
/**
* Live providers resolve credentials lazily, on their first cloud call. A
* failed resolution fails (or, for alchemy services typed as never failing,
* dies) with {@link CredentialsUnavailable}. Applied around every provider
* lifecycle call, this fails the operation with {@link CredentialsRequired}
* naming the resource instead.
*/
export const failCredentialsRequired = (fqn: string) =>
Effect.fn(function* (self: Effect.Effect) {
const isUnavailable = Schema.is(CredentialsUnavailable);
// Annotated: the catch handler returns this or a re-fail of E, and a
// union of Effects does not unify on its own.
const required = (
unavailable: CredentialsUnavailable,
): Effect.Effect =>
Effect.fail(
new CredentialsRequired({
provider: unavailable.provider,
resources: [fqn],
reason: "runs against the real cloud",
message: unavailable.message,
}),
);
return yield* self.pipe(
// oxlint-disable-next-line effecttsgo/catch-conditional-refail-to-catch-if -- catchIf cannot narrow a generic E
Effect.catch((error) => (isUnavailable(error) ? required(error) : Effect.fail(error))),
Effect.catchDefect((defect) =>
isUnavailable(defect) ? required(defect) : Effect.die(defect),
),
);
});
const describeReason = (reason: CredentialDemandReason): string => {
switch (reason) {
case "remote":
return "runs against the real cloud via Alchemy.remote()";
case "remote-binding":
return "has a binding that proxies to a remote resource (dev: { remote: true })";
case "live-delete":
return "deletes an instance that was deployed to the real cloud";
}
};
/** `"AWS.S3.Bucket"` → `"AWS"` (the auth-provider name). */
const cloudOf = (type: string): string => type.split(".")[0] ?? type;
const resourceLines = (demand: CredentialDemand): string =>
demand.resources.map((r) => ` - ${r.fqn} (${describeReason(r.reason)})`).join("\n");
/**
* Build the typed {@link CredentialsRequired} failure for a demand.
* Exported so tests can pin the message format.
*/
export const credentialsRequired = (
demand: CredentialDemand,
profileName: string,
): Effect.Effect =>
Effect.gen(function* () {
const command = yield* profileCommandHint(
`alchemy profile edit --profile ${profileName} --add ${demand.provider}`,
);
return yield* new CredentialsRequired({
provider: demand.provider,
resources: demand.resources.map((r) => r.fqn),
reason: [...new Set(demand.resources.map((r) => r.reason))].join(", "),
message:
`${demand.provider} credentials are required, but none are configured ` +
`for profile '${profileName}'.\n` +
`These resources require ${demand.provider} credentials:\n` +
`${resourceLines(demand)}\n` +
`Run \`${command}\` to configure ` +
"credentials, or set CI=1 to use environment-variable credentials.",
});
});
/**
* The slice of binding data the demand scan cares about: local runtimes
* mark cloud-proxied bindings with a truthy `devRemote` entry.
*/
const RemoteBindingData = Schema.Struct({
devRemote: Schema.optional(Schema.Record(Schema.String, Schema.Boolean)),
});
const decodeRemoteBindingData = Schema.decodeUnknownResult(RemoteBindingData);
const bindingDemandsRemote = (bindings: readonly BindingNode[] | undefined): boolean =>
(bindings ?? []).some((binding) => {
// A binding being REMOVED needs no runtime proxy — the restarted
// local instance simply no longer carries it.
if (binding.action === "delete") return false;
const data = decodeRemoteBindingData(binding.data);
return (
Result.isSuccess(data) &&
Object.values(data.success.devRemote ?? {}).some((remote) => remote === true)
);
});
/**
* Scan a plan for rows that need live (cloud) credentials during a dev
* run, grouped by cloud provider:
*
* 1. resources whose resolved provider mode is `"live"` (`Alchemy.remote()`)
* 2. resources whose binding data carries a truthy `devRemote` entry
* (the local runtime proxies that binding to the real cloud)
* 3. planned deletions of rows stamped `providerMode: "live"`
*
* Pure and side-effect-free — callers gate on the run being a dev run
* (in a live run every dual-provider row resolves `"live"` and the
* pre-existing lazy credential flow applies instead).
*
* Mode-agnostic rows (`mode === undefined`, single-implementation
* providers that run live even in dev) are deliberately NOT collected:
* they resolve credentials lazily exactly as they do today.
*/
export const collectCredentialDemands = (plan: Plan): CredentialDemand[] => {
const byProvider = new Map>();
const add = (type: string, fqn: string, reason: CredentialDemandReason): void => {
const provider = cloudOf(type);
const resources = byProvider.get(provider) ?? new Map();
if (!resources.has(fqn)) resources.set(fqn, reason);
byProvider.set(provider, resources);
};
for (const [fqn, node] of Object.entries(plan.resources)) {
if (node.mode === "live") {
add(node.resource.Type, fqn, "remote");
} else if (bindingDemandsRemote(node.bindings)) {
add(node.resource.Type, fqn, "remote-binding");
}
}
for (const [fqn, node] of Object.entries(plan.deletions)) {
if (node !== undefined && node.mode === "live") {
add(node.resource.Type, fqn, "live-delete");
}
}
return [...byProvider.entries()].map(([provider, resources]) => ({
provider,
resources: [...resources.entries()].map(([fqn, reason]) => ({
fqn,
reason,
})),
}));
};
/**
* Re-fail a warm-up resolution error with the demand attached, so the user
* sees WHY a dev run wanted cloud credentials. Tags are preserved —
* consumers match `NeedsReauth`/`AuthError` by tag, never by message.
*/
const attachDemandContext =
(demand: CredentialDemand) =>
(
self: Effect.Effect,
): Effect.Effect =>
self.pipe(
Effect.mapError((error) => {
const message =
`${error.message}\n` +
`These resources require ${demand.provider} credentials:\n` +
resourceLines(demand);
return error._tag === "NeedsReauth"
? NeedsReauth.make({
provider: error.provider,
profile: error.profile,
message,
cause: error.cause,
})
: AuthError.make({ message, cause: error.cause });
}),
);
/**
* Validate credentials for every demand. Never starts a login flow —
* logging in belongs to `alchemy profile edit` exclusively:
*
* - configured for the active profile → resolve the credentials through
* the exact precedence the run will use ({@link resolveProviderConfig}:
* CI environment, explicit env vars, then the profile). Resolution
* runs the provider's `read` — how much that validates and warms is
* provider-dependent (see the module header): Cloudflare eagerly
* refreshes and persists so a dead refresh token fails HERE as a
* typed {@link NeedsReauth} naming the demanding resources, while
* AWS's lazy credential recipe defers SSO-token failures to mid-run.
* - missing → typed {@link CredentialsRequired} failure with the exact
* `alchemy profile edit` invocation to run
* - CI → validates the provider's environment credentials directly,
* matching every other CI path without creating profile state
*
* Demands whose cloud has no registered auth provider are skipped (bare
* engine runs with test providers demand nothing). All context is
* resolved optionally, so the effect is safe to run in any environment —
* and a plan with zero demand touches no credentials at all.
*/
export const demandCredentials = Effect.fn("Alchemy.demandCredentials")(function* (
demands: readonly CredentialDemand[],
) {
if (demands.length === 0) return;
const registry = Option.getOrUndefined(yield* Effect.serviceOption(AuthProviders));
const profile = Option.getOrUndefined(yield* Effect.serviceOption(ProfileStore));
if (registry === undefined || profile === undefined) return;
const ci = yield* Config.Boolean("CI").pipe(Config.withDefault(false));
// CI credentials come exclusively from the environment. Do not require
// or inspect a local profile first: CI runners intentionally have no
// profile manifest, and doing so would also risk consulting a developer's
// stored profiles when this path is exercised locally under Doppler.
const configuredProfile = yield* Config.option(ALCHEMY_PROFILE);
const profileName = Option.getOrElse(configuredProfile, () => DEFAULT_PROFILE_NAME);
yield* Effect.forEach(
demands,
(demand) =>
Effect.gen(function* () {
const auth = registry[demand.provider];
if (auth == null) return;
if (ci) {
if (auth.readEnvironment === undefined) {
return yield* credentialsRequired(demand, profileName);
}
return yield* auth.readEnvironment.pipe(attachDemandContext(demand));
}
// Read-only precheck of the two non-CI configuration sources the
// resolution precedence below consults: environment credentials
// (which win regardless of the selected profile), or a profile
// entry. "Nothing configured" fails with the actionable
// {@link CredentialsRequired} here, WITHOUT entering
// `resolveProviderConfig`: its profile path goes through
// `ensureProfile`, which fails a nonexistent profile with a
// generic ProfileError that would bury which resources demanded
// credentials and what command fixes it.
const envUsable =
auth.readEnvironment !== undefined &&
(yield* presentEnvironment(auth.environment)) !== undefined;
const existing = yield* profile.getProfile(profileName);
if (existing?.providers[auth.name] == null && !envUsable) {
return yield* credentialsRequired(demand, profileName);
}
// Something IS configured — resolve through the same precedence
// the run's lazy credential flow uses, so the gate can never
// pass something resolution would later reject (or vice versa).
// Suppressed missing-config mode turns a check/resolve race into
// the typed tag below instead of a generic AuthError; it also
// mutes the env-credentials warning here — the run's own
// resolution still emits it.
const resolved = yield* resolveProviderConfig(demand.provider).pipe(
Effect.provideService(AuthProviders, registry),
Effect.provideService(ProfileStore, profile),
Effect.provideService(SuppressMissingProviderConfig, true),
Effect.catchTags({
MissingProviderConfig: () => credentialsRequired(demand, profileName),
ProfileError: (error) => AuthError.make({ message: error.message, cause: error }),
}),
);
yield* resolved.resolve.pipe(attachDemandContext(demand));
}),
{ concurrency: 4, discard: true },
);
});
/**
* Plan-time seam for `Alchemy.remote()` rows. The planner probes every new
* resource with its provider's `read` (engine-level adoption) — for a
* live-mode row in a dev run that is a real cloud call, made BEFORE
* {@link demandPlanCredentials} could run in apply. Demanding here first
* turns "nothing configured" into the typed {@link CredentialsRequired}
* (naming the rows and the exact `alchemy profile edit` command) instead
* of whatever raw error the first credential-less read produces. Bindings
* and live deletions are still gated in apply — nothing reads for them
* during plan.
*/
export const demandRemoteCredentials = (
resources: ReadonlyArray<{ readonly Type: string; readonly FQN: string }>,
) => {
const byProvider = new Map();
for (const resource of resources) {
const provider = cloudOf(resource.Type);
byProvider.set(provider, [
...(byProvider.get(provider) ?? []),
{ fqn: resource.FQN, reason: "remote" },
]);
}
return demandCredentials(
[...byProvider.entries()].map(([provider, resources]) => ({
provider,
resources,
})),
);
};
/**
* The one-call seam wired into the dev path: scan the plan for live
* demand and, if any, run {@link demandCredentials} BEFORE apply begins.
*/
export const demandPlanCredentials = (plan: Plan) =>
demandCredentials(collectCredentialDemands(plan));