sailfork / t3code-github / .repos/ alchemy-effect/ packages/ planetscale/ src/ AuthProvider.ts

import { listOrganizations } from "@distilled.cloud/planetscale";
import * as PsCredentialsModule from "@distilled.cloud/planetscale/Credentials";
import {
  AuthError,
  AuthProviderLayer,
  refreshHint,
  type ConfigureField,
  type ConfigureMethod,
  NeedsReauth,
  type ProviderDetails,
} from "alchemy/Auth/AuthProvider";
import { browserOAuth } from "alchemy/Auth/BrowserOAuth";
import { displayRedacted } from "alchemy/Auth/Credentials";
import { getEnvRedactedRequired, getEnvRequired, mapPromptCancellation } from "alchemy/Auth/Env";
import { withProfileCredentialsLock } from "alchemy/Auth/Lock";
import {
  storedSecret,
  storedValueText,
  validateFieldValues,
} from "alchemy/Auth/StoredAuthProvider";
import * as Interaction from "alchemy/Interaction";
import * as Clock from "effect/Clock";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";
import * as HttpClient from "effect/http/HttpClient";
import * as Layer from "effect/Layer";
import * as Match from "effect/Match";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import * as OAuthClient from "./OAuthClient.ts";

/**
 * Canonical name registered in {@link AuthProviders}. Use this key to look
 * up the PlanetScale {@link AuthProvider} from inside provider Layers.
 */
export const PLANETSCALE_AUTH_PROVIDER_NAME = "Planetscale";

/**
 * Provide PlanetScale `Credentials` + `HttpClient` to an Effect using a
 * just-obtained OAuth access token. Used during configure to call
 * org-discovery endpoints before the user has chosen an org.
 *
 * `organization` is required by the credential type but isn't consulted by
 * `listOrganizations` (it's a user-scoped endpoint), so an empty string is
 * fine here.
 */
const withOAuthCredentials = <A, E, R>(
  accessToken: string,
  effect: Effect.Effect<A, E, R | PsCredentialsModule.Credentials | HttpClient.HttpClient>,
): Effect.Effect<A, E, R> =>
  Effect.provide(
    effect,
    Layer.mergeAll(
      PsCredentialsModule.fromOAuth({
        accessToken: Redacted.make(accessToken),
        organization: "",
      }),
      FetchHttpClient.layer,
    ),
  );

/**
 * List the organizations the OAuth user belongs to and either auto-pick
 * (one org) or prompt the user to choose. Returns the org's URL slug
 * (`name` field, used as `{organization}` in API paths).
 */
const selectOrganization = (accessToken: string) =>
  Effect.gen(function* () {
    const list = yield* listOrganizations;
    const response = yield* list({});
    const orgs = response.data;
    if (orgs.length === 0) {
      return yield* AuthError.make({
        message: "Planetscale: no organizations found for this credential.",
      });
    }
    if (orgs.length === 1) {
      const org = orgs[0];
      if (org === undefined) {
        return yield* AuthError.make({
          message: "Planetscale: organization response was unexpectedly empty.",
        });
      }
      yield* Interaction.info(`Planetscale: using organization: ${org.name} (${org.id})`);
      return org.name;
    }
    return yield* Interaction.select({
      message: "Select a Planetscale organization",
      options: orgs.map((o) => ({
        value: o.name,
        label: o.name,
        description: o.id,
      })),
    }).pipe(mapPromptCancellation);
  }).pipe((e) => withOAuthCredentials(accessToken, e));

const options: Array<{
  value: PlanetscaleAuthConfig["method"];
  label: string;
  description?: string;
}> = [
  {
    value: "oauth",
    label: "OAuth",
    description: "recommended — browser-based login with automatic token refresh",
  },
  {
    value: "stored",
    label: "Service Token",
    description: "enter a service token and store it inline in the provider file",
  },
];

/**
 * Typed values stored in a PlanetScale provider profile document. Both
 * service-token and OAuth values are inline. PlanetScale has no PKCE flow,
 * so the OAuth application's
 *   `client_secret` ships in the CLI — see {@link OAuthClient}.
 */
