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

package/src/modules/auth/oidc-auth-provider.ts

@@ -1,9 +1,13 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('oidc');
 import type express from 'express';
 import type { AuthProviderPlugin } from './auth.routes.js';
 import { AUTH_COOKIE_MAX_AGE_S } from './auth.routes.js';
 import { AUTH_COOKIE_NAME } from './auth.middleware.js';
 import type { AuthService } from './auth.service.js';
+import { normalizeIssuerUrl } from '../settings/oidc-check.js';
 
 // Short-lived CSRF state + PKCE verifier for the OAuth round-trip: set before
 // redirecting to the provider, verified/consumed on callback.
@@ -17,7 +21,8 @@ interface OidcDiscovery {
   userinfo_endpoint: string;
 }
 
-export interface OidcAuthProviderOptions {
+/** The settings that make up one OIDC configuration. */
+export interface OidcSettings {
   /** Issuer base URL; `<issuer>/.well-known/openid-configuration` must exist. */
   issuerUrl: string;
   clientId: string;
@@ -26,12 +31,60 @@ export interface OidcAuthProviderOptions {
   scopes: string;
   /** Login-button label shown by the login screen. */
   label: string;
+}
+
+/**
+ * The OIDC configuration in effect, resolved through deployment settings —
+ * the environment first, then what an admin saved on the setup screen (see
+ * DeploymentSettingsService). Null unless issuer, client id and secret are
+ * all set.
+ */
+export function oidcSettingsFrom(settings: { resolve(key: string): string }): OidcSettings | null {
+  // Normalized so `<issuer>/.well-known/…` is well-formed, `https://idp/` and
+  // `https://idp` are one issuer to the discovery cache, and the values a
+  // sign-in records match the ones the setup screen checks.
+  const issuerUrl = normalizeIssuerUrl(settings.resolve('oidcIssuerUrl'));
+  const clientId = settings.resolve('oidcClientId');
+  const clientSecret = settings.resolve('oidcClientSecret');
+  if (!issuerUrl || !clientId || !clientSecret) return null;
+  return {
+    issuerUrl,
+    clientId,
+    clientSecret,
+    scopes: settings.resolve('oidcScopes') || 'openid profile email',
+    label: settings.resolve('oidcProviderLabel') || 'Single sign-on',
+  };
+}
+
+export interface OidcAuthProviderOptions {
+  /**
+   * The configuration in effect, or null while it is incomplete. Called on
+   * every probe and every sign-in step rather than once at construction, so a
+   * configuration saved on a running deployment applies to the next sign-in
+   * without a restart.
+   */
+  settings(): OidcSettings | null;
   publicBackendUrl: string;
   publicFrontendUrl: string;
   /** See MicrosoftAuthDeps.cookieSecure — scheme-derived, not NODE_ENV. */
   cookieSecure: boolean;
   /** Injectable for tests; defaults to global fetch. */
   fetchImpl?: typeof fetch;
+  /**
+   * Called after someone has signed in through this provider, with the
+   * configuration that sign-in used — the proof that those values work.
+   * Failures are logged, never fail the sign-in.
+   */
+  onSignedIn?: (used: OidcSettings) => void | Promise<void>;
+}
+
+/**
+ * The redirect URI to register with the provider — and the one the
+ * configuration check sends. `publicBackendUrl` arrives from CoreConfig
+ * without userinfo or a trailing slash, so it is used exactly as configured.
+ */
+export function oidcRedirectUri(publicBackendUrl: string): string {
+  return `${publicBackendUrl}/api/auth/oidc/callback`;
 }
 
 /** Read one named cookie from the raw header (no cookie-parser dep, matching auth.middleware). */
@@ -55,7 +108,12 @@ function readCookie(req: express.Request, name: string): string | null {
 /**
  * Generic OIDC single sign-on as an {@link AuthProviderPlugin} — works with
  * any spec-compliant provider (Entra, Okta, Auth0, Keycloak, Google, …),
- * configured purely from the environment (see CoreConfig `oidc*`).
+ * configured from the environment or the setup screen ({@link oidcSettingsFrom}).
+ *
+ * Registered once and LIVE: the configuration is read on every use, so the
+ * provider is advertised only while it is complete ({@link isEnabled}), its
+ * label and scopes follow the latest save, and a changed issuer is
+ * re-discovered on the next sign-in.
  *
  * Flow: authorization-code with PKCE (S256) as a confidential client.
  * Identity claims come from the `userinfo` endpoint called with the freshly
@@ -68,41 +126,60 @@ function readCookie(req: express.Request, name: string): string | null {
  */
 export class OidcAuthProvider implements AuthProviderPlugin {
   readonly key = 'oidc';
-  readonly label: string;
   readonly startPath = '/api/auth/oidc/login';
 
   private readonly fetchImpl: typeof fetch;
-  private discovery: OidcDiscovery | null = null;
+  /**
+   * The discovery for exactly one issuer — the one last asked for. Held as a
+   * promise so concurrent sign-ins share one fetch; replaced whenever the
+   * issuer differs, so no other issuer's document is ever served.
+   */
+  private discovery: { issuerUrl: string; doc: Promise<OidcDiscovery> } | null = null;
 
   constructor(private readonly opts: OidcAuthProviderOptions) {
-    this.label = opts.label;
     this.fetchImpl = opts.fetchImpl ?? fetch;
   }
 
+  get label(): string {
+    return this.opts.settings()?.label ?? '';
+  }
+
+  isEnabled(): boolean {
+    return this.opts.settings() !== null;
+  }
+
   /**
    * Fetch + cache the issuer's discovery document. Resolved lazily (not at
    * boot) so a temporarily unreachable issuer delays the first login instead
    * of failing the whole deployment; a failed attempt is not cached.
    */
-  private async discover(): Promise<OidcDiscovery> {
-    if (this.discovery) return this.discovery;
-    const url = `${this.opts.issuerUrl}/.well-known/openid-configuration`;
+  private discover(issuerUrl: string): Promise<OidcDiscovery> {
+    if (this.discovery?.issuerUrl === issuerUrl) return this.discovery.doc;
+    const entry = { issuerUrl, doc: this.fetchDiscovery(issuerUrl) };
+    this.discovery = entry;
+    entry.doc.catch(() => {
+      if (this.discovery === entry) this.discovery = null;
+    });
+    return entry.doc;
+  }
+
+  private async fetchDiscovery(issuerUrl: string): Promise<OidcDiscovery> {
+    const url = `${issuerUrl}/.well-known/openid-configuration`;
     const res = await this.fetchImpl(url);
     if (!res.ok) throw new Error(`OIDC discovery failed: ${res.status} ${url}`);
     const doc = (await res.json()) as Partial<OidcDiscovery>;
     if (!doc.authorization_endpoint || !doc.token_endpoint || !doc.userinfo_endpoint) {
       throw new Error('OIDC discovery document is missing required endpoints');
     }
-    this.discovery = {
+    return {
       authorization_endpoint: doc.authorization_endpoint,
       token_endpoint: doc.token_endpoint,
       userinfo_endpoint: doc.userinfo_endpoint,
     };
-    return this.discovery;
   }
 
   private redirectUri(): string {
-    return `${this.opts.publicBackendUrl}/api/auth/oidc/callback`;
+    return oidcRedirectUri(this.opts.publicBackendUrl);
   }
 
   mountRoutes(router: express.Router, authService: AuthService): void {
@@ -110,10 +187,16 @@ export class OidcAuthProvider implements AuthProviderPlugin {
 
     // GET /api/auth/oidc/login — start the round-trip: mint state + PKCE
     // verifier (both in one short-lived HttpOnly cookie), redirect to the
-    // provider's authorization endpoint.
+    // provider's authorization endpoint. An incomplete configuration is an
+    // answer, not an error: back to the sign-in page, which says so.
     router.get('/auth/oidc/login', async (_req, res) => {
+      const oidc = this.opts.settings();
+      if (!oidc) {
+        res.redirect(`${publicFrontendUrl}/auth/oidc/callback#error=not_configured`);
+        return;
+      }
       try {
-        const discovery = await this.discover();
+        const discovery = await this.discover(oidc.issuerUrl);
         const state = randomBytes(16).toString('hex');
         const verifier = randomBytes(32).toString('base64url');
         const challenge = createHash('sha256').update(verifier).digest('base64url');
@@ -126,15 +209,15 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         });
         const url = new URL(discovery.authorization_endpoint);
         url.searchParams.set('response_type', 'code');
-        url.searchParams.set('client_id', this.opts.clientId);
+        url.searchParams.set('client_id', oidc.clientId);
         url.searchParams.set('redirect_uri', this.redirectUri());
-        url.searchParams.set('scope', this.opts.scopes);
+        url.searchParams.set('scope', oidc.scopes);
         url.searchParams.set('state', state);
         url.searchParams.set('code_challenge', challenge);
         url.searchParams.set('code_challenge_method', 'S256');
         res.redirect(url.toString());
       } catch (error) {
-        console.error('OIDC start error:', error instanceof Error ? error.message : error);
+        log.error('OIDC start error:', { err: error });
         res.redirect(`${publicFrontendUrl}/auth/oidc/callback#error=start`);
       }
     });
@@ -155,9 +238,16 @@ export class OidcAuthProvider implements AuthProviderPlugin {
           return;
         }
 
-        const discovery = await this.discover();
+        // Read again rather than carried from the login step: the token
+        // endpoint is asked with whatever is in effect now.
+        const oidc = this.opts.settings();
+        if (!oidc) {
+          fail('not_configured');
+          return;
+        }
+        const discovery = await this.discover(oidc.issuerUrl);
         const basic = Buffer.from(
-          `${encodeURIComponent(this.opts.clientId)}:${encodeURIComponent(this.opts.clientSecret)}`,
+          `${encodeURIComponent(oidc.clientId)}:${encodeURIComponent(oidc.clientSecret)}`,
           'utf8',
         ).toString('base64');
         const tokenRes = await this.fetchImpl(discovery.token_endpoint, {
@@ -174,7 +264,10 @@ export class OidcAuthProvider implements AuthProviderPlugin {
           }).toString(),
         });
         if (!tokenRes.ok) {
-          console.error('OIDC token exchange failed:', tokenRes.status, await tokenRes.text().catch(() => ''));
+          log.error('OIDC token exchange failed:', {
+            status: tokenRes.status,
+            body: await tokenRes.text().catch(() => ''),
+          });
           fail('auth');
           return;
         }
@@ -188,7 +281,7 @@ export class OidcAuthProvider implements AuthProviderPlugin {
           headers: { Authorization: `Bearer ${tokens.access_token}` },
         });
         if (!infoRes.ok) {
-          console.error('OIDC userinfo failed:', infoRes.status);
+          log.error('OIDC userinfo failed:', { status: infoRes.status });
           fail('auth');
           return;
         }
@@ -201,7 +294,7 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         };
         if (!claims.email) {
           // Most likely a missing `email` scope / claim mapping at the provider.
-          console.error('OIDC userinfo returned no email claim');
+          log.error('OIDC userinfo returned no email claim');
           fail('auth');
           return;
         }
@@ -212,6 +305,11 @@ export class OidcAuthProvider implements AuthProviderPlugin {
           '';
 
         const { token } = await authService.loginWithSso(claims.email, name);
+        try {
+          await this.opts.onSignedIn?.(oidc);
+        } catch (error) {
+          log.error('OIDC sign-in record failed:', { err: error });
+        }
         res.cookie(AUTH_COOKIE_NAME, token, {
           httpOnly: true,
           sameSite: 'lax',
@@ -221,7 +319,7 @@ export class OidcAuthProvider implements AuthProviderPlugin {
         });
         res.redirect(`${publicFrontendUrl}/auth/oidc/callback#token=${encodeURIComponent(token)}`);
       } catch (error) {
-        console.error('OIDC callback error:', error instanceof Error ? error.message : error);
+        log.error('OIDC callback error:', { err: error });
         fail('auth');
       }
     });

package/src/modules/code-mode/__tests__/code-mode.tool.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
-import type { CodeModeUtcpClient } from '@utcp/code-mode';
+import '@utcp/direct-call';
+import { addFunctionToUtcpDirectCall } from '@utcp/direct-call';
+import { CodeModeUtcpClient } from '@utcp/code-mode';
 
 /**
  * `tools_info` containment of a THROWING name lookup. `findToolByName`
@@ -95,3 +97,109 @@ describe('call_tool_chain image scrub', () => {
     expect(spill.write).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * `merge_change_request` is retired from every agent tool set, the in-app
+ * chat's included. A chain still calling it gets who merges now, not the
+ * runtime's "is not a function".
+ */
+describe('call_tool_chain and a retired tool', () => {
+  const RETIRED_CALL = 'return KNOWLEDGE_BASE.merge_change_request({ body: { number: 4 } })';
+
+  async function runWith(chainClient: CodeModeUtcpClient, code: string) {
+    const { createCallToolChainTool } = await import('../code-mode.tool.js');
+    const tool = createCallToolChainTool(chainClient, { write: vi.fn() } as never) as unknown as {
+      execute: (input: { code: string }) => Promise<{ success: boolean; error?: string; result?: unknown }>;
+    };
+    return tool.execute({ code });
+  }
+
+  // The runner resolves a failed chain as `{ result: null, logs: ['[ERROR] Code
+  // execution failed: …'] }` — it does not throw.
+  it('answers a failed call to merge_change_request with the plain message, as the runner reports it', async () => {
+    const chainClient = {
+      callToolChain: vi.fn(async () => ({
+        result: null,
+        logs: ['[ERROR] Code execution failed: TypeError: KNOWLEDGE_BASE.merge_change_request is not a function'],
+      })),
+    } as unknown as CodeModeUtcpClient;
+    const out = await runWith(chainClient, RETIRED_CALL);
+    expect(out.success).toBe(false);
+    expect(out.error).toMatch(/a change request is merged by a person in the app/);
+  });
+
+  /**
+   * A real runner whose `KNOWLEDGE_BASE` namespace exists and serves a live
+   * tool, but not the retired one — the shape a deployment actually has.
+   *
+   * Not a client with no manuals: there `KNOWLEDGE_BASE` is undefined too, so
+   * the chain dies of `ReferenceError: KNOWLEDGE_BASE is not defined` without
+   * ever naming a tool. That failure proves nothing about a call to a removed
+   * one — it would only satisfy a check that scanned the chain's source.
+   */
+  async function realRunnerWithKnowledgeBase(): Promise<CodeModeUtcpClient> {
+    addFunctionToUtcpDirectCall('kb_manual', async () => ({
+      utcp_version: '1.0.0',
+      manual_version: '1.0.0',
+      tools: [
+        {
+          name: 'read_file',
+          description: 'A live tool, so the namespace is a real object.',
+          inputs: { type: 'object', properties: { path: { type: 'string' } } },
+          outputs: { type: 'object', properties: {} },
+          tool_call_template: { call_template_type: 'direct-call', callable_name: 'kb_read_file' },
+        },
+      ],
+    }));
+    addFunctionToUtcpDirectCall('kb_read_file', async () => ({ content: '' }));
+    const client = await CodeModeUtcpClient.create(process.cwd(), null);
+    const registered = await client.registerManual({
+      name: 'KNOWLEDGE_BASE',
+      call_template_type: 'direct-call',
+      callable_name: 'kb_manual',
+    } as never);
+    expect(registered.success).toBe(true);
+    return client;
+  }
+
+  it('answers it through a real code-mode runner, not a mock', async () => {
+    const client = await realRunnerWithKnowledgeBase();
+    try {
+      const out = await runWith(client, RETIRED_CALL);
+      expect(out.success).toBe(false);
+      expect(out.error).toMatch(/a change request is merged by a person in the app/);
+    } finally {
+      await client.close();
+    }
+  });
+
+  it('leaves a real runner\'s unrelated failure alone, name in the source or not', async () => {
+    // The retired name sits in a comment while the chain dies of something
+    // else: the agent must still be told what actually killed it.
+    const client = await realRunnerWithKnowledgeBase();
+    try {
+      const out = await runWith(
+        client,
+        '// merge_change_request is gone\nreturn KNOWLEDGE_BASE.no_such_tool({})',
+      );
+      expect(JSON.stringify(out)).not.toMatch(/merged by a person in the app/);
+      expect(JSON.stringify(out)).toContain('no_such_tool');
+    } finally {
+      await client.close();
+    }
+  });
+
+  it('answers a thrown failure the same way', async () => {
+    const chainClient = {
+      callToolChain: vi.fn(async () => {
+        throw new TypeError('KNOWLEDGE_BASE.merge_change_request is not a function');
+      }),
+    } as unknown as CodeModeUtcpClient;
+    expect((await runWith(chainClient, RETIRED_CALL)).error).toMatch(/merged by a person in the app/);
+  });
+
+  it('leaves an unrelated failure as it was', async () => {
+    const chainClient = { callToolChain: vi.fn(async () => { throw new Error('boom'); }) } as unknown as CodeModeUtcpClient;
+    expect((await runWith(chainClient, 'return KNOWLEDGE_BASE.read_file({})')).error).toBe('boom');
+  });
+});

package/src/modules/code-mode/code-mode.tool.ts

@@ -2,7 +2,7 @@ import '@utcp/direct-call';
 import { createTool } from '@mastra/core/tools';
 import { z } from 'zod';
 import { CodeModeUtcpClient } from '@utcp/code-mode';
-import { omitImagePayloads } from '@bevel-software/platform-mcp-core';
+import { omitImagePayloads, retiredToolInFailure, retiredToolChainFailure } from '@bevel-software/platform-mcp-core';
 import type { SpillStore } from '../workspace/spill-store.js';
 import { utcpNameToTsInterfaceName, findToolByName, AmbiguousToolNameError } from './code-mode-names.js';
 
@@ -45,6 +45,11 @@ export function createCallToolChainTool(
       const maxOutputSize = input.max_output_size ?? 200_000;
       try {
         const { result: rawResult, logs } = await client.callToolChain(input.code, timeout);
+        // The runner reports a failed chain in `logs` rather than throwing, so
+        // a chain that died calling a removed tool is recognised here: the agent
+        // gets who does it now, not "is not a function".
+        const retired = retiredToolChainFailure({ result: rawResult, logs });
+        if (retired) return { success: false, error: retired, logs };
         // Same policy as the MCP surfaces' `call_tool_chain` (see
         // `omitImagePayloads`): a chain result is stringified JSON, so an image
         // read inside it comes back as an omitted-image note instead of a
@@ -69,7 +74,13 @@ export function createCallToolChainTool(
         // (so non-2xx tool errors aren't reduced to a bare status code), pass
         // them through to the agent — `e.message` already holds the server's
         // reason, and `status` / `data` give it the structured detail.
-        const message = e instanceof Error ? e.message : String(e);
+        const raw = e instanceof Error ? e.message : String(e);
+        // A chain that failed while calling a removed tool gets the reason it
+        // was removed (who does it now, and where), not "is not a function".
+        // The thrown failure is the signal, not the chain's source: a chain
+        // that only mentions the name and died of something else keeps its own
+        // error, instead of hiding it behind a migration notice.
+        const message = retiredToolInFailure(raw) ?? raw;
         const status = (e as { status?: unknown })?.status;
         const data = (e as { data?: unknown })?.data;
         return {

package/src/modules/connection-probe/__tests__/connection-probe.service.test.ts

@@ -634,6 +634,84 @@ describe('ConnectionProbeService: what the probe concludes', () => {
 
       expect(r?.detail).toContain(accept);
     });
+
+    /**
+     * A SHORT credential is still the credential. Nothing stops someone
+     * storing a four-character key — a test account's token, a numeric
+     * customer id used as one — and the provider echoes it back in exactly the
+     * same sentence it echoes a long one in.
+     */
+    it('redacts a credential too short to be a prefix match', async () => {
+      const tiny = 'ab12';
+      const svc = build({ type: 'http', healthCheck: DECLARED_PROBE }, async () => tiny);
+      vi.mocked(fetch).mockResolvedValue(
+        new Response(`Incorrect API key provided: ${tiny}. Check your key at acme.test.`, { status: 401 }),
+      );
+
+      const r = await svc.probe('u1', 'a@b.c', 'acme');
+
+      expect(r?.status).toBe('failed');
+      expect(r?.detail).not.toContain(tiny);
+      expect(r?.detail).toContain('[redacted]');
+      expect(r?.detail).toContain('Check your key at acme.test.');
+    });
+
+    /**
+     * The reason short values are matched as whole runs rather than anywhere:
+     * `substitute` reports every `${VAR}` a manual resolved, not only the
+     * credential ones, so a version or a region arrives here too. Blanking
+     * those wherever their characters fell would leave `rejected (401)` reading
+     * `rejected ([redacted]01)` — destroying the message the quote exists for.
+     */
+    it('leaves a short value alone inside a longer number, and still redacts it alone', async () => {
+      const svc = build(
+        {
+          type: 'http',
+          healthCheck: {
+            url: 'https://api.acme.test/v${VERSION}/me',
+            headers: { Authorization: 'Bearer ${API_KEY}' },
+          },
+        },
+        async (key) => (key.includes('VERSION') ? '1' : SECRET),
+      );
+      vi.mocked(fetch).mockResolvedValue(
+        new Response('Retry after 401 seconds; api version 1 is retired', { status: 401 }),
+      );
+
+      const r = await svc.probe('u1', 'a@b.c', 'acme');
+
+      // The `1`s inside `401` are untouched: the message is still readable.
+      expect(r?.detail).toContain('Retry after 401 seconds');
+      // The one standing on its own is not — redaction does not get to decide
+      // which resolved values were really secrets.
+      expect(r?.detail).toContain('api version [redacted] is retired');
+    });
+
+    /**
+     * Not every short `${VAR}` a manual resolves is even word-shaped. A
+     * separator or a path fragment arrives here as a "secret" like any other,
+     * and a pattern with no boundary on either side matches every occurrence
+     * of that punctuation in the provider's message — which is the whole quote.
+     */
+    it('leaves ordinary punctuation alone when a resolved value IS punctuation', async () => {
+      const svc = build(
+        {
+          type: 'http',
+          healthCheck: {
+            url: 'https://api${SEP}acme.test/me',
+            headers: { Authorization: 'Bearer ${API_KEY}' },
+          },
+        },
+        async (key) => (key.includes('SEP') ? '.' : SECRET),
+      );
+      const body = 'Bad credentials. See https://docs.acme.test/rest for help.';
+      vi.mocked(fetch).mockResolvedValue(new Response(body, { status: 401 }));
+
+      const r = await svc.probe('u1', 'a@b.c', 'acme');
+
+      // Every period survives: the sentence, the hostname, the trailing stop.
+      expect(r?.detail).toContain(body);
+    });
   });
 
   /**

package/src/modules/connection-probe/connection-probe.service.ts

@@ -1,4 +1,7 @@
 import { randomUUID } from 'node:crypto';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('probe');
 import '@utcp/http'; // side effect: registers the 'http' UTCP communication protocol
 import '@utcp/mcp'; // side effect: registers the 'mcp' protocol (remote MCP `.tool` sources)
 import { CommunicationProtocol, UtcpClientConfigSerializer, type CallTemplate } from '@utcp/sdk';
@@ -121,7 +124,7 @@ async function withProbeTimeout<T>(
       () => (abandoned ? onLateSettle?.() : undefined),
     )
     .catch((err) => {
-      console.warn(`[probe] late cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+      log.warn(`late cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
     });
   const deadline = new Promise<typeof TIMED_OUT>((resolve) => {
     timer = setTimeout(() => {
@@ -136,7 +139,11 @@ async function withProbeTimeout<T>(
   }
 }
 
-/** Below this, a "secret" is too short to blank out without eating the message. */
+/**
+ * Below this, a value is redacted only where it stands ALONE — see
+ * {@link SecretRedactor}. It is still redacted; what it may not do is match
+ * inside a longer run of letters and digits.
+ */
 const MIN_SECRET_CHARS = 6;
 /** The shortest leading run of a secret we will treat as an echo of it. */
 const MIN_ECHOED_PREFIX_CHARS = 8;
@@ -155,15 +162,26 @@ const REDACTED = '[redacted]';
  *
  * Leading PREFIXES count as well as whole values, because that echo is usually
  * masked in the middle ("sk-live-abcd…wxyz"): a whole-value search finds
- * nothing there and prints the head of the key regardless. Short values are
- * left alone — blanking a five-character string would hit unrelated text and
- * destroy the message that makes the verdict useful.
+ * nothing there and prints the head of the key regardless.
+ *
+ * SHORT values are redacted too — a four-character key is still the key, and a
+ * provider that quotes it back would otherwise hand it to any reader who can
+ * probe the tool. They are matched only where they stand alone, though,
+ * bounded by something other than a letter or digit. Not every value this
+ * class is told about is a credential: `substitute` hands it whatever every
+ * `${VAR}` in the manual resolved to, so a `${VERSION}` of `1` or a
+ * `${REGION}` of `us` arrives here alongside the token. Blanking those
+ * wherever their characters happened to fall would turn `answered 401` into
+ * `answered 40[redacted]` and destroy the message that makes the verdict
+ * useful — so the short ones may only match a run of their own.
  */
 class SecretRedactor {
   private readonly values = new Set<string>();
 
   remember(value: string): void {
-    if (value.length >= MIN_SECRET_CHARS) this.values.add(value);
+    // Blank is not a secret, and a blank needle matches everywhere: `''` would
+    // put `[redacted]` between every character of the message.
+    if (value.trim()) this.values.add(value);
   }
 
   redact(text: string): string {
@@ -174,6 +192,10 @@ class SecretRedactor {
     // leaves its tail printed — the exact half-redaction this class exists to
     // avoid, arrived at from the other direction.
     for (const secret of [...this.values].sort((a, b) => b.length - a.length)) {
+      if (secret.length < MIN_SECRET_CHARS) {
+        out = out.replace(standingAlone(secret), REDACTED);
+        continue;
+      }
       // Longest match first: replacing the whole value when it is present beats
       // replacing a prefix of it and leaving the tail on screen.
       const shortest = Math.min(secret.length, MIN_ECHOED_PREFIX_CHARS);
@@ -188,6 +210,36 @@ class SecretRedactor {
   }
 }
 
+/**
+ * `value`, wherever it appears as a run of its own.
+ *
+ * Both ends are guarded, unconditionally. An earlier version applied the guard
+ * only where the value's own edge was a letter or a digit, reasoning that a
+ * value ending in punctuation cannot hide inside a longer word — but a value
+ * made ENTIRELY of punctuation then compiled to a bare, unanchored pattern: a
+ * `${SEPARATOR}` of `.` turned every sentence period and every dot of every
+ * hostname in the provider's message into `[redacted]`, which destroys the
+ * quote this class exists to keep readable.
+ *
+ * The cost is a narrow one, and the right way round: a sub-six-character value
+ * whose edge is punctuation and which the provider echoes glued to a word
+ * character (`sk-ab` for a value of `-ab`) is not redacted. That intersection
+ * is far rarer than a punctuation-shaped `${VAR}`, and over-redaction cannot be
+ * recovered from by the reader while this miss still needs a credential short
+ * enough to carry almost no secret in the first place. Values of six
+ * characters or more never come here at all.
+ */
+function standingAlone(value: string): RegExp {
+  // Letters and digits of ANY script are word characters here: a value that
+  // happens to be the tail of a provider's non-ASCII word (`clé`, `código`)
+  // must not be cut out of it.
+  return new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(value)}(?![\\p{L}\\p{N}])`, 'gu');
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /**
  * Names — of a header or of a query parameter — whose value IS a credential
  * rather than a description of the request. Matched as substrings and on
@@ -335,7 +387,7 @@ async function closeProbeSessions(client: CodeModeUtcpClient, template: CallTemp
     const protocol = CommunicationProtocol.communicationProtocols[template.call_template_type];
     await protocol?.deregisterManual(client as never, template);
   } catch (err) {
-    console.warn(`[probe] closing session failed: ${err instanceof Error ? err.message : String(err)}`);
+    log.warn(`closing session failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 }