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

package/src/modules/secrets-vault/__tests__/namespace-secrets.test.ts

@@ -0,0 +1,202 @@
+import { describe, expect, it, vi } from 'vitest';
+import { DbSecretsVaultService } from '../db-secrets-vault.service.js';
+import { isKeyInNamespace } from '../secrets-vault.contract.js';
+import { utcpNamespacePrefix } from '../../../shared/utcp-namespace.js';
+import type { Database } from '../../database/connection.js';
+
+/**
+ * The secrets a tool deletion counts and wipes.
+ *
+ * The rule under test is the one that is easy to get wrong and expensive to
+ * get wrong: namespacing DOUBLES underscores, so `foo`'s prefix `foo_` is also
+ * the start of `foo_bar`'s `foo__bar_`. A plain prefix match would let one
+ * tool's deletion take a differently-named tool's credentials with it.
+ */
+
+describe('isKeyInNamespace', () => {
+  const foo = utcpNamespacePrefix('foo');
+
+  it('takes the manual\'s own keys', () => {
+    expect(foo).toBe('foo_');
+    expect(isKeyInNamespace('foo_API_KEY', foo)).toBe(true);
+    expect(isKeyInNamespace('foo_MCP_OAUTH', foo)).toBe(true);
+  });
+
+  it('leaves a longer name\'s keys alone', () => {
+    const fooBar = utcpNamespacePrefix('foo_bar');
+    expect(fooBar).toBe('foo__bar_');
+    expect(isKeyInNamespace('foo__bar_API_KEY', foo)).toBe(false);
+    expect(isKeyInNamespace('foo__bar_API_KEY', fooBar)).toBe(true);
+  });
+
+  it('never takes a `_`-leading remainder, not even for a manual that declares it', () => {
+    // `foo` declaring `_X` and a manual named `foo_X` store under the same
+    // key, and nothing about the key says which. Since the only use of this
+    // predicate is counting and WIPING a namespace, the ambiguous row is left
+    // standing — recoverable, where one wrongly deleted is not.
+    expect(isKeyInNamespace('foo__X', foo)).toBe(false);
+    expect(isKeyInNamespace('foo__bar_KEY', foo)).toBe(false);
+  });
+
+  it('is not the prefix itself, and not an unrelated key', () => {
+    expect(isKeyInNamespace('foo_', foo)).toBe(false);
+    expect(isKeyInNamespace('bar_API_KEY', foo)).toBe(false);
+  });
+});
+
+/**
+ * The delete's id list is the ONE condition this file has to read back, so
+ * `inArray` is swapped for a plain carrier and everything else in drizzle
+ * stays real.
+ */
+vi.mock('drizzle-orm', async (importOriginal) => {
+  const real = await importOriginal<typeof import('drizzle-orm')>();
+  return { ...real, inArray: (_col: unknown, values: string[]) => ({ ids: values }) };
+});
+
+type Row = { id: string; key: string; userId: string | null; kind: string };
+
+/**
+ * A drizzle chain over a MUTABLE store: `select…where` resolves whatever is
+ * there now, `delete…where…returning` removes the ids it was given and reports
+ * them. Mutable on purpose — `removeNamespace` re-scans until a pass comes
+ * back empty, and a store frozen at the first read could never show that.
+ */
+function fakeDb(initial: Row[], onSelect?: (store: Row[]) => void) {
+  let store = [...initial];
+  const deleted: string[][] = [];
+  const chain = (result: unknown) => {
+    const c: Record<string, unknown> = {};
+    const pass = vi.fn(() => c);
+    c.from = pass;
+    c.where = pass;
+    c.then = (onF: (v: unknown) => unknown, onR: (e: unknown) => unknown) =>
+      Promise.resolve(result).then(onF, onR);
+    return c;
+  };
+  const db = {
+    select: vi.fn(() => {
+      const rows = [...store];
+      // After the read, before the delete: the window a concurrent write lands in.
+      onSelect?.(store);
+      return chain(rows);
+    }),
+    delete: vi.fn(() => {
+      const c = chain([]) as Record<string, unknown>;
+      let gone: Row[] = [];
+      c.where = vi.fn((cond: { ids?: string[] }) => {
+        const ids = cond.ids ?? [];
+        deleted.push(ids);
+        gone = store.filter((r) => ids.includes(r.id));
+        store = store.filter((r) => !ids.includes(r.id));
+        return c;
+      });
+      c.returning = vi.fn(() =>
+        // What the DELETE itself saw, not the scan's copy of it.
+        Promise.resolve(gone.map((r) => ({ userId: r.userId, kind: r.kind }))),
+      );
+      return c;
+    }),
+  } as unknown as Database;
+  return { db, deleted, add: (r: Row) => store.push(r), remaining: () => store };
+}
+
+describe('countNamespace / removeNamespace', () => {
+  const rows: Row[] = [
+    { id: '1', key: 'foo_API_KEY', userId: null, kind: 'static' },
+    { id: '2', key: 'foo_API_KEY', userId: 'u-1', kind: 'static' },
+    { id: '3', key: 'foo_MCP_OAUTH', userId: 'u-1', kind: 'oauth' },
+    { id: '4', key: 'foo_MCP_OAUTH', userId: 'u-2', kind: 'oauth' },
+    // The shared client secret of an oauth variable — a stored key, not a sign-in.
+    { id: '5', key: 'foo_MCP_OAUTH', userId: null, kind: 'oauth' },
+    // Another manual whose prefix merely starts the same way.
+    { id: '6', key: 'foo__bar_API_KEY', userId: 'u-1', kind: 'static' },
+  ];
+
+  it('counts sign-ins apart from keys, and never counts a neighbour\'s', async () => {
+    const { db } = fakeDb(rows);
+    const vault = new DbSecretsVaultService(db, '');
+    await expect(vault.countNamespace('foo_')).resolves.toEqual({ keys: 3, signIns: 2 });
+  });
+
+  it('deletes exactly the namespace\'s rows and tells every affected tier', async () => {
+    const { db, deleted, remaining } = fakeDb(rows);
+    const vault = new DbSecretsVaultService(db, '');
+    const notified: (string | null)[] = [];
+    vault.onMutation((u) => notified.push(u));
+    await expect(vault.removeNamespace('foo_')).resolves.toEqual({ keys: 3, signIns: 2 });
+    expect(deleted).toHaveLength(1);
+    // The neighbour survives.
+    expect(remaining().map((r) => r.id)).toEqual(['6']);
+    // Shared rows affect everyone; each user whose row went is told too.
+    expect(notified).toEqual([null, 'u-1', 'u-2']);
+  });
+
+  it('tells only the affected users when nothing SHARED went', async () => {
+    // The `null` sentinel closes every user's pooled MCP connection. A
+    // namespace of nothing but per-user rows has not earned that.
+    const { db } = fakeDb([
+      { id: '1', key: 'foo_API_KEY', userId: 'u-1', kind: 'static' },
+      { id: '2', key: 'foo_API_KEY', userId: 'u-2', kind: 'static' },
+    ]);
+    const vault = new DbSecretsVaultService(db, '');
+    const notified: (string | null)[] = [];
+    vault.onMutation((u) => notified.push(u));
+    await vault.removeNamespace('foo_');
+    expect(notified).toEqual(['u-1', 'u-2']);
+  });
+
+  it('takes a row written between the scan and the delete', async () => {
+    // The membership rule cannot be said in SQL, so the ids are read before
+    // they are deleted. A credential landing in that window would otherwise
+    // outlive the namespace it belongs to — unreachable and unremovable.
+    let wrote = false;
+    const { db, deleted, remaining } = fakeDb(
+      [{ id: '1', key: 'foo_API_KEY', userId: null, kind: 'static' }],
+      (store) => {
+        if (wrote) return;
+        wrote = true;
+        store.push({ id: '2', key: 'foo_LATE_KEY', userId: 'u-9', kind: 'static' });
+      },
+    );
+    const vault = new DbSecretsVaultService(db, '');
+    await expect(vault.removeNamespace('foo_')).resolves.toEqual({ keys: 2, signIns: 0 });
+    expect(deleted).toHaveLength(2);
+    expect(remaining()).toEqual([]);
+  });
+
+  it('deletes nothing when the namespace is empty', async () => {
+    const { db, deleted } = fakeDb([]);
+    const vault = new DbSecretsVaultService(db, '');
+    await expect(vault.removeNamespace('foo_')).resolves.toEqual({ keys: 0, signIns: 0 });
+    expect(deleted).toHaveLength(0);
+  });
+});
+
+describe('removeNamespace under a database that misbehaves', () => {
+  it('counts what the DELETE returned, not what the scan saw', async () => {
+    // A same-key upsert between the scan and the delete can change a row's
+    // `kind`. The scan's copy would then misreport a sign-in as a stored key.
+    const scanned = { id: '1', key: 'foo_MCP_OAUTH', userId: 'u-1', kind: 'static' };
+    const { db } = fakeDb([scanned]);
+    // The row is an oauth row by the time it is deleted.
+    scanned.kind = 'oauth';
+    const vault = new DbSecretsVaultService(db, '');
+    await expect(vault.removeNamespace('foo_')).resolves.toEqual({ keys: 0, signIns: 1 });
+  });
+
+  it('still tells the listeners about the rows an interrupted run did delete', async () => {
+    // Those rows ARE gone. A listener that never heard would keep serving a
+    // pooled connection for a credential that no longer exists.
+    let scans = 0;
+    const { db } = fakeDb([{ id: '1', key: 'foo_API_KEY', userId: 'u-1', kind: 'static' }], () => {
+      scans += 1;
+      if (scans === 2) throw new Error('connection reset');
+    });
+    const vault = new DbSecretsVaultService(db, '');
+    const notified: (string | null)[] = [];
+    vault.onMutation((u) => notified.push(u));
+    await expect(vault.removeNamespace('foo_')).rejects.toThrow('connection reset');
+    expect(notified).toEqual(['u-1']);
+  });
+});

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -1,5 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { and, desc, eq, inArray, isNull, or } from 'drizzle-orm';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('vault');
+import { and, desc, eq, inArray, isNull, like, or } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { secrets } from '../database/schema.js';
 import { TokenCrypto } from '../../shared/token-crypto.js';
