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

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

@@ -74,6 +74,13 @@ export interface SecretConfigStatus {
   grantedScopes?: string;
 }
 
+/**
+ * A declared sign-in's public provider configuration, as the tool file reads it:
+ * everything but the secret (only the owner's shared row holds it) and the
+ * public-client flag (a declared client is confidential by definition).
+ */
+export type DeclaredOAuthProvider = Omit<OAuthProviderConfig, 'clientSecret' | 'publicClient'>;
+
 /**
  * How a secret is provisioned — mirrors `ToolVariableScope` in the tool-manuals
  * contract, redeclared here to keep the vault free of a tool-manuals import.
@@ -186,8 +193,10 @@ export interface ISecretsVaultService {
   /**
    * Set the confidential client secret + provider config for a tool's OAuth-backed
    * variable, on the SHARED row (`user_id NULL`) for `key`. The provider meta is
-   * stored ALONGSIDE the secret so a later `.tool` edit can't redirect it. Owner-
-   * gated by the route (write access on the `.tool`).
+   * stored ALONGSIDE the secret as a record of the save; a sign-in follows the
+   * declaration as the tool file reads when it starts (`beginToolOAuthByKey`'s
+   * `provider`), not this copy. Owner-gated by the route (write access on the
+   * `.tool`).
    */
   putSharedOAuthClientSecret(input: {
     key: string;
@@ -212,16 +221,26 @@ export interface ISecretsVaultService {
    */
   getSharedOAuthProvider(key: string): Promise<OAuthProviderConfig | null>;
   /**
-   * Provision (if needed) the caller's per-user oauth row for `key` from the SHARED
-   * row's stored provider meta + client secret, then build the consent URL. 409 if
-   * the owner hasn't set the client secret. Returns the provisioned row's id (to
-   * sign into the callback state) and the consent url.
+   * Provision (if needed) the caller's per-user oauth row for `key` and build the
+   * consent URL. 409 if the owner hasn't set the client secret. Returns the
+   * provisioned row's id (to sign into the callback state) and the consent url.
    *
-   * `scopes`, when given, are the permissions to REQUEST on the consent screen —
-   * supplied by the caller from the live tool file so a scope added there takes
-   * effect without the owner re-entering the secret. Only the requested scopes
-   * follow the tool file; the client id, addresses, and secret are still read from
-   * the owner-set shared row. Omitted → the shared row's stored scopes are used.
+   * Where the provider configuration comes from depends on who registered the
+   * client, and each kind of sign-in has exactly one source:
+   *   - `provider` given — a DECLARED sign-in: the client id, endpoints, PKCE,
+   *     resource and authorize params are the declaration as the tool file reads
+   *     now, handed over by the caller. They are validated as the client-secret
+   *     save validates them (https, no private or local address) before anything
+   *     is written or built, and they are what the caller's row records, so the
+   *     token exchange and later refreshes of this grant use the configuration
+   *     the consent was given for. The shared row contributes the client secret
+   *     only, and must hold one.
+   *   - `provider` absent — a client the platform registered itself (dynamic
+   *     client registration): nothing in a file describes it, so the shared
+   *     row's stored configuration is used.
+   *
+   * `scopes`, when given, are the permissions to REQUEST on the consent screen
+   * (the live tool file's); omitted → the provider configuration's own scopes.
    */
   beginToolOAuthByKey(input: {
     userId: string;
@@ -229,6 +248,7 @@ export interface ISecretsVaultService {
     redirectUri: string;
     state: string;
     scopes?: string[];
+    provider?: DeclaredOAuthProvider;
   }): Promise<{ id: string; url: string }>;
 
   /**
@@ -342,6 +362,36 @@ export function scopesCovered(required: string[] | undefined, granted: string |
   return missingScopes(required, granted).length === 0;
 }
 
+/** Why a caller's own value for a per-user variable is not ready yet; see {@link userSecretGap}. */
+export type UserSecretGap = 'missing' | 'wrong-kind' | 'unauthorized' | 'under-scoped';
+
+/**
+ * Whether the CALLER's own value for a per-user variable is ready, and if not,
+ * why: the one rule the MCP proxy hides a tool by and `list_tool_setup` reports
+ * from, so the two cannot disagree. `null` when it is ready.
+ *
+ * - `missing`: no row at all, so it needs a value or a sign-in.
+ * - `wrong-kind`: a row of the OTHER kind than the manual now declares. A
+ *   `.tool` edited from an OAuth sign-in to a plain key (or back) leaves the
+ *   old row behind, and serving a token where a key is declared fails
+ *   opaquely at the provider. The credential has to be set up again.
+ * - `unauthorized`: an OAuth row with no token yet: registered, sign-in not
+ *   completed. Fail closed: anything but a confirmed `true` counts.
+ * - `under-scoped`: a token granted fewer scopes than the tool now declares,
+ *   so the call would fail at the provider; it needs signing in again.
+ */
+export function userSecretGap(
+  declared: { oauth: boolean; oauthScopes?: string[] },
+  status: Pick<SecretConfigStatus, 'userConfigured' | 'userAuthorized' | 'grantedScopes'> & { userKind?: SecretKind | null } | undefined,
+): UserSecretGap | null {
+  if (!status?.userConfigured) return 'missing';
+  const declaredKind: SecretKind = declared.oauth ? 'oauth' : 'static';
+  if (status.userKind && status.userKind !== declaredKind) return 'wrong-kind';
+  if (declared.oauth && status.userAuthorized !== true) return 'unauthorized';
+  if (declared.oauth && !scopesCovered(declared.oauthScopes, status.grantedScopes)) return 'under-scoped';
+  return null;
+}
+
 /**
  * Is the stored row the KIND the manual now declares — i.e. would the thing the
  * UI is about to offer actually work?

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

@@ -10,6 +10,7 @@ import {
   scopesCovered,
   missingScopes,
   configuredAs,
+  type DeclaredOAuthProvider,
   type ISecretsVaultService,
 } from './secrets-vault.contract.js';
 import type { IToolManualService, ToolManualSummary, ToolVariable } from '../tool-manuals/index.js';
@@ -53,6 +54,38 @@ 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,
+    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
@@ -461,8 +494,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 +509,17 @@ 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;
-        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.",
-        });
-      }
+      // 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;
       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,
       });
       res.status(201).json({ ok: true });
     } catch (err) {
@@ -525,12 +537,37 @@ 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(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 key = varKey(found.manual.name, found.variable.name);
+      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,10 +577,10 @@ 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
@@ -657,7 +694,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/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/skills/skills.tools.ts

@@ -33,7 +33,7 @@ const LIST_SKILLS_INPUTS = {
 const GET_SKILL_INPUTS = {
   type: 'object' as const,
   properties: {
-    name: { type: 'string' as const, minLength: 1, description: 'Skill name (its folder name, e.g. `rfi`).' },
+    name: { type: 'string' as const, minLength: 1, description: 'Skill name, as `list_skills` gives it (its `id`, else its `name`, else its folder name; e.g. `rfi`).' },
     file: {
       type: 'string' as const,
       description:

package/src/modules/tool-helpers/__tests__/agent-roles-write.test.ts

@@ -4,21 +4,27 @@ import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
-import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
+import { ToolRegistry } from '../../tool-registry/index.js';
+import {
+  InternalTokenService,
+  RoutineWritePolicyService,
+  WorkflowHooks,
+  createToolAuthMiddleware,
+  loadActiveGroups,
+  registerWorkspaceTools,
+} from '../../../__tests__/tool-wiring.js';
 import { createToolContextResolver } from '../tool-context.js';
 import { createToolHandlerFactory } from '../tool-handler.js';
-import { registerWorkspaceTools } from '../../workspace/workspace.tools.js';
-import { RoutineWritePolicyService } from '../../workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import { ToolDescriptionNotes } from '../../workspace/agent-access.gate.js';
-import { SpillStore } from '../../workspace/spill-store.js';
-import { DocExtractService, WorkerDocumentExtractor } from '../../workspace/index.js';
-import { NEW_ROLE_GUIDANCE } from '../../access-model/roles-yaml-guard.js';
-import { loadActiveGroups } from '../../access/access-control.service.js';
+import { DocExtractService, SpillStore, ToolDescriptionNotes, WorkerDocumentExtractor } from '../../workspace/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
+/**
+ * The sentence a refused role creation carries to the agent, as the agent
+ * guide states it too: asserted as the words a person reads, not as the
+ * module's constant, so a reworded refusal is a visible change here.
+ */
+const NEW_ROLE_GUIDANCE = 'add people to existing roles, and use a GROUP for a task- or team-scoped set of people';
+
 /**
  * The agent's file tools over the production context resolver and a real
  * workspace on disk: a roles.yaml write that creates a role is refused with a
@@ -71,6 +77,8 @@ async function start(): Promise<string> {
     canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
     // The `after` half of a move's or copy's preview — allowing everything, like the gates above.
     previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+    // Who else loses or gains access in a move: nobody, here.
+    prospectiveHolderChanges: async () => ({ lose: [], gain: [] }),
   } as never;
   registerWorkspaceTools(registry, router, toolAuth, createToolHandlerFactory(resolve), new SpillStore(path.join(os.tmpdir(), 'bevel-test-spills')), new DocExtractService(docCache, new WorkerDocumentExtractor()), allowAll, testKbContext({ kbDirName: KB }), {
     // No hook registered: the agent-access gate refuses nothing here.

package/src/modules/tool-helpers/__tests__/route-tool-schemas.catalog.test.ts

@@ -0,0 +1,38 @@
+import { compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
+import { describe, expect, it } from 'vitest';
+import { hexisCatalog } from '../../../__tests__/hexis-catalog.js';
+import { routeToolSchemas } from '../route-tool-schemas.js';
+
+/**
+ * Every tool a route mounts declares two schemas: the one a client sees
+ * (`inputs`, with the platform tools' arguments under `body`) and the FLAT one
+ * the route itself checks a call against. The `Call:` line at the top of each
+ * description is generated from the first; the route refuses by the second.
+ * The two must agree, or a call written from the example is refused one
+ * layer in, with nothing in the description to say why.
+ *
+ * Held here, over the whole catalog Hexis registers, because the flat schema
+ * is this module's: `routeToolSchemas` is how a mounted route finds its own,
+ * and no other module reads it.
+ */
+describe('the flat schema a route checks against accepts the call its own example shows', () => {
+  it('for every tool Hexis mounts on a route', async () => {
+    const { internal } = await hexisCatalog();
+    const mounted = internal.filter((tool) => routeToolSchemas(tool.name) !== undefined);
+    // The catalog is the real one: the family every scenario names is in it.
+    for (const name of ['read_file', 'write_file', 'list_files', 'grep', 'move_file']) {
+      expect(mounted.some((t) => t.name === name), name).toBe(true);
+    }
+    expect(mounted.length).toBeGreaterThan(12);
+    for (const tool of mounted) {
+      // The client's schema is the flat one in its envelope (`bodyEnvelope`),
+      // so the client's example and the route's check meet on the flat schema:
+      // an example written from it must pass the check made from it.
+      const flat = routeToolSchemas(tool.name)!.flat;
+      const check = compileCheck(flat);
+      expect(check.checkable, `${tool.name} (flat): ${check.checkable ? '' : check.reason}`).toBe(true);
+      if (!check.checkable) throw new Error(check.reason);
+      expect(check.check(exampleArguments(flat)), `${tool.name} (flat)`).toEqual([]);
+    }
+  });
+});

package/src/modules/tool-helpers/tool-def.ts

@@ -16,7 +16,7 @@ const toolSerializer = new ToolSerializer();
 export const BRANCH_INPUT: JsonSchema = {
   type: 'string',
   minLength: 1,
-  description: 'The branch (draft) whose workspace this operates on — pass the branch you are currently working on.',
+  description: 'The branch to work on: the default branch (`get_agent_guide` names it) or your draft.',
 };
 
 /**