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

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

@@ -1,4 +1,5 @@
 export { DbSecretsVaultService } from './db-secrets-vault.service.js';
+export { managedSignInErasure } from './managed-sign-in-erasure.js';
 export { McpOAuthDiscoveryService, type McpAuthDiscovery } from './mcp-oauth-discovery.service.js';
 export {
   createSecretsVaultRoutes,
@@ -13,6 +14,12 @@ export type {
   PutStaticSecretInput,
   CreateOAuthSecretInput,
   ForcedRefreshOutcome,
+  ManagedSignInRef,
+  ManagedSignInCard,
+  ManagedSignInPort,
+  ManagedTokenRefresher,
+  ManagedTokenRevoker,
+  DeliveredTokenSet,
 } from './secrets-vault.contract.js';
 export {
   InvalidSecretError,
@@ -27,4 +34,4 @@ export {
   DEFAULT_SECRETS_SCOPE,
 } from './secrets-variable-loader.js';
 // Reached by other modules; exported here so they stop importing the files.
-export { scopesCovered } from './secrets-vault.contract.js';
+export { scopesCovered, userSecretGap, type UserSecretGap } from './secrets-vault.contract.js';

package/src/modules/secrets-vault/managed-sign-in-erasure.ts

@@ -0,0 +1,41 @@
+import type { ISecretsVaultService, ManagedRowsWriter } from './secrets-vault.contract.js';
+
+/**
+ * The vault's slice of account erasure (an `IErasureParticipant`, see the
+ * auth module): a managed sign-in's tokens are told to their provider before
+ * the user row goes and the vault rows cascade away with it. Switching an
+ * account off reaches the same call through `onAccountDeactivated`; erasing
+ * an account that was never switched off would otherwise drop its rows with
+ * the grant still live at the provider, which is the one leak the revoker
+ * exists to close.
+ *
+ * Two passes, because a sign-in can land while an erasure runs:
+ *
+ * - `before`, outside the transaction: revocation is best effort and
+ *   idempotent (a revoked token is deleted here either way, and a second run
+ *   finds no managed row). A row the vault could not settle (its tokens kept
+ *   changing under the revoke) makes the vault throw, and the erasure is
+ *   refused with it: the account itself is not erased, the rows already
+ *   revoked and deleted in this pass stay deleted (each was told to its
+ *   provider first), the admin retries, and the retry finds only what is
+ *   still to settle.
+ * - `inTransaction`, beside the user row's deletion: whatever managed row
+ *   landed since (a reconnect, a broker handoff) is locked, revoked and
+ *   deleted in the same transaction, so a handoff arriving after the lock
+ *   waits and then finds no row, and nothing cascades away unrevoked. A
+ *   sign-in begun after the lock inserts a row holding a nonce and no grant,
+ *   which the cascade removes harmlessly.
+ */
+export function managedSignInErasure(vault: Pick<ISecretsVaultService, 'removeManagedRowsOfUser'>): {
+  before(target: { userId: string }): Promise<void>;
+  inTransaction(tx: ManagedRowsWriter, target: { userId: string }): Promise<void>;
+} {
+  return {
+    async before(target) {
+      await vault.removeManagedRowsOfUser(target.userId);
+    },
+    async inTransaction(tx, target) {
+      await vault.removeManagedRowsOfUser(target.userId, tx);
+    },
+  };
+}

package/src/modules/secrets-vault/secrets-variable-loader.ts

@@ -1,134 +1,134 @@
-import { type VariableLoader, VariableLoaderSerializer, Serializer } from '@utcp/sdk';
-import { logger } from '../../shared/logging.js';
-import type { ISecretsVaultService } from './secrets-vault.contract.js';
-
-const log = logger('secrets-vault');
-
-/**
- * The `bevel-secrets` UTCP variable loader — the swappable seam that lets any
- * UTCP client resolve `${VAR}` placeholders from the Secrets Vault at tool-call
- * time (lazily, so OAuth tokens are refreshed on demand).
- *
- * UTCP resolves a variable in three tiers (see `DefaultVariableSubstitutor`):
- * `config.variables` (exact) → each `config.load_variables_from` loader's
- * async `get()` → `process.env`. We seed a per-user loader instance here so any
- * tool var not already in `config.variables` (the reserved `API_URL` /
- * `CONNECTION_KEY`) is resolved from this user's secrets.
- *
- * The `UtcpClient.create` path re-validates the whole config through the
- * serializer registry, so a loader can't be handed in as a bare live object — it
- * must round-trip through a registered serializer. We therefore put a plain
- * descriptor `{ variable_loader_type, user_id, scope }` in `load_variables_from`
- * (via {@link bevelSecretsLoaderConfig}) and let the registered serializer
- * rebuild a live loader bound to the vault registered under that scope.
- *
- * ONE VAULT PER SCOPE, NOT PER PROCESS. The serializer registry is UTCP's and
- * process-wide, but a process can host several knowledge bases, each with a
- * vault of its own, and a user id is only unique within one of them. So the
- * descriptor names the scope its vault was registered under, and a loader
- * reads through that vault alone: two knowledge bases whose users both stored
- * `weather_WEATHER_KEY` never see each other's value. A single-tenant
- * deployment registers under {@link DEFAULT_SECRETS_SCOPE} and names nothing.
- * Swapping the vault backend (e.g. to a client's external secret manager) is
- * just a different `ISecretsVaultService` passed to
- * {@link registerBevelSecretsVariableLoader}.
- */
-export const BEVEL_SECRETS_LOADER_TYPE = 'bevel_secrets';
-
-/** The scope a deployment that hosts one knowledge base registers under. */
-export const DEFAULT_SECRETS_SCOPE = 'default';
-
-/**
- * The vaults the reconstructed loaders read through, by scope. A composition
- * root registers its vault before any client is built; a graph that is torn
- * down unregisters it so a stale descriptor resolves nothing.
- */
-const vaults = new Map<string, ISecretsVaultService>();
-
-export class BevelSecretsVariableLoader implements VariableLoader {
-  readonly variable_loader_type = BEVEL_SECRETS_LOADER_TYPE;
-  readonly user_id: string;
-  readonly scope: string;
-  // VariableLoader is an open shape; allow arbitrary extra props.
-  [key: string]: unknown;
-
-  constructor(userId: string, scope: string = DEFAULT_SECRETS_SCOPE) {
-    this.user_id = userId;
-    this.scope = scope;
-  }
-
-  /**
-   * Resolve `effectiveKey` — the UTCP-namespaced `<manual>_<VAR>` — against the
-   * vault VERBATIM. Preserving the manual prefix binds a secret to exactly ONE
-   * manual: another manual referencing the same bare `${VAR}` forms a different
-   * key and misses. This is the per-manual isolation UTCP's namespacing gives us
-   * — we intentionally do NOT strip the prefix, so a malicious `.tool` can't
-   * harvest a secret the user configured for a different manual.
-   */
-  async get(effectiveKey: string): Promise<string | null> {
-    const vault = vaults.get(this.scope);
-    if (!vault || !this.user_id) return null;
-    try {
-      return await vault.resolve(this.user_id, effectiveKey);
-    } catch (err) {
-      // Log the fault so a backend failure is distinguishable from a merely
-      // unset secret (resolve returning null) when troubleshooting.
-      log.error(`resolve failed for user=${this.user_id} key=${effectiveKey}:`, { err });
-      return null;
-    }
-  }
-}
-
-class BevelSecretsVariableLoaderSerializer extends Serializer<VariableLoader> {
-  toDict(obj: VariableLoader): Record<string, unknown> {
-    const loader = obj as BevelSecretsVariableLoader;
-    return {
-      variable_loader_type: BEVEL_SECRETS_LOADER_TYPE,
-      user_id: loader.user_id ?? '',
-      scope: loader.scope ?? DEFAULT_SECRETS_SCOPE,
-    };
-  }
-
-  validateDict(obj: Record<string, unknown>): VariableLoader {
-    const userId = typeof obj.user_id === 'string' ? obj.user_id : '';
-    const scope = typeof obj.scope === 'string' && obj.scope ? obj.scope : DEFAULT_SECRETS_SCOPE;
-    return new BevelSecretsVariableLoader(userId, scope);
-  }
-}
-
-// Register the serializer on module load so a `{ variable_loader_type:
-// 'bevel_secrets' }` descriptor round-trips through `UtcpClient.create` as soon
-// as this module is imported — independent of whether a vault has been bound
-// yet. Until `registerBevelSecretsVariableLoader` binds a vault, loaders simply
-// resolve to null (no secrets available), so `create` never throws for lack of
-// registration. Idempotent (safe under tsx hot-reload).
-VariableLoaderSerializer.registerVariableLoader(
-  BEVEL_SECRETS_LOADER_TYPE,
-  new BevelSecretsVariableLoaderSerializer(),
-  true,
-);
-
-/**
- * Bind the vault the loaders of `scope` read through. Called once per
- * knowledge base at composition time; before it runs, loaders of that scope
- * resolve to null.
- */
-export function registerBevelSecretsVariableLoader(
-  secretsVault: ISecretsVaultService,
-  scope: string = DEFAULT_SECRETS_SCOPE,
-): void {
-  vaults.set(scope, secretsVault);
-}
-
-/** Forget a scope's vault — the last step of tearing a knowledge base's graph down. */
-export function unregisterBevelSecretsVariableLoader(scope: string = DEFAULT_SECRETS_SCOPE): void {
-  vaults.delete(scope);
-}
-
-/**
- * The plain descriptor to place in a `UtcpClientConfig.load_variables_from`
- * for a given user of the knowledge base registered under `scope`.
- */
-export function bevelSecretsLoaderConfig(userId: string, scope: string = DEFAULT_SECRETS_SCOPE): Record<string, unknown> {
-  return { variable_loader_type: BEVEL_SECRETS_LOADER_TYPE, user_id: userId, scope };
-}
+import { type VariableLoader, VariableLoaderSerializer, Serializer } from '@utcp/sdk';
+import { logger } from '../../shared/logging.js';
+import type { ISecretsVaultService } from './secrets-vault.contract.js';
+
+const log = logger('secrets-vault');
+
+/**
+ * The `bevel-secrets` UTCP variable loader — the swappable seam that lets any
+ * UTCP client resolve `${VAR}` placeholders from the Secrets Vault at tool-call
+ * time (lazily, so OAuth tokens are refreshed on demand).
+ *
+ * UTCP resolves a variable in three tiers (see `DefaultVariableSubstitutor`):
+ * `config.variables` (exact) → each `config.load_variables_from` loader's
+ * async `get()` → `process.env`. We seed a per-user loader instance here so any
+ * tool var not already in `config.variables` (the reserved `API_URL` /
+ * `CONNECTION_KEY`) is resolved from this user's secrets.
+ *
+ * The `UtcpClient.create` path re-validates the whole config through the
+ * serializer registry, so a loader can't be handed in as a bare live object — it
+ * must round-trip through a registered serializer. We therefore put a plain
+ * descriptor `{ variable_loader_type, user_id, scope }` in `load_variables_from`
+ * (via {@link bevelSecretsLoaderConfig}) and let the registered serializer
+ * rebuild a live loader bound to the vault registered under that scope.
+ *
+ * ONE VAULT PER SCOPE, NOT PER PROCESS. The serializer registry is UTCP's and
+ * process-wide, but a process can host several knowledge bases, each with a
+ * vault of its own, and a user id is only unique within one of them. So the
+ * descriptor names the scope its vault was registered under, and a loader
+ * reads through that vault alone: two knowledge bases whose users both stored
+ * `weather_WEATHER_KEY` never see each other's value. A single-tenant
+ * deployment registers under {@link DEFAULT_SECRETS_SCOPE} and names nothing.
+ * Swapping the vault backend (e.g. to a client's external secret manager) is
+ * just a different `ISecretsVaultService` passed to
+ * {@link registerBevelSecretsVariableLoader}.
+ */
+export const BEVEL_SECRETS_LOADER_TYPE = 'bevel_secrets';
+
+/** The scope a deployment that hosts one knowledge base registers under. */
+export const DEFAULT_SECRETS_SCOPE = 'default';
+
+/**
+ * The vaults the reconstructed loaders read through, by scope. A composition
+ * root registers its vault before any client is built; a graph that is torn
+ * down unregisters it so a stale descriptor resolves nothing.
+ */
+const vaults = new Map<string, ISecretsVaultService>();
+
+export class BevelSecretsVariableLoader implements VariableLoader {
+  readonly variable_loader_type = BEVEL_SECRETS_LOADER_TYPE;
+  readonly user_id: string;
+  readonly scope: string;
+  // VariableLoader is an open shape; allow arbitrary extra props.
+  [key: string]: unknown;
+
+  constructor(userId: string, scope: string = DEFAULT_SECRETS_SCOPE) {
+    this.user_id = userId;
+    this.scope = scope;
+  }
+
+  /**
+   * Resolve `effectiveKey` — the UTCP-namespaced `<manual>_<VAR>` — against the
+   * vault VERBATIM. Preserving the manual prefix binds a secret to exactly ONE
+   * manual: another manual referencing the same bare `${VAR}` forms a different
+   * key and misses. This is the per-manual isolation UTCP's namespacing gives us
+   * — we intentionally do NOT strip the prefix, so a malicious `.tool` can't
+   * harvest a secret the user configured for a different manual.
+   */
+  async get(effectiveKey: string): Promise<string | null> {
+    const vault = vaults.get(this.scope);
+    if (!vault || !this.user_id) return null;
+    try {
+      return await vault.resolve(this.user_id, effectiveKey);
+    } catch (err) {
+      // Log the fault so a backend failure is distinguishable from a merely
+      // unset secret (resolve returning null) when troubleshooting.
+      log.error(`resolve failed for user=${this.user_id} key=${effectiveKey}:`, { err });
+      return null;
+    }
+  }
+}
+
+class BevelSecretsVariableLoaderSerializer extends Serializer<VariableLoader> {
+  toDict(obj: VariableLoader): Record<string, unknown> {
+    const loader = obj as BevelSecretsVariableLoader;
+    return {
+      variable_loader_type: BEVEL_SECRETS_LOADER_TYPE,
+      user_id: loader.user_id ?? '',
+      scope: loader.scope ?? DEFAULT_SECRETS_SCOPE,
+    };
+  }
+
+  validateDict(obj: Record<string, unknown>): VariableLoader {
+    const userId = typeof obj.user_id === 'string' ? obj.user_id : '';
+    const scope = typeof obj.scope === 'string' && obj.scope ? obj.scope : DEFAULT_SECRETS_SCOPE;
+    return new BevelSecretsVariableLoader(userId, scope);
+  }
+}
+
+// Register the serializer on module load so a `{ variable_loader_type:
+// 'bevel_secrets' }` descriptor round-trips through `UtcpClient.create` as soon
+// as this module is imported — independent of whether a vault has been bound
+// yet. Until `registerBevelSecretsVariableLoader` binds a vault, loaders simply
+// resolve to null (no secrets available), so `create` never throws for lack of
+// registration. Idempotent (safe under tsx hot-reload).
+VariableLoaderSerializer.registerVariableLoader(
+  BEVEL_SECRETS_LOADER_TYPE,
+  new BevelSecretsVariableLoaderSerializer(),
+  true,
+);
+
+/**
+ * Bind the vault the loaders of `scope` read through. Called once per
+ * knowledge base at composition time; before it runs, loaders of that scope
+ * resolve to null.
+ */
+export function registerBevelSecretsVariableLoader(
+  secretsVault: ISecretsVaultService,
+  scope: string = DEFAULT_SECRETS_SCOPE,
+): void {
+  vaults.set(scope, secretsVault);
+}
+
+/** Forget a scope's vault — the last step of tearing a knowledge base's graph down. */
+export function unregisterBevelSecretsVariableLoader(scope: string = DEFAULT_SECRETS_SCOPE): void {
+  vaults.delete(scope);
+}
+
+/**
+ * The plain descriptor to place in a `UtcpClientConfig.load_variables_from`
+ * for a given user of the knowledge base registered under `scope`.
+ */
+export function bevelSecretsLoaderConfig(userId: string, scope: string = DEFAULT_SECRETS_SCOPE): Record<string, unknown> {
+  return { variable_loader_type: BEVEL_SECRETS_LOADER_TYPE, user_id: userId, scope };
+}

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

@@ -10,6 +10,14 @@
  * the same contract without any change to the loader or the tools.
  */
 
+import type { Database } from '../database/index.js';
+
+/**
+ * A drizzle client a caller lends the vault for one operation — its own
+ * transaction, usually — so a removal runs under that caller's lock scope.
+ */
+export type ManagedRowsWriter = Pick<Database, 'select' | 'delete'>;
+
 export type SecretKind = 'static' | 'oauth';
 
 /** A secret as shown in listings — NEVER carries the value or token material. */
@@ -72,8 +80,36 @@ export interface SecretConfigStatus {
    * required scopes have grown.
    */
   grantedScopes?: string;
+  /**
+   * For an OAuth-backed SHARED row (a managed connector enabled as a workspace
+   * connection): whether an admin has completed the sign-in. `undefined` when
+   * the shared row is static or absent — the shared row of an ordinary tool
+   * sign-in holds the client secret, never tokens, so this is false there.
+   */
+  adminAuthorized?: boolean;
+  /** The shared row's granted scopes, when it holds tokens. Same rule as `grantedScopes`. */
+  adminGrantedScopes?: string;
+  /** The connected account on the caller's row, when the row remembers one. */
+  userAccount?: string;
+  /** The connected account on the shared row, when it remembers one. */
+  adminAccount?: string;
+  /**
+   * The shared row is an OAuth client of the OWNER's (a `clientId`, no managed
+   * mark). For an ordinary sign-in that is simply its registration; for a
+   * variable declared managed it means an owner replaced the managed app with
+   * the deployment's own, and the ordinary flow applies. `undefined` when the
+   * shared row is static or absent.
+   */
+  adminBringsOwnApp?: boolean;
 }
 
+/**
+ * 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.
@@ -83,10 +119,94 @@ export type SecretScope = 'admin' | 'user';
 /** Resolves a UTCP-namespaced key (`<manual>_<VAR>`) to its provisioning scope. */
 export type VariableScopeResolver = (key: string) => Promise<SecretScope>;
 
+/**
+ * A sign-in made through Bevel's managed OAuth app for a connector: the
+ * tokens arrived from the broker, and renewing them goes back through it.
+ * Redeclared here (the vault takes no import from managed-connectors) in the
+ * same way `SecretScope` mirrors the tool-manuals contract.
+ */
+export interface ManagedSignInRef {
+  connectorId: string;
+  scopeSet: string;
+}
+
+/** The token set a broker refresh or handoff delivers — what the vault stores. */
+export interface DeliveredTokenSet {
+  access_token: string;
+  refresh_token?: string;
+  /** Epoch ms; absent when the provider gave no lifetime. */
+  expires_at?: number;
+  token_type?: string;
+  /** Space-delimited scopes granted, or the requested ones when the provider echoed none. */
+  scope?: string;
+}
+
+/**
+ * Renews a managed sign-in's tokens through the broker, which holds the
+ * managed app's client secret (this deployment never does). Throws
+ * {@link SecretOAuthError} with the broker's `providerStatus` on a refusal,
+ * so the vault tells a dead grant (400/401 → wipe) from an outage (keep).
+ * The vault bounds the call (15 s): a broker that does not answer by then
+ * is an outage, the stale token is served, and the next call asks again.
+ */
+export interface ManagedTokenRefresher {
+  refresh(ref: ManagedSignInRef, refreshToken: string): Promise<DeliveredTokenSet>;
+}
+
+/**
+ * Tells the provider a managed sign-in's tokens are no longer wanted, where
+ * the provider offers a way (Google, HubSpot; Microsoft has none). Best
+ * effort: a failure is logged without token material and the local delete
+ * proceeds — the tokens are gone from here either way.
+ */
+export interface ManagedTokenRevoker {
+  revoke(ref: ManagedSignInRef, tokens: { access_token: string; refresh_token?: string }): Promise<void>;
+}
+
+/** What the Connect page shows for a managed sign-in, from the connector it belongs to. */
+export interface ManagedSignInCard {
+  displayName: string;
+  /** A lucide icon name. */
+  icon: string;
+  /** One line: what connecting lets Hexis do. */
+  description: string;
+  /** Plain-language permissions of the scope set. */
+  permissions: string[];
+  scopeSetLabel: string;
+  dataResidency: string;
+  subprocessor: string;
+}
+
+/**
+ * The distribution's side of a managed sign-in: it knows the connectors
+ * (their names, permissions, data notes) and how to open a sign-in through
+ * the broker. Core asks it two things and otherwise treats the resulting
+ * row like any other OAuth sign-in. Absent, a managed sign-in is listed as
+ * waiting on the deployment and cannot be started.
+ */
+export interface ManagedSignInPort {
+  /** Whether sign-ins can be started here at all (a broker is configured). */
+  available(): boolean;
+  /** The card for a sign-in, or null for a connector this distribution does not know. */
+  describe(ref: ManagedSignInRef): ManagedSignInCard | null;
+  /**
+   * Open a sign-in for `key` and answer the provider URL to send the browser
+   * to. `userId` null is a workspace (shared) connection, which the route
+   * allows only to a writer of the tool. `returnTo` is a same-origin path on
+   * this deployment the browser lands on afterwards.
+   */
+  start(input: { userId: string | null; key: string; ref: ManagedSignInRef; returnTo: string }): Promise<{ url: string }>;
+}
+
 /** Non-secret OAuth provider config the user supplies when registering an oauth secret. */
 export interface OAuthProviderConfig {
   authorizationUrl: string;
   tokenUrl: string;
+  /**
+   * The OAuth client. A managed sign-in (`managed` set) has none of its own,
+   * since the client is the broker's: the vault stores `''` whatever a caller
+   * sends. Every other sign-in requires a non-empty value.
+   */
   clientId: string;
   /** Kept out of listings; stored encrypted alongside the tokens. */
   clientSecret?: string;
@@ -107,6 +227,10 @@ export interface OAuthProviderConfig {
    * server's canonical URL).
    */
   resource?: string;
+  /** Set on a managed sign-in: the broker does the round-trip and the refresh. `clientId` is then `''`. */
+  managed?: ManagedSignInRef;
+  /** The connected account, as the broker reported it (an email, a portal name). Shown on the card. */
+  account?: string;
 }
 
 export interface CreateOAuthSecretInput {
@@ -186,8 +310,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 +338,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.
+   *
+   * 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 —
-   * 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.
+   * `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,8 +365,44 @@ export interface ISecretsVaultService {
     redirectUri: string;
     state: string;
     scopes?: string[];
+    provider?: DeclaredOAuthProvider;
   }): Promise<{ id: string; url: string }>;
 
+  // --- Managed sign-ins (tokens arrive from the broker, not from a code exchange here) ---
+  /**
+   * Open a managed sign-in: write (or keep) the row the handoff will land on,
+   * remembering the one-time `nonce` the broker must echo. `userId` null is
+   * the SHARED row (a workspace connection). Existing tokens survive, so a
+   * reconnect that is abandoned leaves the old connection working.
+   */
+  beginManagedConnection(input: {
+    userId: string | null;
+    key: string;
+    provider: OAuthProviderConfig;
+    nonce: string;
+  }): Promise<void>;
+  /**
+   * Land the broker's handoff: the row's pending nonce must match (constant
+   * time), or the handoff is refused as a replay or a stray. Stores the
+   * tokens, clears the nonce, remembers the account.
+   */
+  completeManagedConnection(input: {
+    userId: string | null;
+    key: string;
+    nonce: string;
+    tokens: DeliveredTokenSet;
+    account?: string;
+  }): Promise<void>;
+  /**
+   * Revoke (where the provider allows) and delete every managed sign-in of
+   * one user — deprovisioning. With `within`, the same inside the caller's
+   * transaction: the rows are locked until it commits, so a sign-in landing
+   * meanwhile finds no row (an account erasure runs this beside the user
+   * row's deletion). Throws when a row could not be settled, so the caller
+   * never believes the person holds nothing.
+   */
+  removeManagedRowsOfUser(userId: string, within?: ManagedRowsWriter): Promise<number>;
+
   /**
    * Resolve the injectable value for a UTCP variable `key` — the only reader of
    * secret material. `static` → the decrypted value; `oauth` → a fresh access
@@ -342,6 +514,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?