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

package/src/modules/marketplace/git-http.routes.ts

@@ -0,0 +1,193 @@
+import express from 'express';
+import { spawn } from 'node:child_process';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import type { MarketplaceRepoService } from './marketplace-repo.service.js';
+import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+
+/** How a bearer string resolves to a user — the connection-key service's shape. */
+export interface MarketplaceKeyResolver {
+  looksLikeExternalApiKey(token: string): boolean;
+  verifyAndLoadToken(plaintext: string): Promise<{ tokenId: string; user: AuthUser } | null>;
+}
+
+/**
+ * The per-user marketplace as a git remote:
+ *
+ *   git clone https://key:<connection-key>@<host>/git/marketplace.git
+ *
+ * Anything that speaks git's smart HTTP protocol — Claude Code, Codex, `npx
+ * skills`, plain git — clones a repository whose `main` is the caller's
+ * compiled tree. The route authenticates, brings the caller's namespace up to
+ * date (`MarketplaceRepoService.ensureCompiled`), and hands the request to
+ * `git http-backend` with `GIT_NAMESPACE` set, so git itself serves the
+ * protocol and only that namespace's refs exist as far as the client can tell.
+ *
+ * AUTH: HTTP Basic with the connection key as the password (the username is
+ * anything — git sends whatever the URL carried), or the key as a Bearer
+ * token. The same keys the MCP endpoint takes, the same service resolving
+ * them, and the same metering stamp (`req.externalApiKeyId`), so a key's
+ * `lastUsedAt` moves when an agent refreshes its plugins. A 401 challenges
+ * with Basic so a client without credentials prompts for them.
+ *
+ * READ-ONLY: the receive-pack service is refused here by name, and the bare
+ * repository pins `http.receivepack=false` for good measure — a push would
+ * otherwise be enabled by http-backend the moment REMOTE_USER is set.
+ */
+export function createMarketplaceGitRoutes(deps: {
+  repo: MarketplaceRepoService;
+  keys: MarketplaceKeyResolver;
+  /** The URL path the router is mounted at, e.g. `/git`. Used for PATH_INFO. */
+  mountPath: string;
+}): express.Router {
+  const { repo, keys, mountPath } = deps;
+  const router = express.Router();
+  const repoRoute = `/${repo.repoName}`;
+
+  const challenge = (res: express.Response, message: string) => {
+    res.setHeader('WWW-Authenticate', 'Basic realm="hexis-marketplace"');
+    res.status(401).type('text/plain').send(message);
+  };
+
+  /** The connection key out of Basic (`user:key`, `key:` or `:key`) or Bearer. */
+  const keyOf = (header: string | undefined): string | null => {
+    if (!header) return null;
+    const space = header.indexOf(' ');
+    if (space < 0) return null;
+    const scheme = header.slice(0, space).toLowerCase();
+    const value = header.slice(space + 1).trim();
+    if (scheme === 'bearer') return value || null;
+    if (scheme !== 'basic') return null;
+    let decoded: string;
+    try {
+      decoded = Buffer.from(value, 'base64').toString('utf-8');
+    } catch {
+      return null;
+    }
+    const colon = decoded.indexOf(':');
+    const user = colon < 0 ? decoded : decoded.slice(0, colon);
+    const pass = colon < 0 ? '' : decoded.slice(colon + 1);
+    // Either half may carry the key: `https://key:<k>@` puts it in the
+    // password, `https://<k>@` in the username.
+    if (pass && keys.looksLikeExternalApiKey(pass)) return pass;
+    if (user && keys.looksLikeExternalApiKey(user)) return user;
+    return pass || user || null;
+  };
+
+  router.all(`${repoRoute}{/*rest}`, async (req, res) => {
+    const service = String(req.query.service ?? '');
+    const rest = `/${([] as string[]).concat((req.params as { rest?: string | string[] }).rest ?? []).join('/')}`;
+    // Refuse writes before touching anything — by service name on info/refs,
+    // and by endpoint on the POST.
+    if (service === 'git-receive-pack' || rest === '/git-receive-pack') {
+      res.status(403).type('text/plain').send('This repository is read-only.');
+      return;
+    }
+
+    const key = keyOf(req.headers.authorization);
+    if (!key || !keys.looksLikeExternalApiKey(key)) {
+      challenge(res, 'A connection key is required: https://key:<connection-key>@<host>/git/marketplace.git');
+      return;
+    }
+    let resolved: { tokenId: string; user: AuthUser } | null;
+    try {
+      resolved = await keys.verifyAndLoadToken(key);
+    } catch (err) {
+      console.error('[marketplace] connection-key verification failed:', err);
+      res.status(500).type('text/plain').send('Authentication backend unavailable');
+      return;
+    }
+    if (!resolved) {
+      challenge(res, 'Invalid or revoked connection key');
+      return;
+    }
+    req.userId = resolved.user.id;
+    req.userEmail = resolved.user.email;
+    req.externalApiKeyId = resolved.tokenId;
+
+    let ensured: { namespace: string };
+    try {
+      ensured = await repo.ensureCompiled({ id: resolved.user.id, email: resolved.user.email });
+    } catch (err) {
+      console.error('[marketplace] compile failed:', err);
+      res.status(500).type('text/plain').send('Could not prepare your marketplace');
+      return;
+    }
+
+    // CGI, as git documents it. PATH_INFO is the path below GIT_PROJECT_ROOT
+    // — `/marketplace.git/info/refs` — regardless of where we are mounted.
+    const query = req.url.includes('?') ? req.url.slice(req.url.indexOf('?') + 1) : '';
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      GIT_PROJECT_ROOT: repo.projectRoot,
+      GIT_HTTP_EXPORT_ALL: '1',
+      GIT_NAMESPACE: ensured.namespace,
+      PATH_INFO: `${repoRoute}${rest}`,
+      REQUEST_METHOD: req.method,
+      QUERY_STRING: query,
+      CONTENT_TYPE: req.headers['content-type'] ?? '',
+      REMOTE_USER: resolved.user.email,
+      REMOTE_ADDR: req.ip ?? '',
+      SERVER_PROTOCOL: 'HTTP/1.1',
+      HTTP_HOST: req.headers.host ?? '',
+      SCRIPT_NAME: mountPath,
+    };
+    if (req.headers['content-length']) env.CONTENT_LENGTH = String(req.headers['content-length']);
+    if (req.headers['content-encoding']) env.HTTP_CONTENT_ENCODING = String(req.headers['content-encoding']);
+    if (req.headers['git-protocol']) env.HTTP_GIT_PROTOCOL = String(req.headers['git-protocol']);
+
+    const child = spawn('git', ['http-backend'], { env, stdio: ['pipe', 'pipe', 'pipe'] });
+    child.stderr.on('data', (chunk: Buffer) => console.warn(`[marketplace] http-backend: ${chunk.toString('utf-8').trim()}`));
+    child.on('error', (err) => {
+      console.error('[marketplace] could not run git http-backend:', err);
+      if (!res.headersSent) res.status(500).type('text/plain').send('git is unavailable');
+    });
+    req.pipe(child.stdin);
+    req.on('aborted', () => child.kill());
+
+    // Parse the CGI header block (`Status:`, `Content-Type:`, …) off stdout,
+    // then stream the body straight through.
+    let headerBuf = Buffer.alloc(0);
+    let headersDone = false;
+    // Backpressure: a slow client must not make Node buffer a whole pack. One
+    // path for every body write, the remainder of the header chunk included.
+    const writeBody = (bytes: Buffer) => {
+      if (!res.write(bytes)) {
+        child.stdout.pause();
+        res.once('drain', () => child.stdout.resume());
+      }
+    };
+    child.stdout.on('data', (chunk: Buffer) => {
+      if (headersDone) {
+        writeBody(chunk);
+        return;
+      }
+      headerBuf = Buffer.concat([headerBuf, chunk]);
+      const cut = headerBuf.indexOf('\r\n\r\n') >= 0 ? headerBuf.indexOf('\r\n\r\n') : headerBuf.indexOf('\n\n');
+      if (cut < 0) return;
+      const sepLen = headerBuf.indexOf('\r\n\r\n') >= 0 ? 4 : 2;
+      const head = headerBuf.subarray(0, cut).toString('utf-8');
+      let status = 200;
+      for (const line of head.split(/\r?\n/)) {
+        const colon = line.indexOf(':');
+        if (colon < 0) continue;
+        const name = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (name.toLowerCase() === 'status') status = Number.parseInt(value, 10) || 200;
+        else res.setHeader(name, value);
+      }
+      res.status(status);
+      headersDone = true;
+      const body = headerBuf.subarray(cut + sepLen);
+      if (body.length > 0) writeBody(body);
+    });
+    child.stdout.on('end', () => {
+      if (!headersDone) {
+        if (!res.headersSent) res.status(502).type('text/plain').send('git http-backend produced no response');
+        return;
+      }
+      res.end();
+    });
+  });
+
+  return router;
+}

