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

package/dist/modules/secrets-vault/db-secrets-vault.service.js

@@ -3,12 +3,13 @@ import { isDeepStrictEqual } from 'node:util';
 import { logger } from '../../shared/logging.js';
 const log = logger('vault');
 import { and, desc, eq, inArray, isNull, like, or } from 'drizzle-orm';
-import { secrets } from '../database/index.js';
+import { pgErrorCode, secrets } from '../database/index.js';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
 import { readCapped } from '../../shared/read-capped.js';
 import { standardTokenErrorCode } from '../../shared/oauth-token-error.js';
 import { isKeyInNamespace, InvalidSecretError, SecretNotFoundError, SecretOAuthError, } from './secrets-vault.contract.js';
+import { timingSafeStringEqual } from '../auth/index.js';
 const MAX_KEY_LEN = 200;
 const MAX_LABEL_LEN = 200;
 const MAX_VALUE_LEN = 100_000;
@@ -16,6 +17,32 @@ const MAX_VALUE_LEN = 100_000;
 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;
+/** Upper bound on telling a provider a managed sign-in is over, so a deletion never waits on it. */
+const REVOKE_TIMEOUT_MS = 10_000;
+/** Upper bound on a broker renewing a managed token: past it the stale token is served and the next call asks again. */
+const REFRESH_TIMEOUT_MS = 15_000;
+/** How many times a guarded replacement re-reads a row that changed under its revoke before giving up. */
+const REPLACE_ATTEMPTS = 3;
+/** How many times a handoff re-reads a row a refresh rotated under it (the nonce rides along) before refusing. */
+const HANDOFF_ATTEMPTS = 3;
+/** `work`, or a rejection once `ms` have passed: a handler that never settles must not hold the vault. */
+async function bounded(work, ms, what) {
+    let timer;
+    try {
+        return await Promise.race([
+            work,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`${what} did not settle within ${ms}ms`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** How often a managed sign-in's opening is retried against a row that keeps changing under it. */
+const BEGIN_MANAGED_ATTEMPTS = 3;
 /** How much of a refusing token endpoint's body is read for its error code: an OAuth error object, never a whole error page. */
 const TOKEN_ERROR_BODY_MAX_BYTES = 2048;
 // Hexis's own sentences for a refused token request: what to change, in our
@@ -111,6 +138,19 @@ export class DbSecretsVaultService {
     now;
     scopeOf;
     cryptoInstance = null;
+    /**
+     * How a MANAGED sign-in's tokens are renewed and revoked — through the
+     * broker and the provider respectively. Setter-injected: both depend on
+     * the connector catalog, which is built after this service. Without them a
+     * managed token that expires is served stale (a transient, retried on the
+     * next call) and a disconnect deletes without revoking.
+     */
+    managedRefresher;
+    managedRevoker;
+    setManagedTokenHandlers(handlers) {
+        this.managedRefresher = handlers.refresher;
+        this.managedRevoker = handlers.revoker;
+    }
     constructor(db, 
     /** 32-byte AES key (hex/base64); empty disables secret read/write with a clear error. */
     encKey, now = Date.now, 
@@ -178,15 +218,18 @@ export class DbSecretsVaultService {
         }
         const label = this.normaliseLabel(input.label);
         const valueEncrypted = this.crypto().encrypt(input.value);
+        // The caller's row may hold a managed sign-in: its tokens are told to the
+        // provider before this value replaces them, as on every replacement.
         // Upsert on (user_id, key): re-saving a key replaces its value in place.
-        const [row] = await this.db
+        const row = await this.revokedReplacement(and(eq(secrets.userId, userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId, key, kind: 'static', label, valueEncrypted, oauthMeta: null })
             .onConflictDoUpdate({
             target: [secrets.userId, secrets.key],
             set: { kind: 'static', label, valueEncrypted, oauthMeta: null, updatedAt: new Date() },
+            ...(guard ? { setWhere: guard } : {}),
         })
-            .returning();
+            .returning());
         this.notifyMutation(userId);
         return this.toSummary(row);
     }
@@ -198,7 +241,9 @@ export class DbSecretsVaultService {
         const blob = { clientSecret: provider.clientSecret };
         const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
         const oauthMeta = this.publicProviderMeta(provider);
-        const [row] = await this.db
+        // A managed sign-in under this key loses its tokens here: the provider is
+        // told first, as on every replacement.
+        const row = await this.revokedReplacement(and(eq(secrets.userId, userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId, key, kind: 'oauth', label, valueEncrypted, oauthMeta })
             .onConflictDoUpdate({
@@ -206,17 +251,15 @@ export class DbSecretsVaultService {
             // Replacing an oauth secret's provider config drops any existing tokens
             // (they belonged to the old client) — the user must re-authorize.
             set: { kind: 'oauth', label, valueEncrypted, oauthMeta, updatedAt: new Date() },
+            ...(guard ? { setWhere: guard } : {}),
         })
-            .returning();
+            .returning());
         this.notifyMutation(userId);
         return this.toSummary(row);
     }
     async remove(userId, id) {
-        const res = await this.db
-            .delete(secrets)
-            .where(and(eq(secrets.id, id), eq(secrets.userId, userId)))
-            .returning({ id: secrets.id });
-        if (res.length === 0)
+        const gone = await this.revokeThenDelete(and(eq(secrets.id, id), eq(secrets.userId, userId)));
+        if (gone.length === 0)
             throw new SecretNotFoundError(id);
         this.notifyMutation(userId);
     }
@@ -230,38 +273,186 @@ export class DbSecretsVaultService {
         }
         const label = this.normaliseLabel(input.label);
         const valueEncrypted = this.crypto().encrypt(input.value);
+        // A shared row that held a managed workspace connection is told to its
+        // provider before this value replaces it; the tokens would otherwise go
+        // unrevoked with the row's kind.
         // Upsert the ONE shared row for this key (user_id NULL). The conflict target
         // is the partial unique index `secrets_shared_key_unq` — hence `targetWhere`.
-        const [row] = await this.db
+        const row = await this.revokedReplacement(and(isNull(secrets.userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId: null, key, kind: 'static', label, valueEncrypted, oauthMeta: null })
             .onConflictDoUpdate({
             target: secrets.key,
             targetWhere: isNull(secrets.userId),
             set: { kind: 'static', label, valueEncrypted, oauthMeta: null, updatedAt: new Date() },
+            ...(guard ? { setWhere: guard } : {}),
         })
-            .returning();
+            .returning());
         this.notifyMutation(null);
         return this.toSummary(row);
     }
     async removeShared(key) {
-        const res = await this.db
-            .delete(secrets)
-            .where(and(isNull(secrets.userId), eq(secrets.key, key)))
-            .returning({ id: secrets.id });
-        if (res.length === 0)
+        const gone = await this.revokeThenDelete(and(isNull(secrets.userId), eq(secrets.key, key)));
+        if (gone.length === 0)
             throw new SecretNotFoundError(key);
         this.notifyMutation(null);
     }
     async removeUserByKey(userId, key) {
-        const res = await this.db
-            .delete(secrets)
-            .where(and(eq(secrets.userId, userId), eq(secrets.key, key)))
-            .returning({ id: secrets.id });
-        if (res.length === 0)
+        const gone = await this.revokeThenDelete(and(eq(secrets.userId, userId), eq(secrets.key, key)));
+        if (gone.length === 0)
             throw new SecretNotFoundError(key);
         this.notifyMutation(userId);
     }
+    /**
+     * Delete the rows `where` names, each told to its provider first when it
+     * is a managed sign-in with tokens (see {@link revokeRow}). The delete is
+     * guarded on the ciphertext the revoke read: a handoff or a refresh landing
+     * in between has replaced the tokens, and deleting THOSE unrevoked is the
+     * leak the revoke exists to prevent. A miss re-reads the row and goes
+     * again, bounded; what could not be settled in those passes is left
+     * standing rather than deleted blind.
+     */
+    async revokeThenDelete(where) {
+        // No revoker, nothing to read first: one plain delete, as every removal
+        // was before managed sign-ins, and no miss to re-read for.
+        if (!this.managedRevoker) {
+            return this.db.delete(secrets).where(where).returning({ id: secrets.id, userId: secrets.userId, kind: secrets.kind });
+        }
+        const gone = [];
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const rows = await this.db.select().from(secrets).where(where);
+            if (rows.length === 0)
+                break;
+            // Every row's revocation at once, so a bulk delete (a namespace, a
+            // person's connections) waits one revocation's bound, not one per row.
+            await Promise.all(rows.map((row) => this.revokeRow(row)));
+            let missed = false;
+            for (const row of rows) {
+                const deleted = await this.db
+                    .delete(secrets)
+                    .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
+                    .returning({ id: secrets.id, userId: secrets.userId, kind: secrets.kind });
+                if (deleted.length === 0)
+                    missed = true;
+                else
+                    gone.push(...deleted);
+            }
+            if (!missed)
+                break;
+        }
+        return gone;
+    }
+    async removeManagedRowsOfUser(userId, within) {
+        if (within)
+            return this.removeManagedRowsLocked(userId, within);
+        // Every oauth row of the user whose meta names a managed app. Read
+        // first (the managed mark lives in JSON the WHERE cannot see), revoked,
+        // then deleted by id; the per-user filter on the delete is what keeps a
+        // row read for this user from ever deleting another's.
+        const rows = await this.db
+            .select()
+            .from(secrets)
+            .where(and(eq(secrets.userId, userId), eq(secrets.kind, 'oauth')));
+        const managed = rows.filter((r) => this.managedRefOf(r.oauthMeta) !== null);
+        if (managed.length === 0)
+            return 0;
+        const deleted = await this.revokeThenDelete(and(eq(secrets.userId, userId), inArray(secrets.id, managed.map((r) => r.id))));
+        if (deleted.length > 0)
+            this.notifyMutation(userId);
+        // A row the guarded delete could not settle (its tokens kept changing
+        // under the revoke) is still here, unrevoked. The caller is told rather
+        // than left to believe the person holds nothing: an erasure refuses and
+        // is retried, a switch-off logs it and the row is refused on use.
+        if (deleted.length < managed.length) {
+            throw new SecretOAuthError(`${managed.length - deleted.length} managed sign-in(s) kept changing while being revoked and were not removed; try again`);
+        }
+        return deleted.length;
+    }
+    /**
+     * The same removal inside a caller's transaction (an account erasure, just
+     * before the user row goes): the rows are LOCKED for the transaction, so a
+     * handoff or a refresh arriving now waits and then finds no row, which is
+     * what makes the revoke final. No guard is needed under the lock; the
+     * revoke stays bounded (see {@link revokeRow}), so the transaction never
+     * waits on a provider longer than that.
+     */
+    async removeManagedRowsLocked(userId, tx) {
+        const rows = await tx
+            .select()
+            .from(secrets)
+            .where(and(eq(secrets.userId, userId), eq(secrets.kind, 'oauth')))
+            .for('update');
+        const managed = rows.filter((r) => this.managedRefOf(r.oauthMeta) !== null);
+        if (managed.length === 0)
+            return 0;
+        await Promise.all(managed.map((row) => this.revokeRow(row)));
+        await tx.delete(secrets).where(and(eq(secrets.userId, userId), inArray(secrets.id, managed.map((r) => r.id))));
+        this.notifyMutation(userId);
+        return managed.length;
+    }
+    /**
+     * Replace what `where` names with `write`, a managed sign-in's tokens told
+     * to their provider first (see {@link revokeRow}; best effort, never holding
+     * the user's decision). The write is guarded on the ciphertext the revoke
+     * read (`setWhere`): a refresh or a handoff landing in between has rotated
+     * the tokens, and writing over THOSE unrevoked is the leak the revoke exists
+     * to prevent — as the guarded delete of {@link revokeThenDelete}. A miss
+     * re-reads and goes again, bounded; a row that kept changing is left as it
+     * is and the caller is told. With no revoker wired there is nothing to read
+     * first: one plain write, as every replacement was before managed sign-ins.
+     */
+    async revokedReplacement(where, write) {
+        if (!this.managedRevoker)
+            return (await write())[0];
+        for (let attempt = 0; attempt < REPLACE_ATTEMPTS; attempt++) {
+            const rows = await this.db.select().from(secrets).where(where);
+            await Promise.all(rows.map((row) => this.revokeRow(row)));
+            // The row as it was read, or no row at all: a conflict with anything
+            // else (a row written meanwhile) is a miss, and the next pass reads it.
+            const guard = rows.length > 0
+                ? inArray(secrets.valueEncrypted, rows.map((row) => row.valueEncrypted))
+                : eq(secrets.valueEncrypted, '');
+            const written = await write(guard);
+            if (written.length > 0)
+                return written[0];
+        }
+        throw new SecretOAuthError('the sign-in kept changing while being replaced; try again');
+    }
+    async revokeRow(row) {
+        if (!this.managedRevoker || row.kind !== 'oauth')
+            return;
+        const ref = this.managedRefOf(row.oauthMeta);
+        if (!ref)
+            return;
+        const tokens = this.readTokensSafe(row.valueEncrypted);
+        if (!tokens?.access_token)
+            return;
+        // Bounded: the delete that follows is the user's decision, and a revoker
+        // that never settles must not hold it.
+        try {
+            await bounded(this.managedRevoker.revoke(ref, { access_token: tokens.access_token, refresh_token: tokens.refresh_token }), REVOKE_TIMEOUT_MS, 'revocation');
+        }
+        catch (err) {
+            // The key and the connector name the sign-in. The error itself stays
+            // out: a revoker's message is its own, and this line is the one place a
+            // token could otherwise reach a log from this path.
+            log.warn('revoking a managed sign-in with its provider failed; deleting it here anyway', {
+                key: row.key,
+                connector: ref.connectorId,
+                failure: err instanceof Error ? err.name : typeof err,
+            });
+        }
+    }
+    /** The managed reference a row's public meta carries, or null for an ordinary sign-in. */
+    managedRefOf(raw) {
+        const meta = (raw ?? {});
+        const m = meta.managed;
+        if (!m || typeof m !== 'object')
+            return null;
+        const connectorId = typeof m.connectorId === 'string' ? m.connectorId : '';
+        const scopeSet = typeof m.scopeSet === 'string' ? m.scopeSet : '';
+        return connectorId && scopeSet ? { connectorId, scopeSet } : null;
+    }
     async countNamespace(prefix) {
         return tally(await this.namespaceRows(prefix));
     }
@@ -282,10 +473,10 @@ export class DbSecretsVaultService {
                 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 });
+                // A managed sign-in under the namespace is told to its provider
+                // before the delete, for the same reason the per-row removals do —
+                // and guarded the same way, when a revoker is there to need it.
+                const deleted = await this.revokeThenDelete(inArray(secrets.id, rows.map((r) => r.id)));
                 gone.push(...deleted);
             }
         }
@@ -335,6 +526,7 @@ export class DbSecretsVaultService {
             userId: secrets.userId,
             kind: secrets.kind,
             valueEncrypted: secrets.valueEncrypted,
+            oauthMeta: secrets.oauthMeta,
         })
             .from(secrets)
             .where(and(inArray(secrets.key, keys), or(isNull(secrets.userId), eq(secrets.userId, userId))));
