@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/src/modules/settings/git-root-folders.ts

@@ -0,0 +1,171 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import type { IGitRunner } from '../../shared/git.contract.js';
+import { printable } from '../../shared/printable.js';
+import { logger } from '../../shared/logging.js';
+import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { probeCredentialArgs, probeGitEnv } from './connection-check.js';
+
+const log = logger('setup');
+
+/** How one `git` invocation is run. Injected by tests; the deployment's git port otherwise. */
+export type GitRunner = (
+  args: string[],
+  options: { env: NodeJS.ProcessEnv; timeout: number },
+) => Promise<{ stdout: string }>;
+
+/**
+ * The listing's git, run through the deployment's git port (see
+ * `shared/git.contract.ts`) — the same port the connection check runs
+ * through — so it carries the same environment, deadline handling and token
+ * redaction as every other git the backend runs, and a clone whose host
+ * stalls mid-transfer is killed with its transport helpers at the deadline
+ * rather than left holding the request open.
+ */
+export function listingRunnerFor(runner: IGitRunner): GitRunner {
+  return async (args, { env, timeout }) => {
+    const { stdout } = await runner.run(process.cwd(), args, { env, timeoutMs: timeout });
+    return { stdout };
+  };
+}
+
+/** The listing bound to one runner: what the composition root hands the setup routes. */
+export function rootFolderListerFor(runner: IGitRunner): typeof listRootFolders {
+  const run = listingRunnerFor(runner);
+  // The bound runner is not a default a caller may override: a `run` in
+  // `deps` would take git back out of the port, deadline and cleanup included.
+  return (listing, deps = {}) => listRootFolders(listing, { ...deps, run });
+}
+
+let defaultRun: GitRunner | undefined;
+/** A runner on default settings, for callers that did not bind one; built once. */
+function runGit(): GitRunner {
+  defaultRun ??= listingRunnerFor(new NodeGitRunner());
+  return defaultRun;
+}
+
+/**
+ * Which branch's root to list: the one the remote calls its trunk, else the
+ * configured one if the remote has it, else the conventional names, else the
+ * first branch it listed — the same order the setup screen guesses in.
+ */
+export function pickListingBranch(
+  remoteDefault: string | null,
+  configured: string | null,
+  branches: string[],
+): string | null {
+  if (remoteDefault) return remoteDefault;
+  if (configured && branches.includes(configured)) return configured;
+  return ['main', 'master', 'trunk'].find((name) => branches.includes(name)) ?? branches[0] ?? null;
+}
+
+/** Per git call. A blob-less clone of one commit is a second or two; this bounds the fallback. */
+const LISTING_TIMEOUT_MS = 30_000;
+
+/** A clone refused because the host cannot filter — worth one retry without the filter. */
+const FILTER_UNSUPPORTED = /filter|partial|not support|unsupported/i;
+
+export interface RootFolderListing {
+  url: string;
+  branch: string;
+  username: string;
+  token: string;
+}
+
+export interface RootFolderListingDeps {
+  run?: GitRunner;
+  makeTempDir?: () => Promise<string>;
+  removeDir?: (dir: string) => Promise<void>;
+}
+
+/**
+ * The top-level folder names of one branch of a remote, or null when they
+ * could not be read.
+ *
+ * `ls-remote` answers with refs only; a folder listing needs the root TREE,
+ * which no transport serves on its own over HTTPS (`git archive --remote` is
+ * refused by GitHub and GitLab alike). So: a clone of exactly one commit with
+ * no blobs and no checkout — trees only, which on a large repository is a
+ * small fraction of it — then `ls-tree` on its root. A host that cannot filter
+ * gets a plain shallow clone of the same commit instead.
+ *
+ * Nothing here can fail the connection check: the credentials were already
+ * proven by `ls-remote`, and a listing that does not come back is reported as
+ * "no listing" (null), not as a broken connection. The scratch clone belongs
+ * to this call and is removed on every path out of it.
+ */
+export async function listRootFolders(
+  { url, branch, username, token }: RootFolderListing,
+  deps: RootFolderListingDeps = {},
+): Promise<string[] | null> {
+  const run = deps.run ?? runGit();
+  const makeTempDir = deps.makeTempDir ?? (() => mkdtemp(path.join(tmpdir(), 'hexis-root-folders-')));
+  const removeDir = deps.removeDir ?? ((dir: string) => rm(dir, { recursive: true, force: true }));
+
+  let scratch: string;
+  try {
+    scratch = await makeTempDir();
+  } catch {
+    return null;
+  }
+  const target = path.join(scratch, 'repo');
+  // The one credential helper every probe uses (see connection-check.ts).
+  const credentials = probeCredentialArgs(username, token);
+  const env = probeGitEnv(token);
+  const clone = (filtered: boolean) =>
+    run(
+      [
+        ...credentials,
+        'clone',
+        '--quiet',
+        '--depth=1',
+        ...(filtered ? ['--filter=blob:none'] : []),
+        '--no-checkout',
+        '--single-branch',
+        // One argv entry: a branch name can never be read as a flag of its own.
+        `--branch=${branch}`,
+        '--end-of-options',
+        url,
+        target,
+      ],
+      { env, timeout: LISTING_TIMEOUT_MS },
+    );
+
+  try {
+    try {
+      await clone(true);
+    } catch (err) {
+      if (!FILTER_UNSUPPORTED.test(errorText(err))) throw err;
+      // Whatever the refused attempt left behind would make the retry's target
+      // a non-empty directory.
+      await removeDir(target);
+      await clone(false);
+    }
+    const { stdout } = await run(
+      ['-C', target, 'ls-tree', '-d', '-z', '--name-only', 'HEAD'],
+      { env, timeout: LISTING_TIMEOUT_MS },
+    );
+    return stdout.split('\0').filter(Boolean);
+  } catch (err) {
+    const text = errorText(err);
+    // Git's error text echoes the remote host's response: token scrubbed, and
+    // escaped so a hostile host cannot forge or colour the log line.
+    log.warn(
+      `could not list the repository root folders: ${printable(
+        (token ? text.replaceAll(token, '***') : text).split('\n')[0]?.slice(0, 200) ?? '',
+      )}`,
+    );
+    return null;
+  } finally {
+    await removeDir(scratch).catch(() => {});
+  }
+}
+
+function errorText(err: unknown): string {
+  if (err instanceof Error) {
+    const stderr = (err as { stderr?: unknown }).stderr;
+    return `${err.message}${typeof stderr === 'string' ? `\n${stderr}` : ''}`;
+  }
+  return String(err);
+}

