@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/modules/secrets-vault/secrets-vault.routes.ts

@@ -10,7 +10,10 @@ import {
   scopesCovered,
   missingScopes,
   configuredAs,
+  type DeclaredOAuthProvider,
   type ISecretsVaultService,
+  type ManagedSignInPort,
+  type SecretConfigStatus,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
 import type { IConnectionProbeService } from '../connection-probe/index.js';
@@ -47,12 +50,76 @@ export interface SecretsVaultRoutesDeps {
   publicBackendUrl: string;
   /** Public base URL of the SPA — where the OAuth callback lands the browser. */
   publicFrontendUrl: string;
+  /**
+   * The distribution's managed sign-in port, read per request (the overlay
+   * binds it after boot). Absent or null: a managed sign-in is listed as
+   * waiting on the deployment, and starting one is refused with that reason.
+   */
+  managedSignIns?: () => ManagedSignInPort | null;
+}
+
+/**
+ * The card a managed sign-in renders as on the Connect page, as `/connect/pending`
+ * and `/secrets/tools` report it beside the ordinary fields.
+ */
+interface ManagedSignInView {
+  connectorId: string;
+  scopeSet: string;
+  /** Who the connection belongs to: each person, or the workspace. */
+  tokenScope: 'user' | 'shared';
+  displayName: string;
+  icon: string;
+  description: string;
+  permissions: string[];
+  scopeSetLabel: string;
+  dataResidency: string;
+  subprocessor: string;
+  /** The connected account the row remembers, for "Connected as …". */
+  account: string | null;
+  /** The owner replaced the managed app with the deployment's own (the ordinary flow then applies). */
+  ownApp: boolean;
+  /** Sign-ins through the broker can be started on this deployment. */
+  available: boolean;
 }
 
 function redirectUriFor(publicBackendUrl: string): string {
   return `${publicBackendUrl}/api/secrets/oauth/callback`;
 }
 
+/**
+ * What of a declared sign-in is its provider configuration — ONE reading, for
+ * the client-secret save (which stores it as a record) and the sign-in start
+ * (which runs from it). `null` while the declaration has no endpoints: it named
+ * only its client id and the server's metadata could not complete it.
+ */
+function declaredProvider(variable: ToolVariable): DeclaredOAuthProvider | null {
+  const oauth = variable.oauth;
+  if (!oauth?.authorizationUrl || !oauth.tokenUrl) return null;
+  return {
+    authorizationUrl: oauth.authorizationUrl,
+    tokenUrl: oauth.tokenUrl,
+    // A managed sign-in declares no client of its own (the broker's app is
+    // the client); the one route that pins a provider requires an owner's.
+    clientId: oauth.clientId ?? '',
+    scopes: oauth.scopes,
+    // Static authorize params (e.g. Google's `access_type=offline`) so the
+    // provider returns a refresh token.
+    authParams: oauth.authParams,
+    // PKCE unless the declaration opted out; the resource indicator when the
+    // server (or the declaration) names one.
+    pkce: oauth.pkce !== false,
+    resource: oauth.resource,
+  };
+}
+
+/** Why a declared sign-in has no endpoints — the discovery's own reason when it gave one. */
+function endpointsUnknown(manual: ToolManualSummary): string {
+  const why = manual.setup?.reason;
+  return why
+    ? `The sign-in endpoints for this server aren't known yet: ${why}.`
+    : "The sign-in endpoints for this server aren't known yet — declare `authorizationUrl` and `tokenUrl` on the sign-in variable.";
+}
+
 /**
  * Is this a SAME-ORIGIN path we're willing to bounce the browser back to after a
  * sign-in? The callback builds `${publicFrontendUrl}${dest}#…`, so anything that
@@ -116,6 +183,36 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     return variable ? { manual, variable } : null;
   }
 
+  /**
+   * The card for a managed sign-in, or null for an ordinary one. Built from
+   * the variable (which connector), the port (what the connector is) and
+   * the row (whose account, whether an owner brought their own app).
+   */
+  function managedView(v: ToolVariable, st: SecretConfigStatus | undefined): ManagedSignInView | null {
+    const ref = v.oauth?.managed;
+    if (!ref) return null;
+    const port = deps.managedSignIns?.() ?? null;
+    const card = port?.describe(ref) ?? null;
+    const shared = v.scope === 'admin';
+    return {
+      connectorId: ref.connectorId,
+      scopeSet: ref.scopeSet,
+      tokenScope: shared ? 'shared' : 'user',
+      displayName: card?.displayName ?? v.label ?? ref.connectorId,
+      icon: card?.icon ?? 'Plug',
+      description: card?.description ?? '',
+      permissions: card?.permissions ?? [],
+      scopeSetLabel: card?.scopeSetLabel ?? ref.scopeSet,
+      dataResidency: card?.dataResidency ?? '',
+      subprocessor: card?.subprocessor ?? '',
+      account: (shared ? st?.adminAccount : st?.userAccount) ?? null,
+      ownApp: st?.adminBringsOwnApp === true,
+      // Startable only for a connector this distribution knows: a broker that
+      // is up cannot open a sign-in through a connector it has no card for.
+      available: port?.available() === true && card !== null,
+    };
+  }
+
   router.get('/secrets', async (req, res) => {
     const userId = req.userId;
     if (!userId) return void res.status(401).json({ error: 'Not authenticated' });
@@ -236,22 +333,31 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
             const key = varKey(m.name, v.name);
             const st = statusByKey.get(key);
             const isOAuth = v.oauth != null;
-            const authorized = isOAuth ? (st?.userAuthorized ?? false) : undefined;
+            // A SHARED sign-in (a managed workspace connection) is authorized
+            // when the shared row holds tokens — one connection for everyone.
+            const shared = isOAuth && v.scope === 'admin';
+            const authorized = isOAuth ? ((shared ? st?.adminAuthorized : st?.userAuthorized) ?? false) : undefined;
             // For an OAuth var: which declared permissions the token doesn't cover,
             // so the panel can say WHAT it works for and what it doesn't. Only
             // meaningful once authorized (an unauthorized var has no token at all).
-            const missing = isOAuth && authorized ? missingScopes(v.oauth?.scopes, st?.grantedScopes) : [];
+            const granted = shared ? st?.adminGrantedScopes : st?.grantedScopes;
+            const missing = isOAuth && authorized ? missingScopes(v.oauth?.scopes, granted) : [];
+            const managed = managedView(v, st);
             return {
               name: v.name,
               scope: v.scope,
               label: v.label ?? null,
               key,
               adminConfigured: st?.adminConfigured ?? false,
+              // What the owner's row IS, so a surface can tell a client of the
+              // OAuth kind from a key left from when the variable was static.
+              adminKind: st?.adminKind ?? null,
               userConfigured: st?.userConfigured ?? false,
               oauth: isOAuth,
               authorized,
               needsReauth: isOAuth && authorized === true && missing.length > 0,
               missingScopes: missing,
+              ...(managed ? { managed } : {}),
             };
           }),
         })),
