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

package/src/modules/marketplace/__tests__/github-facade.test.ts

@@ -1,13 +1,15 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import http from 'node:http';
+import net from 'node:net';
 import { randomBytes } from 'node:crypto';
 import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
 
 import { MarketplaceRepoService, type MarketplaceCompiler } from '../marketplace-repo.service.js';
+import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
 import {
   GitHubFacadeCredentialsService,
   GitHubFacade,
@@ -77,6 +79,23 @@ function makeKeys() {
   };
 }
 
+/** An HTTP/1.1 request written byte for byte (Latin-1), answering with its status code. */
+function rawRequest(base: string, headLines: string[], body = ''): Promise<number> {
+  const { hostname, port } = new URL(base);
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(Number(port), hostname, () => {
+      socket.write(Buffer.from([...headLines, `Host: ${hostname}`, 'Connection: close', '', body].join('\r\n'), 'latin1'));
+    });
+    let received = '';
+    socket.setEncoding('latin1');
+    socket.on('data', (chunk: string) => {
+      received += chunk;
+    });
+    socket.on('end', () => resolve(Number(received.split(' ')[1])));
+    socket.on('error', reject);
+  });
+}
+
 /** One replica: its own bridge over the SHARED stores, its own HTTP listener. */
 async function replica(shared: {
   credentials: MemoryGitHubFacadeCredentialsStore;
@@ -161,7 +180,7 @@ describe('the GitHub facade', () => {
       credentials: new MemoryGitHubFacadeCredentialsStore(),
       codes: new MemoryGitHubFacadeCodeStore(),
       keys: makeKeys(),
-      repo: new MarketplaceRepoService(path.join(root, 'marketplace.git'), compiler),
+      repo: new MarketplaceRepoService(path.join(root, 'marketplace.git'), compiler, new NodeGitRunner()),
       admins: new Set(['alice@x.io']),
     };
     a = await replica(shared);
@@ -236,6 +255,71 @@ describe('the GitHub facade', () => {
     expect(minted.label).toBe(CLAUDE_CONSUMER.keyLabel);
   });
 
+  it('logs every refused hop of the connect flow with the check that failed, never the secret or the code', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const creds = await a.credentials.ensure();
+      const code = await approve(a.base, 'alice');
+
+      const wrongSecret = await exchange(b.base, { client_id: creds.clientId, client_secret: 'not-it', code });
+      expect(wrongSecret.status).toBe(401);
+      const staleCode = await exchange(b.base, { client_id: creds.clientId, client_secret: creds.clientSecret, code: 'never-issued' });
+      expect(staleCode.status).toBe(400);
+      const badClient = await fetch(
+        `${a.base}/login/oauth/authorize?client_id=Iv1.0000&redirect_uri=${encodeURIComponent(CALLBACK)}`,
+        { redirect: 'manual' },
+      );
+      expect(badClient.status).toBe(400);
+
+      const lines = warn.mock.calls.map((c) => String(c[0]));
+      expect(lines).toHaveLength(3);
+      expect(lines[0]).toMatch(/token exchange refused \(401 incorrect_client_credentials\): client_secret is not the registered one/);
+      expect(lines[1]).toMatch(/token exchange refused \(400 bad_verification_code\): no live code/);
+      expect(lines[2]).toMatch(/authorize refused \(400 unknown_client\): client_id is not the registered one/);
+      for (const line of lines) {
+        expect(line).not.toContain(creds.clientSecret);
+        expect(line).not.toContain('not-it');
+        expect(line).not.toContain(code);
+        expect(line).not.toContain('never-issued');
+      }
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('keeps the log to one line per event whatever bytes the caller puts in its headers', async () => {
+    // Node's parser already refuses C0 controls and bare CR/LF in a header
+    // value. What it lets through is obs-text — bytes 0x80–0xFF, read as
+    // Latin-1 — and that includes U+009B, the one-byte CSI that starts an
+    // ANSI sequence on its own and that JSON.stringify leaves raw. It goes
+    // over a bare socket: a fetch client refuses to build such a header.
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const csi = String.fromCharCode(0x9b);
+      const creds = await a.credentials.ensure();
+      const body = JSON.stringify({ client_id: creds.clientId, client_secret: 'not-it', code: 'x' });
+      const exchange = await rawRequest(b.base, [
+        'POST /login/oauth/access_token HTTP/1.1',
+        `User-Agent: httpx${csi}[31mforged`,
+        'Content-Type: application/json',
+        'Accept: application/vnd.github+json',
+        `Content-Length: ${Buffer.byteLength(body)}`,
+      ], body);
+      expect(exchange).toBe(401);
+      const api = await rawRequest(b.base, ['GET /api/v3/repos/git/marketplace HTTP/1.1', `User-Agent: httpx${csi}[31mforged`]);
+      expect(api).toBe(401);
+
+      const lines = warn.mock.calls.map((c) => String(c[0]));
+      expect(lines).toHaveLength(2);
+      for (const line of lines) {
+        expect(line.includes(csi)).toBe(false);
+        expect(line).toContain('"httpx\\u009b[31mforged"');
+      }
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
   it('serves the repository, the head commit and the zipball of that person’s own tree — from the origin, never the configured userinfo', async () => {
     const token = await connect('alice');
 
@@ -403,6 +487,54 @@ describe('the GitHub facade', () => {
     }
   });
 
+  /**
+   * The disclosure boundary. Whether the deployment is registered is what
+   * every signed-in person needs, so the External agent access page can show
+   * them the tutorial or the notice; the credentials stay admin-only exactly
+   * as before, and the boolean endpoint carries nothing else.
+   */
+  it('tells any signed-in person whether it is registered — a boolean only — and keeps the credentials and the switch admin-only', async () => {
+    const read = async (base: string, who?: string) =>
+      fetch(`${base}/api/github-facade/registration`, { headers: who ? { 'x-test-user': who } : {} });
+
+    // Unregistered to start with, for a non-admin as much as an admin.
+    const fresh = await read(a.base, 'bob');
+    expect(fresh.status).toBe(200);
+    expect(await fresh.json()).toEqual({ registered: false });
+    expect((await read(a.base)).status).toBe(401);
+
+    // A non-admin can neither flip it nor reach the credentials.
+    const put = (base: string, who: string, body: unknown) =>
+      fetch(`${base}/api/admin/github-facade/registration`, {
+        method: 'PUT',
+        headers: { 'x-test-user': who, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    expect((await put(a.base, 'bob', { registered: true })).status).toBe(403);
+    expect((await fetch(`${a.base}/api/admin/github-facade`, { headers: { 'x-test-user': 'bob' } })).status).toBe(403);
+    expect(await (await read(a.base, 'bob')).json()).toEqual({ registered: false });
+
+    // An admin marks it on one replica; everyone reads it on the other.
+    expect((await put(a.base, 'alice', { registered: 'yes' })).status).toBe(400);
+    const marked = await put(a.base, 'alice', { registered: true });
+    expect(marked.status).toBe(200);
+    expect(await marked.json()).toEqual({ registered: true });
+    const seen = await read(b.base, 'bob');
+    const raw = await seen.text();
+    expect(JSON.parse(raw)).toEqual({ registered: true });
+    // Not one credential value in what a non-admin was sent.
+    const creds = await a.credentials.ensure();
+    for (const secret of [creds.appId, creds.clientId, creds.clientSecret, creds.webhookSecret, creds.privateKeyPem]) {
+      expect(raw).not.toContain(secret);
+    }
+
+    // A rotation does not unregister it; an admin clearing it does.
+    await fetch(`${b.base}/api/admin/github-facade/rotate`, { method: 'POST', headers: { 'x-test-user': 'alice' } });
+    expect(await (await read(a.base, 'bob')).json()).toEqual({ registered: true });
+    await put(b.base, 'alice', { registered: false });
+    expect(await (await read(a.base, 'bob')).json()).toEqual({ registered: false });
+  });
+
   it('hands an admin the registration fields uncached, and a rotation on one replica is what the other checks', async () => {
     const forbidden = await fetch(`${a.base}/api/admin/github-facade`, { headers: { 'x-test-user': 'bob' } });
     expect(forbidden.status).toBe(403);

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

@@ -10,6 +10,7 @@ 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);
@@ -64,7 +65,7 @@ describe('marketplace git endpoint', () => {
       sourceCommit: async () => source,
       compileFor: async ({ userEmail }) => tree(trees[userEmail] ?? {}, source),
     };
-    repo = new MarketplaceRepoService(path.join(root, 'data', 'marketplace.git'), compiler);
+    repo = new MarketplaceRepoService(path.join(root, 'data', 'marketplace.git'), compiler, new NodeGitRunner());
     const app = express();
     app.use(
       '/git',

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

@@ -1,4 +1,7 @@
 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';
@@ -92,7 +95,7 @@ export function createMarketplaceGitRoutes(deps: {
     try {
       resolved = await keys.verifyAndLoadToken(key);
     } catch (err) {
-      console.error('[marketplace] connection-key verification failed:', err);
+      log.error('connection-key verification failed:', { err });
       res.status(500).type('text/plain').send('Authentication backend unavailable');
       return;
     }
@@ -108,7 +111,7 @@ export function createMarketplaceGitRoutes(deps: {
     try {
       ensured = await repo.ensureCompiled({ id: resolved.user.id, email: resolved.user.email });
     } catch (err) {
-      console.error('[marketplace] compile failed:', err);
+      log.error('compile failed:', { err });
       res.status(500).type('text/plain').send('Could not prepare your marketplace');
       return;
     }
@@ -136,9 +139,9 @@ export function createMarketplaceGitRoutes(deps: {
     if (req.headers['git-protocol']) env.HTTP_GIT_PROTOCOL = String(req.headers['git-protocol']);
 
     const child = spawn('git', ['http-backend'], { env, stdio: ['pipe', 'pipe', 'pipe'] });
-    child.stderr.on('data', (chunk: Buffer) => console.warn(`[marketplace] http-backend: ${chunk.toString('utf-8').trim()}`));
+    child.stderr.on('data', (chunk: Buffer) => log.warn(`http-backend: ${chunk.toString('utf-8').trim()}`));
     child.on('error', (err) => {
-      console.error('[marketplace] could not run git http-backend:', 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);

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

@@ -1,4 +1,7 @@
 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,
@@ -21,8 +24,18 @@ export interface GitHubFacadeAdminRoutesDeps {
  * 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
+ *   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();
@@ -60,7 +73,7 @@ export function createGitHubFacadeAdminRoutes(deps: GitHubFacadeAdminRoutesDeps)
         res.status(409).json({ error: err.message });
         return;
       }
-      console.error('[github-facade admin]', err);
+      log.error('admin route failed:', { err });
       res.status(500).json({ error: 'Internal error' });
     }
   };
@@ -74,5 +87,24 @@ export function createGitHubFacadeAdminRoutes(deps: GitHubFacadeAdminRoutesDeps)
     }),
   );
 
+  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-credentials.service.ts

@@ -55,6 +55,14 @@ export interface GitHubFacadeCredentialsStore {
    * 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';
@@ -106,6 +114,22 @@ export class DbGitHubFacadeCredentialsStore implements GitHubFacadeCredentialsSt
     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`);
@@ -169,6 +193,30 @@ export class GitHubFacadeCredentialsService {
     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 {
@@ -194,9 +242,16 @@ function generateCredentials(createdAt: Date | null): GitHubFacadeCredentials {
 /** 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;

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

@@ -1,10 +1,14 @@
 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;
@@ -52,10 +56,21 @@ export function createGitHubFacadeRoutes(deps: GitHubFacadeRoutesDeps): express.
   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);
     }
   });
@@ -72,6 +87,7 @@ export function createGitHubFacadeRoutes(deps: GitHubFacadeRoutesDeps): express.
         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;
         }
@@ -87,19 +103,19 @@ export function createGitHubFacadeRoutes(deps: GitHubFacadeRoutesDeps): express.
   api.use(async (req, res, next) => {
     const token = bearerOf(req);
     if (!token || !keys.looksLikeExternalApiKey(token)) {
-      unauthorized(res);
+      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) {
-      console.error('[github-facade] key verification failed:', err);
+      log.error('key verification failed:', { err });
       res.status(500).json({ message: 'Authentication backend unavailable' });
       return;
     }
     if (!resolved) {
-      unauthorized(res);
+      unauthorized(req, res, 'connection key unknown or revoked');
       return;
     }
     req.userId = resolved.user.id;
@@ -144,7 +160,7 @@ export function createGitHubFacadeRoutes(deps: GitHubFacadeRoutesDeps): express.
       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}`);
+        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.
@@ -188,11 +204,21 @@ function bearerOf(req: express.Request): string | null {
   return rest.join(' ').trim() || null;
 }
 
-function unauthorized(res: express.Response): void {
+/** 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,
@@ -215,7 +241,7 @@ function answerError(res: express.Response, err: unknown): void {
     res.status(err.status).json({ message: err.message });
     return;
   }
-  console.error('[github-facade]', err);
+  log.error('request failed:', { err });
   res.status(500).json({ message: 'Internal error' });
 }