export const PlanetscaleAuthConfigSchema = Schema.Union([
  Schema.Struct({
    method: Schema.Literal("stored"),
    tokenId: Schema.String,
    token: Schema.String,
    organization: Schema.String,
  }),
  Schema.Struct({
    method: Schema.Literal("oauth"),
    organization: Schema.String,
    clientId: Schema.optional(Schema.String),
    access: Schema.String,
    refresh: Schema.String,
    expires: Schema.Number,
    scopes: Schema.String.pipe(Schema.Array, Schema.mutable),
  }),
]);
export type PlanetscaleAuthConfig = typeof PlanetscaleAuthConfigSchema.Type;

/**
 * Resolved in-memory PlanetScale credentials returned by
 * {@link AuthProviderImpl.read}. Either a service token (`tokenId`/`token`)
 * or an OAuth access token.
 */
export type PlanetscaleResolvedCredentials =
  | {
      type: "apiToken";
      tokenId: Redacted.Redacted<string>;
      token: Redacted.Redacted<string>;
      organization: string;
      source: {
        type: PlanetscaleAuthConfig["method"] | "env";
        details?: string;
      };
    }
  | {
      type: "oauth";
      accessToken: Redacted.Redacted<string>;
      expires: number;
      organization: string;
      source: {
        type: PlanetscaleAuthConfig["method"] | "env";
        details?: string;
      };
    };

/**
 * Layer that registers the PlanetScale {@link AuthProvider} into the
 * {@link AuthProviders} registry when built. Include this in the
 * PlanetScale `providers()` layer so the alchemy CLI can discover it.
 *
 * Supported methods:
 * - `stored`: prompts for a service token and stores it inline.
 * - `oauth`: browser-based login storing access/refresh values inline.
 */
export const PlanetscaleAuth = AuthProviderLayer<
  PlanetscaleAuthConfig,
  PlanetscaleResolvedCredentials
