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

package/src/modules/marketplace/__tests__/marketplace-git.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import express from 'express';
+import type { AuthUser } from '@bevel-software/platform-shared';
+
+import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
+import { createMarketplaceGitRoutes } from '../git-http.routes.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import type { VirtualTree } from '../../plugins/compile/compile-marketplace.js';
+
+const execFileAsync = promisify(execFile);
+// No credential helper and no prompt: a 401 must FAIL the command, not open
+// the OS credential manager (which would hang the test on Windows). No
+// autocrlf either, so the bytes the server sent are the bytes we read back.
+const git = (args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) =>
+  execFileAsync('git', ['-c', 'credential.helper=', '-c', 'core.autocrlf=false', ...args], {
+    cwd: opts.cwd,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_ASKPASS: 'echo', ...opts.env },
+  });
+
+/**
+ * The marketplace as a git remote, driven the way a client drives it: real
+ * `git clone` and `git pull` over HTTP against the express router, with a
+ * stub compiler standing in for the knowledge base. What is under test is
+ * the namespace isolation, the fast-forward contract, the auth, and the
+ * read-only guarantee — not the compiler.
+ */
+
+const users: Record<string, AuthUser> = {
+  'bevel_alice': { id: 'user-alice', email: 'alice@x.io', name: 'Alice' } as AuthUser,
+  'bevel_bob': { id: 'user-bob', email: 'bob@x.io', name: 'Bob' } as AuthUser,
+};
+
+function tree(files: Record<string, string>, sourceCommit: string): VirtualTree & { sourceCommit: string } {
+  return {
+    files: new Map(Object.entries(files).map(([k, v]) => [k, Buffer.from(v)])),
+    warnings: [],
+    plugins: [],
+    sourceCommit,
+  };
+}
+
+describe('marketplace git endpoint', () => {
+  let root: string;
+  let repo: MarketplaceRepoService;
+  let server: http.Server;
+  let base: string;
+  /** What the "knowledge base" currently is, per user. */
+  let source = 'aaa111';
+  let trees: Record<string, Record<string, string>>;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-mp-'));
+    source = 'aaa111';
+    trees = {
+      'alice@x.io': { 'README.md': 'alice v1\n', 'plugins/gtm/skills/deploy/SKILL.md': '---\n---\nship\n' },
+      'bob@x.io': { 'README.md': 'bob v1\n' },
+    };
+    const compiler: MarketplaceCompiler = {
+      sourceCommit: async () => source,
+      compileFor: async ({ userEmail }) => tree(trees[userEmail] ?? {}, source),
+    };
+    repo = new MarketplaceRepoService(path.join(root, 'data', 'marketplace.git'), compiler, new NodeGitRunner());
+    const app = express();
+    app.use(
+      '/git',
+      createMarketplaceGitRoutes({
+        repo,
+        keys: {
+          looksLikeExternalApiKey: (t) => t.startsWith('bevel_'),
+          verifyAndLoadToken: async (t) => (users[t] ? { tokenId: `tok-${t}`, user: users[t] } : null),
+        },
+        mountPath: '/git',
+      }),
+    );
+    server = await new Promise<http.Server>((resolve) => {
+      const s = app.listen(0, '127.0.0.1', () => resolve(s));
+    });
+    const { port } = server.address() as { port: number };
+    base = `http://127.0.0.1:${port}/git/marketplace.git`;
+  });
+  afterEach(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  const withKey = (key: string) => base.replace('http://', `http://key:${key}@`);
+  const clone = async (key: string, dir: string) => git(['clone', '--quiet', withKey(key), dir]);
+  const read = (dir: string, rel: string) => fs.readFile(path.join(dir, rel), 'utf-8');
+
+  it('clones each caller their own tree, and nothing of anyone else\'s', async () => {
+    const a = path.join(root, 'alice');
+    const b = path.join(root, 'bob');
+    await clone('bevel_alice', a);
+    await clone('bevel_bob', b);
+    expect(await read(a, 'README.md')).toBe('alice v1\n');
+    expect(await read(a, 'plugins/gtm/skills/deploy/SKILL.md')).toContain('ship');
+    expect(await read(b, 'README.md')).toBe('bob v1\n');
+    await expect(read(b, 'plugins/gtm/skills/deploy/SKILL.md')).rejects.toThrow();
+    // One object store underneath: both namespaces live in the same bare repo.
+    const { stdout } = await git(['-C', repo.repoDir, 'for-each-ref', '--format=%(refname)', 'refs/namespaces/']);
+    // Each namespace carries a HEAD symref beside its branch; the branches are the point.
+    expect(stdout.split('\n').filter((r) => r.endsWith('/refs/heads/main')).sort()).toEqual([
+      'refs/namespaces/u-user-alice/refs/heads/main',
+      'refs/namespaces/u-user-bob/refs/heads/main',
+    ]);
+  });
+
+  it('pulls fast-forward after the knowledge base moves, and does not recompile when it has not', async () => {
+    const a = path.join(root, 'alice');
+    await clone('bevel_alice', a);
+    const first = (await git(['-C', a, 'rev-parse', 'HEAD'])).stdout.trim();
+
+    // Same source: a pull is a no-op with the same head.
+    expect((await repo.ensureCompiled({ id: 'user-alice', email: 'alice@x.io' })).compiled).toBe(false);
+    await git(['-C', a, 'pull', '--quiet', '--ff-only']);
+    expect((await git(['-C', a, 'rev-parse', 'HEAD'])).stdout.trim()).toBe(first);
+
+    // The KB moves and access is withdrawn from the skill: one new commit,
+    // the file is gone, and the pull is still a fast-forward.
+    source = 'bbb222';
+    trees['alice@x.io'] = { 'README.md': 'alice v2\n' };
+    await git(['-C', a, 'pull', '--quiet', '--ff-only']);
+    expect(await read(a, 'README.md')).toBe('alice v2\n');
+    await expect(read(a, 'plugins/gtm/skills/deploy/SKILL.md')).rejects.toThrow();
+    const log = (await git(['-C', a, 'log', '--format=%s'])).stdout.trim().split('\n');
+    expect(log).toEqual(['Compile marketplace from bbb222', 'Compile marketplace from aaa111']);
+  });
+
+  it('restores a namespace HEAD lost between the branch update and the symref — on the unchanged path', async () => {
+    await repo.ensureCompiled({ id: 'user-alice', email: 'alice@x.io' });
+    const head = 'refs/namespaces/u-user-alice/HEAD';
+    await git(['-C', repo.repoDir, 'symbolic-ref', '--delete', head]);
+    await expect(git(['-C', repo.repoDir, 'symbolic-ref', head])).rejects.toThrow();
+    // Same source, same tree: nothing to compile — and still a served namespace.
+    expect((await repo.ensureCompiled({ id: 'user-alice', email: 'alice@x.io' })).compiled).toBe(false);
+    expect((await git(['-C', repo.repoDir, 'symbolic-ref', head])).stdout.trim()).toBe(
+      'refs/namespaces/u-user-alice/refs/heads/main',
+    );
+    const a = path.join(root, 'alice-again');
+    await clone('bevel_alice', a);
+    expect(await read(a, 'README.md')).toBe('alice v1\n');
+  });
+
+  it('a moved source with an identical tree writes no new commit', async () => {
+    const a = path.join(root, 'alice');
+    await clone('bevel_alice', a);
+    source = 'ccc333';
+    const r = await repo.ensureCompiled({ id: 'user-alice', email: 'alice@x.io' });
+    expect(r.compiled).toBe(false);
+    await git(['-C', a, 'pull', '--quiet', '--ff-only']);
+    expect((await git(['-C', a, 'log', '--format=%s'])).stdout.trim().split('\n')).toHaveLength(1);
+  });
+
+  it('refuses a missing or unknown key with a Basic challenge, and refuses pushes', { timeout: 60_000 }, async () => {
+    await expect(git(['clone', '--quiet', base, path.join(root, 'anon')])).rejects.toThrow();
+    await expect(git(['clone', '--quiet', withKey('bevel_nobody'), path.join(root, 'bad')])).rejects.toThrow();
+    const res = await fetch(`${base}/info/refs?service=git-upload-pack`);
+    expect(res.status).toBe(401);
+    expect(res.headers.get('www-authenticate')).toContain('Basic');
+
+    const a = path.join(root, 'alice');
+    await clone('bevel_alice', a);
+    await fs.writeFile(path.join(a, 'evil.md'), 'no');
+    await git(['-C', a, 'add', 'evil.md']);
+    await git(['-C', a, 'commit', '--quiet', '-m', 'push attempt'], {
+      env: { GIT_AUTHOR_NAME: 'x', GIT_AUTHOR_EMAIL: 'x@x', GIT_COMMITTER_NAME: 'x', GIT_COMMITTER_EMAIL: 'x@x' },
+    });
+    await expect(git(['-C', a, 'push', '--quiet', 'origin', 'HEAD:main'])).rejects.toThrow();
+    const push = await fetch(`${base}/info/refs?service=git-receive-pack`, {
+      headers: { authorization: `Basic ${Buffer.from('key:bevel_alice').toString('base64')}` },
+    });
+    expect(push.status).toBe(403);
+  });
+});

