alchemy 2.0.0-beta.75 → 2.0.0-beta.77

package/lib/AWS/AuthProvider.js

@@ -1,53 +1,115 @@
 import * as Floci from "@alchemy.run/floci";
 import * as DistilledAuth from "@distilled.cloud/aws/Auth";
-import { Credentials } from "@distilled.cloud/aws/Credentials";
+import { Credentials, ExpiredSSOToken, InvalidSSOToken, } from "@distilled.cloud/aws/Credentials";
 import * as STS from "@distilled.cloud/aws/sts";
-import * as Console from "effect/Console";
+import * as EffectConsole from "effect/Console";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Match from "effect/Match";
+import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Redacted from "effect/Redacted";
+import * as Ref from "effect/Ref";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { ChildProcess } from "effect/unstable/process";
 import * as NodeCrypto from "node:crypto";
 import * as NodeOs from "node:os";
-import { AuthError, AuthProviderLayer, } from "../Auth/AuthProvider.js";
-import { CredentialsStore, displayRedacted } from "../Auth/Credentials.js";
-import { getEnv, getEnvRedacted, getEnvRedactedRequired, getEnvRequired, retryOnce, } from "../Auth/Env.js";
-import * as Clank from "../Util/Clank.js";
+import { AuthError, AuthProviderLayer, NeedsReauth, reconfigureHint, refreshHint, } from "../Auth/AuthProvider.js";
+import { displayRedacted } from "../Auth/Credentials.js";
+import { getEnv, getEnvRedacted, getEnvRedactedRequired, getEnvRequired, mapPromptCancellation, } from "../Auth/Env.js";
+import { storedSecret, storedValueText, validateFieldValues, } from "../Auth/StoredAuthProvider.js";
+import * as Interaction from "../Interaction.js";
 import * as Endpoint from "./Endpoint.js";
 import * as Region from "./Region.js";
 export const AWS_AUTH_PROVIDER_NAME = "AWS";
-/** Default endpoint of a local AWS emulator (floci / LocalStack). */
 export const DEFAULT_LOCAL_ENDPOINT = `http://localhost:${Floci.DEFAULT_FLOCI_PORT}`;
 /**
- * Dummy account stamped on every floci / `{ method: "local" }` environment.
+ * Dummy account stamped on every floci environment.
  * A custom `AWS_ENDPOINT_URL` on env/sso credentials does NOT use this —
  * those keep the real account from STS / `AWS_ACCOUNT_ID`.
  */
 export const LOCAL_ACCOUNT_ID = "000000000000";