@@ -8,11 +11,15 @@ import {
   type ISecretsVaultService,
   type SecretSummary,
   type SecretConfigStatus,
+  type SecretKind,
   type PutStaticSecretInput,
   type PutSharedStaticSecretInput,
   type CreateOAuthSecretInput,
   type OAuthProviderConfig,
   type VariableScopeResolver,
+  type NamespaceSecretCount,
+  isKeyInNamespace,
+  type ForcedRefreshOutcome,
   InvalidSecretError,
   SecretNotFoundError,
   SecretOAuthError,
@@ -26,6 +33,16 @@ const REFRESH_SKEW_MS = 60_000;
 /** Upper bound on a token-endpoint round-trip, so a hung provider can't block callers. */
 const TOKEN_REQUEST_TIMEOUT_MS = 10_000;
 
+/**
+ * How a row is stored, or `null` when there is no row — the column is a plain
+ * string, and anything that is not `oauth` is a stored value (`toSummary` reads
+ * it the same way).
+ */
+function kindOf(row: { kind: string } | undefined): SecretKind | null {
+  if (!row) return null;
+  return row.kind === 'oauth' ? 'oauth' : 'static';
+}
+
 /** The token material stored (encrypted) for an `oauth` secret. */
 interface OAuthTokenSet {
   access_token: string;
@@ -121,7 +138,7 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       try {
         listener(userId);
       } catch (err) {
-        console.warn('[vault] mutation listener failed:', err instanceof Error ? err.message : err);
+        log.warn('mutation listener failed:', { err });
       }
     }
   }
