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

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

@@ -0,0 +1,268 @@
+import express from 'express';
+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';
+
+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}`;
+
+  router.get('/login/oauth/authorize', async (req, res) => {
+    try {
+      res.redirect(302, await facade.authorizeRedirect(req.query as Record<string, unknown>));
+    } catch (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) {
+          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(res);
+      return;
+    }
+    let resolved: { tokenId: string; user: AuthUser } | null;
+    try {
+      resolved = await keys.verifyAndLoadToken(token);
+    } catch (err) {
+      console.error('[github-facade] key verification failed:', err);
+      res.status(500).json({ message: 'Authentication backend unavailable' });
+      return;
+    }
+    if (!resolved) {
+      unauthorized(res);
+      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) => {
+        console.error(`[github-facade] 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;
+}
+
+function unauthorized(res: express.Response): void {
+  res.setHeader('WWW-Authenticate', 'Bearer realm="hexis-marketplace"');
+  res.status(401).json({ message: 'Bad credentials' });
+}
+
+/** 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;
+  }
+  console.error('[github-facade]', 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: [],
+  };
+}

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

@@ -0,0 +1,221 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import type { MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
+import { signAuthRequest, type McpAuthRequestState } from '../../mcp/oauth/oauth-state.js';
+import type { GitHubFacadeCredentialsService } from './github-facade-credentials.service.js';
+import type { GitHubFacadeCodeStore } from './github-facade-codes.store.js';
+
+/**
+ * The KIND stored on a connection key minted through the facade, and the
+ * plaintext prefix that kind is minted with. `gho_` is what a GitHub OAuth
+ * token looks like — the shape a consumer expecting a GitHub Enterprise host
+ * accepts; the key is otherwise an ordinary connection key — hashed at rest,
+ * revocable from the person's external-agent page, accepted by every surface
+ * a connection key is. The kind, not the label, is what tells such a key
+ * apart: a label is the person's to edit.
+ */
+export const GITHUB_LINK_KEY_KIND = 'github-link';
+export const GITHUB_LINK_KEY_PREFIX = 'gho_';
+
+/**
+ * A product that talks to this deployment as if it were a GitHub Enterprise
+ * Server. The facade itself is consumer-neutral — GitHub's OAuth pair and
+ * REST subset are the contract — and a consumer is the one thing that is not:
+ * where its callback lives (the only place a code may be sent), what the
+ * consent page calls it, and how the keys it holds are labelled for the
+ * person. Claude is the first; another product with a "connect your GitHub
+ * Enterprise" flow is one more entry, not one more module.
+ */
+export interface GitHubFacadeConsumer {
+  id: string;
+  /** What the consent page says is asking. */
+  name: string;
+  /** Hostnames a redirect_uri may point at. */
+  redirectHosts: readonly string[];
+  /** The label on the connection keys minted for this consumer. */
+  keyLabel: string;
+}
+
+/** claude.ai and Cowork: the consumer this facade was built against. */
+export const CLAUDE_CONSUMER: GitHubFacadeConsumer = {
+  id: 'claude',
+  name: 'Claude',
+  redirectHosts: ['claude.ai'],
+  keyLabel: 'Claude (claude.ai and Cowork)',
+};
+
+const CODE_TTL_MS = 10 * 60_000;
+const CODE_BYTES = 10;
+
+export interface GitHubFacadeKeyMinter {
+  mint(userId: string, label: string, options?: { kind?: string }): Promise<MintedExternalApiKey>;
+}
+
+export interface GitHubFacadeDeps {
+  credentials: GitHubFacadeCredentialsService;
+  codes: GitHubFacadeCodeStore;
+  keys: GitHubFacadeKeyMinter;
+  /** Who may connect through the facade. */
+  consumers: readonly GitHubFacadeConsumer[];
+  /** HMAC secret for the signed authorize state — the same one the MCP flow uses. */
+  stateSecret: string;
+  /** SPA base URL — where the browser is sent to sign in and approve. */
+  publicFrontendUrl: string;
+}
+
+export class GitHubFacadeRequestError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'GitHubFacadeRequestError';
+  }
+}
+
+/**
+ * The "connect your GitHub Enterprise account" flow, as a consumer such as claude.ai drives it
+ * against a GitHub Enterprise host — with hexis standing where GitHub would.
+ *
+ *   1. The browser lands on `/login/oauth/authorize?client_id&redirect_uri&state`.
+ *      We check the client id is ours and the redirect goes to claude.ai,
+ *      pack the request into the SAME signed state the MCP authorization
+ *      flow uses, and send the browser to the SPA's `/connect` page — where a
+ *      hexis session (or a sign-in) attaches a person to the request.
+ *   2. Finish on that page comes back through the consent routes with the
+ *      state; {@link completeConsent} stores a one-time code bound to that
+ *      person and returns the callback URL carrying it.
+ *   3. Anthropic's backend posts the code with our client id and secret to
+ *      `/login/oauth/access_token`; {@link exchangeCode} turns it into a
+ *      connection key for that person — the token every later fetch carries.
+ *
+ * Nothing here is remembered in the process: credentials and codes are read
+ * from their stores on every step, so the replica that issued a code and the
+ * replica that exchanges it need not be the same one.
+ */
+export class GitHubFacade {
+  constructor(private readonly deps: GitHubFacadeDeps) {}
+
+  /** Where to send the browser for an authorize request, or a 4xx to answer with. */
+  async authorizeRedirect(query: Record<string, unknown>): Promise<string> {
+    const clientId = str(query.client_id);
+    const redirectUri = str(query.redirect_uri);
+    const state = str(query.state);
+    const creds = await this.deps.credentials.ensure();
+    if (!clientId || !safeEqual(clientId, creds.clientId)) {
+      throw new GitHubFacadeRequestError(400, 'unknown_client', 'Unknown client_id.');
+    }
+    if (!this.consumerFor(redirectUri)) {
+      throw new GitHubFacadeRequestError(400, 'invalid_redirect', 'redirect_uri does not belong to a known consumer.');
+    }
+    const signed = signAuthRequest(this.deps.stateSecret, {
+      c: clientId,
+      r: redirectUri,
+      s: state || undefined,
+      gh: true,
+    });
+    const url = new URL('/connect', this.deps.publicFrontendUrl);
+    url.searchParams.set('oauth', signed);
+    return url.toString();
+  }
+
+  /** True when a verified state is one of ours (a GitHub-shaped link, not an MCP client). */
+  isFacadeRequest(st: McpAuthRequestState): boolean {
+    return st.gh === true;
+  }
+
+  /** What the consent page should say is asking, for one of our states. */
+  clientNameFor(st: McpAuthRequestState): string {
+    return this.consumerFor(st.r)?.name ?? 'an external product';
+  }
+
+  /**
+   * The person approved on `/connect`: a one-time code for them, and the
+   * claude.ai callback to send the browser to. Supersedes any live code the
+   * same person already had for this client.
+   */
+  async completeConsent(userId: string, st: McpAuthRequestState): Promise<{ redirectTo: string }> {
+    const creds = await this.deps.credentials.ensure();
+    if (!safeEqual(st.c, creds.clientId) || !this.consumerFor(st.r)) {
+      throw new GitHubFacadeRequestError(400, 'invalid_request', 'The authorization request is not one of ours.');
+    }
+    const code = randomBytes(CODE_BYTES).toString('hex');
+    await this.deps.codes.put({
+      codeHash: hashCode(code),
+      userId,
+      clientId: st.c,
+      redirectUri: st.r,
+      expiresAt: new Date(Date.now() + CODE_TTL_MS),
+    });
+    const url = new URL(st.r);
+    url.searchParams.set('code', code);
+    if (st.s) url.searchParams.set('state', st.s);
+    return { redirectTo: url.toString() };
+  }
+
+  /**
+   * The token exchange. Client id and secret must be ours and the code live;
+   * every check runs BEFORE the code is spent, so a request that is wrong
+   * about something else (its redirect, say) can be corrected and retried.
+   * Spending is one conditional update in the store — the first exchange
+   * wins, on whichever replica, and only the winner mints.
+   */
+  async exchangeCode(body: Record<string, unknown>): Promise<{
+    access_token: string;
+    token_type: 'bearer';
+    scope: '';
+  }> {
+    const creds = await this.deps.credentials.ensure();
+    const clientId = str(body.client_id);
+    const clientSecret = str(body.client_secret);
+    const code = str(body.code);
+    if (!clientId || !clientSecret || !safeEqual(clientId, creds.clientId) || !safeEqual(clientSecret, creds.clientSecret)) {
+      throw new GitHubFacadeRequestError(401, 'incorrect_client_credentials', 'The client_id and/or client_secret passed are incorrect.');
+    }
+    const pending = code ? await this.deps.codes.peek(hashCode(code)) : null;
+    if (!pending || pending.clientId !== clientId) {
+      throw new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.');
+    }
+    const redirectUri = str(body.redirect_uri);
+    if (redirectUri && redirectUri !== pending.redirectUri) {
+      throw new GitHubFacadeRequestError(400, 'redirect_uri_mismatch', 'The redirect_uri does not match the authorization.');
+    }
+    const spent = await this.deps.codes.consume(pending.codeHash);
+    if (!spent) {
+      throw new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.');
+    }
+    // The consumer is the one the code was issued for — the redirect the
+    // person approved names it — so the key is labelled for that product.
+    const consumer = this.consumerFor(spent.redirectUri);
+    const minted = await this.deps.keys.mint(spent.userId, consumer?.keyLabel ?? 'GitHub-compatible link', {
+      kind: GITHUB_LINK_KEY_KIND,
+    });
+    return { access_token: minted.plaintext, token_type: 'bearer', scope: '' };
+  }
+
+  /** The consumer whose callback a redirect_uri is, or null — https only, host exactly. */
+  private consumerFor(redirectUri: string): GitHubFacadeConsumer | null {
+    let parsed: URL;
+    try {
+      parsed = new URL(redirectUri);
+    } catch {
+      return null;
+    }
+    if (parsed.protocol !== 'https:') return null;
+    return this.deps.consumers.find((c) => c.redirectHosts.includes(parsed.hostname)) ?? null;
+  }
+}
+
+function hashCode(code: string): string {
+  return createHash('sha256').update(code).digest('hex');
+}
+
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : '';
+}
+
+function safeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  return ab.length === bb.length && timingSafeEqual(ab, bb);
+}

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