@@ -343,6 +535,15 @@ export class DbSecretsVaultService {
             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;
+            // The shared row holds tokens only for a managed workspace connection;
+            // an ordinary sign-in's shared row is the client secret and reads as
+            // "no tokens" here, which is the truthful answer for it.
+            const adminTokens = adminRow?.kind === 'oauth' ? this.readTokensSafe(adminRow.valueEncrypted) : undefined;
+            const adminMeta = (adminRow?.oauthMeta ?? null);
+            const accountOf = (meta) => {
+                const a = meta?.account;
+                return typeof a === 'string' && a ? a : undefined;
+            };
             return {
                 key,
                 adminConfigured: !!adminRow,
@@ -356,9 +557,154 @@ export class DbSecretsVaultService {
                 // Only meaningful for an oauth row: the scopes the caller's token was granted,
                 // so a coverage check can tell whether it still covers the tool's live scopes.
                 grantedScopes: userRow?.kind === 'oauth' ? tokens?.scope : undefined,
+                adminAuthorized: adminRow?.kind === 'oauth' ? Boolean(adminTokens?.access_token) : undefined,
+                adminGrantedScopes: adminRow?.kind === 'oauth' ? adminTokens?.scope : undefined,
+                userAccount: userRow?.kind === 'oauth' ? accountOf(userRow.oauthMeta) : undefined,
+                adminAccount: adminRow?.kind === 'oauth' ? accountOf(adminMeta) : undefined,
+                // An owner's own app on the shared row: a client id without the managed mark.
+                adminBringsOwnApp: adminRow?.kind === 'oauth'
+                    ? this.managedRefOf(adminMeta) === null && typeof adminMeta?.clientId === 'string' && adminMeta.clientId !== ''
+                    : undefined,
             };
         });
     }
