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

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

@@ -1,20 +1,26 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import type { MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
+import { logger } from '../../../shared/logging.js';
+
+const log = logger('github-facade');
+import type { KeyKindSpec, 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';
+import { printable } from '../../../shared/printable.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.
+ * The KIND stored on a connection key minted through the facade, and how
+ * that kind is spelled. `gho_` plus forty letters and digits is what a
+ * GitHub OAuth token looks like — the shape a consumer expecting a GitHub
+ * Enterprise host accepts, and may well check; 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_';
+export const GITHUB_LINK_KEY_SPEC: KeyKindSpec = { prefix: GITHUB_LINK_KEY_PREFIX, shape: 'github-token' };
 
 /**
  * A product that talks to this deployment as if it were a GitHub Enterprise
@@ -62,11 +68,21 @@ export interface GitHubFacadeDeps {
   publicFrontendUrl: string;
 }
 
+/**
+ * A refusal the caller is answered with in GitHub's terms — and, for the
+ * server log only, WHY: `detail` names the check that failed (a client
+ * secret that is not the registered one, a code nobody issued) where the
+ * response deliberately says no more than GitHub would. A consumer's
+ * backend never shows its user what we answered; the log is the only place
+ * an operator can see which hop of the connect flow went wrong. It never
+ * carries a secret or a code.
+ */
 export class GitHubFacadeRequestError extends Error {
   constructor(
     readonly status: number,
     readonly code: string,
     message: string,
+    readonly detail: string = message,
   ) {
     super(message);
     this.name = 'GitHubFacadeRequestError';
@@ -103,10 +119,20 @@ export class GitHubFacade {
     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.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'unknown_client',
+        'Unknown client_id.',
+        clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request',
+      );
     }
     if (!this.consumerFor(redirectUri)) {
-      throw new GitHubFacadeRequestError(400, 'invalid_redirect', 'redirect_uri does not belong to a known consumer.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'invalid_redirect',
+        'redirect_uri does not belong to a known consumer.',
+        `redirect_uri host is ${hostOf(redirectUri)}, not a consumer's`,
+      );
     }
     const signed = signAuthRequest(this.deps.stateSecret, {
       c: clientId,
@@ -169,27 +195,47 @@ export class GitHubFacade {
     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.');
+    // One answer for every credential failure, as GitHub gives; the log
+    // alone says which half was wrong.
+    const credentialsWrong = (detail: string) =>
+      new GitHubFacadeRequestError(
+        401,
+        'incorrect_client_credentials',
+        'The client_id and/or client_secret passed are incorrect.',
+        detail,
+      );
+    if (!clientId || !safeEqual(clientId, creds.clientId)) {
+      throw credentialsWrong(clientId ? 'client_id is not the registered one (rotated since, or mistyped)' : 'no client_id in the request');
     }
-    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.');
+    if (!clientSecret || !safeEqual(clientSecret, creds.clientSecret)) {
+      throw credentialsWrong(clientSecret ? 'client_secret is not the registered one (rotated since, or mistyped)' : 'no client_secret in the request');
     }
+    const codeWrong = (detail: string) =>
+      new GitHubFacadeRequestError(400, 'bad_verification_code', 'The code passed is incorrect or expired.', detail);
+    if (!code) throw codeWrong('no code in the request');
+    const pending = await this.deps.codes.peek(hashCode(code));
+    if (!pending) throw codeWrong('no live code with that value: never issued, already spent, or older than 10 minutes');
+    if (pending.clientId !== clientId) throw codeWrong('the code was issued under a different client id');
     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.');
+      throw new GitHubFacadeRequestError(
+        400,
+        'redirect_uri_mismatch',
+        'The redirect_uri does not match the authorization.',
+        `redirect_uri host is ${hostOf(redirectUri)}, the code was issued for ${hostOf(pending.redirectUri)}`,
+      );
     }
     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.');
-    }
+    if (!spent) throw codeWrong('the code was spent by a concurrent exchange');
     // 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,
     });
+    log.info(
+      `${printable(consumer?.name ?? 'a consumer')} connected user ${printable(spent.userId)}: link key ${printable(minted.summary.id)} minted`,
+    );
     return { access_token: minted.plaintext, token_type: 'bearer', scope: '' };
   }
 
@@ -210,6 +256,21 @@ function hashCode(code: string): string {
   return createHash('sha256').update(code).digest('hex');
 }
 
+/**
+ * The host of a URL for a log line, or what was sent when it is not one.
+ * The caller chose the URL, so the host is rendered printable even though a
+ * parsed host is ASCII: the log's one-line rule holds by construction, not
+ * by an argument about URL parsing.
+ */
+function hostOf(url: string): string {
+  try {
+    const host = new URL(url).host;
+    return host ? printable(host) : '(empty)';
+  } catch {
+    return url ? '(not a URL)' : '(empty)';
+  }
+}
+
 function str(v: unknown): string {
   return typeof v === 'string' ? v : '';
 }

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

@@ -17,6 +17,7 @@ export {
   GitHubFacadeRequestError,
   GITHUB_LINK_KEY_KIND,
   GITHUB_LINK_KEY_PREFIX,
+  GITHUB_LINK_KEY_SPEC,
   CLAUDE_CONSUMER,
   type GitHubFacadeConsumer,
   type GitHubFacadeDeps,

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -1,12 +1,10 @@
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { execFile, spawn, type ChildProcess } from 'node:child_process';
-import { promisify } from 'node:util';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { WorkspaceMutex } from '../kb-fs/mutex.js';
 import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
-
-const execFileAsync = promisify(execFile);
+import { type IGitRunner } from '../../shared/git.contract.js';
 
 /** What the repo service asks the compiler for — the one seam it has. */
 export interface MarketplaceCompiler {
@@ -59,6 +57,8 @@ export class MarketplaceRepoService {
     /** Absolute path of the bare repository (created on first use). */
     readonly repoDir: string,
     private readonly compiler: MarketplaceCompiler,
+    /** How git is run — see `shared/git.contract.ts`. */
+    private readonly gitRunner: IGitRunner,
     private readonly committer: { name: string; email: string } = {
       name: 'Hexis',
       email: 'hexis@localhost',
@@ -220,7 +220,14 @@ export class MarketplaceRepoService {
     try {
       const { stdout } = await this.git(['-C', this.repoDir, 'rev-parse', '--verify', '--quiet', this.refOf(namespace)]);
       return stdout.trim() || null;
-    } catch {
+    } catch (err) {
+      // "No such ref" is the answer this null stands for, and `rev-parse
+      // --verify --quiet` says it with exit code 1 and nothing else. Every
+      // other failure — a deadline, a repository git cannot open, a spawn that
+      // never ran — is not an answer about the ref, and read as one it would
+      // have `ensureCompiled` start a namespace's history over on top of the
+      // one it has.
+      if (exitCodeOf(err) !== 1) throw err;
       return null;
     }
   }
@@ -314,14 +321,22 @@ export class MarketplaceRepoService {
     await fs.writeFile(path.join(this.sidecarDir(), `${namespace}.json`), sourceCommit);
   }
 
+  /**
+   * Every command names the bare repository with `-C`, so the working
+   * directory only has to be somewhere that EXISTS: the process's own, as
+   * before. Not the repository — the first command ever run here is the `init`
+   * that creates it, and a spawn into a directory that is not there fails as
+   * `ENOENT` on git itself, which reads as git being missing. The plumbing
+   * that reads a scratch checkout passes its own `cwd`.
+   */
   private git(args: string[], opts: { cwd?: string; env?: NodeJS.ProcessEnv } = {}) {
-    return execFileAsync('git', args, { cwd: opts.cwd, env: opts.env ?? process.env, maxBuffer: 64 * 1024 * 1024 });
+    return this.gitRunner.run(opts.cwd ?? process.cwd(), args, { env: opts.env });
   }
 }
 
-/** The exit code an execFile failure carries, or null when the process never ran. */
+/** The exit code a git failure carries, or null when the process never ran. */
 function exitCodeOf(err: unknown): number | null {
-  const code = (err as { code?: unknown } | null)?.code;
+  const code = (err as { exitCode?: unknown } | null)?.exitCode;
   return typeof code === 'number' ? code : null;
 }
 

package/src/modules/mcp/__tests__/downstream-pool.test.ts

@@ -0,0 +1,278 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  DEFAULT_DOWNSTREAM_IDLE_TTL_MS,
+  DEFAULT_DOWNSTREAM_MAX_ENTRIES,
+  DownstreamPool,
+} from '../downstream-pool.js';
+
+/**
+ * The downstream pool's own contract, isolated from MCP: single-flight
+ * creation, failures never cached, idle eviction and the size cap — each of
+ * which must CLOSE what it drops — invalidation that reaches a creation still
+ * in flight, and leases that keep a connection in use from being closed.
+ */
+
+/** Let fire-and-forget disposals run. */
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+function deferred<T>() {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+function makePool(opts: { idleTtlMs?: number; maxEntries?: number } = {}) {
+  let now = 0;
+  const disposed: string[] = [];
+  const pool = new DownstreamPool<string>({
+    ...opts,
+    now: () => now,
+    dispose: async (value) => {
+      disposed.push(value);
+    },
+  });
+  /** One completed use: acquire, release at once, return the value. */
+  const use = async (key: string, create: () => Promise<string>) => {
+    const lease = await pool.acquire(key, create);
+    lease.release();
+    return lease.value;
+  };
+  return { pool, use, disposed, advance: (ms: number) => (now += ms) };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('DownstreamPool', () => {
+  it("defaults to the retired session store's numbers: 4 hours idle, 5000 entries", () => {
+    expect(DEFAULT_DOWNSTREAM_IDLE_TTL_MS).toBe(4 * 60 * 60 * 1000);
+    expect(DEFAULT_DOWNSTREAM_MAX_ENTRIES).toBe(5000);
+  });
+
+  it('single-flight: concurrent first acquires share ONE creation', async () => {
+    const { use } = makePool();
+    const gate = deferred<string>();
+    const create = vi.fn(() => gate.promise);
+    const waiters = [use('k', create), use('k', create), use('k', create)];
+    gate.resolve('conn-1');
+    expect(await Promise.all(waiters)).toEqual(['conn-1', 'conn-1', 'conn-1']);
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('reuses a pooled value until it is evicted', async () => {
+    const { pool, use } = makePool();
+    const create = vi.fn(async () => 'conn');
+    await use('k', create);
+    await use('k', create);
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(pool.size()).toBe(1);
+  });
+
+  it('keys are independent: (user, server) pairs never share a value', async () => {
+    const { use } = makePool();
+    expect(await use('user-A/notion', async () => 'a')).toBe('a');
+    expect(await use('user-B/notion', async () => 'b')).toBe('b');
+  });
+
+  it('a failed creation is not cached: every waiter sees it, the next acquire retries', async () => {
+    const { pool, use } = makePool();
+    const gate = deferred<string>();
+    const failing = vi.fn(() => gate.promise);
+    const waiters = [use('k', failing), use('k', failing)];
+    gate.reject(new Error('dial failed'));
+    for (const w of waiters) await expect(w).rejects.toThrow('dial failed');
+    expect(pool.size()).toBe(0);
+
+    const create = vi.fn(async () => 'conn');
+    expect(await use('k', create)).toBe('conn');
+    expect(create).toHaveBeenCalledTimes(1);
+  });
+
+  it('idle eviction closes an entry unused past the TTL; the next acquire re-creates it', async () => {
+    const { use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+    let n = 0;
+    const create = vi.fn(async () => `conn-${++n}`);
+    await use('k', create);
+    advance(1001);
+    expect(await use('k', create)).toBe('conn-2');
+    await flush();
+    expect(disposed).toEqual(['conn-1']);
+  });
+
+  it('use keeps an entry alive: idleness is measured from the LAST use', async () => {
+    const { use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+    const create = vi.fn(async () => 'conn');
+    await use('k', create);
+    advance(800);
+    await use('k', create);
+    advance(800); // 1600 since creation, 800 since last use
+    await use('k', create);
+    await flush();
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(disposed).toEqual([]);
+  });
+
+  it('the size cap evicts (and closes) the least-recently-used entry', async () => {
+    const { pool, use, disposed, advance } = makePool({ maxEntries: 2 });
+    await use('a', async () => 'A');
+    advance(1);
+    await use('b', async () => 'B');
+    advance(1);
+    await use('a', async () => 'A-again'); // touch a → b is now the oldest
+    advance(1);
+    await use('c', async () => 'C');
+    await flush();
+    expect(disposed).toEqual(['B']);
+    expect(pool.size()).toBe(2);
+  });
+
+  it('evictWhere closes matching entries and leaves the rest', async () => {
+    const { pool, use, disposed } = makePool();
+    await use('user-A\u0000x', async () => 'ax');
+    await use('user-A\u0000y', async () => 'ay');
+    await use('user-B\u0000x', async () => 'bx');
+    pool.evictWhere((key) => key.startsWith('user-A\u0000'));
+    await flush();
+    expect(disposed.sort()).toEqual(['ax', 'ay']);
+    expect(pool.size()).toBe(1);
+  });
+
+  it('an invalidation that lands mid-creation closes the stale result and builds a fresh one', async () => {
+    const { pool, use, disposed } = makePool();
+    const gate = deferred<string>();
+    const create = vi
+      .fn<() => Promise<string>>()
+      .mockImplementationOnce(() => gate.promise)
+      .mockImplementationOnce(async () => 'fresh');
+    const first = use('k', create);
+    const joiner = use('k', create);
+    pool.evictWhere(() => true);
+    gate.resolve('stale');
+    expect(await first).toBe('fresh');
+    expect(await joiner).toBe('fresh');
+    await flush();
+    expect(disposed).toEqual(['stale']);
+    expect(create).toHaveBeenCalledTimes(2);
+  });
+
+  it('a dispose that throws is logged, never thrown into the request that swept', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    let now = 0;
+    const pool = new DownstreamPool<string>({
+      idleTtlMs: 10,
+      now: () => now,
+      dispose: async () => {
+        throw new Error('close failed');
+      },
+    });
+    (await pool.acquire('user\u0000manual\u0000fp', async () => 'old')).release();
+    now = 100;
+    const lease = await pool.acquire('user\u0000manual\u0000fp', async () => 'new');
+    expect(lease.value).toBe('new');
+    await flush();
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('user=user manual=manual'), expect.any(Error));
+  });
+
+  describe('leases', () => {
+    it('an entry in use outlives the idle TTL; idleness restarts when the use ends', async () => {
+      const { pool, use, disposed, advance } = makePool({ idleTtlMs: 1000 });
+      const lease = await pool.acquire('k', async () => 'conn');
+      advance(5000); // a long call, well past the TTL
+      await use('other', async () => 'other'); // sweeps
+      await flush();
+      expect(disposed).toEqual([]);
+
+      lease.release();
+      advance(999);
+      await use('other', async () => 'other');
+      await flush();
+      expect(disposed).toEqual([]);
+
+      advance(2);
+      await use('other', async () => 'other');
+      await flush();
+      expect(disposed).toEqual(['conn']);
+    });
+
+    it('the size cap never evicts an entry in use: the idle LRU goes instead', async () => {
+      const { pool, use, disposed, advance } = makePool({ maxEntries: 2 });
+      const held = await pool.acquire('a', async () => 'A'); // oldest, but in use
+      advance(1);
+      await use('b', async () => 'B');
+      advance(1);
+      await use('c', async () => 'C');
+      await flush();
+      expect(disposed).toEqual(['B']);
+      expect(held.value).toBe('A');
+      held.release();
+    });
+
+    it('when every entry is in use, the cap is exceeded rather than closing a live call', async () => {
+      const { pool, disposed } = makePool({ maxEntries: 1 });
+      const a = await pool.acquire('a', async () => 'A');
+      const b = await pool.acquire('b', async () => 'B');
+      await flush();
+      expect(disposed).toEqual([]);
+      expect(pool.size()).toBe(2);
+      a.release();
+      b.release();
+    });
+
+    it('an invalidated entry in use leaves the pool at once but is closed only on its last release', async () => {
+      const { pool, disposed } = makePool();
+      const create = vi
+        .fn<() => Promise<string>>()
+        .mockImplementationOnce(async () => 'old')
+        .mockImplementationOnce(async () => 'new');
+      const first = await pool.acquire('k', create);
+      const second = await pool.acquire('k', create);
+      pool.evictWhere(() => true);
+      await flush();
+      expect(disposed).toEqual([]);
+
+      // New callers get a connection built from the current state.
+      const fresh = await pool.acquire('k', create);
+      expect(fresh.value).toBe('new');
+
+      first.release();
+      first.release(); // idempotent: does not count as the second lease ending
+      await flush();
+      expect(disposed).toEqual([]);
+      second.release();
+      await flush();
+      expect(disposed).toEqual(['old']);
+      fresh.release();
+    });
+  });
+});
+
+describe('cap after an all-leased overflow', () => {
+  it('re-applies the cap when a lease ends, instead of waiting for the next acquire', async () => {
+    const { pool, disposed } = makePool({ maxEntries: 2 });
+    const a = await pool.acquire('a', async () => 'A');
+    const b = await pool.acquire('b', async () => 'B');
+    // Every entry is leased, so this insert cannot evict: the pool overflows.
+    const c = await pool.acquire('c', async () => 'C');
+    expect(pool.size()).toBe(3);
+    expect(disposed).toEqual([]);
+
+    // Ending A's lease makes it the only idle entry — and the cap applies now,
+    // with no acquire in sight. A is the least recently used idle entry.
+    a.release();
+    await flush();
+    expect(disposed).toEqual(['A']);
+    expect(pool.size()).toBe(2);
+
+    // Back within the cap: further releases evict nothing.
+    b.release();
+    c.release();
+    await flush();
+    expect(disposed).toEqual(['A']);
+    expect(pool.size()).toBe(2);
+  });
+});