package/src/modules/marketplace/github-facade/github-facade-admin.routes.ts

@@ -0,0 +1,78 @@
+import express from 'express';
+import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import {
+  GitHubFacadeUnavailableError,
+  type GitHubFacadeCredentialsService,
+} from './github-facade-credentials.service.js';
+
+export interface GitHubFacadeAdminRoutesDeps {
+  credentials: GitHubFacadeCredentialsService;
+  isAdmin(email: string | undefined): Promise<boolean>;
+  /** The deployment's public address; only its host is shown. */
+  publicUrl: string;
+  /** The marketplace URL people paste — the same one Claude Code clones. */
+  marketplaceUrl: string;
+}
+
+/**
+ * What an Owner needs to register this deployment in Claude's admin settings
+ * as a GitHub Enterprise Server, in the fields that form has — and the one
+ * verb on it, rotate. Admins only: the client secret is what makes claude.ai
+ * trust the token exchange. Never cached: after a rotation or a sign-out no
+ * copy of the old secrets may linger in a browser or a proxy.
+ *
+ *   GET  /api/admin/github-facade          the credentials and the two URLs
+ *   POST /api/admin/github-facade/rotate   new credentials, all of them
+ */
+export function createGitHubFacadeAdminRoutes(deps: GitHubFacadeAdminRoutesDeps): express.Router {
+  const router = express.Router();
+
+  const requireAdmin: express.RequestHandler = async (req, res, next) => {
+    if (!(await deps.isAdmin(req.userEmail))) {
+      res.status(403).json({ error: 'Admins only' });
+      return;
+    }
+    next();
+  };
+
+  const describe = async () => {
+    const creds = await deps.credentials.ensure();
+    return {
+      host: new URL(deps.publicUrl).host,
+      appId: creds.appId,
+      clientId: creds.clientId,
+      clientSecret: creds.clientSecret,
+      webhookSecret: creds.webhookSecret,
+      privateKeyPem: creds.privateKeyPem,
+      marketplaceUrl: deps.marketplaceUrl,
+      createdAt: creds.createdAt.getTime(),
+      rotatedAt: creds.rotatedAt ? creds.rotatedAt.getTime() : null,
+    };
+  };
+
+  const send = async (res: express.Response, body: () => Promise<unknown>) => {
+    try {
+      const payload = await body();
+      res.setHeader('Cache-Control', 'no-store');
+      res.json(payload);
+    } catch (err) {
+      if (err instanceof GitHubFacadeUnavailableError) {
+        res.status(409).json({ error: err.message });
+        return;
+      }
+      console.error('[github-facade admin]', err);
+      res.status(500).json({ error: 'Internal error' });
+    }
+  };
+
+  router.get('/admin/github-facade', requireAdmin, (_req, res) => send(res, describe));
+
+  router.post('/admin/github-facade/rotate', requireAdmin, (_req, res) =>
+    send(res, async () => {
+      await deps.credentials.rotate();
+      return describe();
+    }),
+  );
+
+  return router;
+}

