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

import {
  AuthError,
  AuthProviderLayer,
  NeedsReauth,
  refreshHint,
  type ConfigureField,
  type ConfigureMethod,
  type ProviderDetails,
} from "alchemy/Auth/AuthProvider";
import { displayRedacted } from "alchemy/Auth/Credentials";
import { getEnvRedacted, mapPromptCancellation } from "alchemy/Auth/Env";
import {
  storedSecret,
  storedValueText,
  validateFieldValues,
} from "alchemy/Auth/StoredAuthProvider";
import * as Interaction from "alchemy/Interaction";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Match from "effect/Match";
import * as ChildProcess from "effect/process/ChildProcess";
import { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
import * as Redacted from "effect/Redacted";
import * as Schema from "effect/Schema";
import * as Stream from "effect/Stream";
import { githubHostname, normalizeGitHubBaseUrl, resolveGitHubBaseUrlFromEnv } from "./BaseUrl.ts";

const options: Array<{
  value: GitHubAuthConfig["method"];
  label: string;
  description?: string;
}> = [
  {
    value: "gh-cli",
    label: "GitHub CLI",
    description: "delegate to `gh auth token` (run `gh auth login` first)",
  },
  {
    value: "stored",
    label: "Personal Access Token",
    description: "enter PAT interactively and store it in the profile",
  },
];

/** Typed values stored in a GitHub provider profile document. */
export const GitHubAuthConfigSchema = Schema.Union([
  Schema.Struct({
    method: Schema.Literal("stored"),
    token: Schema.String,
    baseUrl: Schema.optionalKey(Schema.String),
  }),
  Schema.Struct({
    method: Schema.Literal("gh-cli"),
    // v0 delegated to `gh auth token` and therefore had no inline token.
    // Keep that migration state readable; the first credential resolution
    // captures the token inline through updateConfig.
    token: Schema.optionalKey(Schema.String),
    baseUrl: Schema.optionalKey(Schema.String),
  }),
]);
export type GitHubAuthConfig = typeof GitHubAuthConfigSchema.Type;

export interface GitHubResolvedCredentials {
  type: "token";
  token: Redacted.Redacted<string>;
  /**
   * Normalized REST API base URL for GitHub Enterprise (e.g.
   * `https://github.example.com/api/v3` or `https://api.acme.ghe.com`).
   * `undefined` means github.com.
   */
  baseUrl?: string;
  source: { type: GitHubAuthConfig["method"] | "env"; details?: string };
}

export const GITHUB_AUTH_PROVIDER_NAME = "GitHub";

class GhCliError extends Data.TaggedError("GhCliError")<{
  readonly message: string;
}> {}

const readEnvTokenFor = (
  baseUrl: string | undefined,
): Effect.Effect<GitHubResolvedCredentials, AuthError> =>
  Effect.gen(function* () {
    const candidates =
      baseUrl !== undefined
        ? ["GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN", "GITHUB_ACCESS_TOKEN", "GITHUB_TOKEN"]
        : ["GITHUB_ACCESS_TOKEN", "GITHUB_TOKEN"];
    for (const key of candidates) {
      const token = yield* getEnvRedacted(key);
      if (token) {
        return {
          type: "token" as const,
          token,
          baseUrl,
          source: { type: "env" as const, details: key },
        };
      }
    }
    return yield* AuthError.make({
      message: `GitHub env credentials not found. Set ${candidates.join(", ")}.`,
    });
  });

/** Resolve standalone GitHub credentials from environment variables. */
export const readEnvCredentials = (
  configBaseUrl?: string,
): Effect.Effect<GitHubResolvedCredentials, AuthError> =>
  Effect.gen(function* () {
    const baseUrl = configBaseUrl ?? (yield* resolveGitHubBaseUrlFromEnv);
    return yield* readEnvTokenFor(baseUrl);
  });

/**
 * Build the Layer that registers the GitHub {@link AuthProvider} into the
 * {@link AuthProviders} registry. Included in the GitHub `providers()` layer
 * so the alchemy CLI can discover it.
 *
 * Supported methods:
 * - `gh-cli`: shells out to `gh auth token` (recommended).
 * - `stored`: prompts for a PAT and stores it inline in the provider file.
 *
 * GitHub Enterprise (Server or Cloud with data residency) is supported by
 * every method: `alchemy profile edit --reconfigure GitHub` prompts for the host, or set
 * `GITHUB_BASE_URL` / `GITHUB_API_URL` / `GH_HOST` in the environment. The
 * host is normalized into the REST API base URL the SDK calls, and
 * `gh auth token` is invoked with `--hostname` so the CLI returns the token
 * for the right host.
 *
 * Browser/device OAuth is intentionally not implemented: GitHub's
 * OAuth App flow requires a `client_secret` we cannot ship, and
 * device flow is exactly what `gh auth login` already does.
 */
export interface GitHubAuthOptions {
  /**
   * Hard-code the GitHub host or API base URL (e.g. `github.example.com`
   * or `https://github.example.com/api/v3`). When set, it takes precedence
   * over the profile's configured host and the environment for every auth
   * method, the configure flow stops prompting for a host, and the `gh` CLI
   * method authenticates against this host. `GitHub.providers({ baseUrl })`
   * threads its option here.
   */
  readonly baseUrl?: string;
}

export const makeGitHubAuth = (authOptions?: GitHubAuthOptions) =>
  AuthProviderLayer<GitHubAuthConfig, GitHubResolvedCredentials>()(
    GITHUB_AUTH_PROVIDER_NAME,
    Effect.gen(function* () {
      // Prompts use the top-level `Interaction.*` forms, NOT `yield* Interaction.Interaction`: resolving the service
      // at impl build would put the terminal in the registration layer's
      // requirements, and child processes (which only ever call `read`) build
      // this layer with no interaction services at all.
      const cp = yield* ChildProcessSpawner;

      // Hard-coded host from `providers({ baseUrl })`, resolved once at layer
      // build. Kept as an object so "no option" (undefined) is distinct from
      // "option normalized to the github.com default" ({ baseUrl: undefined })
      // — both matter: the latter still pins the host and mutes the prompt.
      const fixed =
        authOptions?.baseUrl !== undefined
          ? {
              baseUrl: yield* normalizeGitHubBaseUrl(authOptions.baseUrl).pipe(Effect.orDie),
            }
          : undefined;

      // The host every method authenticates against: the hard-coded value
      // wins, then the profile's configured host, then the environment.
      const effectiveBaseUrl = (
        config: GitHubAuthConfig,
      ): Effect.Effect<string | undefined, AuthError> =>
        fixed !== undefined
          ? Effect.succeed(fixed.baseUrl)
          : config.baseUrl !== undefined
            ? Effect.succeed(config.baseUrl)
            : resolveGitHubBaseUrlFromEnv;

      const ghCliToken = (hostname?: string): Effect.Effect<string, AuthError> =>
        Effect.gen(function* () {
          const handle = yield* cp.spawn(
            ChildProcess.make(
              "gh",
              ["auth", "token", ...(hostname !== undefined ? ["--hostname", hostname] : [])],
              { shell: false },
            ),
          );
          const [exitCode, stdout, stderr] = yield* Effect.all(
            [
              handle.exitCode,
              handle.stdout.pipe(Stream.decodeText, Stream.mkString),
              handle.stderr.pipe(Stream.decodeText, Stream.mkString),
            ],
            { concurrency: 3 },
          );
          if (exitCode !== 0) {
            return yield* new GhCliError({
              message: `gh auth token exited with ${exitCode}: ${stderr.trim() || stdout.trim()}`,
            });
          }
          const token = stdout.trim();
          if (!token) {
            return yield* new GhCliError({ message: "gh auth token returned empty output" });
          }
          return token;
        }).pipe(
          Effect.scoped,
          Effect.mapError((e) =>
            e instanceof GhCliError
              ? AuthError.make({ message: e.message, cause: e })
              : AuthError.make({
                  message:
                    "Could not invoke `gh`. Install GitHub CLI from https://cli.github.com/ and run `gh auth login`.",
                  cause: e,
                }),
          ),
        );

      const loginStored = Effect.fn(function* (baseUrl?: string) {
        const token = yield* Interaction.password({
          message: "GitHub Personal Access Token",
          description: "Requires `repo` scope and `workflow` for GitHub Actions.",
          validate: (v) => (v.length === 0 ? "Required" : undefined),
        }).pipe(mapPromptCancellation);
        yield* Interaction.success("GitHub: credentials saved.");
        return { method: "stored" as const, token, baseUrl };
      });

      // Optional GitHub Enterprise host. Blank means github.com; anything else
      // is normalized into the REST API base URL (GHES gets `/api/v3`
      // appended, data-residency hosts get the `api.` prefix).
      const promptBaseUrl = Interaction.text({
        message: "GitHub host",
        description:
          "Leave blank for github.com; use a hostname such as github.example.com for GitHub Enterprise.",
        placeholder: "github.com",
        defaultValue: "",
      }).pipe(
        mapPromptCancellation,
        Effect.flatMap((input) => {
          const trimmed = (input ?? "").trim();
          return trimmed === "" ? Effect.undefined : normalizeGitHubBaseUrl(trimmed);
        }),
      );

      const configureInteractive = (_profileName: string) =>
        Effect.gen(function* () {
          const method = yield* Interaction.select({
            message: "GitHub authentication method",
            options,
          });
          // The host prompt is skipped when providers({ baseUrl }) pinned it —
          // nothing is stored in the profile config; `read` re-applies the
          // pinned value from code on every resolution.
          const baseUrl = fixed !== undefined ? undefined : yield* promptBaseUrl;
          const verifyHost = fixed !== undefined ? fixed.baseUrl : baseUrl;
          return yield* Match.value(method).pipe(
            Match.when("gh-cli", () =>
              ghCliToken(verifyHost !== undefined ? githubHostname(verifyHost) : undefined).pipe(
                Effect.map((token) => ({
                  method: "gh-cli" as const,
                  token,
                  baseUrl,
                })),
                Effect.mapError((e) =>
                  AuthError.make({
                    message: `gh CLI not available: ${e.message}`,
                    cause: e,
                  }),
                ),
              ),
            ),
            Match.when("stored", () => loginStored(baseUrl)),
            Match.exhaustive,
          );
        });

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

      const resolveCredentials = (
        profileName: string,
        config: GitHubAuthConfig,
        updateConfig?: (config: GitHubAuthConfig) => Effect.Effect<void, AuthError>,
      ): Effect.Effect<GitHubResolvedCredentials, AuthError | NeedsReauth> =>
        Match.value(config).pipe(
          Match.when(
            { method: "stored" },
            Effect.fn(function* (c) {
              const baseUrl = yield* effectiveBaseUrl(c);
              return {
                type: "token" as const,
                token: Redacted.make(c.token),
                baseUrl,
                source: { type: "stored" as const },
              };
            }),
          ),
          Match.when(
            { method: "gh-cli" },
            Effect.fn(function* (c) {
              const baseUrl = yield* effectiveBaseUrl(c);
              const token =
                c.token ??
                (yield* ghCliToken(
                  baseUrl !== undefined ? githubHostname(baseUrl) : undefined,
                ).pipe(
                  Effect.mapError((cause) =>
                    NeedsReauth.make({
                      provider: GITHUB_AUTH_PROVIDER_NAME,
                      profile: profileName,
                      message: `GitHub CLI credentials need to be refreshed. ${refreshHint(GITHUB_AUTH_PROVIDER_NAME, profileName)}`,
                      cause,
                    }),
                  ),
                ));
              if (c.token === undefined && updateConfig !== undefined) {
                yield* updateConfig({ ...c, token });
              }
              return {
                type: "token" as const,
                token: Redacted.make(token),
                baseUrl,
                source: { type: "gh-cli" as const },
              };
            }),
          ),
          Match.exhaustive,
        );

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

      const login = (_profileName: string, config: GitHubAuthConfig) =>
        Match.value(config).pipe(
          Match.when({ method: "gh-cli" }, (c) =>
            effectiveBaseUrl(c).pipe(
              Effect.flatMap((baseUrl) =>
                ghCliToken(baseUrl !== undefined ? githubHostname(baseUrl) : undefined),
              ),
              Effect.tap(() => Interaction.success("GitHub: gh CLI authentication available.")),
              Effect.map((token) => ({ ...c, token })),
            ),
          ),
          Match.when({ method: "stored" }, (c) => Effect.succeed(c)),
          Match.exhaustive,
          Effect.mapError((e) => AuthError.make({ message: "login failed", cause: e })),
        );

      const details = (
        profileName: string,
        config: GitHubAuthConfig,
        updateConfig?: (config: GitHubAuthConfig) => Effect.Effect<void, AuthError>,
      ): Effect.Effect<ProviderDetails, AuthError | NeedsReauth> =>
        resolveCredentials(profileName, config, updateConfig).pipe(
          Effect.map((creds) => {
            const sourceStr = creds.source.details
              ? `${creds.source.type} - ${creds.source.details}`
              : creds.source.type;
            return {
              lines: [
                { key: "token", value: displayRedacted(creds.token, 6) },
                { key: "source", value: sourceStr },
                ...(creds.baseUrl !== undefined ? [{ key: "baseUrl", value: creds.baseUrl }] : []),
              ],
            };
          }),
        );

      // Flag-driven configuration covers the "stored" (PAT) method only;
      // "gh-cli" requires an interactive `gh auth login` session and is
      // deliberately absent from configureMethods.
      const storedFields: ReadonlyArray<ConfigureField> = [
        {
          name: "token",
          label: "GitHub Personal Access Token",
          description: "Requires `repo` scope and `workflow` for GitHub Actions.",
          secret: true,
        },
        {
          name: "baseUrl",
          label: "GitHub host",
          description:
            "Leave blank for github.com; use a hostname such as github.example.com for GitHub Enterprise.",
          optional: true,
        },
      ];

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

      const configureWith = (
        _profileName: string,
        input: {
          readonly method: string;
          readonly values: Record<string, string>;
        },
      ): Effect.Effect<GitHubAuthConfig, AuthError, Interaction.Interaction> =>
        input.method === "stored"
          ? validateFieldValues(GITHUB_AUTH_PROVIDER_NAME, storedFields, input.values).pipe(
              Effect.flatMap(
                Effect.fn(function* (values) {
                  // A hard-coded providers({ baseUrl }) pins the host; nothing
                  // is stored in the profile config in that case (mirrors the
                  // interactive configure flow).
                  const baseUrl =
                    fixed !== undefined
                      ? undefined
                      : values.baseUrl !== undefined
                        ? yield* normalizeGitHubBaseUrl(storedValueText(values.baseUrl) ?? "")
                        : undefined;
                  const token = Redacted.value(storedSecret(values.token) ?? Redacted.make(""));
                  yield* Interaction.success("GitHub: credentials saved.");
                  return { method: "stored" as const, token, baseUrl };
                }),
              ),
            )
          : Effect.fail(
              AuthError.make({
                message: `GitHub: unknown method '${input.method}'. Valid methods: stored. (gh-cli is interactive-only.)`,
              }),
            );

      return {
        configSchema: GitHubAuthConfigSchema,
        configure: configureCredentials,
        configureWith,
        configureMethods,
        logout,
        login,
        details,
        read: resolveCredentials,
        readEnvironment: readEnvCredentials(fixed !== undefined ? fixed.baseUrl : undefined),
        environment: [
          {
            name: "GITHUB_ACCESS_TOKEN",
            required: true,
            secret: true,
            alternatives: ["GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"],
            description:
              "Personal access token. The enterprise variants are only consulted when a GitHub Enterprise host is configured.",
          },
          {
            name: "GITHUB_BASE_URL",
            required: false,
            alternatives: ["GITHUB_API_URL", "GH_HOST"],
            description: "GitHub Enterprise host or REST API base URL.",
          },
        ],
      };
    }),
  );

/**
 * The default GitHub AuthProvider layer — {@link makeGitHubAuth} with no
 * hard-coded host. Use `GitHub.providers({ baseUrl })` (or
 * `makeGitHubAuth({ baseUrl })` directly) to pin a GitHub Enterprise host.
 */
export const GitHubAuth = makeGitHubAuth();