package/src/modules/marketplace/__tests__/marketplace-repo.head.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
+import { GitRunError, type IGitRunner } from '../../../shared/git.contract.js';
+
+const SHA = 'a'.repeat(40);
+
+/** A runner whose `rev-parse` fails the way `failure` says; everything else succeeds empty. */
+function runnerFailingRevParse(failure: GitRunError): IGitRunner {
+  return {
+    defaultTimeoutMs: 1_000,
+    run: (async (_cwd: string, args: string[]) => {
+      if (args.includes('rev-parse')) throw failure;
+      return { stdout: '', stderr: '' };
+    }) as IGitRunner['run'],
+  };
+}
+
+const compiler: MarketplaceCompiler = {
+  sourceCommit: async () => 'aaa111',
+  compileFor: async () => ({ files: new Map(), warnings: [], plugins: [], sourceCommit: 'aaa111' }),
+};
+
+/**
+ * "No such ref" is the one git answer a missing namespace head stands for,
+ * and `rev-parse --verify --quiet` gives it as exit code 1 and nothing else.
+ * Every other failure — a deadline, a repository git cannot open — is not an
+ * answer about the ref, and read as "no head" it would have the service start
+ * a namespace's history over on top of the one it has.
+ */
+describe('MarketplaceRepoService — a namespace head that cannot be read', () => {
+  it('reads exit code 1 as "no head": a commit is then simply not contained', async () => {
+    const svc = new MarketplaceRepoService('/nowhere/marketplace.git', compiler, runnerFailingRevParse(
+      new GitRunError('fatal: Needed a single revision', { exitCode: 1 }),
+    ));
+    expect(await svc.contains('user-alice', SHA)).toBe(false);
+  });
+
+  it('lets any other failure through — a deadline is not an answer about the ref', async () => {
+    for (const failure of [
+      new GitRunError('git timed out', { timedOut: true }),
+      new GitRunError('fatal: not a git repository', { exitCode: 128 }),
+    ]) {
+      const svc = new MarketplaceRepoService('/nowhere/marketplace.git', compiler, runnerFailingRevParse(failure));
+      await expect(svc.contains('user-alice', SHA)).rejects.toBe(failure);
+    }
+  });
+});

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