package/src/modules/marketplace/github-facade/github-facade-codes.store.ts

@@ -0,0 +1,145 @@
+import { and, eq, gt, isNull } from 'drizzle-orm';
+import type { Database } from '../../database/connection.js';
+import { githubFacadeCodes } from '../../database/schema.js';
+
+/**
+ * A one-time code the consent page issued, waiting for Anthropic's backend
+ * to exchange it. Looked up by the code's hash; the plaintext travels once,
+ * in the redirect.
+ */
+export interface PendingFacadeCode {
+  codeHash: string;
+  userId: string;
+  clientId: string;
+  redirectUri: string;
+  expiresAt: Date;
+}
+
+/**
+ * Where pending codes live. The database in production, so the consent
+ * finish on one replica and the exchange on another see the same row.
+ *
+ * The rule "one live code per person" is the TABLE'S: the person is its
+ * primary key, so issuing is an upsert — the newest code overwrites the last
+ * in one statement, two finishes racing each other cannot both leave a row
+ * behind, and the table holds at most one row per user, which goes when the
+ * user does. That is the whole bound; nothing here ever sweeps, and no
+ * rotation of the client id can strand a row, because the client id is data
+ * the exchange checks rather than part of the key. Spending is one
+ * conditional update: the first exchange wins, on whichever replica, and
+ * every later attempt finds the code spent. Nothing in memory takes part in
+ * either guarantee.
+ */
+export interface GitHubFacadeCodeStore {
+  /** Store a fresh code, replacing whatever the same person had. */
+  put(code: PendingFacadeCode): Promise<void>;
+  /** The live (unspent, unexpired) code with this hash, without spending it. */
+  peek(codeHash: string): Promise<PendingFacadeCode | null>;
+  /** Spend the code if it is live; null when it was not (unknown, spent, expired). */
+  consume(codeHash: string): Promise<PendingFacadeCode | null>;
+}
+
+export class DbGitHubFacadeCodeStore implements GitHubFacadeCodeStore {
+  constructor(private readonly db: Database) {}
+
+  async put(code: PendingFacadeCode): Promise<void> {
+    const fresh = {
+      clientId: code.clientId,
+      codeHash: code.codeHash,
+      redirectUri: code.redirectUri,
+      expiresAt: code.expiresAt,
+      consumedAt: null,
+      createdAt: new Date(),
+    };
+    await this.db
+      .insert(githubFacadeCodes)
+      .values({ userId: code.userId, ...fresh })
+      .onConflictDoUpdate({ target: githubFacadeCodes.userId, set: fresh });
+  }
+
+  async peek(codeHash: string): Promise<PendingFacadeCode | null> {
+    const [row] = await this.db
+      .select()
+      .from(githubFacadeCodes)
+      .where(live(codeHash))
+      .limit(1);
+    return row ? toPending(row) : null;
+  }
+
+  async consume(codeHash: string): Promise<PendingFacadeCode | null> {
+    const [row] = await this.db
+      .update(githubFacadeCodes)
+      .set({ consumedAt: new Date() })
+      .where(live(codeHash))
+      .returning();
+    return row ? toPending(row) : null;
+  }
+}
+
+/** The one definition of "live": this hash, unspent, unexpired. */
+function live(codeHash: string) {
+  return and(
+    eq(githubFacadeCodes.codeHash, codeHash),
+    isNull(githubFacadeCodes.consumedAt),
+    gt(githubFacadeCodes.expiresAt, new Date()),
+  );
+}
+
+function toPending(row: typeof githubFacadeCodes.$inferSelect): PendingFacadeCode {
+  return {
+    codeHash: row.codeHash,
+    userId: row.userId,
+    clientId: row.clientId,
+    redirectUri: row.redirectUri,
+    expiresAt: row.expiresAt,
+  };
+}
+
+/**
+ * For tests: the same rules over a map keyed the way the table is. Share one
+ * instance to model shared storage. Check-and-mark is synchronous, as the
+ * database's conditional update is atomic: two exchanges of one code cannot
+ * both win here either.
+ */
+export class MemoryGitHubFacadeCodeStore implements GitHubFacadeCodeStore {
+  private readonly rows = new Map<string, PendingFacadeCode & { consumedAt: Date | null }>();
+
+  async put(code: PendingFacadeCode): Promise<void> {
+    this.rows.set(code.userId, { ...code, consumedAt: null });
+  }
+
+  async peek(codeHash: string): Promise<PendingFacadeCode | null> {
+    const row = this.findLive(codeHash);
+    return row ? strip(row) : null;
+  }
+
+  async consume(codeHash: string): Promise<PendingFacadeCode | null> {
+    const row = this.findLive(codeHash);
+    if (!row) return null;
+    row.consumedAt = new Date();
+    return strip(row);
+  }
+
+  /** How many rows the store holds — at most one per person. */
+  get size(): number {
+    return this.rows.size;
+  }
+
+  private findLive(codeHash: string) {
+    const now = Date.now();
+    for (const row of this.rows.values()) {
+      if (row.codeHash === codeHash && row.consumedAt === null && row.expiresAt.getTime() > now) return row;
+    }
+    return null;
+  }
+}
+
+function strip(row: PendingFacadeCode & { consumedAt: Date | null }): PendingFacadeCode {
+  return {
+    codeHash: row.codeHash,
+    userId: row.userId,
+    clientId: row.clientId,
+    redirectUri: row.redirectUri,
+    expiresAt: row.expiresAt,
+  };
+}

