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

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

@@ -0,0 +1,263 @@
+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>;
+  /**
+   * When an admin marked the deployment registered with Claude, or null.
+   * Reads the one unsealed column only: answering "is it registered?" must
+   * never decrypt a secret, and must work without the secrets key at all.
+   */
+  registeredAt(): Promise<Date | null>;
+  /** Record (a date) or clear (null) the registration on the existing row. */
+  setRegisteredAt(at: Date | null): Promise<void>;
+}
+
+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');
+  }
+
+  async registeredAt(): Promise<Date | null> {
+    const [row] = await this.db
+      .select({ registeredAt: githubFacadeIdentity.registeredAt })
+      .from(githubFacadeIdentity)
+      .where(eq(githubFacadeIdentity.id, ROW_ID))
+      .limit(1);
+    return row?.registeredAt ?? null;
+  }
+
+  async setRegisteredAt(at: Date | null): Promise<void> {
+    await this.db
+      .update(githubFacadeIdentity)
+      .set({ registeredAt: at })
+      .where(eq(githubFacadeIdentity.id, ROW_ID));
+  }
+
+  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));
+  }
+
+  /**
+   * Whether an admin has said this deployment is registered with their Claude
+   * organization. A boolean and nothing else — this is what every signed-in
+   * person may learn, so the External agent access page can tell them whether
+   * the Cowork route is open yet. No row yet means nobody has even seen the
+   * credentials, so it cannot be registered.
+   */
+  async isRegistered(): Promise<boolean> {
+    return (await this.store.registeredAt()) !== null;
+  }
+
+  /**
+   * Mark the deployment registered (or not). Rotation leaves this alone: it
+   * says the Claude side needs the new values, which is the rotate dialog's
+   * job to tell the admin, not a reason to hide the tutorial from everyone.
+   */
+  async setRegistered(registered: boolean): Promise<boolean> {
+    // The row must exist to carry the flag; registering credentials nobody
+    // generated would describe a registration that cannot have happened.
+    if (registered) await this.ensure();
+    await this.store.setRegisteredAt(registered ? new Date() : null);
+    return this.isRegistered();
+  }
+}
+
+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;
+  private registered: Date | null = null;
+  async load(): Promise<GitHubFacadeCredentials | null> {
+    return this.row;
+  }
+  async registeredAt(): Promise<Date | null> {
+    return this.row ? this.registered : null;
+  }
+  async setRegisteredAt(at: Date | null): Promise<void> {
+    if (this.row) this.registered = at;
+  }
+  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!;
+  }
+}

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