@@ -356,21 +462,35 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       const toolOAuth = manuals.flatMap((m) => {
         const canWrite = canWriteBySlug.get(m.slug) ?? false;
         return (m.variables ?? [])
-          .filter((v) => v.scope === 'user' && v.oauth)
+          // Every per-user sign-in, plus a managed WORKSPACE connection (the
+          // one `admin`-scoped sign-in there is): listed for everyone who can
+          // read the tool, since everyone calls through it, with Connect
+          // offered to the writers who can make it.
+          .filter((v) => v.oauth && (v.scope === 'user' || v.oauth.managed))
           .map((v) => {
             const st = statusByKey.get(varKey(m.name, v.name));
-            const authorized = st?.userAuthorized ?? false;
+            const managed = managedView(v, st);
+            const shared = v.scope === 'admin';
+            const authorized = (shared ? st?.adminAuthorized : st?.userAuthorized) ?? false;
             // Signed in, but the token's granted scopes no longer cover what the
             // tool declares → surface as needing re-authorization, not as connected.
             const needsReauth =
-              authorized && !scopesCovered(v.oauth?.scopes, st?.grantedScopes);
+              authorized && !scopesCovered(v.oauth?.scopes, shared ? st?.adminGrantedScopes : st?.grantedScopes);
             // On an oauth var the ADMIN row is the provider registration — the
             // client secret — without which nobody's Authorize can work. It is a
             // workspace value like any other, so it carries the same flag. It
             // must be an OAUTH row: `beginToolOAuthByKey` refuses a static one,
             // so a shared key left over from before this var was made OAuth
             // would otherwise light up Authorize with nothing behind it.
-            const ownerConfigured = configuredAs('oauth', st?.adminConfigured, st?.adminKind);
+            //
+            // A MANAGED sign-in needs no registration here — the broker holds
+            // it — so it is configured when the deployment can reach a broker,
+            // when an owner replaced the managed app with their own, or when a
+            // token is already stored (nothing is outstanding for a connection
+            // that works, whatever the broker is doing).
+            const ownerConfigured = managed
+              ? managed.ownApp || managed.available || authorized
+              : configuredAs('oauth', st?.adminConfigured, st?.adminKind);
             return {
               slug: m.slug,
               varName: v.name,
@@ -380,7 +500,13 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
               authorized,
               needsReauth,
               ownerConfigured,
-              ownerOnly: !ownerConfigured && !canWrite,
+              // Not the caller's to do: an ordinary sign-in waiting on a
+              // registration the caller may not write, or a managed WORKSPACE
+              // connection seen by someone who may not write the tool. A
+              // managed personal sign-in is always the caller's own, broker or
+              // no broker.
+              ownerOnly: managed ? shared && !canWrite : !ownerConfigured && !canWrite,
+              ...(managed ? { managed, canWrite } : {}),
             };
           });
       });