package/src/modules/marketplace/github-facade/github-facade-credentials.service.ts

@@ -0,0 +1,208 @@
+import { generateKeyPairSync, randomBytes, randomInt } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import type { Database } from '../../database/connection.js';
+import { githubFacadeIdentity } from '../../database/schema.js';
+import type { TokenCrypto } from '../../../shared/token-crypto.js';
+
+/**
+ * What Claude's "Add manually" form for a GitHub Enterprise Server asks an
+ * Owner to paste, and what the token exchange later checks: the identity
+ * this deployment presents to claude.ai as if it were a GitHub App.
+ *
+ * Every field is generated HERE, once per deployment — nothing is registered
+ * anywhere else, because there is no GitHub: hexis is the host Claude talks
+ * to. The private key is handed over because the form requires one; the
+ * user-added marketplace flow never signs with it (the observed contract is
+ * the OAuth pair plus three REST calls), but a future organization
+ * marketplace would, and rotating everything together is simpler than
+ * explaining which half matters.
+ */
+export interface GitHubFacadeCredentials {
+  appId: string;
+  clientId: string;
+  clientSecret: string;
+  webhookSecret: string;
+  privateKeyPem: string;
+  publicKeyPem: string;
+  createdAt: Date;
+  rotatedAt: Date | null;
+}
+
+/**
+ * Where the one credentials row lives — the database in production, memory
+ * in tests. THE row, not a copy of it: every replica reads the store on
+ * every use, so a rotation on one replica is what every other replica
+ * checks the very next exchange. The reads are rare (a connect, an admin
+ * page), and a cache would be a second source of truth with no invalidation.
+ *
+ * Both writes are conditional, so two replicas writing at once cannot
+ * disagree about what is stored: creation happens only when no row exists,
+ * and a rotation replaces only the set the caller was looking at. Either way
+ * the caller gets back what the store holds afterwards, never what it sent.
+ */
+export interface GitHubFacadeCredentialsStore {
+  load(): Promise<GitHubFacadeCredentials | null>;
+  /**
+   * Store `creds` only if no row exists yet, and return whichever row
+   * exists afterwards — so two replicas initialising at once agree on one
+   * set, and the loser's generated values are simply dropped.
+   */
+  createIfAbsent(creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials>;
+  /**
+   * Replace the row only while it still carries `expectedClientId`, and
+   * return what is stored afterwards. Two admins rotating at once: the first
+   * write wins, the second finds a different client id, writes nothing, and
+   * is shown the winner's set — the only one Claude will accept.
+   */
+  replaceIfCurrent(expectedClientId: string, creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials>;
+}
+
+const ROW_ID = 'default';
+
+/**
+ * The database-backed store. Secrets are sealed with the deployment's secrets
+ * key, exactly as stored settings are; without that key there is nowhere safe
+ * to keep a client secret, so the store refuses rather than writing plaintext.
+ */
+export class DbGitHubFacadeCredentialsStore implements GitHubFacadeCredentialsStore {
+  constructor(
+    private readonly db: Database,
+    private readonly crypto: TokenCrypto | null,
+  ) {}
+
+  async load(): Promise<GitHubFacadeCredentials | null> {
+    const [row] = await this.db
+      .select()
+      .from(githubFacadeIdentity)
+      .where(eq(githubFacadeIdentity.id, ROW_ID))
+      .limit(1);
+    if (!row) return null;
+    const crypto = this.requireCrypto();
+    return {
+      appId: row.appId,
+      clientId: row.clientId,
+      clientSecret: crypto.decrypt(row.clientSecret),
+      webhookSecret: crypto.decrypt(row.webhookSecret),
+      privateKeyPem: crypto.decrypt(row.privateKeyPem),
+      publicKeyPem: row.publicKeyPem,
+      createdAt: row.createdAt,
+      rotatedAt: row.rotatedAt,
+    };
+  }
+
+  async createIfAbsent(creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials> {
+    await this.db
+      .insert(githubFacadeIdentity)
+      .values({ id: ROW_ID, ...this.seal(creds) })
+      .onConflictDoNothing({ target: githubFacadeIdentity.id });
+    return this.stored('insert');
+  }
+
+  async replaceIfCurrent(expectedClientId: string, creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials> {
+    await this.db
+      .update(githubFacadeIdentity)
+      .set(this.seal(creds))
+      .where(and(eq(githubFacadeIdentity.id, ROW_ID), eq(githubFacadeIdentity.clientId, expectedClientId)));
+    return this.stored('replace');
+  }
+
+  private async stored(after: string): Promise<GitHubFacadeCredentials> {
+    const row = await this.load();
+    if (!row) throw new Error(`claude bridge credentials vanished between ${after} and read`);
+    return row;
+  }
+
+  private seal(creds: GitHubFacadeCredentials) {
+    const crypto = this.requireCrypto();
+    return {
+      appId: creds.appId,
+      clientId: creds.clientId,
+      clientSecret: crypto.encrypt(creds.clientSecret),
+      webhookSecret: crypto.encrypt(creds.webhookSecret),
+      privateKeyPem: crypto.encrypt(creds.privateKeyPem),
+      publicKeyPem: creds.publicKeyPem,
+      createdAt: creds.createdAt,
+      rotatedAt: creds.rotatedAt,
+    };
+  }
+
+  private requireCrypto(): TokenCrypto {
+    if (!this.crypto) {
+      throw new GitHubFacadeUnavailableError(
+        'SECRETS_ENC_KEY is not set, so the Claude connection credentials cannot be stored.',
+      );
+    }
+    return this.crypto;
+  }
+}
+
+export class GitHubFacadeUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GitHubFacadeUnavailableError';
+  }
+}
+
+/**
+ * Generates the credentials on first use and reads them from the store on
+ * every use after that. No in-process copy: the store is the one place the
+ * truth lives, whichever replica asks.
+ */
+export class GitHubFacadeCredentialsService {
+  constructor(private readonly store: GitHubFacadeCredentialsStore) {}
+
+  /** The credentials, generated on first use. */
+  async ensure(): Promise<GitHubFacadeCredentials> {
+    const existing = await this.store.load();
+    if (existing) return existing;
+    return this.store.createIfAbsent(generateCredentials(null));
+  }
+
+  /**
+   * New credentials, all of them — replacing the set this call read, and
+   * returning whatever is stored afterwards. Every registration on the
+   * Claude side stops matching at once, which is the point of rotating: the
+   * Owner re-enters the new set, and connected users' tokens (connection
+   * keys) are untouched, since those are ours.
+   */
+  async rotate(): Promise<GitHubFacadeCredentials> {
+    const current = await this.ensure();
+    return this.store.replaceIfCurrent(current.clientId, generateCredentials(current.createdAt));
+  }
+}
+
+function generateCredentials(createdAt: Date | null): GitHubFacadeCredentials {
+  // The shapes GitHub uses, because the form was built for them: a numeric
+  // app id, an `Iv1.`-prefixed client id, hex secrets, a PKCS#1 RSA key.
+  const { privateKey, publicKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    publicKeyEncoding: { type: 'spki', format: 'pem' },
+  });
+  return {
+    appId: String(randomInt(100_000, 999_999)),
+    clientId: `Iv1.${randomBytes(8).toString('hex')}`,
+    clientSecret: randomBytes(20).toString('hex'),
+    webhookSecret: randomBytes(16).toString('hex'),
+    privateKeyPem: privateKey,
+    publicKeyPem: publicKey,
+    createdAt: createdAt ?? new Date(),
+    rotatedAt: createdAt ? new Date() : null,
+  };
+}
+
+/** For tests: the row kept in memory, with the same conditional writes. */
+export class MemoryGitHubFacadeCredentialsStore implements GitHubFacadeCredentialsStore {
+  private row: GitHubFacadeCredentials | null = null;
+  async load(): Promise<GitHubFacadeCredentials | null> {
+    return this.row;
+  }
+  async createIfAbsent(creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials> {
+    this.row ??= creds;
+    return this.row;
+  }
+  async replaceIfCurrent(expectedClientId: string, creds: GitHubFacadeCredentials): Promise<GitHubFacadeCredentials> {
+    if (this.row?.clientId === expectedClientId) this.row = creds;
+    return this.row!;
+  }
+}