+    async beginManagedConnection(input) {
+        const key = this.requireKey(input.key);
+        const userId = input.userId === null ? null : this.requireUserId(input.userId);
+        const ref = input.provider.managed;
+        if (!ref)
+            throw new InvalidSecretError('a managed sign-in needs its connector reference');
+        if (typeof input.nonce !== 'string' || input.nonce.length < 16)
+            throw new InvalidSecretError('nonce is required');
+        const oauthMeta = this.publicProviderMeta(this.requireProvider(input.provider, { managed: true }));
+        const where = userId === null ? and(isNull(secrets.userId), eq(secrets.key, key)) : and(eq(secrets.userId, userId), eq(secrets.key, key));
+        // Read-modify-write on a LIVE credential: a refresh running concurrently
+        // may rotate the tokens between the read and the write, and writing our
+        // copy over them would leave the row holding a dead refresh token. So the
+        // update is guarded on the ciphertext read, and a miss re-reads and
+        // rebuilds from the fresh row; bounded, so a row that keeps changing
+        // fails loudly rather than forever. The same rule `beginOAuth` follows.
+        for (let attempt = 0; attempt < BEGIN_MANAGED_ATTEMPTS; attempt++) {
+            const [existing] = await this.db.select().from(secrets).where(where).limit(1);
+            // Keep what the SAME connection already holds (its tokens, so an
+            // abandoned reconnect costs nothing). The same connection means the same
+            // connector and scope set: a row of another connector's, or of another
+            // set's, holds a token for something else, and a declaration that
+            // changed must not hand it to the new one. Start clean over anything
+            // else too — a static value or an owner-app sign-in under this key.
+            const storedRef = existing?.kind === 'oauth' ? this.managedRefOf(existing.oauthMeta) : null;
+            const sameConnection = storedRef !== null && storedRef.connectorId === ref.connectorId && storedRef.scopeSet === ref.scopeSet;
+            let kept = {};
+            if (existing && sameConnection) {
+                try {
+                    kept = this.readBlob(existing.valueEncrypted);
+                }
+                catch {
+                    kept = {};
+                }
+            }
+            const next = { tokens: kept.tokens, pendingNonce: input.nonce };
+            const valueEncrypted = this.crypto().encrypt(JSON.stringify(next));
+            const account = sameConnection ? existing.oauthMeta?.account : undefined;
+            const meta = typeof account === 'string' && account ? { ...oauthMeta, account } : oauthMeta;
+            if (!existing) {
+                try {
+                    await this.db.insert(secrets).values({ userId, key, kind: 'oauth', label: null, valueEncrypted, oauthMeta: meta });
+                    return;
+                }
+                catch (err) {
+                    // Another start of the same sign-in inserted the row first: the
+                    // next pass finds it and updates it, as it would any existing row.
+                    if (pgErrorCode(err) === '23505')
+                        continue; // unique_violation
+                    throw err;
+                }
+            }
+            // A row that held ANOTHER connection's tokens is about to lose them:
+            // the provider is told first, as on every other replacement.
+            if (!sameConnection && storedRef)
+                await this.revokeRow(existing);
+            const written = await this.db
+                .update(secrets)
+                .set({ kind: 'oauth', valueEncrypted, oauthMeta: meta, updatedAt: new Date() })
+                .where(and(eq(secrets.id, existing.id), eq(secrets.valueEncrypted, existing.valueEncrypted)))
+                .returning({ id: secrets.id });
+            if (Array.isArray(written) && written.length === 0)
+                continue;
+            // A row that held something ELSE (a value, another connection's
+            // tokens, an owner's app) no longer does: caches keyed on it are told.
+            // The same connection's tokens carried over unchanged tell nobody.
+            if (!kept.tokens)
+                this.notifyMutation(userId);
+            return;
+        }
+        throw new SecretOAuthError('The sign-in could not be opened: its stored credential kept changing. Try again.');
+    }
+    async completeManagedConnection(input) {
+        const key = this.requireKey(input.key);
+        const userId = input.userId === null ? null : this.requireUserId(input.userId);
+        const where = userId === null ? and(isNull(secrets.userId), eq(secrets.key, key)) : and(eq(secrets.userId, userId), eq(secrets.key, key));
+        // Every refusal below is the same words: a caller that can tell "no such
+        // sign-in" from "wrong nonce" from "already used" has learned which rows
+        // exist, and the handoff route is reachable with the broker secret alone.
+        const refused = () => new SecretOAuthError('No managed sign-in is waiting for this handoff');
+        const tokens = input.tokens;
+        if (typeof tokens?.access_token !== 'string' || !tokens.access_token) {
+            throw new InvalidSecretError('the handoff carries no access token');
+        }
+        // Read, check the nonce, write guarded on what was read; and again when
+        // the write misses. A miss with the nonce still on the row is a refresh
+        // that rotated the row's tokens meanwhile (a refresh carries the nonce
+        // across, see `inFlightOf`), not a second handoff: the broker delivered
+        // these tokens once, and refusing them would lose a valid sign-in for
+        // good. A row whose nonce is gone or changed refuses on the re-read.
+        for (let attempt = 0;; attempt++) {
+            const [row] = await this.db.select().from(secrets).where(where).limit(1);
+            if (!row || row.kind !== 'oauth' || !this.managedRefOf(row.oauthMeta))
+                throw refused();
+            let blob;
+            try {
+                blob = this.readBlob(row.valueEncrypted);
+            }
+            catch {
+                throw refused();
+            }
+            if (!blob.pendingNonce || typeof input.nonce !== 'string' || !timingSafeStringEqual(input.nonce, blob.pendingNonce)) {
+                throw refused();
+            }
+            const meta = { ...(row.oauthMeta ?? {}) };
+            // A broker that echoes no `scope` delivered what the sign-in asked for:
+            // the scopes the row was opened with stand in, as `pendingScopes` does
+            // for the code exchange. Stored as unknown, the grant would count as
+            // covering nothing, and the sign-in would read as under-scoped for good.
+            // An EMPTY scope is not "none echoed": it is an empty grant, kept as such.
+            const requested = Array.isArray(meta.scopes) && meta.scopes.length > 0 ? meta.scopes.map(String).join(' ') : undefined;
+            const stored = {
+                access_token: tokens.access_token,
+                refresh_token: typeof tokens.refresh_token === 'string' ? tokens.refresh_token : undefined,
+                expires_at: typeof tokens.expires_at === 'number' ? tokens.expires_at : undefined,
+                token_type: typeof tokens.token_type === 'string' ? tokens.token_type : undefined,
+                scope: typeof tokens.scope === 'string' ? tokens.scope : requested,
+            };
+            // The nonce is one-time: it leaves with the handoff it was minted for,
+            // so the same handoff presented twice finds nothing to match.
+            const next = { tokens: stored };
+            if (typeof input.account === 'string' && input.account.trim())
+                meta.account = input.account.trim().slice(0, MAX_LABEL_LEN);
+            // Guarded on the ciphertext read above: two handoffs racing for one
+            // nonce cannot both land, whichever the provider sent first wins.
+            const landed = await this.db
+                .update(secrets)
+                .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), oauthMeta: meta, updatedAt: new Date() })
+                .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
+                .returning({ id: secrets.id });
+            if (!(Array.isArray(landed) && landed.length === 0))
+                break;
+            if (attempt + 1 >= HANDOFF_ATTEMPTS)
+                throw refused();
+        }
+        this.notifyMutation(userId);
+    }
     /**
      * Decrypt+parse an oauth row's token set once, or undefined if the blob can't be
      * read — a corrupted row or rotated encKey must degrade to "not authorized", not throw.
@@ -495,14 +841,18 @@ export class DbSecretsVaultService {
         const blob = { clientSecret: provider.clientSecret };
         const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
         const oauthMeta = this.publicProviderMeta(provider);
-        await this.db
+        // An owner's own app replacing a managed workspace connection: the
+        // connection's tokens are revoked with the provider before they go.
+        await this.revokedReplacement(and(isNull(secrets.userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId: null, key, kind: 'oauth', label: null, valueEncrypted, oauthMeta })
             .onConflictDoUpdate({
             target: secrets.key,
             targetWhere: isNull(secrets.userId),
             set: { kind: 'oauth', valueEncrypted, oauthMeta, updatedAt: new Date() },
-        });
+            ...(guard ? { setWhere: guard } : {}),
+        })
+            .returning({ id: secrets.id }));
         this.notifyMutation(null);
     }
     async beginToolOAuthByKey(input) {
@@ -532,8 +882,11 @@ export class DbSecretsVaultService {
             }
             // The save's own validation (https, no private or local address), BEFORE
             // the caller's row is written or a URL built: a declaration that fails it
-            // sends nothing anywhere.
-            meta = this.requireProvider({ ...input.provider, publicClient: false });
+            // sends nothing anywhere. A MANAGED declaration names no client of its
+            // own; reaching here means an owner pinned the deployment's own app on
+            // the shared row, and that app's id is the one the flow runs with.
+            const clientId = input.provider.clientId || this.readMeta(shared.oauthMeta).clientId;
+            meta = this.requireProvider({ ...input.provider, clientId, publicClient: false });
             oauthMeta = this.publicProviderMeta(meta);
             // A MOVED PROPERTY, decided on the ticket (OAuth-Sign-In-Follows-The-Live-
             // Declaration, 2026-10-27): the secret used to be bound to the token
@@ -610,14 +963,20 @@ export class DbSecretsVaultService {
             pendingScopes,
         };
         const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
-        const [row] = await this.db
+        // A managed sign-in on the caller's row (an owner pinned their own app
+        // after the person connected through the broker) is replaced by this
+        // start: its tokens are told to the provider first, and the write is
+        // guarded on what the revoke read. Tokens carried over above were minted
+        // under THIS configuration, never a managed one.
+        const row = await this.revokedReplacement(and(eq(secrets.userId, userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId, key, kind: 'oauth', label: shared.label, valueEncrypted, oauthMeta })
             .onConflictDoUpdate({
             target: [secrets.userId, secrets.key],
             set: { kind: 'oauth', valueEncrypted, oauthMeta, updatedAt: new Date() },
+            ...(guard ? { setWhere: guard } : {}),
         })
-            .returning();
+            .returning());
         // Build the consent URL exactly as beginOAuth does, from the configuration
         // this start uses, with the requested scopes chosen above.
         const url = new URL(meta.authorizationUrl);
@@ -695,10 +1054,16 @@ export class DbSecretsVaultService {
         return result.accessToken;
     }
     async forceRefresh(userId, key) {
+        // The caller's own row, or — for a variable the manual declares shared
+        // (a managed workspace connection) — the one shared row every caller
+        // resolves. Same tier rule as `resolve`, so a 401 against a shared
+        // token repairs the row the call actually used.
+        const scope = (await this.scopeOf?.(key)) ?? 'admin';
+        const scopeFilter = scope === 'user' ? eq(secrets.userId, userId) : isNull(secrets.userId);
         const [row] = await this.db
             .select()
             .from(secrets)
-            .where(and(eq(secrets.userId, userId), eq(secrets.key, key)))
+            .where(and(scopeFilter, eq(secrets.key, key)))
             .limit(1);
         if (!row || row.kind !== 'oauth')
             return 'skipped';
@@ -739,18 +1104,38 @@ export class DbSecretsVaultService {
             return this.wipeTokens(row, blob);
         }
         const meta = this.readMeta(row.oauthMeta);
-        const body = new URLSearchParams({
-            grant_type: 'refresh_token',
-            refresh_token: tokens.refresh_token,
-            client_id: meta.clientId,
-        });
-        if (blob.clientSecret)
-            body.set('client_secret', blob.clientSecret);
-        if (meta.resource)
-            body.set('resource', meta.resource);
         let refreshed;
         try {
-            refreshed = await this.tokenRequest(meta.tokenUrl, body);
+            if (meta.managed) {
+                // A managed sign-in renews through the broker, which holds the
+                // client secret this deployment never sees. No broker wired is an
+                // outage from here, not a dead grant: the stale token is served and
+                // the next call asks again.
+                if (!this.managedRefresher)
+                    return { outcome: 'transient' };
+                // Bounded like a revocation: a broker that never answers is an outage
+                // (the stale token is served) and must not hold every resolution.
+                const delivered = await bounded(this.managedRefresher.refresh(meta.managed, tokens.refresh_token), REFRESH_TIMEOUT_MS, 'the broker refresh');
+                refreshed = {
+                    access_token: delivered.access_token,
+                    refresh_token: delivered.refresh_token,
+                    expires_at: delivered.expires_at,
+                    token_type: delivered.token_type,
+                    scope: delivered.scope,
+                };
+            }
+            else {
+                const body = new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    refresh_token: tokens.refresh_token,
+                    client_id: meta.clientId,
+                });
+                if (blob.clientSecret)
+                    body.set('client_secret', blob.clientSecret);
+                if (meta.resource)
+                    body.set('resource', meta.resource);
+                refreshed = await this.tokenRequest(meta.tokenUrl, body);
+            }
         }
         catch (err) {
             // A DEFINITIVE provider rejection (400/401 — invalid_grant and friends)
@@ -771,7 +1156,12 @@ export class DbSecretsVaultService {
                     : result.outcome === 'refreshed'
                         ? 'the row had been rotated by a concurrent refresh meanwhile; the rotated sign-in is kept'
                         : 'the row had been removed or replaced meanwhile; nothing wiped';
-                log.warn(`refresh refused for "${row.key}", ${did}: ${err.message}`);
+                // A managed row's refusal came from the refresher, whose words are its
+                // own (a port may put the refresh token it was handed in them): only
+                // the status it reported is logged. The vault's own token request
+                // writes fixed sentences, which are safe to repeat.
+                const why = meta.managed ? `the broker refused it (HTTP ${err.providerStatus ?? 'unknown'})` : err.message;
+                log.warn(`refresh refused for "${row.key}", ${did}: ${why}`);
                 return result;
             }
             return { outcome: 'transient' };
@@ -785,7 +1175,10 @@ export class DbSecretsVaultService {
         // value, empty included, is the provider's word.
         if (refreshed.scope === undefined)
             refreshed.scope = tokens.scope;
-        const next = { clientSecret: blob.clientSecret, tokens: refreshed };
+        // A sign-in in flight on this row (a managed reconnect waiting for its
+        // handoff, a consent waiting for its exchange) survives the refresh: the
+        // nonce or verifier it minted is what that handoff must match.
+        const next = { clientSecret: blob.clientSecret, tokens: refreshed, ...this.inFlightOf(blob) };
         // Optimistic concurrency: only persist if the stored ciphertext is unchanged,
         // so a concurrent refresh on the same row doesn't clobber (Microsoft pattern).
         const stored = await this.db
@@ -831,9 +1224,23 @@ export class DbSecretsVaultService {
             return undefined;
         }
     }
-    /** Drop a dead grant's token set, keeping the client secret. See {@link refreshRow}. */
+    /**
+     * What a row holds for a sign-in IN FLIGHT: the one-time nonce a managed
+     * handoff must echo, the PKCE verifier and requested scopes a code exchange
+     * must present. A refresh or a wipe rewrites the row's tokens, never these:
+     * dropping them would refuse the handoff or the exchange that is about to
+     * land, for a reason the person could not see.
+     */
+    inFlightOf(blob) {
+        return {
+            ...(blob.pendingNonce ? { pendingNonce: blob.pendingNonce } : {}),
+            ...(blob.pendingVerifier ? { pendingVerifier: blob.pendingVerifier } : {}),
+            ...(blob.pendingScopes ? { pendingScopes: blob.pendingScopes } : {}),
+        };
+    }
+    /** Drop a dead grant's token set, keeping the client secret and any sign-in in flight. See {@link refreshRow}. */
     async wipeTokens(row, blob) {
-        const next = { clientSecret: blob.clientSecret };
+        const next = { clientSecret: blob.clientSecret, ...this.inFlightOf(blob) };
         // 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
@@ -866,7 +1273,7 @@ export class DbSecretsVaultService {
         const blob = { clientSecret: provider.clientSecret };
         const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
         const oauthMeta = this.publicProviderMeta(provider);
-        await this.db
+        await this.revokedReplacement(and(isNull(secrets.userId), eq(secrets.key, key)), (guard) => this.db
             .insert(secrets)
             .values({ userId: null, key, kind: 'oauth', label, valueEncrypted, oauthMeta })
             // Preserve an existing row's label on re-upsert (matches
@@ -876,7 +1283,9 @@ export class DbSecretsVaultService {
             target: secrets.key,
             targetWhere: isNull(secrets.userId),
             set: { kind: 'oauth', valueEncrypted, oauthMeta, updatedAt: new Date() },
-        });
+            ...(guard ? { setWhere: guard } : {}),
+        })
+            .returning({ id: secrets.id }));
         this.notifyMutation(null);
     }
     async getSharedOAuthProvider(key) {
@@ -970,13 +1379,17 @@ export class DbSecretsVaultService {
         const authorizationUrl = typeof meta.authorizationUrl === 'string' ? meta.authorizationUrl : '';
         const tokenUrl = typeof meta.tokenUrl === 'string' ? meta.tokenUrl : '';
         const clientId = typeof meta.clientId === 'string' ? meta.clientId : '';
-        if (!authorizationUrl || !tokenUrl || !clientId) {
+        const managed = this.managedRefOf(meta) ?? undefined;
+        // A managed row has no client id of its own (the broker's app is the
+        // client); everything else must name one, or no flow can run from it.
+        if (!authorizationUrl || !tokenUrl || (!clientId && !managed)) {
             throw new SecretOAuthError('OAuth secret is missing provider configuration');
         }
         return {
             authorizationUrl,
             tokenUrl,
             clientId,
+            managed,
             scopes: Array.isArray(meta.scopes) ? meta.scopes.map(String) : undefined,
             authParams: meta.authParams && typeof meta.authParams === 'object'
                 ? meta.authParams
@@ -996,16 +1409,27 @@ export class DbSecretsVaultService {
             ...(p.pkce ? { pkce: true } : {}),
             ...(p.publicClient ? { publicClient: true } : {}),
             ...(p.resource ? { resource: p.resource } : {}),
+            ...(p.managed ? { managed: { connectorId: p.managed.connectorId, scopeSet: p.managed.scopeSet } } : {}),
+            ...(p.account ? { account: p.account } : {}),
         };
     }
-    requireProvider(p) {
+    /**
+     * @param opts.managed Accept a MANAGED provider (no client id of its own,
+     *   a connector reference instead). Only the managed sign-in paths pass it:
+     *   everywhere else a provider needs a client id, and a `managed` field a
+     *   caller slipped in is dropped rather than making the row one.
+     */
+    requireProvider(p, opts = {}) {
         if (!p || typeof p !== 'object')
             throw new InvalidSecretError('provider is required');
         const cfg = p;
         const authorizationUrl = this.requireUrl(cfg.authorizationUrl, 'authorizationUrl');
         const tokenUrl = this.requireUrl(cfg.tokenUrl, 'tokenUrl');
-        const clientId = typeof cfg.clientId === 'string' ? cfg.clientId.trim() : '';
-        if (!clientId)
+        const managed = opts.managed ? (this.managedRefOf(cfg) ?? undefined) : undefined;
+        // A managed sign-in has no client of its own: whatever id a caller sends
+        // beside the connector reference is not stored, so no row can claim one.
+        const clientId = managed ? '' : typeof cfg.clientId === 'string' ? cfg.clientId.trim() : '';
+        if (!clientId && !managed)
             throw new InvalidSecretError('clientId is required');
         const scopes = Array.isArray(cfg.scopes) ? cfg.scopes.map(String) : undefined;
         const authParams = cfg.authParams && typeof cfg.authParams === 'object'
@@ -1025,6 +1449,8 @@ export class DbSecretsVaultService {
             resource: typeof cfg.resource === 'string' && cfg.resource.trim()
                 ? this.requireUrl(cfg.resource, 'resource')
                 : undefined,
+            managed,
+            account: typeof cfg.account === 'string' && cfg.account.trim() ? cfg.account.trim().slice(0, MAX_LABEL_LEN) : undefined,
         };
     }
     requireUrl(value, field) {