@@ -242,6 +259,71 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     this.notifyMutation(userId);
   }
 
+  async countNamespace(prefix: string): Promise<NamespaceSecretCount> {
+    return tally(await this.namespaceRows(prefix));
+  }
+
+  async removeNamespace(prefix: string): Promise<NamespaceSecretCount> {
+    // Scanned and deleted until a pass finds NOTHING. The membership rule
+    // (`isKeyInNamespace`) cannot be said in SQL, so the ids have to be read
+    // before they are deleted — and a row written in that window would
+    // otherwise outlive the namespace it belongs to, which is precisely the
+    // orphan this method exists to prevent. Bounded, so a writer looping
+    // against us cannot hold the request open.
+    //
+    // What it reports and notifies is what the DELETE itself returned, row by
+    // row — never the scan's copy, which a same-key upsert may have changed
+    // the `kind` of in between.
+    const gone: { userId: string | null; kind: string }[] = [];
+    try {
+      for (let pass = 0; pass < 5; pass++) {
+        const rows = await this.namespaceRows(prefix);
+        if (rows.length === 0) break;
+        const deleted = await this.db
+          .delete(secrets)
+          .where(inArray(secrets.id, rows.map((r) => r.id)))
+          .returning({ userId: secrets.userId, kind: secrets.kind });
+        gone.push(...deleted);
+      }
+    } finally {
+      // In `finally`, because a pass that throws does not un-delete the passes
+      // before it: those rows are gone, and a listener that never heard would
+      // serve a cached connection for a credential that no longer exists.
+      this.notifyNamespaceGone(gone);
+    }
+    return tally(gone);
+  }
+
+  /**
+   * Tell the tiers a namespace deletion actually touched. The `null` sentinel
+   * means "everyone's pooled connection" — earned only by a SHARED row going,
+   * never by one user's secret.
+   */
+  private notifyNamespaceGone(gone: readonly { userId: string | null }[]): void {
+    if (gone.length === 0) return;
+    if (gone.some((r) => r.userId === null)) this.notifyMutation(null);
+    for (const userId of new Set(gone.map((r) => r.userId).filter((u): u is string => u !== null))) {
+      this.notifyMutation(userId);
+    }
+  }
+
+  /**
+   * The rows under a namespace, across every user. `LIKE` narrows in the
+   * database (its `_` and `%` escaped — `_` is in nearly every prefix); the
+   * exact membership rule, which `LIKE` cannot say, is applied here.
+   */
+  private async namespaceRows(
+    prefix: string,
+  ): Promise<{ id: string; key: string; userId: string | null; kind: string }[]> {
+    if (!prefix) return [];
+    const pattern = `${prefix.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
+    const rows = await this.db
+      .select({ id: secrets.id, key: secrets.key, userId: secrets.userId, kind: secrets.kind })
+      .from(secrets)
+      .where(like(secrets.key, pattern));
+    return rows.filter((r) => isKeyInNamespace(r.key, prefix));
+  }
+
   async statusFor(userId: string, keys: string[]): Promise<SecretConfigStatus[]> {
     if (keys.length === 0) return [];
     const rows = await this.db
@@ -255,12 +337,17 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       .where(and(inArray(secrets.key, keys), or(isNull(secrets.userId), eq(secrets.userId, userId))));
     return keys.map((key) => {
       const userRow = rows.find((r) => r.key === key && r.userId === userId);
+      const adminRow = rows.find((r) => r.key === key && r.userId === null);
       // Decrypt+parse the oauth row's token set once, then derive both fields from it.
       const tokens = userRow?.kind === 'oauth' ? this.readTokensSafe(userRow.valueEncrypted) : undefined;
       return {
         key,
-        adminConfigured: rows.some((r) => r.key === key && r.userId === null),
+        adminConfigured: !!adminRow,
         userConfigured: !!userRow,
+        // How each row is stored, so a caller can tell a row that backs the kind
+        // the manual NOW declares from one left behind by an earlier edit.
+        adminKind: kindOf(adminRow),
+        userKind: kindOf(userRow),
         // Only meaningful for an oauth row: has the caller completed sign-in?
         userAuthorized: userRow?.kind === 'oauth' ? Boolean(tokens?.access_token) : undefined,
         // Only meaningful for an oauth row: the scopes the caller's token was granted,
@@ -564,6 +651,64 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     if (!expired) return tokens.access_token;
     if (!tokens.refresh_token) return tokens.access_token; // best-effort; may be stale
 
+    const result = await this.refreshRow(row, blob, tokens);
+    // Transient failure (timeout, network, 5xx) — return the stale token so
+    // the caller gets a clear 401 from the provider rather than a silent
+    // missing var, and the next call retries the refresh.
+    if (result.outcome === 'transient') return tokens.access_token;
+    return result.accessToken;
+  }
+
+  async forceRefresh(userId: string, key: string): Promise<ForcedRefreshOutcome> {
+    const [row] = await this.db
+      .select()
+      .from(secrets)
+      .where(and(eq(secrets.userId, userId), eq(secrets.key, key)))
+      .limit(1);
+    if (!row || row.kind !== 'oauth') return 'skipped';
+    let blob: OAuthBlob;
+    try {
+      blob = this.readBlob(row.valueEncrypted);
+    } catch {
+      return 'skipped';
+    }
+    const tokens = blob.tokens;
+    if (!tokens?.access_token) return 'skipped'; // already not connected
+    // The stored expiry is deliberately NOT consulted: the provider just
+    // refused this token, which outranks whatever lifetime it was issued with.
+    const result = await this.refreshRow(row, blob, tokens);
+    return result.outcome;
+  }
+
+  /**
+   * Trade `tokens.refresh_token` for a fresh token set and persist it — the ONE
+   * refresh path, shared by the expiry-driven `resolve` and the rejection-driven
+   * `forceRefresh`. Three outcomes, each already persisted:
+   *
+   *   - `refreshed` — fresh tokens stored (or a concurrent refresh already
+   *     stored some); `accessToken` is the one to use.
+   *   - `rejected` — the grant is dead: the provider refused it (400/401) or
+   *     there is no refresh token to try. The token set is wiped, the client
+   *     secret kept, so `statusFor` reports not-authorized and /connect routes
+   *     the user to re-authorize.
+   *   - `transient` — timeout, network, 5xx: nothing is changed, so a later
+   *     call tries again.
+   */
+  private async refreshRow(
+    row: typeof secrets.$inferSelect,
+    blob: OAuthBlob,
+    tokens: OAuthTokenSet,
+  ): Promise<
+    | { outcome: 'refreshed'; accessToken: string }
+    | { outcome: 'rejected'; accessToken: null }
+    | { outcome: 'transient' }
+  > {
+    if (!tokens.refresh_token) {
+      // Only the rejection-driven path reaches here without one (`resolve`
+      // serves a refresh-less token as is): the provider refused the only
+      // credential there is, and nothing can renew it.
+      return this.wipeTokens(row, blob);
+    }
     const meta = this.readMeta(row.oauthMeta);
     const body = new URLSearchParams({
       grant_type: 'refresh_token',
@@ -587,36 +732,9 @@ export class DbSecretsVaultService implements ISecretsVaultService {
         err instanceof SecretOAuthError &&
         (err.providerStatus === 400 || err.providerStatus === 401)
       ) {
-        const next: OAuthBlob = { clientSecret: blob.clientSecret };
-        // Guarded on the ciphertext we read, so a concurrent refresh that
-        // already persisted ROTATED tokens can't be wiped by our stale
-        // failure. When that guard trips (0 rows), the failure was against a
-        // dead pre-rotation refresh token — re-read and serve the fresh grant
-        // instead of reporting not-authorized.
-        const wiped = await this.db
-          .update(secrets)
-          .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), updatedAt: new Date() })
-          .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
-          .returning({ id: secrets.id });
-        if (Array.isArray(wiped) && wiped.length === 0) {
-          const [current] = await this.db
-            .select({ valueEncrypted: secrets.valueEncrypted })
-            .from(secrets)
-            .where(eq(secrets.id, row.id))
-            .limit(1);
-          try {
-            const fresh = current ? this.readBlob(current.valueEncrypted) : null;
-            return fresh?.tokens?.access_token ?? null;
-          } catch {
-            return null;
-          }
-        }
-        return null;
+        return this.wipeTokens(row, blob);
       }
-      // Transient failure (timeout, network, 5xx) — return the stale token so
-      // the caller gets a clear 401 from the provider rather than a silent
-      // missing var, and the next call retries the refresh.
-      return tokens.access_token;
+      return { outcome: 'transient' };
     }
     // Some providers omit the refresh_token on refresh — keep the old one.
     if (!refreshed.refresh_token) refreshed.refresh_token = tokens.refresh_token;
@@ -629,15 +747,73 @@ export class DbSecretsVaultService implements ISecretsVaultService {
 
     // Optimistic concurrency: only persist if the stored ciphertext is unchanged,
     // so a concurrent refresh on the same row doesn't clobber (Microsoft pattern).
-    await this.db
+    const stored = await this.db
       .update(secrets)
       .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), updatedAt: new Date() })
-      .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)));
+      .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
+      .returning({ id: secrets.id });
+    if (Array.isArray(stored) && stored.length === 0) {
+      // Nothing was written: the row changed under us, so our fresh token is
+      // not what the vault holds and handing it out would be a lie about
+      // stored state. Same resolution as the guarded wipe — re-read and serve
+      // whatever the winner persisted, or report the grant not-connected when
+      // the winner was a wipe.
+      const current = await this.currentAccessToken(row.id);
+      return current
+        ? { outcome: 'refreshed', accessToken: current }
+        : { outcome: 'rejected', accessToken: null };
+    }
     // A successful refresh is a credential repair — notify so dependent caches
     // (the MCP proxy's manual-failure memo) retry immediately. `row.userId` is
     // null for a shared (admin-scope) row, which maps to "affects everyone".
     this.notifyMutation(row.userId);
-    return refreshed.access_token;
+    return { outcome: 'refreshed', accessToken: refreshed.access_token };
+  }
+
+  /**
+   * The access token currently stored on `id`, or undefined if there is none to
+   * read — including when the row is no longer an OAuth row at all: a concurrent
+   * edit can turn a sign-in into a static value, and a static value that happens
+   * to parse as a token blob must not be handed out as a refreshed grant.
+   */
+  private async currentAccessToken(id: string): Promise<string | undefined> {
+    const [current] = await this.db
+      .select({ kind: secrets.kind, valueEncrypted: secrets.valueEncrypted })
+      .from(secrets)
+      .where(eq(secrets.id, id))
+      .limit(1);
+    if (!current || current.kind !== 'oauth') return undefined;
+    try {
+      return this.readBlob(current.valueEncrypted).tokens?.access_token;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Drop a dead grant's token set, keeping the client secret. See {@link refreshRow}. */
+  private async wipeTokens(
+    row: typeof secrets.$inferSelect,
+    blob: OAuthBlob,
+  ): Promise<{ outcome: 'refreshed'; accessToken: string } | { outcome: 'rejected'; accessToken: null }> {
+    const next: OAuthBlob = { clientSecret: blob.clientSecret };
+    // Guarded on the ciphertext we read, so a concurrent refresh that
+    // already persisted ROTATED tokens can't be wiped by our stale
+    // failure. When that guard trips (0 rows), the failure was against a
+    // dead pre-rotation refresh token — re-read and serve the fresh grant
+    // instead of reporting not-authorized.
+    const wiped = await this.db
+      .update(secrets)
+      .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), updatedAt: new Date() })
+      .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
+      .returning({ id: secrets.id });
+    if (Array.isArray(wiped) && wiped.length === 0) {
+      const fresh = await this.currentAccessToken(row.id);
+      return fresh ? { outcome: 'refreshed', accessToken: fresh } : { outcome: 'rejected', accessToken: null };
+    }
+    // The sign-in just became not-connected — let credential-validity caches
+    // (pooled downstream connections dialed with the dead token) drop it now.
+    this.notifyMutation(row.userId);
+    return { outcome: 'rejected', accessToken: null };
   }
 
   async putSharedOAuthProvider(input: {
@@ -876,3 +1052,9 @@ export class DbSecretsVaultService implements ISecretsVaultService {
 function sha256base64url(verifier: string): string {
   return createHash('sha256').update(verifier).digest('base64url');
 }
+
+/** A namespace's rows, counted by what a person would call them. */
+function tally(rows: { userId: string | null; kind: string }[]): NamespaceSecretCount {
+  const signIns = rows.filter((r) => r.userId !== null && r.kind === 'oauth').length;
+  return { keys: rows.length - signIns, signIns };
+}

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

@@ -12,6 +12,7 @@ export type {
   OAuthProviderConfig,
   PutStaticSecretInput,
   CreateOAuthSecretInput,
+  ForcedRefreshOutcome,
 } from './secrets-vault.contract.js';
 export {
   InvalidSecretError,

package/src/modules/secrets-vault/mcp-oauth-discovery.service.ts

@@ -1,4 +1,7 @@
 import type { ISecretsVaultService, OAuthProviderConfig } from './secrets-vault.contract.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('mcp-oauth-discovery');
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { utcpNamespacedKey, MCP_OAUTH_VAR } from '../../shared/utcp-namespace.js';
 
@@ -142,7 +145,7 @@ export class McpOAuthDiscoveryService {
       existing = await this.deps.secretsVault.getSharedOAuthProvider(key);
     } catch (err) {
       const reason = `provider lookup failed (not re-registering): ${err instanceof Error ? err.message : String(err)}`;
-      console.warn(`[mcp-oauth-discovery] "${manualName}" (${mcpUrl}): ${reason}`);
+      log.warn(`"${manualName}" (${mcpUrl}): ${reason}`);
       return { status: 'unsupported', reason };
     }
     if (existing) return this.remember(key, { status: 'oauth', provider: existing });
@@ -157,7 +160,7 @@ export class McpOAuthDiscoveryService {
       };
     }
     if (result.status === 'unsupported') {
-      console.warn(`[mcp-oauth-discovery] "${manualName}" (${mcpUrl}): ${result.reason}`);
+      log.warn(`"${manualName}" (${mcpUrl}): ${result.reason}`);
     }
     return this.remember(key, result);
   }
@@ -234,7 +237,7 @@ export class McpOAuthDiscoveryService {
         }))
         .then((result) => {
           if (result.status === 'unsupported') {
-            console.warn(`[mcp-oauth-discovery] "${manualName}" (${mcpUrl}): ${result.reason}`);
+            log.warn(`"${manualName}" (${mcpUrl}): ${result.reason}`);
           }
           this.asCache.set(mcpUrl, { result, expiresAt: this.now() + NEGATIVE_TTL_MS });
           return result;

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

@@ -1,6 +1,9 @@
 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
@@ -55,10 +58,7 @@ export class BevelSecretsVariableLoader implements VariableLoader {
     } catch (err) {
       // Log the fault so a backend failure is distinguishable from a merely
       // unset secret (resolve returning null) when troubleshooting.
-      console.error(
-        `[secrets-vault] resolve failed for user=${this.user_id} key=${effectiveKey}:`,
-        err instanceof Error ? err.message : String(err),
-      );
+      log.error(`resolve failed for user=${this.user_id} key=${effectiveKey}:`, { err });
       return null;
     }
   }