@@ -461,8 +587,8 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
 
   // Set the confidential client secret for a tool's OAuth-backed variable — the
   // ONLY place the secret is provided. Requires WRITE on the `.tool`. The provider
-  // config comes from the variable's own `oauth` declaration (stored WITH the
-  // secret so a later `.tool` edit can't redirect it).
+  // config of the variable's own `oauth` declaration is stored with the secret as
+  // a record of the save; a sign-in start reads the declaration afresh.
   router.put('/secrets/tools/:slug/vars/:var/oauth/admin', async (req, res) => {
     const userId = req.userId;
     const email = req.userEmail;
@@ -476,38 +602,28 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
       if (!(await accessControl.canWrite(defaultWs(), email, found.manual.path))) {
         return void res.status(403).json({ error: 'You need write access to this tool to set its client secret.' });
       }
-      const { authorizationUrl, tokenUrl } = found.variable.oauth;
       // A declaration that names only its client id is completed from the
-      // server's OAuth metadata at scan time. When that didn't happen, pinning
-      // the secret to a provider with no endpoints would leave every sign-in
-      // failing later with a far less specific error than the catalog's own.
-      if (!authorizationUrl || !tokenUrl) {
-        const why = found.manual.setup?.reason;
+      // server's OAuth metadata. When that didn't happen, storing the secret
+      // with a provider that has no endpoints would leave every sign-in failing
+      // later with a far less specific error than the catalog's own.
+      const provider = declaredProvider(found.variable);
+      if (!provider) return void res.status(422).json({ error: endpointsUnknown(found.manual) });
+      const clientSecret = (req.body ?? {}).clientSecret;
+      // A managed sign-in names no client of its own; an owner who brings
+      // the deployment's own app ("use our own app") supplies its id here
+      // with the secret, and the pinned row then runs the ordinary flow:
+      // this deployment's redirect URI, a direct token exchange and refresh.
+      const ownClientId = typeof (req.body ?? {}).clientId === 'string' ? (req.body.clientId as string).trim() : '';
+      const clientId = provider.clientId || ownClientId;
+      if (!clientId) {
         return void res.status(422).json({
-          error: why
-            ? `The sign-in endpoints for this server aren't known yet: ${why}.`
-            : "The sign-in endpoints for this server aren't known yet — declare `authorizationUrl` and `tokenUrl` on the sign-in variable.",
+          error: 'This sign-in goes through the managed connector. To use your own OAuth app instead, send its client id with the secret.',
         });
       }
-      const clientSecret = (req.body ?? {}).clientSecret;
       await secretsVault.putSharedOAuthClientSecret({
         key: varKey(found.manual.name, found.variable.name),
         clientSecret,
-        provider: {
-          authorizationUrl,
-          tokenUrl,
-          clientId: found.variable.oauth.clientId,
-          scopes: found.variable.oauth.scopes,
-          // Static authorize params (e.g. Google's `access_type=offline`) so the
-          // provider returns a refresh token — stored with the secret so a later
-          // `.tool` edit can't redirect the flow.
-          authParams: found.variable.oauth.authParams,
-          // PKCE unless the declaration opted out; the resource indicator when
-          // the server (or the declaration) names one. Both pinned here for the
-          // same reason as the rest: the flow runs from the stored row.
-          pkce: found.variable.oauth.pkce !== false,
-          resource: found.variable.oauth.resource,
-        },
+        provider: { ...provider, clientId },
       });
       res.status(201).json({ ok: true });
     } catch (err) {
@@ -525,12 +641,81 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
     const email = req.userEmail;
     if (!userId || !email) return void res.status(401).json({ error: 'Not authenticated' });
     try {
-      const found = await findManualVar(email, req.params.slug, req.params.var);
-      if (!found) return void res.status(404).json({ error: 'Tool or variable not found' });
-      if (!found.variable.oauth) {
-        return void res.status(422).json({ error: 'This variable is not an OAuth sign-in.' });
+      // Two sources, one per kind of sign-in. A DECLARED one follows its tool
+      // file as it reads now — never the catalog's scan, which can be a refresh
+      // behind the file, and never the copy the client-secret save stored. A
+      // client the platform registered itself (oauth-auto) is described by no
+      // file: the catalog's discovery surfaced it, and its stored row is the
+      // only description of it there is.
+      const [live, catalog] = await Promise.all([
+        toolManualService.liveDeclaration(email, req.params.slug, req.params.var),
+        findManualVar(email, req.params.slug, req.params.var),
+      ]);
+      // The file is there but its declaration is refused as it reads now (an
+      // http:// or private endpoint, say): the parser's reason is the answer,
+      // and neither a catalog still holding the earlier version nor the stored
+      // row stands in for it. Nothing is sent anywhere.
+      if (live?.refused) return void res.status(422).json({ error: live.refused });
+      const manual = live?.manual ?? catalog?.manual;
+      if (!manual || (!live?.variable && !catalog)) {
+        return void res.status(404).json({ error: 'Tool or variable not found' });
       }
-      const key = varKey(found.manual.name, found.variable.name);
+      const key = varKey(manual.name, req.params.var);
+      const declared = live?.variable?.oauth ? live.variable : null;
+      const registered =
+        !declared && catalog?.manual.setup?.kind === 'oauth-auto' && catalog.variable.oauth ? catalog.variable : null;
+      const signIn = declared ?? registered;
+      // No sign-in in the file and none the platform registered: whatever the
+      // shared row still holds is not used.
+      if (!signIn?.oauth) {
+        throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+      }
+      const returnTo: unknown = (req.body ?? {}).returnTo;
+      // A MANAGED sign-in goes through the broker — unless an owner pinned the
+      // deployment's own app on the shared row, in which case the ordinary
+      // flow below applies exactly as for a file-declared client. Read from
+      // the LIVE declaration like everything else here.
+      const ref = signIn.oauth.managed;
+      if (ref) {
+        const [st] = await secretsVault.statusFor(userId, [key]);
+        // An owner's own app runs the ordinary flow, whose tokens land on the
+        // caller's own row. A WORKSPACE connection reads the shared row, so
+        // the two cannot meet: that combination is refused here rather than
+        // signing an owner in to a row nobody reads.
+        if (st?.adminBringsOwnApp === true && signIn.scope === 'admin') {
+          return void res.status(422).json({
+            error: 'A workspace connection cannot use your own OAuth app yet. Remove the client secret to connect it through the managed connector.',
+          });
+        }
+        if (st?.adminBringsOwnApp !== true) {
+          const port = deps.managedSignIns?.() ?? null;
+          if (!port || !port.available()) {
+            return void res.status(409).json({
+              error: 'This deployment is not connected to a connector broker yet. Ask your admin to configure it.',
+            });
+          }
+          // The same answer the card gives (`available`): a connector the
+          // distribution does not know cannot be started through its broker.
+          if (!port.describe(ref)) {
+            return void res.status(409).json({
+              error: 'This deployment does not offer the connector this sign-in names. Ask your admin.',
+            });
+          }
+          const shared = signIn.scope === 'admin';
+          if (shared && !(await accessControl.canWrite(defaultWs(), email, manual.path))) {
+            return void res.status(403).json({ error: 'Only a writer of this tool can connect its workspace account.' });
+          }
+          const { url } = await port.start({
+            userId: shared ? null : userId,
+            key,
+            ref,
+            returnTo: isSafeReturnPath(returnTo) ? returnTo : '/connect',
+          });
+          return void res.json({ url });
+        }
+      }
+      const provider = declared ? declaredProvider(declared) : undefined;
+      if (provider === null) return void res.status(422).json({ error: endpointsUnknown(manual) });
       // Provision the caller's oauth row (from the owner-set secret) FIRST — its id
       // is what the un-authed callback keys on. Pass an empty state placeholder; we
       // sign the real state below with the returned id and swap it into the URL, so
@@ -540,17 +725,16 @@ export function createSecretsVaultRoutes(deps: SecretsVaultRoutesDeps): express.
         key,
         redirectUri: redirectUriFor(deps.publicBackendUrl),
         state: '',
-        // Request the permissions the tool file declares RIGHT NOW (not the frozen
-        // copy on the owner-set row), so adding a scope to the `.tool` takes effect
-        // on the next sign-in. The secret/clientId/addresses stay owner-pinned.
-        scopes: found.variable.oauth.scopes,
+        // Request the permissions the tool file declares RIGHT NOW, so adding a
+        // scope takes effect on the next sign-in.
+        scopes: signIn.oauth.scopes,
+        provider,
       });
       // The return path is signed INTO the state (HMAC-SHA256) rather than kept
       // in a query param or a cookie: the callback arrives un-authenticated from
       // the provider, so the state is the only thing it can trust. An absent or
       // unsafe `returnTo` falls back to the legacy `'connect'` marker, which
       // keeps a body-less start byte-identical to what it produced before.
-      const returnTo: unknown = (req.body ?? {}).returnTo;
       const state = signState(deps.stateSecret, {
         u: userId,
         i: id,
@@ -657,7 +841,22 @@ export function createSecretsVaultPublicRoutes(deps: SecretsVaultRoutesDeps): ex
       back(`authorized=${encodeURIComponent(state.i)}`, dest);
     } catch (err) {
       log.error('oauth callback failed:', { err });
-      back(`error=${encodeURIComponent('Authorization failed. Check the provider configuration and try again.')}`, dest);
+      // A provider's REFUSAL (the vault's error carrying the provider's HTTP
+      // status) names the provider's error code and Hexis's own sentence for
+      // it — the one thing the person on the Connect page (or the agent they
+      // paste it to) can act on: a client the provider does not accept, a
+      // refused authorization code. Nothing of the provider's text is in it.
+      // Every other failure stays the generic line: a transport error quotes
+      // what fetch said, which is not a provider's word.
+      const refusal = err instanceof SecretOAuthError && err.providerStatus !== undefined ? err.message : null;
+      back(
+        `error=${encodeURIComponent(
+          refusal
+            ? `Authorization failed. ${refusal}`
+            : 'Authorization failed. Check the provider configuration and try again.',
+        )}`,
+        dest,
+      );
     }
   });
 

package/src/modules/settings/__tests__/repository-source.test.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { ManagedRepository, MANAGED_REPOSITORY_DIR } from '../managed-repository.js';
 import { RepositorySource, type GitHubAppRepository } from '../repository-source.js';
 

package/src/modules/settings/__tests__/setup.routes.layout-phase.test.ts

@@ -10,7 +10,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';

package/src/modules/settings/__tests__/setup.routes.managed-phase.test.ts

@@ -12,7 +12,7 @@ import { createSetupRoutes } from '../setup.routes.js';
 import { DeploymentSettingsService } from '../deployment-settings.service.js';
 import { ManagedRepository } from '../managed-repository.js';
 import { RepositorySource } from '../repository-source.js';
-import { NodeGitRunner } from '../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../version-control/git/node-git-runner.js';
 import { TemplateFilesStep } from '../../workspace/startup/steps/template-files.step.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { defaultKbTemplateDir } from '../../../assets.js';

package/src/modules/settings/connection-check.ts

@@ -6,7 +6,7 @@ import { validateHttpsRemote } from './deployment-settings.service.js';
 import { classifyGitFailure } from '../../shared/git-failure.js';
 import { redactSecret, urlQuerySecrets } from '../../shared/redact-secret.js';
 import { GitRunError, type IGitRunner } from '../../shared/git.contract.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 
 /** The repository connection a deployment reads and writes its knowledge base with. */
 export interface RepositoryConnection {

package/src/modules/settings/deployment-settings.service.ts

@@ -325,7 +325,7 @@ export const CORE_SETTINGS: SettingDef[] = [
   {
     /**
      * Whether the server removes, on its own, the branches merged change
-     * requests left behind (`WorkflowService.retireLeftoverMergedBranches`).
+     * requests left behind (`VersionControlService.retireLeftoverMergedBranches`).
      * On unless set to `false`; a blanked field puts the default back. Read
      * at every round, so it applies without a restart. It covers that cleanup
      * only: the removal of a branch when its change request is merged does

package/src/modules/settings/git-root-folders.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { IGitRunner } from '../../shared/git.contract.js';
 import { printable } from '../../shared/printable.js';
 import { logger } from '../../shared/logging.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 import { probeCredentialArgs, probeGitEnv } from './connection-check.js';
 
 const log = logger('setup');

package/src/modules/settings/oidc-check.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from 'node:crypto';
+import { isStandardTokenErrorCode } from '../../shared/oauth-token-error.js';
 
 /** The single sign-on configuration a deployment would sign people in with. */
 export interface OidcConfiguration {
@@ -55,21 +56,6 @@ const REQUEST_TIMEOUT_MS = 10_000;
  */
 const CODE_REJECTIONS: readonly string[] = ['invalid_grant'];
 
-/**
- * The other error codes RFC 6749 §5.2 (and OIDC Core §3.1.2.6) define — the
- * only ones echoed back in an "unverified" message. Anything else in `error`
- * is text of the provider's choosing, and could be the secret reflected back.
- */
-const ECHOED_ERRORS: readonly string[] = [
-  'invalid_request',
-  'unauthorized_client',
-  'unsupported_grant_type',
-  'invalid_scope',
-  'access_denied',
-  'server_error',
-  'temporarily_unavailable',
-];
-
 /** The issuer as the provider appends `/.well-known/...` to it: no trailing slash. */
 export function normalizeIssuerUrl(issuerUrl: string): string {
   return issuerUrl.trim().replace(/\/+$/, '');
@@ -219,9 +205,10 @@ export async function checkOidcConfiguration(
     };
   }
   if (CODE_REJECTIONS.includes(errorCode)) return { outcome: 'verified' };
-  // Only a standard error code is echoed — anything else could be text of the
-  // provider's choosing, the secret included.
-  const code = ECHOED_ERRORS.includes(errorCode) ? ` (${errorCode})` : ` (HTTP ${status})`;
+  // Only a standard error code is echoed (the one list the vault reads a
+  // refusal by too) — anything else could be text of the provider's choosing,
+  // the secret included.
+  const code = isStandardTokenErrorCode(errorCode) ? ` (${errorCode})` : ` (HTTP ${status})`;
   return {
     outcome: 'unverified',
     error: `The application ID and secret could not be verified — the provider gave an answer that does not say whether they are right${code}.`,

package/src/modules/settings/setup.routes.ts

@@ -207,7 +207,7 @@ export function createSetupRoutes(
    * What a change of the knowledge-base repository has to decide about, and
    * what to do when the admin decides to close.
    *
-   * Injected because the setup routes must stay free of the workflow module —
+   * Injected because the setup routes must stay free of the version-control module —
    * and a minimal mount (tests, a distribution without change requests) simply
    * has none: the default answers "no open requests", so the confirmation
    * offers no choice it cannot honour.

package/src/modules/skills/__tests__/allowed-tools-warn.tools.test.ts

@@ -11,7 +11,7 @@ import type { ToolContext } from '../../tool-helpers/tool.contract.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
 import { SpillStore } from '../../workspace/spill-store.js';
 import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
@@ -96,7 +96,7 @@ async function start(): Promise<string> {
     sessionId,
     abortSignal: signal,
     workspaceService: {} as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async () => fs,
   });
@@ -112,7 +112,7 @@ async function start(): Promise<string> {
   registerWorkspaceTools(
     registry, router, fakeAuth, toolHandler,
     new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB_DIR }),
-    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,
     checker,

package/src/modules/skills/__tests__/branch-skills.tools.test.ts

@@ -93,7 +93,7 @@ async function start(): Promise<string> {
       source: auth.source,
       abortSignal: signal,
       workspaceService: {} as never,
-      workflowService: {} as never,
+      versionControlService: {} as never,
       events: {} as never,
       getFilesystem: async () => ({}) as never,
     }) as unknown as ToolContext;

package/src/modules/skills/__tests__/pending-skills.service.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, type ChangeRequest, type IVersionControlService } from '@bevel-software/platform-shared';
 import { PendingSkillsService } from '../pending-skills.service.js';
 import { hashEmail } from '../../../shared/email-identity.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
@@ -74,11 +74,11 @@ function harness(opts: {
     listSkills: async () => opts.released ?? [],
   } as unknown as ISkillService;
 
-  const workflow = {
+  const versionControl = {
     listChangeRequests: async () => opts.crs,
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
-  return new PendingSkillsService(workspaceService, accessControl, skillService, workflow, testKbContext());
+  return new PendingSkillsService(workspaceService, accessControl, skillService, versionControl, testKbContext());
 }
 
 const ADMIN_WRITES = {
@@ -197,20 +197,20 @@ describe('PendingSkillsService', () => {
   });
 
   /**
-   * This hangs off the library's list load. A workflow service that cannot
+   * This hangs off the library's list load. A version-control service that cannot
    * answer must cost the reader an empty review shelf, not their whole library.
    */
   test('degrades to nothing pending when the change requests cannot be listed', async () => {
-    const workflow = {
+    const versionControl = {
       listChangeRequests: async () => {
         throw new Error('offline');
       },
-    } as unknown as IWorkflowService;
+    } as unknown as IVersionControlService;
     const svc = new PendingSkillsService(
       {} as unknown as WorkspaceService,
       {} as unknown as IAccessControl,
       { listSkills: async () => [] } as unknown as ISkillService,
-      workflow,
+      versionControl,
       testKbContext(),
     );
     await expect(svc.listPendingSkills(AUTHOR)).resolves.toEqual([]);