@@ -0,0 +1,294 @@
+import express from 'express';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('github-facade');
+import type { AuthUser } from '@bevel-software/platform-shared';
+import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import type { MarketplaceRepoService } from '../marketplace-repo.service.js';
+import type { MarketplaceKeyResolver } from '../git-http.routes.js';
+import { GitHubFacadeRequestError, type GitHubFacade } from './github-facade.service.js';
+import { printable } from '../../../shared/printable.js';
+
+export interface GitHubFacadeRoutesDeps {
+  facade: GitHubFacade;
+  keys: MarketplaceKeyResolver;
+  repo: MarketplaceRepoService;
+  /**
+   * The owner and name claude.ai derives from the marketplace URL people
+   * paste — the SAME URL Claude Code clones: `https://<host>/git/marketplace.git`
+   * reads as owner `git`, repository `marketplace`. One address for every
+   * Claude surface.
+   */
+  owner: string;
+  repoName: string;
+  /**
+   * The deployment's public address. Only its ORIGIN is ever emitted: a
+   * configured URL may carry userinfo or a path, and neither belongs in a
+   * body handed to a third party.
+   */
+  publicUrl: string;
+}
+
+/**
+ * The GitHub Enterprise surface a consumer (claude.ai, Cowork) talks to when
+ * a person adds this deployment's marketplace from their own settings —
+ * observed call for call against a lookalike host, and nothing beyond it:
+ *
+ *   GET  /login/oauth/authorize        the "connect your account" redirect
+ *   POST /login/oauth/access_token     code → token (our client id + secret)
+ *   GET  /api/v3/repos/:owner/:repo    repository metadata
+ *   GET  …/commits?per_page=1          the head commit — of THIS person's tree
+ *   GET  …/zipball/:ref                that tree, zipped
+ *
+ * Mounted at the app root, ahead of the SPA and the `/api` JWT mounts: the
+ * first two are hit by a bare browser and by Anthropic's backend, the rest
+ * carry the person's token as a Bearer. The token is a connection key, so a
+ * revoked link fails here the same way it fails on the git remote.
+ *
+ * Errors are GitHub-shaped too (`{ message }`, and the OAuth error body on
+ * the token endpoint, in whichever encoding the client negotiated): the
+ * caller is a GitHub client and reads them as one.
+ */
+export function createGitHubFacadeRoutes(deps: GitHubFacadeRoutesDeps): express.Router {
+  const router = express.Router();
+  const { facade, keys, repo, owner, repoName } = deps;
+  const origin = new URL(deps.publicUrl).origin;
+  const fullName = `${owner}/${repoName}`;
+
+  // Every refusal on the connect flow is logged with its reason: the
+  // consumer's backend swallows our answer, so a person who "connected and
+  // came back to Claude" with nothing to show for it has only this log to
+  // say which hop failed. Reasons name a check, never a secret or a code;
+  // what the caller sent (its user agent) is rendered printable, so the
+  // caller cannot write a line of its own.
+  const refused = (req: express.Request, hop: string, err: GitHubFacadeRequestError) => {
+    log.warn(`${hop} refused (${err.status} ${err.code}): ${err.detail} — from ${userAgentOf(req)}`);
+  };
+
+  router.get('/login/oauth/authorize', async (req, res) => {
+    try {
+      res.redirect(302, await facade.authorizeRedirect(req.query as Record<string, unknown>));
+    } catch (err) {
+      if (err instanceof GitHubFacadeRequestError) refused(req, 'authorize', err);
+      answerError(res, err);
+    }
+  });
+
+  // GitHub's token endpoint takes JSON or a form and answers in the shape
+  // `Accept` asks for — success and failure alike; claude.ai sends JSON and
+  // asks for JSON.
+  router.post(
+    '/login/oauth/access_token',
+    express.json({ limit: '16kb' }),
+    express.urlencoded({ extended: false, limit: '16kb' }),
+    async (req, res) => {
+      try {
+        negotiated(req, res, 200, await facade.exchangeCode((req.body ?? {}) as Record<string, unknown>));
+      } catch (err) {
+        if (err instanceof GitHubFacadeRequestError) {
+          refused(req, 'token exchange', err);
+          negotiated(req, res, err.status, { error: err.code, error_description: err.message });
+          return;
+        }
+        answerError(res, err);
+      }
+    },
+  );
+
+  // --- the REST API, as far as the observed contract goes ---------------------
+
+  const api = express.Router();
+
+  api.use(async (req, res, next) => {
+    const token = bearerOf(req);
+    if (!token || !keys.looksLikeExternalApiKey(token)) {
+      unauthorized(req, res, token ? 'bearer is not a connection key' : 'no bearer');
+      return;
+    }
+    let resolved: { tokenId: string; user: AuthUser } | null;
+    try {
+      resolved = await keys.verifyAndLoadToken(token);
+    } catch (err) {
+      log.error('key verification failed:', { err });
+      res.status(500).json({ message: 'Authentication backend unavailable' });
+      return;
+    }
+    if (!resolved) {
+      unauthorized(req, res, 'connection key unknown or revoked');
+      return;
+    }
+    req.userId = resolved.user.id;
+    req.userEmail = resolved.user.email;
+    req.externalApiKeyId = resolved.tokenId;
+    next();
+  });
+
+  const isOurs = (req: express.Request) => req.params.owner === owner && req.params.repo === repoName;
+  const notFound = (res: express.Response) => res.status(404).json({ message: 'Not Found' });
+
+  api.get('/repos/:owner/:repo', (req, res) => {
+    if (!isOurs(req)) return void notFound(res);
+    res.json(repositoryBody(fullName, owner, repoName, origin));
+  });
+
+  api.get('/repos/:owner/:repo/commits', async (req, res) => {
+    if (!isOurs(req)) return void notFound(res);
+    try {
+      const { sha } = await repo.headFor({ id: req.userId!, email: req.userEmail! });
+      const commit = await repo.describeCommit(sha);
+      res.json([commitBody(commit, fullName, origin)]);
+    } catch (err) {
+      answerError(res, err);
+    }
+  });
+
+  api.get('/repos/:owner/:repo/zipball/:ref', async (req, res) => {
+    if (!isOurs(req)) return void notFound(res);
+    try {
+      const { namespace, sha: head } = await repo.headFor({ id: req.userId!, email: req.userEmail! });
+      const ref = req.params.ref;
+      // Only THIS person's tree, at its head or a commit behind it: the object
+      // store is shared across everyone, so a sha alone must never be enough
+      // to read a tree compiled for someone else.
+      const sha = ref === 'HEAD' || ref === 'main' ? head : ref;
+      if (!(await repo.contains(namespace, sha))) return void notFound(res);
+      res.status(200);
+      res.setHeader('Content-Type', 'application/zip');
+      res.setHeader('Content-Disposition', `attachment; filename=${owner}-${repoName}-${sha.slice(0, 7)}.zip`);
+      const archive = repo.archiveZip(sha, `${owner}-${repoName}-${sha.slice(0, 7)}`);
+      const stderr: Buffer[] = [];
+      archive.stderr?.on('data', (chunk: Buffer) => stderr.push(chunk));
+      const fail = (reason: string) => {
+        log.error(`zipball ${sha.slice(0, 7)} failed: ${reason}`);
+        // Headers are already out once the stream started; the only honest
+        // answer then is a cut connection, which the client sees as a failed
+        // download rather than a truncated archive it might unpack.
+        if (!res.headersSent) res.status(500).json({ message: 'Archive failed' });
+        else res.destroy();
+      };
+      archive.on('error', (err: Error) => fail(err.message));
+      // A client that goes away mid-download must not leave git running —
+      // and that kill is the ONE signal exit that is not a failure: git dying
+      // to any other signal left a truncated archive on the wire.
+      let stopped = false;
+      const stop = () => {
+        if (archive.exitCode === null && !archive.killed) {
+          stopped = true;
+          archive.kill();
+        }
+      };
+      archive.on('close', (code, signal) => {
+        if (code === 0 || stopped) return;
+        fail(`git archive exited ${code ?? `on ${signal}`}: ${Buffer.concat(stderr).toString().trim()}`);
+      });
+      req.on('aborted', stop);
+      res.on('close', stop);
+      archive.stdout!.pipe(res);
+    } catch (err) {
+      answerError(res, err);
+    }
+  });
+
+  api.use((_req, res) => notFound(res));
+  router.use('/api/v3', api);
+
+  return router;
+}
+
+function bearerOf(req: express.Request): string | null {
+  const header = req.headers.authorization;
+  if (!header) return null;
+  const [scheme, ...rest] = header.split(' ');
+  if (!scheme || !/^(bearer|token)$/i.test(scheme)) return null;
+  return rest.join(' ').trim() || null;
+}
+
+/** GitHub's 401 — and a log line saying why, since the consumer's backend will not. */
+function unauthorized(req: express.Request, res: express.Response, why: string): void {
+  // The PATH, never the full URL: a query string is the caller's to fill,
+  // and a credential put there would otherwise land in the log.
+  log.warn(`${req.method} ${printable(req.path)} refused: ${why} — from ${userAgentOf(req)}`);
+  res.setHeader('WWW-Authenticate', 'Bearer realm="hexis-marketplace"');
+  res.status(401).json({ message: 'Bad credentials' });
+}
+
+/** The caller's user agent as one printable token — it is theirs to fill with anything. */
+function userAgentOf(req: express.Request): string {
+  const ua = req.headers['user-agent'];
+  return ua ? printable(ua) : 'no user-agent';
+}
+
+/** The token endpoint's reply, in the encoding the client asked for. */
+function negotiated(
+  req: express.Request,
+  res: express.Response,
+  status: number,
+  payload: Record<string, string>,
+): void {
+  const accept = req.headers.accept ?? '';
+  const wantsForm = accept.includes('application/x-www-form-urlencoded') && !accept.includes('json');
+  res.status(status);
+  if (wantsForm) {
+    res.type('application/x-www-form-urlencoded').send(new URLSearchParams(payload).toString());
+    return;
+  }
+  res.json(payload);
+}
+
+function answerError(res: express.Response, err: unknown): void {
+  if (err instanceof GitHubFacadeRequestError) {
+    res.status(err.status).json({ message: err.message });
+    return;
+  }
+  log.error('request failed:', { err });
+  res.status(500).json({ message: 'Internal error' });
+}
+
+/** A repository as GitHub describes one — the fields a marketplace sync reads. */
+function repositoryBody(fullName: string, owner: string, name: string, origin: string) {
+  const html = `${origin}/${fullName}`;
+  return {
+    id: 1,
+    node_id: 'R_hexis_marketplace',
+    name,
+    full_name: fullName,
+    private: true,
+    owner: { login: owner, id: 1, type: 'Organization' },
+    html_url: html,
+    description: 'The skills you may read, compiled as native plugins.',
+    fork: false,
+    url: `${origin}/api/v3/repos/${fullName}`,
+    clone_url: `${html}.git`,
+    default_branch: 'main',
+    visibility: 'private',
+    archived: false,
+    disabled: false,
+    permissions: { admin: false, maintain: false, push: false, triage: false, pull: true },
+  };
+}
+
+function commitBody(
+  commit: { sha: string; message: string; authorName: string; authorEmail: string; date: string; tree: string },
+  fullName: string,
+  origin: string,
+) {
+  const base = `${origin}/api/v3/repos/${fullName}`;
+  const who = { name: commit.authorName, email: commit.authorEmail, date: commit.date };
+  return {
+    sha: commit.sha,
+    node_id: `C_${commit.sha}`,
+    commit: {
+      author: who,
+      committer: who,
+      message: commit.message,
+      tree: { sha: commit.tree, url: `${base}/git/trees/${commit.tree}` },
+      comment_count: 0,
+    },
+    url: `${base}/commits/${commit.sha}`,
+    html_url: `${origin}/${fullName}/commit/${commit.sha}`,
+    author: null,
+    committer: null,
+    parents: [],
+  };
+}