@runuai/host 0.9.138 → 0.9.140

package/lib/github-tokens.ts

@@ -9,7 +9,7 @@
 
 import { and, eq } from "drizzle-orm";
 
-import { queueStoreWrite, userParameterName } from "./credential-store";
+import { configuredCredentialStore, queueStoreWrite, userParameterName } from "./credential-store";
 import { getDb, schema } from "./db";
 import { sealAesGcm, openAesGcm } from "./secrets";
 import { dockerCli } from "./docker-exec";
@@ -34,6 +34,7 @@ import {
 } from "./git-identity";
 import type { TaskEnvironmentHandle } from "./task-environment/types";
 import { sidecarMode } from "./sidecar";
+import { signInBoxMode } from "./signin-box";
 import {
   MAX_GITHUB_INSTALLATIONS,
   MAX_GITHUB_REPOSITORIES_PER_INSTALLATION,
@@ -403,7 +404,22 @@ export async function onConnectSet(
     // Invalidate and drain them before publishing the replacement grant.
     await deps.invalidateCredentials?.(frame.userId);
 
-    (deps.storeLocal ?? storeTokenRow)(frame.userId, fields);
+    if (deps.storeLocal) deps.storeLocal(frame.userId, fields);
+    else if (signInBoxMode()) {
+      // ADR-136 sign-in box: the store first, awaited; a row with no
+      // material; the token in the bounded cache only.
+      await storeGithubTokenStoreFirst(
+        frame.userId,
+        {
+          installationId: fields.installationId,
+          generation: fields.generation,
+          refreshTokenExpiresAt: fields.refreshTokenExpiresAt,
+          kind,
+          updatedAt: now,
+        },
+        token,
+      );
+    } else storeTokenRow(frame.userId, fields);
     replacementStored = true;
     // Advance again only after the replacement is durable. This detaches work
     // started during the no-grant fence and lets reconciliation capture B.
@@ -448,6 +464,7 @@ export async function onConnectSet(
 }
 
 function deleteStoredTokenRow(userId: string): void {
+  forgetGithubToken(userId);
   const result = getDb()
     .delete(schema.githubTokens)
     .where(eq(schema.githubTokens.userId, userId))
@@ -515,7 +532,9 @@ export function githubTokenParameterName(userId: string): string {
   return userParameterName(userId, "github");
 }
 
-/** The row as it is mirrored (token decrypted). Never logged. */
+/** The row as it is mirrored (token decrypted). Never logged. On the
+ *  sign-in box a store-held row yields the cached token, or null when the
+ *  cache is cold — there is nothing here to mirror then. */
 export function githubTokenStoreValue(userId: string): StoredGithubToken | null {
   const row = getDb()
     .select()
@@ -523,6 +542,13 @@ export function githubTokenStoreValue(userId: string): StoredGithubToken | null
     .where(eq(schema.githubTokens.userId, userId))
     .get();
   if (!row) return null;
+  const token = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (token === null) return null;
   return {
     v: 1,
     kind: "github",
@@ -530,10 +556,7 @@ export function githubTokenStoreValue(userId: string): StoredGithubToken | null
     installationId: row.installationId,
     generation: row.generation,
     tokenKind: row.kind,
-    token: openAesGcm(
-      Buffer.from(row.refreshTokenCt as Uint8Array),
-      Buffer.from(row.refreshTokenNonce as Uint8Array),
-    ),
+    token,
     expiresAt: row.refreshTokenExpiresAt ?? null,
     updatedAt: row.updatedAt,
   };
@@ -555,6 +578,8 @@ export function listGithubTokenStoreRows(): Array<{ userId: string; storeRef: st
 }
 
 export function mirrorGithubTokenToStore(userId: string): void {
+  // ADR-136 sign-in box: rows hold no material; the store was written first.
+  if (signInBoxMode()) return;
   queueStoreWrite(`mirror github token ${userId}`, async (store) => {
     const value = githubTokenStoreValue(userId);
     if (!value) return;
@@ -754,10 +779,15 @@ function readStoredToken(
     .where(eq(schema.githubTokens.userId, userId))
     .get();
   if (!row) return null;
-  const token = openAesGcm(
-    Buffer.from(row.refreshTokenCt as Uint8Array),
-    Buffer.from(row.refreshTokenNonce as Uint8Array),
-  );
+  // ADR-136 sign-in box: a store-held row answers from the bounded cache
+  // (filled by `loadGithubTokenIntoCache` on the async paths) or not at all.
+  const token = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (token === null) return null;
   return {
     token,
     kind: row.kind,
@@ -775,6 +805,7 @@ function readCurrentStoredToken(userId: string): PersistedGitHubGrant | null {
 }
 
 export function deleteToken(userId: string): void {
+  forgetGithubToken(userId);
   getDb()
     .delete(schema.githubTokens)
     .where(eq(schema.githubTokens.userId, userId))
@@ -785,7 +816,14 @@ export function deleteToken(userId: string): void {
 }
 
 export function hasToken(userId: string): boolean {
-  return readCurrentStoredToken(userId) !== null;
+  // Metadata only: a store-held row (sign-in box) counts as connected whether
+  // or not its token is in the cache right now.
+  const row = getDb()
+    .select({ generation: schema.githubTokens.generation })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  return row !== undefined && githubCredentialGenerationMatches(userId, row.generation);
 }
 
 /** All cloud user ids with a GitHub token on this host (for capabilities). */
@@ -1299,9 +1337,20 @@ export function clearAllAccessCache(): void {
   githubAuthGenerations.clear();
 }
 
-export function requestAccessToken(
+export async function requestAccessToken(
   userId: string,
 ): Promise<{ accessToken: string; expiresAt: number | null } | null> {
+  // ADR-136 sign-in box: the token is read from the store on demand for
+  // the installation listing and a legacy exchange, never kept on disk.
+  if (signInBoxMode()) {
+    try {
+      await loadGithubTokenIntoCache(userId);
+    } catch (err) {
+      console.warn(
+        `[github] user ${userId}: could not read the token from the credential store: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
   const generation = githubAuthGeneration(userId);
   // ADR-033 non-expiring path: the stored token IS the access token — return it
   // directly, no exchange/cache/rotation. `expiresAt: null` ⇒ no refresh.
@@ -1361,10 +1410,13 @@ async function doRequestAccessToken(
   });
   if (!row) return null;
 
-  const refreshToken = openAesGcm(
-    Buffer.from(row.refreshTokenCt as Uint8Array),
-    Buffer.from(row.refreshTokenNonce as Uint8Array),
-  );
+  const refreshToken = isStoreHeldGithubRow(row)
+    ? cachedGithubToken(userId)
+    : openAesGcm(
+        Buffer.from(row.refreshTokenCt as Uint8Array),
+        Buffer.from(row.refreshTokenNonce as Uint8Array),
+      );
+  if (refreshToken === null) return null;
   const res = await fetch(exchangeUrl(), {
     method: "POST",
     headers: {
@@ -1394,6 +1446,28 @@ async function doRequestAccessToken(
   // exchange was in flight. Never overwrite that newer grant with the rotated
   // refresh token from the superseded exchange.
   if (
+    data.refreshToken &&
+    githubAuthGeneration(userId) === generation &&
+    isStoreHeldGithubRow(row)
+  ) {
+    // ADR-136 sign-in box: the rotated token goes to the cache and the store,
+    // never onto the row.
+    rememberGithubToken(userId, data.refreshToken);
+    const rotated: StoredGithubToken = {
+      v: 1,
+      kind: "github",
+      userId,
+      installationId: row.installationId,
+      generation: row.generation,
+      tokenKind: row.kind,
+      token: data.refreshToken,
+      expiresAt: data.refreshTokenExpiresAt ?? row.refreshTokenExpiresAt ?? null,
+      updatedAt: Date.now(),
+    };
+    queueStoreWrite(`rotate github token ${userId}`, (store) =>
+      store.put(githubTokenParameterName(userId), JSON.stringify(rotated)),
+    );
+  } else if (
     data.refreshToken &&
     githubAuthGeneration(userId) === generation
   ) {
@@ -1433,6 +1507,196 @@ async function doRequestAccessToken(
   return { accessToken: data.accessToken, expiresAt: data.expiresAt };
 }
 
+// ---------------------------------------------------------------------------
+// ADR-136 sign-in box: a token row here holds NO ciphertext — `refresh_token_ct`
+// is empty, the row is "store-held" — the token lives in the store and, only
+// while the box needs it (the installation listing, a legacy exchange, the
+// revoke of a superseded grant), in this bounded in-memory cache. Never on
+// disk. The row's metadata still drives `hasToken` / `connectedUserIds` and
+// the generation fence exactly as on any host.
+// ---------------------------------------------------------------------------
+
+const BOX_TOKEN_CACHE_MS = 10 * 60_000;
+const boxTokens = new Map<string, { token: string; until: number }>();
+
+export const GITHUB_TOKEN_TAGS = {
+  installationId: "uai_installation_id",
+  generation: "uai_generation",
+  tokenKind: "uai_token_kind",
+  expiresAt: "uai_expires_at",
+  updatedAt: "uai_updated_at",
+} as const;
+
+export function isStoreHeldGithubRow(row: { refreshTokenCt: unknown }): boolean {
+  const ct = row.refreshTokenCt;
+  if (ct === null || ct === undefined) return true;
+  if (ct instanceof Uint8Array) return ct.byteLength === 0;
+  return false;
+}
+
+export function rememberGithubToken(userId: string, token: string): void {
+  boxTokens.set(userId, { token, until: Date.now() + BOX_TOKEN_CACHE_MS });
+}
+
+export function cachedGithubToken(userId: string): string | null {
+  const entry = boxTokens.get(userId);
+  if (!entry) return null;
+  if (entry.until <= Date.now()) {
+    boxTokens.delete(userId);
+    return null;
+  }
+  return entry.token;
+}
+
+export function forgetGithubToken(userId: string): void {
+  boxTokens.delete(userId);
+}
+
+/** Test seam. */
+export function clearGithubTokenCacheForTesting(): void {
+  boxTokens.clear();
+}
+
+/** The secret-free metadata a token parameter carries as tags, so a
+ *  replacement box lists the user as connected without reading the value. */
+export function githubTokenMetadataTags(value: {
+  installationId: number;
+  generation: number;
+  tokenKind: string;
+  expiresAt: number | null;
+  updatedAt: number;
+}): Record<string, string> {
+  return {
+    [GITHUB_TOKEN_TAGS.installationId]: String(value.installationId),
+    [GITHUB_TOKEN_TAGS.generation]: String(value.generation),
+    [GITHUB_TOKEN_TAGS.tokenKind]: value.tokenKind,
+    [GITHUB_TOKEN_TAGS.expiresAt]: value.expiresAt === null ? "" : String(value.expiresAt),
+    [GITHUB_TOKEN_TAGS.updatedAt]: String(value.updatedAt),
+  };
+}
+
+/** Fill the cache from the store for a store-held row. True when a token is
+ *  cached afterwards (or the row is not store-held); false when there is no
+ *  row, no store, or no parameter. Throws on a store failure. */
+export async function loadGithubTokenIntoCache(userId: string): Promise<boolean> {
+  if (cachedGithubToken(userId) !== null) return true;
+  const row = getDb()
+    .select({
+      refreshTokenCt: schema.githubTokens.refreshTokenCt,
+      generation: schema.githubTokens.generation,
+    })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return false;
+  if (!isStoreHeldGithubRow(row)) return true;
+  const store = configuredCredentialStore();
+  if (!store) return false;
+  const raw = await store.get(githubTokenParameterName(userId));
+  if (!raw) return false;
+  const parsed: unknown = JSON.parse(raw);
+  const value =
+    parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as { token?: unknown; generation?: unknown })
+      : {};
+  if (typeof value.token !== "string" || value.token.length === 0) {
+    throw new Error("the stored GitHub token is malformed");
+  }
+  if (value.generation !== row.generation) {
+    console.warn(
+      `[github] user ${userId}: the credential store holds generation ${String(value.generation)}, this box recorded ${row.generation}`,
+    );
+  }
+  rememberGithubToken(userId, value.token);
+  return true;
+}
+
+/** A token row with no material (sign-in box). Same fence as `storeTokenRow`. */
+export function insertStoreHeldGithubTokenRow(
+  userId: string,
+  fields: {
+    installationId: number;
+    generation: number;
+    refreshTokenExpiresAt: number | null;
+    kind: string;
+    updatedAt: number;
+    storeRef: string;
+  },
+): void {
+  const values = {
+    ...fields,
+    refreshTokenCt: Buffer.alloc(0),
+    refreshTokenNonce: Buffer.alloc(0),
+  };
+  getDb().transaction((tx) => {
+    const fence = tx
+      .select({
+        generation: schema.githubCredentialGenerations.generation,
+        mutation: schema.githubCredentialGenerations.mutation,
+      })
+      .from(schema.githubCredentialGenerations)
+      .where(eq(schema.githubCredentialGenerations.userId, userId))
+      .get();
+    if (fence?.mutation !== "set" || fence.generation !== fields.generation) {
+      throw new Error("GitHub credential generation changed before storage");
+    }
+    tx.insert(schema.githubTokens)
+      .values({ userId, ...values })
+      .onConflictDoUpdate({ target: schema.githubTokens.userId, set: values })
+      .run();
+  });
+}
+
+/** Sign-in box (ADR-136): the store first, awaited — a refused put is the
+ *  connect's failure — then tags, a store-held row, and the cache. */
+export async function storeGithubTokenStoreFirst(
+  userId: string,
+  fields: {
+    installationId: number;
+    generation: number;
+    refreshTokenExpiresAt: number | null;
+    kind: string;
+    updatedAt: number;
+  },
+  token: string,
+): Promise<void> {
+  const store = configuredCredentialStore();
+  if (!store) throw new Error("the sign-in box has no credential store to hold the token");
+  const name = githubTokenParameterName(userId);
+  const value: StoredGithubToken = {
+    v: 1,
+    kind: "github",
+    userId,
+    installationId: fields.installationId,
+    generation: fields.generation,
+    tokenKind: fields.kind,
+    token,
+    expiresAt: fields.refreshTokenExpiresAt,
+    updatedAt: fields.updatedAt,
+  };
+  await store.put(name, JSON.stringify(value));
+  try {
+    await store.tag(name, githubTokenMetadataTags(value));
+  } catch (err) {
+    console.warn(
+      `[github] user ${userId}: tagging ${name} failed (${err instanceof Error ? err.message : String(err)}) — a replacement box reads the value once to list this user`,
+    );
+  }
+  insertStoreHeldGithubTokenRow(userId, { ...fields, storeRef: name });
+  rememberGithubToken(userId, token);
+}
+
+/** Delete the row only (no store call) — the start-time reconcile's "gone
+ *  elsewhere" move on the sign-in box. */
+export function deleteGithubTokenRowLocal(userId: string): void {
+  forgetGithubToken(userId);
+  getDb()
+    .delete(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .run();
+  notifyGithubChange();
+}
+
 // --- container injection ----------------------------------------------------
 
 /** Injectable docker-exec seam (mocked in tests). Async so the docker call

package/lib/host-env.ts

@@ -25,6 +25,7 @@ import {
 } from "./credential-store";
 import { getDb, schema } from "./db";
 import { sealAesGcm, openAesGcm } from "./secrets";
+import { signInBoxMode } from "./signin-box";
 
 /** Pack a sealed value (ct + nonce) into the single TEXT column. */
 function packValue(value: string): string {
@@ -227,6 +228,9 @@ export function listProjectEnvStoreRows(): Array<{ projectId: string; key: strin
 }
 
 export function mirrorProjectEnvToStore(projectId: string, key: string): void {
+  // ADR-136 sign-in box: no local rows; env.var.* is a store passthrough
+  // (lib/signin-box-credentials.ts).
+  if (signInBoxMode()) return;
   const name = projectEnvParameterName(projectId, key);
   if (!name) return;
   queueStoreWrite(`mirror project env ${projectId}/${key}`, async (store) => {

package/lib/mcp-connections.ts

@@ -14,9 +14,10 @@
 import { createHash, randomBytes } from "node:crypto";
 import { eq } from "drizzle-orm";
 
-import { queueStoreWrite, userParameterName } from "./credential-store";
+import { configuredCredentialStore, queueStoreWrite, userParameterName } from "./credential-store";
 import { getDb, schema } from "./db";
 import { sealAesGcm, openAesGcm } from "./secrets";
+import { signInBoxMode } from "./signin-box";
 import type { McpOp } from "../src/protocol";
 
 const FETCH_TIMEOUT_MS = 10_000;
@@ -311,6 +312,27 @@ async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
       const lead = `unexpected response (${res.status})`;
       throw new Error(why ? `${lead}: ${why}` : lead);
     }
+    if (signInBoxMode()) {
+      // ADR-136 sign-in box: the store first, a row with no secret.
+      await putMcpConnectionStoreFirst({
+        v: 1,
+        kind: "mcp",
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "token",
+        tokenEndpoint: null,
+        redirectUri: null,
+        clientId: null,
+        clientSecret: null,
+        pkceVerifier: null,
+        secret: JSON.stringify(header),
+        status: "connected",
+        scopes: null,
+        updatedAt: now,
+      });
+      return { status: "connected" };
+    }
     db.insert(schema.mcpConnections)
       .values({
         id: op.connectionId,
@@ -339,6 +361,26 @@ async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
   // Bare probe.
   const res = await mcpInitialize(op.url);
   if (res.ok) {
+    if (signInBoxMode()) {
+      await putMcpConnectionStoreFirst({
+        v: 1,
+        kind: "mcp",
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "none",
+        tokenEndpoint: null,
+        redirectUri: null,
+        clientId: null,
+        clientSecret: null,
+        pkceVerifier: null,
+        secret: null,
+        status: "connected",
+        scopes: null,
+        updatedAt: now,
+      });
+      return { status: "connected" };
+    }
     db.insert(schema.mcpConnections)
       .values({
         id: op.connectionId,
@@ -396,6 +438,28 @@ async function probe(op: Extract<McpOp, { kind: "probe" }>): Promise<McpAck> {
     authorize.searchParams.set("scope", found.scopesSupported.join(" "));
   }
 
+  if (signInBoxMode()) {
+    // ADR-136 sign-in box: the pending half-flow (verifier, client secret)
+    // lives in memory only until oauth.complete; nothing pending reaches the
+    // store or the row. A box restart mid-flow means "probe again".
+    boxPendingOauth.set(op.connectionId, { verifier, clientSecret: clientSecret ?? null });
+    upsertStoreHeldMcpConnectionRow(
+      {
+        id: op.connectionId,
+        userId: op.userId,
+        url: op.url,
+        authKind: "oauth",
+        tokenEndpoint: found.tokenEndpoint,
+        redirectUri: op.redirectUri,
+        clientId,
+        status: "pending",
+        scopes: found.scopesSupported?.join(" ") ?? null,
+        updatedAt: now,
+      },
+      null,
+    );
+    return { status: "auth_required", authorizeUrl: authorize.toString() };
+  }
   const fields = {
     userId: op.userId,
     url: op.url,
@@ -426,9 +490,25 @@ async function oauthComplete(connectionId: string, code: string): Promise<McpAck
     .where(eq(schema.mcpConnections.id, connectionId))
     .get();
   if (!row) throw new Error("unknown connection — probe first");
-  if (!row.tokenEndpoint || !row.clientId || !row.pkceVerifierEnc || !row.redirectUri) {
-    throw new Error("connection has no pending OAuth flow");
+  const pending = signInBoxMode() ? (boxPendingOauth.get(connectionId) ?? null) : null;
+  if (
+    !row.tokenEndpoint ||
+    !row.clientId ||
+    !row.redirectUri ||
+    (!pending && !row.pkceVerifierEnc)
+  ) {
+    throw new Error(
+      signInBoxMode() && !pending
+        ? "the sign-in box restarted during this OAuth flow — probe again"
+        : "connection has no pending OAuth flow",
+    );
   }
+  const verifier = pending ? pending.verifier : unpack(row.pkceVerifierEnc!);
+  const clientSecret = pending
+    ? (pending.clientSecret ?? undefined)
+    : row.clientSecretEnc
+      ? unpack(row.clientSecretEnc)
+      : undefined;
 
   const { ok, status, json } = await postTokenEndpoint(
     row.tokenEndpoint,
@@ -437,12 +517,12 @@ async function oauthComplete(connectionId: string, code: string): Promise<McpAck
       code,
       redirect_uri: row.redirectUri,
       client_id: row.clientId,
-      code_verifier: unpack(row.pkceVerifierEnc),
+      code_verifier: verifier,
       // RFC 8707, mirrored from the authorize request.
       resource: row.url,
     },
     row.clientId,
-    row.clientSecretEnc ? unpack(row.clientSecretEnc) : undefined,
+    clientSecret,
   );
   if (!ok || typeof json.access_token !== "string") {
     const detail =
@@ -463,6 +543,30 @@ async function oauthComplete(connectionId: string, code: string): Promise<McpAck
     typeof json.scope === "string" && json.scope.length > 0
       ? json.scope
       : row.scopes;
+  if (pending) {
+    await putMcpConnectionStoreFirst({
+      v: 1,
+      kind: "mcp",
+      id: connectionId,
+      userId: row.userId,
+      url: row.url,
+      authKind: "oauth",
+      tokenEndpoint: row.tokenEndpoint,
+      redirectUri: row.redirectUri,
+      clientId: row.clientId,
+      clientSecret: pending.clientSecret,
+      pkceVerifier: null,
+      secret: JSON.stringify(secret),
+      status: "connected",
+      scopes,
+      updatedAt: Date.now(),
+    });
+    boxPendingOauth.delete(connectionId);
+    return {
+      status: "connected",
+      scopes: scopes ? scopes.split(" ").filter(Boolean) : undefined,
+    };
+  }
   db.update(schema.mcpConnections)
     .set({
       secretEnc: pack(JSON.stringify(secret)),
@@ -698,6 +802,9 @@ export function listMcpConnectionStoreRows(): Array<{
 }
 
 export function mirrorMcpConnectionToStore(id: string): void {
+  // ADR-136 sign-in box: rows hold no secret; the store was written first,
+  // and a mirror of a secret-less row would overwrite the only copy.
+  if (signInBoxMode()) return;
   queueStoreWrite(`mirror mcp connection ${id}`, async (store) => {
     const value = mcpConnectionStoreValue(id);
     if (!value) return;
@@ -720,6 +827,102 @@ export function deleteMcpConnectionLocal(id: string): void {
   queueStoreWrite(`delete mcp connection ${id}`, (store) => store.delete(name));
 }
 
+// ---------------------------------------------------------------------------
+// ADR-136 sign-in box: connection rows here hold NO secret — the header or
+// OAuth tokens, the client secret and the PKCE verifier live in the store (or,
+// for a half-finished OAuth flow, in memory only). What the box lists (url,
+// auth kind, status, scopes) also rides as tags so a replacement box needs no
+// value read.
+// ---------------------------------------------------------------------------
+
+export const MCP_CONNECTION_TAGS = {
+  urlB64: "uai_url_b64",
+  authKind: "uai_auth_kind",
+  status: "uai_status",
+  scopesB64: "uai_scopes_b64",
+  updatedAt: "uai_updated_at",
+} as const;
+
+const boxPendingOauth = new Map<string, { verifier: string; clientSecret: string | null }>();
+
+/** Test seam. */
+export function pendingOauthForTesting(connectionId: string): boolean {
+  return boxPendingOauth.has(connectionId);
+}
+
+export type StoreHeldMcpConnectionRow = Pick<
+  StoredMcpConnection,
+  "id" | "userId" | "url" | "authKind" | "tokenEndpoint" | "redirectUri" | "clientId" | "status" | "scopes" | "updatedAt"
+>;
+
+export function mcpConnectionMetadataTags(value: {
+  url: string;
+  authKind: string;
+  status: string;
+  scopes: string | null;
+  updatedAt: number;
+}): Record<string, string> {
+  return {
+    [MCP_CONNECTION_TAGS.urlB64]: Buffer.from(value.url, "utf8").toString("base64url").slice(0, 256),
+    [MCP_CONNECTION_TAGS.authKind]: value.authKind,
+    [MCP_CONNECTION_TAGS.status]: value.status,
+    [MCP_CONNECTION_TAGS.scopesB64]: value.scopes
+      ? Buffer.from(value.scopes, "utf8").toString("base64url").slice(0, 256)
+      : "",
+    [MCP_CONNECTION_TAGS.updatedAt]: String(value.updatedAt),
+  };
+}
+
+/** Upsert a row with every secret column null. */
+export function upsertStoreHeldMcpConnectionRow(
+  value: StoreHeldMcpConnectionRow,
+  storeRef: string | null,
+): void {
+  const fields = {
+    userId: value.userId,
+    url: value.url,
+    authKind: value.authKind,
+    tokenEndpoint: value.tokenEndpoint,
+    redirectUri: value.redirectUri,
+    clientId: value.clientId,
+    clientSecretEnc: null,
+    pkceVerifierEnc: null,
+    secretEnc: null,
+    status: value.status,
+    scopes: value.scopes,
+    updatedAt: value.updatedAt,
+    storeRef,
+  };
+  getDb()
+    .insert(schema.mcpConnections)
+    .values({ id: value.id, ...fields })
+    .onConflictDoUpdate({ target: schema.mcpConnections.id, set: fields })
+    .run();
+}
+
+/** The store first, awaited (a refused put is the op's failure), then tags
+ *  and a secret-less row. */
+export async function putMcpConnectionStoreFirst(value: StoredMcpConnection): Promise<void> {
+  const store = configuredCredentialStore();
+  if (!store) throw new Error("the sign-in box has no credential store to hold the connection");
+  const name = mcpConnectionParameterName(value.userId, value.id);
+  await store.put(name, JSON.stringify(value));
+  try {
+    await store.tag(name, mcpConnectionMetadataTags(value));
+  } catch (err) {
+    console.warn(
+      `[mcp] connection ${value.id}: tagging ${name} failed (${err instanceof Error ? err.message : String(err)}) — a replacement box needs the transitional read to list it`,
+    );
+  }
+  upsertStoreHeldMcpConnectionRow(value, name);
+}
+
+/** Delete the row only (no store call). */
+export function deleteMcpConnectionRowLocal(id: string): void {
+  boxPendingOauth.delete(id);
+  getDb().delete(schema.mcpConnections).where(eq(schema.mcpConnections.id, id)).run();
+}
+
 /** Reconcile import: a connection this host lacks. Existing rows win. */
 export function importMcpConnectionFromStore(
   value: StoredMcpConnection,