@@ -0,0 +1,25 @@
+export {
+  GitHubFacadeCredentialsService,
+  DbGitHubFacadeCredentialsStore,
+  MemoryGitHubFacadeCredentialsStore,
+  GitHubFacadeUnavailableError,
+  type GitHubFacadeCredentials,
+  type GitHubFacadeCredentialsStore,
+} from './github-facade-credentials.service.js';
+export {
+  DbGitHubFacadeCodeStore,
+  MemoryGitHubFacadeCodeStore,
+  type GitHubFacadeCodeStore,
+  type PendingFacadeCode,
+} from './github-facade-codes.store.js';
+export {
+  GitHubFacade,
+  GitHubFacadeRequestError,
+  GITHUB_LINK_KEY_KIND,
+  GITHUB_LINK_KEY_PREFIX,
+  CLAUDE_CONSUMER,
+  type GitHubFacadeConsumer,
+  type GitHubFacadeDeps,
+} from './github-facade.service.js';
+export { createGitHubFacadeRoutes, type GitHubFacadeRoutesDeps } from './github-facade.routes.js';
+export { createGitHubFacadeAdminRoutes, type GitHubFacadeAdminRoutesDeps } from './github-facade-admin.routes.js';

package/src/modules/marketplace/index.ts

@@ -0,0 +1,3 @@
+export { MarketplaceRepoService, type MarketplaceCompiler, type EnsureResult } from './marketplace-repo.service.js';
+export { createMarketplaceGitRoutes, type MarketplaceKeyResolver } from './git-http.routes.js';
+export * from './github-facade/index.js';