@@ -0,0 +1,196 @@
+import express from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('marketplace');
+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) {
+      log.error('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) {
+      log.error('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) => log.warn(`http-backend: ${chunk.toString('utf-8').trim()}`));
+    child.on('error', (err) => {
+      log.error('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,110 @@
+import express from 'express';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('github-facade');
+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
+ *   PUT  /api/admin/github-facade/registration  `{ registered }` — an admin says so
+ *
+ * And one read that is NOT admin-only, because the External agent access page
+ * shows every signed-in person either the tutorial or "an admin has to set
+ * this up first":
+ *
+ *   GET  /api/github-facade/registration        `{ registered: boolean }`, nothing else
+ *
+ * That answer is built from a boolean, never from the credentials object, so
+ * no future field on the credentials can ride along into it.
+ */
+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;
+      }
+      log.error('admin route failed:', { 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();
+    }),
+  );
+
+  router.get('/github-facade/registration', (req, res) => {
+    // Mounted behind the session middleware; this is belt and braces for a
+    // mount that forgets it — anonymous callers learn nothing.
+    if (!req.userId) {
+      res.status(401).json({ error: 'Sign in first' });
+      return;
+    }
+    return send(res, async () => ({ registered: await deps.credentials.isRegistered() }));
+  });
+
+  router.put('/admin/github-facade/registration', requireAdmin, (req, res) => {
+    const registered = (req.body as { registered?: unknown } | undefined)?.registered;
+    if (typeof registered !== 'boolean') {
+      res.status(400).json({ error: '`registered` must be true or false' });
+      return;
+    }
+    return send(res, async () => ({ registered: await deps.credentials.setRegistered(registered) }));
+  });
+
+  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,
+  };
+}