+/**
+ * distilled's SSO credential loader `Console.log`s its expired-token
+ * diagnostic in addition to failing with the typed `ExpiredSSOToken`. The
+ * typed error already carries the same message (and the profile UI surfaces
+ * it as a reauth diagnostic), so the raw console write only smears over the
+ * Interaction renderer. Provide this no-op Console on every distilled
+ * `loadProfileCredentials` call so distilled has nowhere to print.
+ */
+const noop = () => { };
+export const silentConsole = {
+    assert: noop,
+    clear: noop,
+    count: noop,
+    countReset: noop,
+    debug: noop,
+    dir: noop,
+    dirxml: noop,
+    error: noop,
+    group: noop,
+    groupCollapsed: noop,
+    groupEnd: noop,
+    info: noop,
+    log: noop,
+    table: noop,
+    time: noop,
+    timeEnd: noop,
+    timeLog: noop,
+    trace: noop,
+    warn: noop,
+};
+/** Typed values stored in an AWS provider profile document. */
+export const AwsAuthConfigSchema = Schema.Union([
+    Schema.Struct({
+        method: Schema.Literal("sso"),
+        ssoProfile: Schema.String,
+        authorizationMethod: Schema.optional(Schema.Union([Schema.Literal("oauth"), Schema.Literal("device")])),
+    }),
+    Schema.Struct({
+        method: Schema.Literal("stored"),
+        accountId: Schema.optional(Schema.String),
+        accessKeyId: Schema.String,
+        secretAccessKey: Schema.String,
+        sessionToken: Schema.optional(Schema.String),
+        region: Schema.String,
+    }),
+]);
 const options = [
     {
         value: "sso",
         label: "SSO",
-        hint: "aws sso login — credentials loaded from AWS SSO cache",
-    },
-    {
-        value: "env",
-        label: "Environment Variables",
-        hint: "AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY",
+        description: "sign in with an AWS IAM Identity Center profile",
     },
     {
         value: "stored",
-        label: "Stored",
-        hint: "stored in ~/.alchemy/credentials",
+        label: "Access Keys",
+        description: "enter an access key and secret directly",
     },
+];
+/** `--set` fields for `--method stored` (static access keys, persisted). */
+const keysFields = [
+    { name: "accessKeyId", label: "AWS Access Key ID" },
+    { name: "secretAccessKey", label: "AWS Secret Access Key", secret: true },
     {
-        value: "local",
-        label: "Local emulator",
-        hint: "floci / LocalStack on localhost:4566 — no AWS account",
+        name: "sessionToken",
+        label: "AWS Session Token",
+        secret: true,
+        optional: true,
     },
+    { name: "region", label: "AWS Region", placeholder: "us-east-1" },
+];
+/** `--set` fields for `--method sso` (nothing persisted; profile validated). */
+const ssoFields = [
+    { name: "ssoProfile", label: "AWS profile name (from ~/.aws/config)" },
+];
+const configureMethods = [
+    { method: "stored", fields: keysFields },
+    { method: "sso", fields: ssoFields },
 ];
 /**
  * An explicitly-set `AWS_REGION` env var wins over the region recorded in an
@@ -59,11 +121,11 @@ export const applyEnvRegionOverride = (creds) => getEnv("AWS_REGION").pipe(Effec
 /**
  * Layer that registers the AWS {@link AuthProvider} into the
  * {@link AuthProviders} registry when built. Include this in the AWS
- * `providers()` layer so `alchemy login` can discover it.
+ * `providers()` layer so the alchemy CLI can discover it.
  */
 export const AwsAuth = AuthProviderLayer()(AWS_AUTH_PROVIDER_NAME, Effect.gen(function* () {
-    const store = yield* CredentialsStore;
-    const getAccountId = ({ accessKeyId, secretAccessKey, sessionToken, region, endpoint, }) => STS.getCallerIdentity({}).pipe(Effect.provide(Layer.mergeAll(Layer.succeed(Credentials, Effect.succeed({
+    const interaction = Interaction.accessors;
+    const getAccountId = ({ accessKeyId, secretAccessKey, sessionToken, region, }) => STS.getCallerIdentity({}).pipe(Effect.provide(Layer.mergeAll(Layer.succeed(Credentials, Effect.succeed({
         accessKeyId,
         secretAccessKey,
         sessionToken,
@@ -74,120 +136,308 @@ export const AwsAuth = AuthProviderLayer()(AWS_AUTH_PROVIDER_NAME, Effect.gen(fu
     // deadlock: it derives the region from AWSEnvironment, which is the
     // very service still being constructed by this STS call.
     Region.of(region), 
-    // A custom endpoint (local emulator) must apply to this STS call
-    // too — the default resolver would call real AWS. When there is
-    // no custom endpoint we must still provide `Endpoint.none`
-    // rather than leaving it unset: falling through to the ambient
-    // `Endpoint.fromEnvironment` reads it off AWSEnvironment — the
-    // very service this STS call is constructing — and deadlocks
-    // the fiber on its own in-flight cache (no I/O, no timer, no
-    // output). Same reason as `Region.of` above.
-    endpoint ? Endpoint.of(endpoint) : Endpoint.none)), Effect.flatMap((self) => self.Account
+    // Provide `Endpoint.none` rather than leaving it unset: falling
+    // through to the ambient `Endpoint.fromEnvironment` reads it off
+    // AWSEnvironment — the very service this STS call is
+    // constructing — and deadlocks the fiber on its own in-flight
+    // cache (no I/O, no timer, no output). Same reason as
+    // `Region.of` above.
+    Endpoint.none)), Effect.flatMap((self) => self.Account
         ? Effect.succeed(self.Account)
         : Effect.die(new Error("No account ID found"))));
     const loginStored = Effect.fn(function* (profileName) {
-        const accessKeyId = yield* Clank.text({
+        const accessKeyId = yield* interaction.prompt
+            .text({
             message: "AWS Access Key ID",
             validate: (v) => (v.length === 0 ? "Required" : undefined),
-        }).pipe(retryOnce);
-        const secretAccessKey = yield* Clank.password({
+        })
+            .pipe(mapPromptCancellation);
+        const secretAccessKey = yield* interaction.prompt
+            .password({
             message: "AWS Secret Access Key",
             validate: (v) => (v.length === 0 ? "Required" : undefined),
-        }).pipe(retryOnce);
-        const sessionToken = yield* Clank.text({
-            message: "AWS Session Token (optional — press Enter or Esc to skip)",
+        })
+            .pipe(mapPromptCancellation);
+        const sessionToken = yield* interaction.prompt
+            .password({
+            message: "AWS Session Token (optional; press Enter to skip)",
             placeholder: "(none)",
-        }).pipe(Effect.catch(() => Effect.succeed("")));
-        const region = yield* Clank.text({
+        })
+            .pipe(mapPromptCancellation);
+        const region = yield* interaction.prompt
+            .text({
             message: "AWS Region",
             placeholder: "us-east-1",
             defaultValue: "us-east-1",
-        }).pipe(retryOnce);
+        })
+            .pipe(mapPromptCancellation);
         const accountId = yield* getAccountId({
             accessKeyId: Redacted.make(accessKeyId),
             secretAccessKey: Redacted.make(secretAccessKey),
             sessionToken: sessionToken ? Redacted.make(sessionToken) : undefined,
             region,
         });
-        yield* store.write(profileName, "aws", {
+        yield* interaction.output.success("AWS credentials saved.");
+        return {
+            method: "stored",
             accountId,
             accessKeyId,
             secretAccessKey,
-            sessionToken,
+            sessionToken: sessionToken || undefined,
             region,
-        });
-        yield* Clank.success("AWS credentials saved.");
-        return { method: "stored" };
+        };
     });
-    const configureInteractive = (profileName) => Clank.select({
+    const configureInteractive = (profileName) => interaction.prompt
+        .select({
         message: "AWS authentication method",
         options,
-    }).pipe(Effect.flatMap((method) => Match.value(method).pipe(Match.when("env", () => Effect.succeed({ method: "env" })), Match.when("sso", () => Effect.gen(function* () {
-        const ssoProfile = yield* Clank.text({
+    })
+        .pipe(Effect.flatMap((method) => Match.value(method).pipe(Match.when("sso", () => Effect.gen(function* () {
+        const ssoProfile = yield* interaction.prompt.text({
             message: "AWS profile name (from ~/.aws/config)",
             placeholder: "default",
             defaultValue: "default",
         });
+        const authorizationMethod = yield* interaction.prompt.select({
+            message: "AWS SSO authorization method",
+            options: [
+                {
+                    value: "oauth",
+                    label: "Browser OAuth",
+                    description: "authorize in this device's browser",
+                },
+                {
+                    value: "device",
+                    label: "Device code",
+                    description: "authorize with a short code on any device",
+                },
+            ],
+        });
         const config = {
             method: "sso",
             ssoProfile: ssoProfile ?? "default",
+            authorizationMethod,
         };
-        yield* loginSSO(config);
+        yield* loginSSO(config, authorizationMethod);
         return config;
-    })), Match.when("stored", () => loginStored(profileName)), Match.when("local", () => Effect.gen(function* () {
-        const endpoint = yield* Clank.text({
-            message: "Emulator endpoint",
-            placeholder: DEFAULT_LOCAL_ENDPOINT,
-            defaultValue: DEFAULT_LOCAL_ENDPOINT,
-        });
-        const region = yield* Clank.text({
-            message: "Region",
-            placeholder: "us-east-1",
-            defaultValue: "us-east-1",
-        });
+    })), Match.when("stored", () => loginStored(profileName)), Match.exhaustive)));
+    // The declared requirements are the union of the interactive path
+    // (ChildProcessSpawner for `aws sso login`) and `configureWith`'s
+    // (FileSystem/Path for ~/.aws/config probing) — the contract shares one
+    // ConfigureReq type parameter between the two entry points.
+    const configureCredentials = (profileName) => configureInteractive(profileName).pipe(Effect.mapError((e) => e instanceof AuthError
+        ? e
+        : new AuthError({
+            message: "failed to configure credentials",
+            cause: e,
+        })));
+    const configureWith = (profileName, input) => Match.value(input.method).pipe(Match.when("stored", () => Effect.gen(function* () {
+        const values = yield* validateFieldValues(AWS_AUTH_PROVIDER_NAME, keysFields, input.values);
+        // validateFieldValues guarantees the required fields are present.
+        const accessKeyId = storedSecret(values.accessKeyId);
+        const secretAccessKey = storedSecret(values.secretAccessKey);
+        const sessionToken = storedSecret(values.sessionToken);
+        const region = storedValueText(values.region) ?? "";
+        if (accessKeyId === undefined || secretAccessKey === undefined) {
+            return yield* Effect.fail(new AuthError({
+                message: "AWS: required key fields are missing.",
+            }));
+        }
+        const accountId = yield* getAccountId({
+            accessKeyId,
+            secretAccessKey,
+            sessionToken,
+            region,
+        }).pipe(Effect.mapError((cause) => new AuthError({
+            message: "AWS: failed to verify credentials via STS GetCallerIdentity.",
+            cause,
+        })));
         return {
-            method: "local",
-            endpoint: endpoint || DEFAULT_LOCAL_ENDPOINT,
-            region: region || "us-east-1",
+            method: "stored",
+            accountId,
+            accessKeyId: Redacted.value(accessKeyId),
+            secretAccessKey: Redacted.value(secretAccessKey),
+            sessionToken: sessionToken === undefined
+                ? undefined
+                : Redacted.value(sessionToken),
+            region,
         };
-    })), Match.exhaustive)));
-    const configureCredentials = (profileName, ctx) => Effect.gen(function* () {
-        if (ctx.ci) {
-            return { method: "env" };
+    })), Match.when("sso", () => Effect.gen(function* () {
+        const values = yield* validateFieldValues(AWS_AUTH_PROVIDER_NAME, ssoFields, input.values);
+        const ssoProfile = storedValueText(values.ssoProfile) ?? "";
+        const auth = yield* DistilledAuth.Default;
+        const profile = yield* auth
+            .loadProfile(ssoProfile)
+            .pipe(Effect.catch(() => Effect.succeed(undefined)));
+        if (profile == null) {
+            return yield* Effect.fail(new AuthError({
+                message: `AWS SSO profile '${ssoProfile}' was not found in ~/.aws/config. Configure it with \`aws configure sso\` first, then log in. ${refreshHint(AWS_AUTH_PROVIDER_NAME, profileName)}`,
+            }));
         }
-        if (ctx.reason) {
-            // e.g. the credential-demand seam (`Auth/Demand.ts`) explaining
-            // which dev-plan resources require real AWS credentials.
-            yield* Clank.info(ctx.reason);
+        // Nothing is persisted for SSO — credentials come from the AWS
+        // SSO cache. `aws sso login` is interactive, so it is NOT run
+        // here; the user runs `alchemy profile refresh` afterwards.
+        return { method: "sso", ssoProfile };
+    })), Match.orElse(() => Effect.fail(new AuthError({
+        message: `AWS: unknown method '${input.method}'. Valid methods: stored, sso.`,
+    }))));
+    const resolveCredentials = (profileName, config, updateConfig) => Effect.gen(function* () {
+        const reauth = refreshHint(AWS_AUTH_PROVIDER_NAME, profileName);
+        return yield* Match.value(config)
+            .pipe(Match.when({ method: "stored" }, (config) => Effect.gen(function* () {
+            const credentials = {
+                accessKeyId: Redacted.make(config.accessKeyId),
+                secretAccessKey: Redacted.make(config.secretAccessKey),
+                sessionToken: config.sessionToken === undefined
+                    ? undefined
+                    : Redacted.make(config.sessionToken),
+                region: config.region,
+            };
+            const accountId = config.accountId ?? (yield* getAccountId(credentials));
+            if (config.accountId === undefined &&
+                updateConfig !== undefined) {
+                yield* updateConfig({ ...config, accountId });
+            }
+            return {
+                accountId,
+                credentials: Effect.succeed(credentials),
+                region: config.region,
+                source: { type: "stored" },
+            };
+        })), Match.when({ method: "sso" }, (config) => Effect.gen(function* () {
+            const auth = yield* DistilledAuth.Default;
+            const profile = yield* auth
+                .loadProfile(config.ssoProfile)
+                .pipe(Effect.catch(() => Effect.succeed(undefined)));
+            if (profile?.sso_account_id == null) {
+                const reconfigure = reconfigureHint(AWS_AUTH_PROVIDER_NAME, profileName);
+                return yield* Effect.fail(new AuthError({
+                    message: profile == null
+                        ? `AWS SSO profile '${config.ssoProfile}' was not found in ~/.aws/config. Configure it with \`aws configure sso\`. ${reconfigure}`
+                        : `AWS SSO profile '${config.ssoProfile}' has no sso_account_id in ~/.aws/config. Add it. ${reconfigure}`,
+                }));
+            }
+            // `applyEnvRegionOverride` below only overrides an existing
+            // region, so an env-provided region must be consulted here for
+            // profiles that don't record one.
+            const region = profile.region ?? (yield* getEnv("AWS_REGION"));
+            if (!region) {
+                return yield* Effect.fail(new AuthError({
+                    message: `AWS SSO profile '${config.ssoProfile}' has no region in ~/.aws/config and AWS_REGION is not set.`,
+                }));
+            }
+            return {
+                accountId: profile.sso_account_id,
+                // Rewrite the message of an expired/invalid SSO token to the
+                // alchemy refresh hint, but PRESERVE the error tags: the inner
+                // effect must stay a `CredentialsError` for downstream
+                // consumers (AWSEnvironment), while `details` and other
+                // in-provider consumers match these tags to surface a typed
+                // `NeedsReauth` instead of a generic failure.
+                credentials: auth
+                    .loadProfileCredentials(config.ssoProfile)
+                    .pipe(Effect.provideService(EffectConsole.Console, silentConsole), Effect.mapError((error) => {
+                    if (error._tag === "Alchemy::AWS::ExpiredSSOToken") {
+                        return new ExpiredSSOToken({
+                            message: `AWS SSO credentials need to be refreshed. ${reauth}`,
+                            profile: error.profile,
+                        });
+                    }
+                    if (error._tag === "Alchemy::AWS::InvalidSSOToken") {
+                        return new InvalidSSOToken({
+                            message: `AWS SSO credentials need to be refreshed. ${reauth}`,
+                            sso_session: error.sso_session,
+                        });
+                    }
+                    return error;
+                })),
+                region,
+                source: { type: "sso", details: config.ssoProfile },
+            };
+        })), Match.exhaustive)
+            .pipe(
+        // Pass diagnosable failures through untouched: NeedsReauth (stored
+        // credentials missing) and the specific AuthErrors raised above
+        // (missing SSO profile / sso_account_id / region) carry the real
+        // diagnosis. Only genuinely unexpected failures (store I/O, the
+        // STS accountId backfill) get wrapped.
+        Effect.mapError((e) => e._tag === "AuthError"
+            ? e
+            : new AuthError({
+                message: "failed to resolve AWS credentials",
+                cause: e,
+            })), Effect.flatMap(applyEnvRegionOverride), Effect.map((creds) => ({
+            ...creds,
+            credentials: creds.credentials.pipe(Effect.map((credentials) => ({
+                ...credentials,
+                region: creds.region,
+            }))),
+        })));
+    });
+    const details = (profileName, config, updateConfig) => Effect.gen(function* () {
+        const creds = yield* resolveCredentials(profileName, config, updateConfig);
+        const reauth = refreshHint(AWS_AUTH_PROVIDER_NAME, profileName);
+        // Resolve the live credentials. An expired/invalid SSO token only
+        // surfaces here (the inner effect is lazy), so convert those tags
+        // into a typed NeedsReauth instead of a generic error line.
+        const { accessKeyId, secretAccessKey, sessionToken } = yield* creds.credentials.pipe(Effect.mapError((error) => error._tag === "Alchemy::AWS::ExpiredSSOToken" ||
+            error._tag === "Alchemy::AWS::InvalidSSOToken"
+            ? new NeedsReauth({
+                provider: AWS_AUTH_PROVIDER_NAME,
+                profile: profileName,
+                message: `AWS SSO credentials need to be refreshed. ${reauth}`,
+                cause: error,
+            })
+            : new AuthError({
+                message: "failed to load AWS credentials",
+                cause: error,
+            })));
+        const lines = [
+            { key: "accessKeyId", value: displayRedacted(accessKeyId) },
+            { key: "secretAccessKey", value: displayRedacted(secretAccessKey) },
+        ];
+        if (sessionToken) {
+            lines.push({
+                key: "sessionToken",
+                value: displayRedacted(sessionToken),
+            });
         }
-        return yield* configureInteractive(profileName);
-    }).pipe(Effect.mapError((e) => new AuthError({
-        message: "failed to configure credentials",
-        cause: e,
-    })));
-    const resolveCredentials = (profileName, config) => Match.value(config)
-        .pipe(Match.when({ method: "env" }, Effect.fn(function* () {
+        if (creds.region) {
+            lines.push({ key: "region", value: creds.region });
+        }
+        const source = creds.source;
+        lines.push({
+            key: "source",
+            value: "details" in source
+                ? `${source.type} - ${source.details}`
+                : source.type,
+        });
+        return { lines };
+    });
+    const logout = (_profileName, config) => Match.value(config).pipe(Match.when({ method: "sso" }, (config) => interaction.output
+        .info(`AWS: running 'aws sso logout --profile ${config.ssoProfile}'...`)
+        .pipe(Effect.zip(runSsoCommand("logout", config.ssoProfile)), Effect.zip(clearDistilledSsoCache(config.ssoProfile)), Effect.match({
+        onSuccess: () => interaction.output.success("AWS: SSO logout complete"),
+        onFailure: (e) => interaction.output.warning(`AWS: SSO logout failed: \`${e.message}\``),
+    }))), Match.when({ method: "stored" }, () => Effect.void), Match.exhaustive);
+    const login = (profileName, config) => Match.value(config)
+        .pipe(Match.when({ method: "sso" }, (config) => loginSSO(config, config.authorizationMethod ?? "oauth")), Match.when({ method: "stored" }, (config) => Effect.succeed(config)), Match.exhaustive)
+        .pipe(Effect.mapError((e) => new AuthError({ message: "login failed", cause: e })));
+    const readEnvironment = Effect.gen(function* () {
         const accessKeyId = yield* getEnvRedactedRequired("AWS_ACCESS_KEY_ID");
         const secretAccessKey = yield* getEnvRedactedRequired("AWS_SECRET_ACCESS_KEY");
         const sessionToken = yield* getEnvRedacted("AWS_SESSION_TOKEN");
-        const region = yield* getEnv("AWS_REGION").pipe(Effect.flatMap((region) => region
-            ? Effect.succeed(region)
-            : getEnv("AWS_DEFAULT_REGION")));
+        const region = yield* getEnv("AWS_REGION").pipe(Effect.flatMap((value) => value ? Effect.succeed(value) : getEnv("AWS_DEFAULT_REGION")));
         if (!region) {
-            return yield* Effect.fail(new AuthError({
-                message: "AWS region not found. Set AWS_REGION or AWS_DEFAULT_REGION.",
-            }));
+            return yield* new AuthError({
+                message: "AWS CI region not found. Set AWS_REGION or AWS_DEFAULT_REGION.",
+            });
         }
-        // LocalStack-standard endpoint override: with
-        // AWS_ENDPOINT_URL set, every AWS call (including the STS
-        // account lookup below) targets the emulator.
-        const endpoint = yield* getEnv("AWS_ENDPOINT_URL");
         const accountId = yield* getEnvRequired("AWS_ACCOUNT_ID").pipe(Effect.catch(() => getAccountId({
             accessKeyId,
             secretAccessKey,
             sessionToken,
             region,
-            endpoint,
         })));
         return {
             accountId,
@@ -198,136 +448,53 @@ export const AwsAuth = AuthProviderLayer()(AWS_AUTH_PROVIDER_NAME, Effect.gen(fu
                 region,
             }),
             region,
-            endpoint,
             source: { type: "env" },
         };
-    })), Match.when({ method: "local" }, Effect.fn(function* (config) {
-        const endpoint = config.endpoint ?? DEFAULT_LOCAL_ENDPOINT;
-        const autoStart = config.autoStart ?? endpoint === DEFAULT_LOCAL_ENDPOINT;
-        if (autoStart) {
-            const port = yield* Effect.try({
-                try: () => Number.parseInt(new URL(endpoint).port, 10) ||
-                    Floci.DEFAULT_FLOCI_PORT,
-                catch: () => new AuthError({
-                    message: `invalid local emulator endpoint: ${endpoint}`,
-                }),
-            });
-            // Reuses anything already serving on the endpoint (dev-mode
-            // JVM, hand-run container, previous session's container);
-            // otherwise starts the managed floci container and waits for
-            // health.
-            yield* Floci.ensureFloci({ port }).pipe(Effect.mapError((e) => new AuthError({ message: e.message, cause: e })));
-        }
-        else {
-            const serving = yield* Floci.isServing(endpoint);
-            if (!serving) {
-                return yield* Effect.fail(new AuthError({
-                    message: `no local AWS emulator is listening at ${endpoint} — start one, or omit \`endpoint\` to auto-start floci on ${DEFAULT_LOCAL_ENDPOINT}`,
-                }));
-            }
-        }
-        const region = config.region ?? "us-east-1";
-        return {
-            // Fixed dummy account — emulators accept any non-empty
-            // credentials, and calling STS here would be pure overhead.
-            accountId: config.accountId ?? LOCAL_ACCOUNT_ID,
-            credentials: Effect.succeed({
-                accessKeyId: Redacted.make("test"),
-                secretAccessKey: Redacted.make("test"),
-                sessionToken: undefined,
-                region,
-            }),
-            region,
-            endpoint,
-            source: { type: "local", details: endpoint },
-        };
-    })), Match.when({ method: "stored" }, () => store.read(profileName, "aws").pipe(Effect.flatMap((creds) => creds == null
-        ? Effect.fail(new AuthError({
-            message: "AWS stored credentials not found. Run: alchemy login --configure",
-        }))
-        : Effect.succeed({
-            accountId: creds.accountId,
-            credentials: Effect.succeed({
-                accessKeyId: Redacted.make(creds.accessKeyId),
-                secretAccessKey: Redacted.make(creds.secretAccessKey),
-                sessionToken: creds.sessionToken
-                    ? Redacted.make(creds.sessionToken)
-                    : undefined,
-                region: creds.region,
-            }),
-            region: creds.region,
-            source: { type: "stored" },
-        })), 
-    // an older verson of the stored credentials didn't include the account ID, so we patch it hre
-    Effect.flatMap((creds) => creds.accountId
-        ? Effect.succeed(creds)
-        : creds.credentials.pipe(Effect.flatMap((resolved) => getAccountId({
-            accessKeyId: resolved.accessKeyId,
-            secretAccessKey: resolved.secretAccessKey,
-            sessionToken: resolved.sessionToken,
-            region: creds.region,
-        })), Effect.map((accountId) => ({
-            ...creds,
-            accountId,
-        })), 
-        // re-write the stored credentials
-        Effect.tap((creds) => creds.credentials.pipe(Effect.tap(({ accessKeyId, secretAccessKey, sessionToken }) => store.write(profileName, "aws", {
-            accessKeyId: Redacted.value(accessKeyId),
-            secretAccessKey: Redacted.value(secretAccessKey),
-            sessionToken: sessionToken
-                ? Redacted.value(sessionToken)
-                : undefined,
-            region: creds.region,
-            accountId: creds.accountId,
-        })))))))), Match.when({ method: "sso" }, (config) => Effect.gen(function* () {
-        const auth = yield* DistilledAuth.Default;
-        const profile = yield* auth
-            .loadProfile(config.ssoProfile)
-            .pipe(Effect.catch(() => Effect.succeed(undefined)));
-        return {
-            accountId: profile?.sso_account_id,
-            credentials: auth
-                .loadProfileCredentials(config.ssoProfile)
-                .pipe(Effect.mapError((e) => new AuthError({
-                message: "failed to load credentials",
-                cause: e,
-            })), Effect.orDie),
-            region: profile?.region,
-            source: { type: "sso", details: config.ssoProfile },
-        };
-    })), Match.exhaustive)
-        .pipe(Effect.mapError((e) => new AuthError({ message: "login failed", cause: e })), Effect.flatMap(applyEnvRegionOverride));
-    const prettyPrint = (profileName, config) => resolveCredentials(profileName, config).pipe(Effect.tap(Effect.fn(function* (creds) {
-        const { accessKeyId, secretAccessKey, sessionToken } = yield* creds.credentials;
-        yield* Console.log(`  accessKeyId:     ${displayRedacted(accessKeyId)}`);
-        yield* Console.log(`  secretAccessKey: ${displayRedacted(secretAccessKey)}`);
-        if (sessionToken) {
-            yield* Console.log(`  sessionToken:    ${displayRedacted(sessionToken)}`);
-        }
-        if (creds.region) {
-            yield* Console.log(`  region:          ${creds.region}`);
-        }
-        yield* Console.log(
-        //@ts-expect-error
-        `  source: ${creds.source.details ? `${creds.source.type} - ${creds.source.details}` : creds.source.type}`);
-    })));
-    const logout = (profileName, config) => Match.value(config).pipe(Match.when({ method: "env" }, () => Effect.void), Match.when({ method: "local" }, () => Effect.void), Match.when({ method: "sso" }, (config) => Clank.info(`AWS: running 'aws sso logout --profile ${config.ssoProfile}'...`).pipe(Effect.zip(runSsoCommand("logout", config.ssoProfile)), Effect.zip(clearDistilledSsoCache(config.ssoProfile)), Effect.match({
-        onSuccess: () => Clank.success("AWS: SSO logout complete"),
-        onFailure: (e) => Clank.warn(`AWS: SSO logout failed: \`${e.message}\``),
-    }))), Match.when({ method: "stored" }, () => store
-        .delete(profileName, "aws")
-        .pipe(Effect.andThen(Clank.success("AWS: stored credentials removed")))), Match.exhaustive);
-    const login = (profileName, config) => Match.value(config)
-        .pipe(Match.when({ method: "env" }, () => Effect.void), Match.when({ method: "local" }, () => Effect.void), Match.when({ method: "sso" }, loginSSO), Match.when({ method: "stored" }, () => store
-        .read(profileName, "aws")
-        .pipe(Effect.flatMap((creds) => creds == null ? loginStored(profileName) : Effect.void))), Match.exhaustive)
-        .pipe(Effect.mapError((e) => new AuthError({ message: "login failed", cause: e })));
+    }).pipe(Effect.mapError((cause) => cause instanceof AuthError
+        ? cause
+        : new AuthError({
+            message: "Failed to resolve AWS credentials from the CI environment.",
+            cause,
+        })));
     return {
+        configSchema: AwsAuthConfigSchema,
         configure: configureCredentials,
+        configureWith,
+        configureMethods,
         login,
         logout,
-        prettyPrint,
+        details,
         read: resolveCredentials,
+        readEnvironment,
+        environment: [
+            {
+                name: "AWS_ACCESS_KEY_ID",
+                required: true,
+                secret: true,
+            },
+            {
+                name: "AWS_SECRET_ACCESS_KEY",
+                required: true,
+                secret: true,
+            },
+            {
+                name: "AWS_SESSION_TOKEN",
+                required: false,
+                secret: true,
+                description: "Required when the access key is a temporary STS key.",
+            },
+            {
+                name: "AWS_REGION",
+                required: true,
+                alternatives: ["AWS_DEFAULT_REGION"],
+                description: "Region the stack deploys into.",
+            },
+            {
+                name: "AWS_ACCOUNT_ID",
+                required: false,
+                description: "Derived via STS GetCallerIdentity when unset.",
+            },
+        ],
     };
 }));
 const runSsoCommand = (command, ssoProfile) => Effect.gen(function* () {
@@ -344,9 +511,107 @@ const runSsoCommand = (command, ssoProfile) => Effect.gen(function* () {
         });
     }
 }).pipe(Effect.scoped);
-const loginSSO = (config) => Clank.info(`AWS SSO: running 'aws sso login --profile ${config.ssoProfile}'...`).pipe(Effect.andThen(runSsoCommand("login", config.ssoProfile)), Effect.matchEffect({
-    onSuccess: () => Clank.success("AWS SSO: login complete"),
-    onFailure: (e) => Clank.warn(`AWS SSO: login faield: \`${e.message}\``),
+const AwsSsoLoginOutput = Schema.Struct({
+    url: Schema.optional(Schema.String),
+    authUrl: Schema.optional(Schema.String),
+    authorizationUrl: Schema.optional(Schema.String),
+    verificationUri: Schema.optional(Schema.String),
+    verificationUriComplete: Schema.optional(Schema.String),
+    code: Schema.optional(Schema.String),
+    userCode: Schema.optional(Schema.String),
+});
+export const parseAwsSsoLoginOutput = (output) => {
+    try {
+        const decoded = Schema.decodeUnknownOption(AwsSsoLoginOutput)(JSON.parse(output));
+        if (Option.isSome(decoded)) {
+            const event = decoded.value;
+            return {
+                url: event.authorizationUrl ??
+                    event.authUrl ??
+                    event.verificationUriComplete ??
+                    event.verificationUri ??
+                    event.url,
+                code: event.userCode ?? event.code,
+            };
+        }
+    }
+    catch {
+        // `sso login` accepts the global `--output json` option but current AWS
+        // CLI releases still render this custom command's authorization prompt as
+        // text. Keep accepting structured output if AWS starts honoring the flag.
+    }
+    return {
+        url: output.match(/https?:\/\/[^\s]+/)?.[0],
+        code: output.match(/Then enter the code:\s*([A-Z0-9-]+)/i)?.[1],
+    };
+};
+const loginSSO = (config, authorizationMethod = "oauth") => Effect.scoped(Effect.gen(function* () {
+    const interaction = yield* Interaction.Interaction;
+    const services = yield* Effect.context();
+    const runOpenUrl = Effect.runPromiseWith(services);
+    const authorizationUrl = yield* Deferred.make();
+    const deviceCode = yield* Deferred.make();
+    const stdout = yield* Ref.make("");
+    const stderr = yield* Ref.make("");
+    const handle = yield* ChildProcess.make("aws", [
+        "sso",
+        "login",
+        "--profile",
+        config.ssoProfile,
+        "--no-browser",
+        "--output",
+        "json",
+        ...(authorizationMethod === "device" ? ["--use-device-code"] : []),
+    ], {
+        shell: false,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    const collectStdout = handle.stdout.pipe(Stream.decodeText(), Stream.runForEach((chunk) => Effect.gen(function* () {
+        const combined = yield* Ref.updateAndGet(stdout, (current) => current + chunk);
+        const { url, code } = parseAwsSsoLoginOutput(combined);
+        if (url !== undefined) {
+            yield* Deferred.succeed(authorizationUrl, url);
+        }
+        if (code !== undefined) {
+            yield* Deferred.succeed(deviceCode, code);
+        }
+    })));
+    const collectStderr = handle.stderr.pipe(Stream.decodeText(), Stream.runForEach((chunk) => Ref.update(stderr, (current) => current + chunk)));
+    const process = Effect.gen(function* () {
+        const [exitCode] = yield* Effect.all([handle.exitCode, collectStdout, collectStderr], { concurrency: 3 });
+        if (exitCode !== 0) {
+            const detail = (yield* Ref.get(stderr)).trim();
+            return yield* Effect.fail(new AuthError({
+                message: `aws sso login exited with code ${exitCode}${detail === "" ? "" : `: ${detail}`}`,
+            }));
+        }
+    });
+    const processFiber = yield* Effect.forkScoped(process);
+    const url = yield* Deferred.await(authorizationUrl).pipe(Effect.raceFirst(Fiber.join(processFiber).pipe(Effect.flatMap(() => Effect.fail(new AuthError({
+        message: "AWS SSO login completed without providing an authorization URL.",
+    }))))));
+    const code = authorizationMethod === "device"
+        ? yield* Deferred.await(deviceCode).pipe(Effect.raceFirst(Fiber.join(processFiber).pipe(Effect.flatMap(() => Effect.fail(new AuthError({
+            message: "AWS SSO device login completed without providing an authorization code.",
+        }))))))
+        : undefined;
+    const openFailed = yield* Interaction.openUrl(url).pipe(Effect.as(false), Effect.catch(() => Effect.succeed(true)));
+    yield* Fiber.join(processFiber).pipe(Effect.raceFirst(interaction.prompt
+        .awaitExternal({
+        message: "AWS authorization",
+        waitingLabel: authorizationMethod === "device"
+            ? "waiting for device authorization (up to 5 minutes)…"
+            : "waiting for browser authorization (up to 5 minutes)…",
+        url,
+        code,
+        openFailed,
+        onOpen: () => runOpenUrl(Interaction.openUrl(url)),
+        allowManualInput: false,
+    })
+        .pipe(Effect.asVoid)));
+    yield* interaction.output.success("AWS SSO: login complete");
 }));
 /**
  * `aws sso logout` only clears AWS CLI's own caches — it does not know about the