@opengeni/db 1.0.1 → 3.1.0-canary.0

package/src/connection-token-resolver.ts

@@ -14,6 +14,18 @@ import type {
   TurnInitiator,
   TurnInitiatorContext,
 } from "@opengeni/contracts";
+import {
+  ConnectionUseAuthoritySnapshot,
+  type ConnectionUseAttribution,
+  type ConnectionUseAuthorizationResult,
+} from "@opengeni/contracts/connection-authority";
+import {
+  PERSONAL_GITHUB_REQUESTED_SCOPES,
+  PERSONAL_GITHUB_PROVIDER_DOMAIN,
+  PERSONAL_GITHUB_TOKEN_URL,
+  PersonalGitHubConnectionMetadata,
+} from "@opengeni/contracts/personal-github";
+import { createHash } from "node:crypto";
 import {
   OAUTH_MAX_RESPONSE_BYTES,
   pinnedFetch,
@@ -28,6 +40,11 @@ import { Buffer } from "node:buffer";
 import { isIP } from "node:net";
 import { encryptEnvironmentValue } from "./environment-crypto";
 import type { Database } from "./database";
+import type {
+  AcceptedConnectionUseContext,
+  AcceptedConnectionUseResolution,
+} from "./connection-authority";
+import { connectionScopeKey } from "./connection-scopes";
 
 const MAX_CREDENTIAL_PLACEMENTS = 32;
 const MAX_CREDENTIAL_NAME_BYTES = 256;
@@ -60,6 +77,8 @@ export type ConnectionCredentialForBroker = {
   expiresAt: Date | null;
   lastRefreshAt: Date | null;
   version: number;
+  /** Immutable execution authority generation; distinct from token refresh version. */
+  authorityGeneration?: number;
   metadata: Record<string, unknown>;
 };
 
@@ -70,6 +89,7 @@ export type ConnectionCredentialLookupInput = {
   kind?: ConnectionKind;
   subjectId?: string | null;
   allowSubjectOwned?: boolean;
+  expectedAuthorityGeneration?: number;
 };
 
 export type ConnectionTokenRefreshInput = {
@@ -79,6 +99,7 @@ export type ConnectionTokenRefreshInput = {
   credentialEncrypted: string;
   expiresAt: Date | null;
   grantedScopes?: string[];
+  metadata?: Record<string, unknown>;
   lastRefreshAt: Date;
   subjectId?: string | null;
 };
@@ -98,6 +119,14 @@ export type ResolveConnectionCredentialResult =
       connectionId: string;
       /** Exact durable version when the credential came from the local connection store. */
       connectionVersion?: number;
+      /** Metadata-only owner attribution from the immediate pre-use fence. */
+      connectionUseAttribution?: ConnectionUseAttribution;
+      /**
+       * Revalidate the exact accepted attempt immediately before one target
+       * provider request. Credential lookup/refresh is a separate audited
+       * boundary and must not manufacture a provider-request fact by itself.
+       */
+      authorizeProviderRequest?: () => Promise<boolean>;
       expiresAt?: Date | null;
     }
   | {
@@ -129,6 +158,10 @@ export type ResolveConnectionCredentialInput = {
   /** Defaults to header-only MCP transport. */
   credentialTarget?: "mcp" | "http_api";
   forceRefresh?: boolean;
+  /** Exact immutable accepted-work authority; never credential-bearing. */
+  connectionUseAuthority?: unknown;
+  /** Exact accepted attempt plus one stable physical-provider request id. */
+  connectionUseContext?: AcceptedConnectionUseContext;
 };
 
 export type HostMcpCredentialResolverContext = {
@@ -142,7 +175,6 @@ export type HostMcpCredentialResolverContext = {
   initiator: TurnInitiator;
   initiatorContext: TurnInitiatorContext;
   surface: McpCredentialsRequest["surface"];
-  allowOfficialGmailRestDestination?: boolean;
 };
 
 export class HostMcpCredentialScopeError extends Error {
@@ -173,10 +205,11 @@ const OFFICIAL_GMAIL_MCP_RESOURCE = "https://gmailmcp.googleapis.com/mcp/v1";
 const OFFICIAL_GMAIL_REST_HOST = "gmail.googleapis.com";
 
 /**
- * The opt-in Gmail REST adapter reuses the exact OAuth grant created for
- * Google's hosted Gmail MCP while the preview endpoint is unavailable. Keep
- * this exception narrower than ordinary provider-domain binding: HTTPS only,
- * Google's canonical Gmail API host, and the authenticated `users/me` path.
+ * The Gmail bridge reuses the exact OAuth grant created for the official
+ * hosted Gmail MCP resource, executing every tool against Gmail's REST API
+ * instead of Google's Developer Preview MCP endpoint. Keep this exception
+ * narrower than ordinary provider-domain binding: HTTPS only, Google's
+ * canonical Gmail API host, and the authenticated `users/me` path.
  */
 function isOfficialGmailRestDestination(
   destinationUrl: string,
@@ -216,10 +249,7 @@ export function buildHostConnectionTokenResolver(
     if (
       !destinationUrl ||
       (!destinationHostMatchesProvider(destinationUrl, input.connectionRef.providerDomain) &&
-        !(
-          context.allowOfficialGmailRestDestination === true &&
-          isOfficialGmailRestDestination(destinationUrl, input.connectionRef)
-        ))
+        !isOfficialGmailRestDestination(destinationUrl, input.connectionRef))
     ) {
       throw new HostMcpCredentialBindingError("destinationUrl");
     }
@@ -255,6 +285,12 @@ export function buildHostConnectionTokenResolver(
           : {}),
       },
       forceRefresh: input.forceRefresh === true,
+      ...(input.connectionUseAuthority !== undefined
+        ? { connectionUseAuthority: input.connectionUseAuthority }
+        : {}),
+      ...(input.connectionUseContext
+        ? { connectionUseRequestId: input.connectionUseContext.physicalRequestId }
+        : {}),
       ...(toolName ? { toolName } : {}),
       ...(input.subjectId ? { callerSubjectId: input.subjectId } : {}),
     };
@@ -575,6 +611,21 @@ export type ConnectionBrokerDeps = {
   encrypt: typeof encryptEnvironmentValue;
   keyBytes: typeof environmentsEncryptionKeyBytes;
   now: () => Date;
+  authorizeUse?: (
+    db: Database,
+    input: { snapshot: unknown },
+  ) => Promise<ConnectionUseAuthorizationResult>;
+  authorizeAcceptedUse?: (
+    db: Database,
+    input: AcceptedConnectionUseContext & {
+      serverId: string;
+      connectionId?: string;
+      providerDomain: string;
+      connectionKind?: ConnectionKind;
+      subjectScope?: "workspace" | "subject";
+      ownerSubjectId?: string;
+    },
+  ) => Promise<AcceptedConnectionUseResolution>;
 };
 
 export type PermanentConnectionRefreshFailure = {
@@ -618,7 +669,7 @@ export function buildConnectionTokenResolver(
   type CredentialLookupInput = Pick<
     ResolveConnectionCredentialInput,
     "workspaceId" | "connectionRef" | "subjectId"
-  >;
+  > & { expectedAuthorityGeneration?: number };
   const load = async (
     input: CredentialLookupInput,
   ): Promise<ConnectionCredentialForBroker | null> => {
@@ -631,6 +682,9 @@ export function buildConnectionTokenResolver(
       providerDomain: input.connectionRef.providerDomain,
       allowSubjectOwned: subjectOwned,
       ...(subjectOwned ? { subjectId: input.subjectId! } : {}),
+      ...(input.expectedAuthorityGeneration !== undefined
+        ? { expectedAuthorityGeneration: input.expectedAuthorityGeneration }
+        : {}),
     };
     if (input.connectionRef.connectionId !== undefined) {
       request.connectionId = input.connectionRef.connectionId;
@@ -640,6 +694,12 @@ export function buildConnectionTokenResolver(
     }
     const credential = await deps.loadCredential(db, settings, request);
     if (!credential) return null;
+    if (
+      input.expectedAuthorityGeneration !== undefined &&
+      credential.authorityGeneration !== input.expectedAuthorityGeneration
+    ) {
+      return null;
+    }
     if (subjectOwned) {
       return credential.subjectId === input.subjectId ? credential : null;
     }
@@ -651,14 +711,19 @@ export function buildConnectionTokenResolver(
     ref: McpServerConnectionRef,
     destinationUrl: string,
     inputCredentialTarget: "mcp" | "http_api",
+    connectionUseAttribution?: ConnectionUseAttribution,
   ): Promise<ResolveConnectionCredentialResult> => {
     if (cred.status !== "active") {
       return authNeededForStatus(cred, ref);
     }
-    if (!connectionBindingMatches(cred, ref, destinationUrl, settings.gmailRestAdapterEnabled)) {
+    if (!connectionBindingMatches(cred, ref, destinationUrl)) {
       return authNeeded(ref, "missing_connection", cred.id);
     }
-    const missingScopes = missingRequestedScopes(ref.scopes, cred.grantedScopes);
+    const missingScopes = missingRequestedScopes(
+      ref.scopes,
+      cred.grantedScopes,
+      cred.providerDomain,
+    );
     if (missingScopes.length > 0) {
       return {
         status: "auth_needed",
@@ -695,6 +760,7 @@ export function buildConnectionTokenResolver(
       ...(material.placements ? { placements: material.placements } : {}),
       connectionId: cred.id,
       connectionVersion: cred.version,
+      ...(connectionUseAttribution ? { connectionUseAttribution } : {}),
       expiresAt: cred.expiresAt,
     };
   };
@@ -720,6 +786,9 @@ export function buildConnectionTokenResolver(
     if (refreshed.grantedScopes !== undefined) {
       refreshRecord.grantedScopes = refreshed.grantedScopes;
     }
+    if (refreshed.metadata !== undefined) {
+      refreshRecord.metadata = refreshed.metadata;
+    }
     const persisted = await deps.recordRefresh(db, refreshRecord);
     if (persisted) {
       const current = await load({
@@ -761,10 +830,11 @@ export function buildConnectionTokenResolver(
   };
 
   return async (input) => {
-    const ref = input.connectionRef;
-    if (ref.subjectScope === "subject" && !input.subjectId) {
-      return authNeeded(ref, "personal_authority_unavailable", ref.connectionId);
-    }
+    let ref = input.connectionRef;
+    let subjectId = input.subjectId;
+    let credentialWorkspaceId = input.workspaceId;
+    let expectedAuthorityGeneration: number | undefined;
+    let connectionUseAttribution: ConnectionUseAttribution | undefined;
     // Repository-scoped provider bindings require a broker that can prove the
     // selected-resource boundary. The generic standalone credential store has
     // no provider-specific containment adapter, so it must fail closed instead
@@ -772,9 +842,99 @@ export function buildConnectionTokenResolver(
     if (ref.selectedResources) {
       return authNeeded(ref, "resource_scope_unavailable", ref.connectionId);
     }
+    if (input.connectionUseContext !== undefined) {
+      if (!deps.authorizeAcceptedUse) {
+        return authNeeded(
+          ref,
+          ref.subjectScope === "subject" ? "personal_authority_unavailable" : "missing_connection",
+          ref.connectionId,
+        );
+      }
+      const authorization = await deps.authorizeAcceptedUse(db, {
+        ...input.connectionUseContext,
+        serverId: input.serverId,
+        ...(ref.connectionId ? { connectionId: ref.connectionId } : {}),
+        providerDomain: ref.providerDomain,
+        ...(ref.kind ? { connectionKind: ref.kind } : {}),
+        subjectScope: ref.subjectScope === "subject" ? "subject" : "workspace",
+        // An owner binding belongs only to the personal lanes. Interactive
+        // turns stamp the initiating human's subjectId on every credential
+        // request regardless of ref scope; forwarding it for a workspace ref
+        // would make the 0279 workspace lane deny the ambient shared row.
+        ...(ref.subjectScope === "subject" && subjectId ? { ownerSubjectId: subjectId } : {}),
+      });
+      if (authorization.status === "denied") {
+        return authNeeded(
+          ref,
+          ref.subjectScope === "subject" ? "personal_authority_unavailable" : "missing_connection",
+          ref.connectionId,
+        );
+      }
+      connectionUseAttribution = authorization.attribution;
+      expectedAuthorityGeneration = authorization.attribution.connectionGeneration;
+      const expectedPersonal = authorization.attribution.scope !== "workspace";
+      credentialWorkspaceId = authorization.originWorkspaceId;
+      subjectId = authorization.attribution.ownerSubjectId ?? undefined;
+      ref = {
+        ...ref,
+        connectionId: authorization.attribution.connectionId,
+        kind: authorization.connectionKind,
+        subjectScope: expectedPersonal ? "subject" : "workspace",
+      };
+    } else if (input.connectionUseAuthority !== undefined) {
+      const authority = ConnectionUseAuthoritySnapshot.parse(input.connectionUseAuthority);
+      const expectedPersonal = authority.scope === "user";
+      if (
+        authority.targetWorkspaceId !== input.workspaceId ||
+        authority.providerDomain.toLowerCase() !== ref.providerDomain.toLowerCase() ||
+        (ref.connectionId !== undefined && ref.connectionId !== authority.connectionId) ||
+        (ref.kind !== undefined && ref.kind !== authority.connectionKind) ||
+        (ref.subjectScope === "subject") !== expectedPersonal ||
+        !deps.authorizeUse
+      ) {
+        return authNeeded(
+          ref,
+          expectedPersonal ? "personal_authority_unavailable" : "missing_connection",
+          ref.connectionId,
+        );
+      }
+      const authorization = await deps.authorizeUse(db, { snapshot: authority });
+      if (authorization.status === "denied") {
+        return authNeeded(
+          ref,
+          expectedPersonal ? "personal_authority_unavailable" : "missing_connection",
+          authority.connectionId,
+        );
+      }
+      connectionUseAttribution = authorization.attribution;
+      expectedAuthorityGeneration = authority.connectionGeneration;
+      // Personal resources are organization-user owned and may originate in a
+      // different workspace from the session using them. Authorization is
+      // evaluated against the target workspace above; the exact credential is
+      // then loaded from its frozen physical origin, never rediscovered in the
+      // target workspace.
+      credentialWorkspaceId = expectedPersonal
+        ? authority.originWorkspaceId
+        : authority.targetWorkspaceId;
+      subjectId = authority.ownerSubjectId ?? undefined;
+      ref = {
+        ...ref,
+        connectionId: authority.connectionId,
+        kind: authority.connectionKind,
+        subjectScope: expectedPersonal ? "subject" : "workspace",
+      };
+    }
+    if (ref.subjectScope === "subject" && !subjectId) {
+      return authNeeded(ref, "personal_authority_unavailable", ref.connectionId);
+    }
     let cred: ConnectionCredentialForBroker | null;
     try {
-      cred = await load(input);
+      cred = await load({
+        workspaceId: credentialWorkspaceId,
+        connectionRef: ref,
+        ...(subjectId ? { subjectId } : {}),
+        ...(expectedAuthorityGeneration !== undefined ? { expectedAuthorityGeneration } : {}),
+      });
     } catch {
       return authNeeded(ref, "refresh_failed");
     }
@@ -787,9 +947,7 @@ export function buildConnectionTokenResolver(
     // Reject an audience/destination mismatch before any provider-side refresh
     // or usage update. Refreshing first would still create an unauthorized
     // external side effect even though the token was never sent to the target.
-    if (
-      !connectionBindingMatches(cred, ref, input.destinationUrl, settings.gmailRestAdapterEnabled)
-    ) {
+    if (!connectionBindingMatches(cred, ref, input.destinationUrl)) {
       return authNeeded(ref, "missing_connection", cred.id);
     }
     if (shouldRefresh(cred, input.forceRefresh === true, deps.now())) {
@@ -828,15 +986,30 @@ export function buildConnectionTokenResolver(
         return authNeeded(ref, "refresh_failed", cred.id);
       }
     }
-    return await snapshot(cred, ref, input.destinationUrl, input.credentialTarget ?? "mcp");
+    if (
+      expectedAuthorityGeneration !== undefined &&
+      cred.authorityGeneration !== expectedAuthorityGeneration
+    ) {
+      return authNeeded(ref, authorityReasonForScope(ref.subjectScope === "subject"), cred.id);
+    }
+    return await snapshot(
+      cred,
+      ref,
+      input.destinationUrl,
+      input.credentialTarget ?? "mcp",
+      connectionUseAttribution,
+    );
   };
 }
 
+function authorityReasonForScope(personal: boolean): AuthNeededReason {
+  return personal ? "personal_authority_unavailable" : "missing_connection";
+}
+
 function connectionBindingMatches(
   cred: ConnectionCredentialForBroker,
   ref: McpServerConnectionRef,
   destinationUrl: string,
-  gmailRestAdapterEnabled: boolean,
 ): boolean {
   if (cred.providerDomain.toLowerCase() !== ref.providerDomain.toLowerCase()) return false;
   if (ref.kind && cred.kind !== ref.kind) return false;
@@ -852,7 +1025,6 @@ function connectionBindingMatches(
       !binding ||
       (destination !== binding &&
         !(
-          gmailRestAdapterEnabled &&
           binding === canonicalHttpUrl(OFFICIAL_GMAIL_MCP_RESOURCE) &&
           isOfficialGmailRestDestination(destination, ref)
         ))
@@ -979,12 +1151,16 @@ function authNeededForStatus(
   );
 }
 
-function missingRequestedScopes(requested: string[] | undefined, granted: string[]): string[] {
+function missingRequestedScopes(
+  requested: string[] | undefined,
+  granted: string[],
+  providerDomain: string,
+): string[] {
   if (!requested?.length) {
     return [];
   }
-  const grantedSet = new Set(granted);
-  return requested.filter((scope) => !grantedSet.has(scope));
+  const grantedSet = new Set(granted.map((scope) => connectionScopeKey(providerDomain, scope)));
+  return requested.filter((scope) => !grantedSet.has(connectionScopeKey(providerDomain, scope)));
 }
 
 /**
@@ -1057,6 +1233,7 @@ export async function refreshOAuthConnectionCredential(
   credential: Record<string, unknown>;
   expiresAt: Date | null;
   grantedScopes?: string[];
+  metadata?: Record<string, unknown>;
 }> {
   if (cred.kind !== "oauth2") {
     return {
@@ -1066,13 +1243,21 @@ export async function refreshOAuthConnectionCredential(
     };
   }
   const refreshToken = stringValue((cred.credential as { refresh_token?: unknown }).refresh_token);
-  const tokenEndpoint =
+  const personalGitHubMetadata = PersonalGitHubConnectionMetadata.safeParse(cred.metadata);
+  const personalGitHub =
+    cred.providerDomain.toLowerCase() === PERSONAL_GITHUB_PROVIDER_DOMAIN &&
+    personalGitHubMetadata.success;
+  const storedTokenEndpoint =
     stringValue((cred.credential as { token_endpoint?: unknown }).token_endpoint) ??
     stringValue((cred.metadata as { tokenEndpoint?: unknown }).tokenEndpoint) ??
     stringValue((cred.metadata as { token_endpoint?: unknown }).token_endpoint);
+  const tokenEndpoint = personalGitHub ? PERSONAL_GITHUB_TOKEN_URL : storedTokenEndpoint;
   if (!refreshToken || !tokenEndpoint) {
     throw new Error("connection has no refresh token endpoint");
   }
+  if (personalGitHub && storedTokenEndpoint !== PERSONAL_GITHUB_TOKEN_URL) {
+    throw new ConnectionRefreshHttpError(401, "client_unavailable");
+  }
   let validatedTokenEndpoint: string;
   try {
     validatedTokenEndpoint = validateHttpUrl(tokenEndpoint, {
@@ -1092,11 +1277,25 @@ export async function refreshOAuthConnectionCredential(
     stringValue((cred.credential as { client_id?: unknown }).client_id) ??
     stringValue((cred.metadata as { clientId?: unknown }).clientId) ??
     stringValue((cred.metadata as { client_id?: unknown }).client_id);
-  const clientSecret = stringValue((cred.credential as { client_secret?: unknown }).client_secret);
+  const clientSecret = personalGitHub
+    ? settings.githubPersonalOauthClientSecret
+    : stringValue((cred.credential as { client_secret?: unknown }).client_secret);
   const authMethod =
     stringValue(
       (cred.credential as { token_endpoint_auth_method?: unknown }).token_endpoint_auth_method,
     ) ?? "none";
+  if (
+    personalGitHub &&
+    (!settings.githubPersonalOauthEnabled ||
+      !clientId ||
+      clientId !== settings.githubPersonalOauthClientId ||
+      personalGitHubMetadata.data.oauthEnvironment !== settings.environment ||
+      personalGitHubMetadata.data.oauthClientMarker !==
+        createHash("sha256").update(clientId).digest("hex").slice(0, 32) ||
+      !clientSecret)
+  ) {
+    throw new ConnectionRefreshHttpError(401, "client_unavailable");
+  }
   if (clientId) {
     body.set("client_id", clientId);
   }
@@ -1123,7 +1322,10 @@ export async function refreshOAuthConnectionCredential(
   if (resource && resourceParameterSupported) {
     body.set("resource", resource);
   }
-  if (ref.scopes?.length) {
+  const scopeParameterSupported =
+    (cred.credential as { scope_parameter_supported?: unknown }).scope_parameter_supported !==
+    false;
+  if (ref.scopes?.length && scopeParameterSupported) {
     body.set("scope", ref.scopes.join(" "));
   }
   const requestBody: BodyInit =
@@ -1165,6 +1367,23 @@ export async function refreshOAuthConnectionCredential(
   }
   const expiresAt = expiresAtFromTokenResponse(payload, cred.expiresAt);
   const scopeText = stringValue(payload.scope);
+  const returnedScopes = scopeText?.split(/[\s,]+/).filter(Boolean) ?? [];
+  const refreshTokenExpiresIn =
+    typeof payload.refresh_token_expires_in === "number"
+      ? payload.refresh_token_expires_in
+      : undefined;
+  const refreshTokenExpiresAt =
+    personalGitHub && refreshTokenExpiresIn && refreshTokenExpiresIn > 0
+      ? new Date(Date.now() + refreshTokenExpiresIn * 1000).toISOString()
+      : null;
+  if (
+    personalGitHub &&
+    scopeText &&
+    (returnedScopes.length !== PERSONAL_GITHUB_REQUESTED_SCOPES.length ||
+      returnedScopes.some((scope) => !PERSONAL_GITHUB_REQUESTED_SCOPES.includes(scope as "repo")))
+  ) {
+    throw new ConnectionRefreshHttpError(401, "scope_changed");
+  }
   const nextCredential = {
     ...cred.credential,
     access_token: accessToken,
@@ -1176,14 +1395,27 @@ export async function refreshOAuthConnectionCredential(
     ...(expiresAt ? { expires_at: expiresAt.toISOString() } : {}),
     ...(resource ? { resource } : {}),
     ...(scopeText ? { scope: scopeText } : {}),
-    ...(clientSecret
+    ...(refreshTokenExpiresAt ? { refresh_token_expires_at: refreshTokenExpiresAt } : {}),
+    ...(clientSecret && !personalGitHub
       ? { client_secret: clientSecret, token_endpoint_auth_method: authMethod }
       : {}),
   };
   return {
     credential: nextCredential,
     expiresAt,
-    ...(scopeText ? { grantedScopes: scopeText.split(/\s+/).filter(Boolean) } : {}),
+    ...(personalGitHub
+      ? { grantedScopes: [...PERSONAL_GITHUB_REQUESTED_SCOPES] }
+      : scopeText
+        ? { grantedScopes: returnedScopes }
+        : {}),
+    ...(refreshTokenExpiresAt
+      ? {
+          metadata: PersonalGitHubConnectionMetadata.parse({
+            ...personalGitHubMetadata.data,
+            refreshTokenExpiresAt,
+          }),
+        }
+      : {}),
   };
 }
 

package/src/database.ts

@@ -115,6 +115,18 @@ export type RlsStrategy = "force" | "scoped";
  */
 export type UserLookup = (db: Database, email: string) => Promise<string | null>;
 
+export type ManagedUserProfile = {
+  id: string;
+  name: string | null;
+  email: string;
+};
+
+/** Host identity projection used by organization administration rosters. */
+export type UserProfileLookup = (
+  db: Database,
+  userIds: readonly string[],
+) => Promise<ManagedUserProfile[]>;
+
 export type CreateDbOptions = {
   /**
    * The Postgres `search_path` for this connection (Step I, §7.8 runtime half).
@@ -132,6 +144,8 @@ export type CreateDbOptions = {
   rlsStrategy?: RlsStrategy;
   /** Host-provided user-by-email resolver; unset → today's raw `auth_users` query. */
   userLookup?: UserLookup;
+  /** Host-provided user profile projection; unset → standalone `auth_users`. */
+  userProfileLookup?: UserProfileLookup;
   /** postgres-js pool size; defaults to today's `10`. */
   max?: number;
   /**
@@ -150,7 +164,11 @@ export type CreateDbOptions = {
  * config (e.g. one built outside `createDb`, or in a test) falls back to the
  * standalone defaults: `rlsStrategy: "force"`, raw `auth_users` lookup.
  */
-type DbBinding = { rlsStrategy: RlsStrategy; userLookup?: UserLookup };
+type DbBinding = {
+  rlsStrategy: RlsStrategy;
+  userLookup?: UserLookup;
+  userProfileLookup?: UserProfileLookup;
+};
 
 const dbBindings = new WeakMap<object, DbBinding>();
 
@@ -314,6 +332,7 @@ export function createDb(databaseUrl: string, options: CreateDbOptions = {}): Db
   dbBindings.set(db as unknown as object, {
     rlsStrategy: options.rlsStrategy ?? "force",
     ...(options.userLookup ? { userLookup: options.userLookup } : {}),
+    ...(options.userProfileLookup ? { userProfileLookup: options.userProfileLookup } : {}),
   });
   return {
     db,
@@ -331,11 +350,16 @@ export function createDb(databaseUrl: string, options: CreateDbOptions = {}): Db
  */
 export function registerDbBinding(
   db: Database,
-  binding: { rlsStrategy?: RlsStrategy; userLookup?: UserLookup },
+  binding: {
+    rlsStrategy?: RlsStrategy;
+    userLookup?: UserLookup;
+    userProfileLookup?: UserProfileLookup;
+  },
 ): void {
   dbBindings.set(db as unknown as object, {
     rlsStrategy: binding.rlsStrategy ?? "force",
     ...(binding.userLookup ? { userLookup: binding.userLookup } : {}),
+    ...(binding.userProfileLookup ? { userProfileLookup: binding.userProfileLookup } : {}),
   });
 }
 
@@ -662,6 +686,14 @@ async function finalizeSessionActivityGate(
   await db.execute(
     sql`set constraints sessions_activity_insert_commit_guard, sessions_activity_update_commit_guard immediate`,
   );
+  // A restored activity scope can be followed by another workspace scope, or
+  // by a SECURITY DEFINER lifecycle that opens and finalizes its own gate in
+  // the same outer transaction. Keep the guards deferred after proving this
+  // scope's final state so those later writes reach their own finalizer instead
+  // of firing the commit guard at the first session update.
+  await db.execute(
+    sql`set constraints sessions_activity_insert_commit_guard, sessions_activity_update_commit_guard deferred`,
+  );
 }
 
 /**
@@ -709,6 +741,47 @@ export async function withWorkspaceSessionActivityRls<T>(
   );
 }
 
+/**
+ * Run one of several ordered workspace activity scopes inside a caller-owned
+ * transaction. Each scope is fully finalized before restoring the caller's
+ * gate GUCs, so the next workspace can reuse the same outer transaction.
+ */
+export async function withRestoredSessionActivityRlsContext<T>(
+  db: Database,
+  context: RlsContext & { workspaceId: string },
+  fn: (db: SessionActivityDatabase) => Promise<T>,
+): Promise<T> {
+  if (!isTransactionHandle(db)) {
+    throw new Error("Sequential workspace activity scopes require a caller-owned transaction");
+  }
+  const [prior] = await rawRows<{ state: string; workspace_id: string }>(
+    db,
+    sql`select
+      coalesce(current_setting('opengeni.session_activity_gate_state', true), '') as state,
+      coalesce(
+        current_setting('opengeni.session_activity_gate_workspace_id', true), ''
+      ) as workspace_id`,
+  );
+  try {
+    return await withRlsContext(db, context, async (scopedDb) => {
+      const gate = await beginSessionActivityGate(scopedDb, context.workspaceId);
+      if (!gate.owner) {
+        throw new Error("Sequential workspace activity scope unexpectedly reused an open gate");
+      }
+      const value = await fn(gate.db);
+      await assertRlsContextApplied(gate.db, context);
+      await finalizeSessionActivityGate(gate.db, context.workspaceId);
+      return value;
+    });
+  } finally {
+    await db.execute(sql`select
+      set_config('opengeni.session_activity_gate_state', ${prior?.state ?? ""}, true),
+      set_config(
+        'opengeni.session_activity_gate_workspace_id', ${prior?.workspace_id ?? ""}, true
+      )`);
+  }
+}
+
 /**
  * Open one nested savepoint without losing the gate brand. Drizzle correctly
  * preserves the backend-local gate GUCs, but its structural transaction type