>()(
  PLANETSCALE_AUTH_PROVIDER_NAME,
  Effect.gen(function* () {
    const oauthLogin = (_profileName: string) =>
      Effect.gen(function* () {
        const authorization = yield* OAuthClient.authorize();

        const credentials = yield* browserOAuth({
          provider: "Planetscale",
          url: authorization.url,
          callback: OAuthClient.callback(authorization),
          exchange: (input) => OAuthClient.exchangeCallbackInput(input, authorization),
        });
        yield* Interaction.success("Planetscale: OAuth credentials saved.");
        return credentials;
      });

    const configureOAuth = Effect.fn(function* (profileName: string) {
      const oauthCreds = yield* oauthLogin(profileName);

      // Use the just-issued access token to list the user's orgs and let
      // them pick (mirrors Cloudflare's selectAccount). Requires the
      // `user:read_organizations` scope. If the call fails for any
      // reason — missing scope, network, off-spec response — fall back
      // to a manual prompt so login still completes.
      const organization = yield* oauthCreds.access.pipe(
        Redacted.value,
        selectOrganization,
        Effect.catch((e) =>
          Effect.gen(function* () {
            yield* Interaction.warning(
              `Planetscale: could not auto-list organizations (${String(e)}). Falling back to manual entry.`,
            );
            return yield* Interaction.text({
              message: "Planetscale Organization (URL slug)",
              validate: (v) => (v.length === 0 ? "Required" : undefined),
            }).pipe(mapPromptCancellation);
          }),
        ),
      );

      return {
        method: "oauth" as const,
        organization,
        clientId: oauthCreds.clientId,
        access: Redacted.value(oauthCreds.access),
        refresh: Redacted.value(oauthCreds.refresh),
        expires: oauthCreds.expires,
        scopes: oauthCreds.scopes,
      };
    });

    const loginStored = Effect.fn(function* (_profileName: string) {
      const tokenId = yield* Interaction.text({
        message: "Planetscale Service Token ID",
        validate: (v) => (v.length === 0 ? "Required" : undefined),
      }).pipe(mapPromptCancellation);

      const token = yield* Interaction.password({
        message: "Planetscale Service Token",
        validate: (v) => (v.length === 0 ? "Required" : undefined),
      }).pipe(mapPromptCancellation);

      const organization = yield* Interaction.text({
        message: "Planetscale Organization (URL slug)",
        validate: (v) => (v.length === 0 ? "Required" : undefined),
      }).pipe(mapPromptCancellation);

      yield* Interaction.success("Planetscale: credentials saved.");
      return { method: "stored" as const, tokenId, token, organization };
    });

    const configureInteractive = (profileName: string) =>
      Interaction.select({
        message: "Planetscale authentication method",
        options,
      }).pipe(
        Effect.flatMap((method) =>
          Match.value(method).pipe(
            Match.when("oauth", () => configureOAuth(profileName)),
            Match.when("stored", () => loginStored(profileName)),
            Match.exhaustive,
          ),
        ),
      );

    const configureCredentials = (profileName: string) =>
      configureInteractive(profileName).pipe(
        Effect.mapError((e) =>
          AuthError.make({
            message: "failed to configure credentials",
            cause: e,
          }),
        ),
      );

    /**
     * Flag-driven (`--method stored --set ...`) fields, mirroring the
     * interactive service-token prompts. OAuth requires a browser and stays
     * interactive-only, so it is deliberately absent from
     * {@link configureMethods}.
     */
    const serviceTokenFields: ReadonlyArray<ConfigureField> = [
      { name: "tokenId", label: "Planetscale Service Token ID" },
      { name: "token", label: "Planetscale Service Token", secret: true },
      { name: "organization", label: "Planetscale Organization (URL slug)" },
    ];

    const configureMethods: ReadonlyArray<ConfigureMethod> = [
      { method: "stored", fields: serviceTokenFields },
    ];

    const configureWith = (
      _profileName: string,
      input: {
        readonly method: string;
        readonly values: Record<string, string>;
      },
    ): Effect.Effect<PlanetscaleAuthConfig, AuthError, Interaction.Interaction> =>
      input.method === "stored"
        ? validateFieldValues(
            PLANETSCALE_AUTH_PROVIDER_NAME,
            serviceTokenFields,
            input.values,
          ).pipe(
            Effect.map((values) => ({
              method: "stored" as const,
              tokenId: Redacted.value(storedSecret(values.tokenId) ?? Redacted.make("")),
              token: Redacted.value(storedSecret(values.token) ?? Redacted.make("")),
              organization: storedValueText(values.organization) ?? "",
            })),
            Effect.tap(() => Interaction.success("Planetscale: credentials saved.")),
          )
        : Effect.fail(
            AuthError.make({
              message: `Planetscale: unknown method '${input.method}'. Valid methods: stored. (OAuth is interactive-only.)`,
            }),
          );

    const resolveCredentials = (
      profileName: string,
      config: PlanetscaleAuthConfig,
      updateConfig?: (config: PlanetscaleAuthConfig) => Effect.Effect<void, AuthError>,
    ) =>
      Effect.gen(function* () {
        const reauth = refreshHint(PLANETSCALE_AUTH_PROVIDER_NAME, profileName);
        return yield* Match.value(config).pipe(
          Match.when({ method: "stored" }, (stored) =>
            Effect.succeed({
              type: "apiToken" as const,
              tokenId: Redacted.make(stored.tokenId),
              token: Redacted.make(stored.token),
              organization: stored.organization,
              source: { type: "stored" as const, details: undefined },
            } satisfies PlanetscaleResolvedCredentials),
          ),
          Match.when({ method: "oauth" }, (cfg) =>
            Effect.gen(function* () {
              const creds: OAuthClient.OAuthCredentials = {
                type: "oauth",
                clientId: cfg.clientId,
                access: Redacted.make(cfg.access),
                refresh: Redacted.make(cfg.refresh),
                expires: cfg.expires,
                scopes: cfg.scopes,
              };
              if (!OAuthClient.usesCurrentClient(creds)) {
                return yield* NeedsReauth.make({
                  provider: PLANETSCALE_AUTH_PROVIDER_NAME,
                  profile: profileName,
                  message: `Planetscale OAuth credentials for profile '${profileName}' were issued to an incompatible OAuth client and have been removed. ${reauth}`,
                });
              }
              // Refresh proactively if the token has expired (or is within
              // 10s of expiring). Persist the refreshed creds so subsequent
              // resolves don't repeat the round-trip.
              const now = yield* Clock.currentTimeMillis;
              const fresh =
                creds.expires > now + 10_000
                  ? creds
                  : yield* OAuthClient.refresh(creds).pipe(
                      // Only the refresh round-trip maps to NeedsReauth — a
                      // failed persist afterwards is a local I/O AuthError and
                      // passes through untouched.
                      Effect.mapError((e) =>
                        NeedsReauth.make({
                          provider: PLANETSCALE_AUTH_PROVIDER_NAME,
                          profile: profileName,
                          message: `Planetscale OAuth refresh failed. ${reauth}`,
                          cause: e,
                        }),
                      ),
                    );
              if (fresh !== creds) {
                yield* (
                  updateConfig?.({
                    method: "oauth",
                    organization: cfg.organization,
                    clientId: fresh.clientId,
                    access: Redacted.value(fresh.access),
                    refresh: Redacted.value(fresh.refresh),
                    expires: fresh.expires,
                    scopes: fresh.scopes,
                  }) ?? Effect.void
                );
              }
              return {
                type: "oauth" as const,
                accessToken: fresh.access,
                expires: fresh.expires,
                organization: cfg.organization,
                source: { type: "oauth" as const },
              } satisfies PlanetscaleResolvedCredentials;
            }),
          ),
          Match.exhaustive,
        );
      });

    const logout = (_profileName: string, config: PlanetscaleAuthConfig) =>
      Match.value(config).pipe(
        Match.when({ method: "stored" }, () => Effect.void),
        Match.when({ method: "oauth" }, () => Effect.void),
        Match.exhaustive,
      );

    const login = (
      profileName: string,
      config: PlanetscaleAuthConfig,
      updateConfig?: (config: PlanetscaleAuthConfig) => Effect.Effect<void, AuthError>,
      reload?: Effect.Effect<PlanetscaleAuthConfig, AuthError>,
    ) =>
      Match.value(config).pipe(
        Match.when({ method: "stored" }, (stored) => Effect.succeed(stored)),
        Match.when({ method: "oauth" }, (oauth) =>
          Effect.gen(function* () {
            const credentials: OAuthClient.OAuthCredentials = {
              type: "oauth",
              clientId: oauth.clientId,
              access: Redacted.make(oauth.access),
              refresh: Redacted.make(oauth.refresh),
              expires: oauth.expires,
              scopes: oauth.scopes,
            };
            if (!OAuthClient.usesCurrentClient(credentials)) {
              return yield* configureOAuth(profileName);
            }
            // Refresh tokens are single-use: refresh with the token stored
            // now, read under the lock, not the one `config` was read with.
            const outcome = yield* withProfileCredentialsLock(
              profileName,
              Effect.gen(function* () {
                const current = yield* reload ?? Effect.succeed(oauth);
                if (current.method !== "oauth") return { type: "browser" as const };
                const currentCredentials: OAuthClient.OAuthCredentials = {
                  type: "oauth",
                  clientId: current.clientId,
                  access: Redacted.make(current.access),
                  refresh: Redacted.make(current.refresh),
                  expires: current.expires,
                  scopes: current.scopes,
                };
                if (!OAuthClient.usesCurrentClient(currentCredentials)) {
                  return { type: "browser" as const };
                }
                return yield* Interaction.info("Planetscale: refreshing OAuth credentials...").pipe(
                  Effect.andThen(OAuthClient.refresh(currentCredentials)),
                  Effect.flatMap((credentials) => {
                    const config = {
                      ...current,
                      clientId: credentials.clientId,
                      access: Redacted.value(credentials.access),
                      refresh: Redacted.value(credentials.refresh),
                      expires: credentials.expires,
                      scopes: credentials.scopes,
                    };
                    // Saved here, under the lock, when the caller can take it;
                    // otherwise handed back for the caller to save.
                    const unsaved: Effect.Effect<typeof config | undefined, AuthError> =
                      updateConfig === undefined
                        ? Effect.succeed(config)
                        : Effect.as(updateConfig(config), undefined);
                    return unsaved.pipe(
                      Effect.map((config) => ({ type: "refreshed" as const, config })),
                    );
                  }),
                  Effect.tap(() =>
                    Interaction.success("Planetscale: OAuth credentials refreshed."),
                  ),
                );
              }),
            ).pipe(
              Effect.catchTag(
                [
                  "OAuthError",
                  "OAuthNetworkError",
                  "OAuthServerUnavailable",
                  "OAuthInvalidResponse",
                ],
                () => Effect.succeed({ type: "browser" as const }),
              ),
            );
            if (outcome.type === "browser") {
              return yield* configureOAuth(profileName);
            }
            return outcome.config;
          }),
        ),
        Match.exhaustive,
        Effect.mapError((e) => AuthError.make({ message: "login failed", cause: e })),
      );

    const details = (
      profileName: string,
      config: PlanetscaleAuthConfig,
      updateConfig?: (config: PlanetscaleAuthConfig) => Effect.Effect<void, AuthError>,
    ) =>
      Effect.all([
        resolveCredentials(profileName, config, updateConfig),
        Clock.currentTimeMillis,
      ]).pipe(
        Effect.map(([creds, now]): ProviderDetails => {
          const source: PlanetscaleResolvedCredentials["source"] = creds.source;
          const sourceStr = source.details ? `${source.type} - ${source.details}` : source.type;
          return Match.value(creds).pipe(
            Match.when({ type: "apiToken" }, (c) => ({
              lines: [
                { key: "tokenId", value: displayRedacted(c.tokenId, 3) },
                { key: "token", value: displayRedacted(c.token, 6) },
                { key: "organization", value: c.organization },
                { key: "source", value: sourceStr },
              ],
            })),
            Match.when({ type: "oauth" }, (c) => {
              const remainingMs = c.expires - now;
              const expiresAt = new Date(c.expires).toISOString();
              const expiresStr =
                remainingMs <= 0
                  ? `expired (${expiresAt})`
                  : `in ${Duration.format(Duration.millis(remainingMs))} (${expiresAt})`;
              return {
                lines: [
                  { key: "accessToken", value: displayRedacted(c.accessToken) },
                  { key: "expires", value: expiresStr },
                  { key: "organization", value: c.organization },
                  { key: "source", value: sourceStr },
                ],
              };
            }),
            Match.exhaustive,
          );
        }),
      );

    const readEnvironment = Effect.gen(function* () {
      const tokenId = yield* getEnvRedactedRequired("PLANETSCALE_API_TOKEN_ID");
      const token = yield* getEnvRedactedRequired("PLANETSCALE_API_TOKEN");
      const organization = yield* getEnvRequired("PLANETSCALE_ORGANIZATION");
      return {
        type: "apiToken" as const,
        tokenId,
        token,
        organization,
        source: {
          type: "env" as const,
          details: "PLANETSCALE_API_TOKEN_ID/PLANETSCALE_API_TOKEN",
        },
      } satisfies PlanetscaleResolvedCredentials;
    });

    return {
      configSchema: PlanetscaleAuthConfigSchema,
      configure: configureCredentials,
      configureWith,
      configureMethods,
      logout,
      login,
      details,
      read: resolveCredentials,
      readEnvironment,
      environment: [
        {
          name: "PLANETSCALE_API_TOKEN_ID",
          required: true,
          description: "Service token id.",
        },
        {
          name: "PLANETSCALE_API_TOKEN",
          required: true,
          secret: true,
          description: "Service token secret.",
        },
        {
          name: "PLANETSCALE_ORGANIZATION",
          required: true,
          description: "Organization URL slug.",
        },
        {
          name: "PLANETSCALE_API_BASE_URL",
          required: false,
          description: "API base URL override.",
        },
      ],
    };
  }),
);