package/src/modules/settings/oidc-check.ts

@@ -0,0 +1,229 @@
+import { randomBytes } from 'node:crypto';
+
+/** The single sign-on configuration a deployment would sign people in with. */
+export interface OidcConfiguration {
+  issuerUrl: string;
+  clientId: string;
+  clientSecret: string;
+  /** `<PUBLIC_BACKEND_URL>/api/auth/oidc/callback` — what the real callback sends. */
+  redirectUri: string;
+}
+
+/** Which form field a definitive refusal is about — the save reports it against that input. */
+export type OidcField = 'oidcIssuerUrl' | 'oidcClientSecret';
+
+/**
+ * What asking the issuer about its discovery document came to:
+ *
+ *  - `verified`: an OIDC issuer — it published the authorization, token and
+ *    userinfo endpoints the sign-in flow uses;
+ *  - `unreachable`: no discovery document came back — a refused or failed
+ *    request, a non-2xx answer, or an address that is not https;
+ *  - `not-oidc`: a document came back, but not one this flow can sign in with.
+ */
+export type IssuerCheck =
+  | { outcome: 'verified'; tokenEndpoint: string }
+  | { outcome: 'unreachable' | 'not-oidc'; field: 'oidcIssuerUrl'; error: string };
+
+/**
+ * The three answers a configuration can give:
+ *
+ *  - `verified`: the issuer is an OIDC issuer, and its token endpoint accepted
+ *    the application id and secret (it went on to refuse the made-up code);
+ *  - `unverified`: the issuer is fine, but the token endpoint's answer says
+ *    nothing definite about the credentials — saved, labelled Unverified;
+ *  - `rejected`: a definitive no — the issuer (on the issuer field) or the
+ *    credentials (on the secret field).
+ */
+export type OidcCheck =
+  | { outcome: 'verified' }
+  | { outcome: 'unverified'; error: string }
+  | {
+      outcome: 'rejected';
+      reason: 'unreachable' | 'not-oidc' | 'credentials';
+      field: OidcField;
+      error: string;
+    };
+
+/** Bounds each request, so a hung issuer cannot hold a save open. */
+const REQUEST_TIMEOUT_MS = 10_000;
+
+/**
+ * The token endpoint's `error` codes that mean "the client authenticated, and
+ * then the code was refused". `invalid_grant` is the one RFC 6749 §5.2 names
+ * for a bad authorization code, and the one every mainstream provider sends.
+ */
+const CODE_REJECTIONS: readonly string[] = ['invalid_grant'];
+
+/**
+ * The other error codes RFC 6749 §5.2 (and OIDC Core §3.1.2.6) define — the
+ * only ones echoed back in an "unverified" message. Anything else in `error`
+ * is text of the provider's choosing, and could be the secret reflected back.
+ */
+const ECHOED_ERRORS: readonly string[] = [
+  'invalid_request',
+  'unauthorized_client',
+  'unsupported_grant_type',
+  'invalid_scope',
+  'access_denied',
+  'server_error',
+  'temporarily_unavailable',
+];
+
+/** The issuer as the provider appends `/.well-known/...` to it: no trailing slash. */
+export function normalizeIssuerUrl(issuerUrl: string): string {
+  return issuerUrl.trim().replace(/\/+$/, '');
+}
+
+function isHttps(url: string): boolean {
+  try {
+    return new URL(url).protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+const UNREACHABLE = 'The provider address could not be reached — check it and try again.';
+const NOT_OIDC =
+  'That address is not a single sign-on provider — its discovery document is missing the authorization, token or userinfo endpoint.';
+
+/**
+ * Fetch `<issuer>/.well-known/openid-configuration` and say whether it
+ * describes an issuer the sign-in flow can use. Never throws.
+ *
+ * The SAME RULES AS THE SIGN-IN ITSELF (`OidcAuthProvider.discover()`), which
+ * is the point of checking at all: https, redirects followed, and no
+ * address-range guard. The issuer is deployment configuration an admin types,
+ * not a URL anyone else can author, and an identity provider on a private
+ * network (`https://10.0.0.5/…`, `https://sso.corp.internal`) is a first-class
+ * case that signs people in today.
+ */
+export async function checkOidcIssuer(
+  issuerUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<IssuerCheck> {
+  const url = `${normalizeIssuerUrl(issuerUrl)}/.well-known/openid-configuration`;
+  const unreachable = (error = UNREACHABLE): IssuerCheck => ({
+    outcome: 'unreachable',
+    field: 'oidcIssuerUrl',
+    error,
+  });
+  if (!isHttps(url)) return unreachable('The provider address must start with https://.');
+  let doc: Record<string, unknown>;
+  try {
+    const res = await fetchImpl(url, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!res.ok) return unreachable();
+    const body = (await res.json().catch(() => null)) as unknown;
+    if (!body || typeof body !== 'object') {
+      return { outcome: 'not-oidc', field: 'oidcIssuerUrl', error: NOT_OIDC };
+    }
+    doc = body as Record<string, unknown>;
+  } catch {
+    return unreachable();
+  }
+  const endpoint = (key: string) => (typeof doc[key] === 'string' ? (doc[key] as string) : '');
+  if (!endpoint('authorization_endpoint') || !endpoint('token_endpoint') || !endpoint('userinfo_endpoint')) {
+    return { outcome: 'not-oidc', field: 'oidcIssuerUrl', error: NOT_OIDC };
+  }
+  // Never in the clear: the secret is about to be sent to the token endpoint,
+  // and every sign-in sends its access token to the userinfo endpoint. A plain
+  // scheme check — no address-range guard (see above).
+  for (const key of ['token_endpoint', 'userinfo_endpoint'] as const) {
+    if (!isHttps(endpoint(key))) {
+      const name = key === 'token_endpoint' ? 'token' : 'userinfo';
+      return {
+        outcome: 'not-oidc',
+        field: 'oidcIssuerUrl',
+        error: `The provider names a ${name} endpoint that does not use https://.`,
+      };
+    }
+  }
+  return { outcome: 'verified', tokenEndpoint: endpoint('token_endpoint') };
+}
+
+/**
+ * Ask the issuer whether this configuration signs people in: discovery first,
+ * then a token request for an authorization code that does not exist, with the
+ * application id and secret as HTTP Basic and the configured redirect URI —
+ * exactly the shape the real callback sends.
+ *
+ * A provider authenticates the client BEFORE it looks at the code, so its
+ * refusal says which half was wrong: `invalid_client` is the credentials,
+ * `invalid_grant` is the code (and so the credentials passed). Nothing else is
+ * read as an answer either way.
+ *
+ * THE SECRET GOES ONLY TO THE TOKEN ENDPOINT THIS ISSUER PUBLISHES, over
+ * https, with redirects refused so it is never re-sent to a redirect target —
+ * and never into a log line or a returned message: every message here is
+ * fixed text, and the provider's response body is read for its `error` code
+ * alone.
+ *
+ * The ONE function both "Test sign-in configuration" and the settings save
+ * call, so the button can never say "verified" about values the save refuses.
+ * Never throws.
+ */
+export async function checkOidcConfiguration(
+  config: OidcConfiguration,
+  fetchImpl: typeof fetch = fetch,
+): Promise<OidcCheck> {
+  const issuer = await checkOidcIssuer(config.issuerUrl, fetchImpl);
+  if (issuer.outcome !== 'verified') {
+    return { outcome: 'rejected', reason: issuer.outcome, field: issuer.field, error: issuer.error };
+  }
+
+  const basic = Buffer.from(
+    `${encodeURIComponent(config.clientId)}:${encodeURIComponent(config.clientSecret)}`,
+    'utf8',
+  ).toString('base64');
+  let status: number;
+  let errorCode = '';
+  try {
+    const res = await fetchImpl(issuer.tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+        Authorization: `Basic ${basic}`,
+      },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        // Random, so it cannot collide with a code anyone was issued.
+        code: `hexis-configuration-check-${randomBytes(16).toString('hex')}`,
+        redirect_uri: config.redirectUri,
+        // No `code_verifier`: no challenge was ever issued for this code, and
+        // a PKCE-enforcing provider could answer a verifier it cannot match
+        // with something other than the code rejection this reads.
+      }).toString(),
+      redirect: 'error',
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    status = res.status;
+    const body = (await res.json().catch(() => null)) as { error?: unknown } | null;
+    if (body && typeof body.error === 'string') errorCode = body.error;
+  } catch {
+    return {
+      outcome: 'unverified',
+      error: 'The provider’s token endpoint did not answer, so the application ID and secret could not be verified.',
+    };
+  }
+
+  if (errorCode === 'invalid_client') {
+    return {
+      outcome: 'rejected',
+      reason: 'credentials',
+      field: 'oidcClientSecret',
+      error: 'The provider rejected the application ID or secret.',
+    };
+  }
+  if (CODE_REJECTIONS.includes(errorCode)) return { outcome: 'verified' };
+  // Only a standard error code is echoed — anything else could be text of the
+  // provider's choosing, the secret included.
+  const code = ECHOED_ERRORS.includes(errorCode) ? ` (${errorCode})` : ` (HTTP ${status})`;
+  return {
+    outcome: 'unverified',
+    error: `The application ID and secret could not be verified — the provider gave an answer that does not say whether they are right${code}.`,
+  };
+}