@opengeni/db 0.6.1 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -8,6 +8,11 @@
     "url": "git+https://github.com/Cloudgeni-ai/opengeni.git",
     "directory": "packages/db"
   },
+  "files": [
+    "dist",
+    "src",
+    "drizzle"
+  ],
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -31,14 +36,6 @@
       "import": "./dist/provision-roles.js"
     }
   },
-  "files": [
-    "dist",
-    "src",
-    "drizzle"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -47,15 +44,18 @@
     "generate": "drizzle-kit generate",
     "migrate": "bun src/migrate.ts",
     "provision-roles": "bun src/provision-roles.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "build": "tsup",
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codex": "^0.2.1",
-    "@opengeni/config": "^0.4.0",
-    "@opengeni/contracts": "^0.9.0",
+    "@opengeni/codex": "^0.2.2",
+    "@opengeni/config": "^0.5.0",
+    "@opengeni/contracts": "^0.10.0",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

package/src/codex-token-resolver.ts

@@ -12,14 +12,10 @@
 // refresh helpers and the @opengeni/config key — keeping the refresh-CAS + RLS
 // invariants co-located with the rows they protect.
 //
-// CROSS-PROCESS SAFETY is preserved unchanged: the single-flight `inflight` map is
-// process-module-scoped, so worker and api each get their own — that is CORRECT
-// (each process coalesces its own concurrent refreshes). The real cross-process
-// guard is the (id, version) CAS inside recordCodexTokenRefresh: if the api
-// refreshes a token while a worker turn refreshes the same account, the loser's
-// CAS writes 0 rows (stale version) and it re-reads the winner's token, so the
-// one-time refresh token is never double-spent. RLS is untouched (every accessor
-// wraps withWorkspaceRls internally).
+// CROSS-PROCESS SAFETY: the process-module `inflight` map coalesces local callers,
+// while a Postgres advisory transaction lock serializes API/worker replicas. A
+// waiter re-reads after taking that lock and skips refresh when the version moved.
+// The existing (id,version) CAS remains the final stale-family write fence.
 
 import { environmentsEncryptionKeyBytes, type Settings } from "@opengeni/config";
 import {
@@ -40,6 +36,7 @@ import {
   recordCodexAccountUsage,
   recordCodexTokenRefresh,
   setCodexCredentialStatus,
+  withCodexCredentialRefreshLock,
   type CodexCredentialForRun,
   type Database,
 } from "./index";
@@ -63,6 +60,7 @@ export type CodexAuthDeps = {
   refresh: typeof refreshCodexToken;
   encrypt: typeof encryptEnvironmentValue;
   keyBytes: typeof environmentsEncryptionKeyBytes;
+  withRefreshLock: typeof withCodexCredentialRefreshLock;
 };
 
 const defaultDeps: CodexAuthDeps = {
@@ -72,6 +70,7 @@ const defaultDeps: CodexAuthDeps = {
   refresh: refreshCodexToken,
   encrypt: encryptEnvironmentValue,
   keyBytes: environmentsEncryptionKeyBytes,
+  withRefreshLock: withCodexCredentialRefreshLock,
 };
 
 export function buildCodexTokenResolver(
@@ -92,7 +91,10 @@ export function buildCodexTokenResolver(
     isFedramp: cred.isFedramp,
   });
 
-  const performRefresh = async (cred: CodexCredentialForRun): Promise<CodexTokenSnapshot> => {
+  const performRefresh = async (
+    refreshDb: Database,
+    cred: CodexCredentialForRun,
+  ): Promise<CodexTokenSnapshot> => {
     try {
       const next = await deps.refresh(cred.tokens.refreshToken);
       const tokens = {
@@ -107,7 +109,7 @@ export function buildCodexTokenResolver(
       // Compare-and-set on the loaded (id, version): if a disconnect→reconnect
       // replaced the row mid-refresh, this writes 0 rows and we must NOT clobber
       // the new credential with our now-defunct rotated tokens.
-      const persisted = await deps.recordRefresh(db, {
+      const persisted = await deps.recordRefresh(refreshDb, {
         id: cred.id,
         version: cred.version,
         workspaceId,
@@ -119,40 +121,73 @@ export function buildCodexTokenResolver(
         // The row changed under us. Our rotated tokens belong to a stale family;
         // fall back to whatever is connected NOW (a reconnect leaves an active
         // row). If nothing active remains, a relogin is genuinely required.
-        const current = await deps.loadCredential(db, settings, workspaceId, credentialId);
+        const current = await deps.loadCredential(refreshDb, settings, workspaceId, credentialId);
         if (current && current.status === "active") {
           return snapshot(current);
         }
-        throw new CodexReloginRequired("Codex credential changed during token refresh; reconnect required.");
+        throw new CodexReloginRequired(
+          "Codex credential changed during token refresh; reconnect required.",
+        );
       }
-      return { accessToken: tokens.access_token, chatgptAccountId: cred.chatgptAccountId, isFedramp: cred.isFedramp };
+      return {
+        accessToken: tokens.access_token,
+        chatgptAccountId: cred.chatgptAccountId,
+        isFedramp: cred.isFedramp,
+      };
     } catch (error) {
       if (error instanceof CodexReloginRequired) {
         // Stamp needs_relogin ONLY if the row we refreshed is STILL current
         // (compare-and-set on the loaded id+version). A relogin triggered by the
         // OLD token family must never stamp needs_relogin onto a freshly
         // reconnected credential.
-        await deps.setStatus(db, workspaceId, "needs_relogin", error.message, { id: cred.id, version: cred.version });
+        await deps.setStatus(refreshDb, workspaceId, "needs_relogin", error.message, {
+          id: cred.id,
+          version: cred.version,
+        });
       }
       throw error;
     }
   };
 
-  // ALL refreshes — whether triggered by proactive staleness (getToken) or by a
-  // 401 retry (refresh) — coalesce onto one in-flight promise per credential
-  // instance, so concurrent calls can never double-spend the one-time refresh
-  // token (which would trigger refresh_token_reused -> needs_relogin).
+  // ALL refreshes — whether proactive or a 401 retry — coalesce locally and then
+  // serialize globally before any rotating refresh token reaches the provider.
   const doRefresh = (cred: CodexCredentialForRun): Promise<CodexTokenSnapshot> => {
     const key = `${cred.id}:${cred.version}`;
     const existing = inflight.get(key);
     if (existing) {
       return existing;
     }
-    const promise = performRefresh(cred).finally(() => {
-      if (inflight.get(key) === promise) {
-        inflight.delete(key);
-      }
-    });
+    const promise = deps
+      .withRefreshLock(db, workspaceId, credentialId, async (lockedDb) => {
+        try {
+          const current = await deps.loadCredential(lockedDb, settings, workspaceId, credentialId);
+          if (!current || current.status !== "active") {
+            throw new CodexReloginRequired(
+              "Codex credential became unavailable while waiting to refresh.",
+            );
+          }
+          if (current.version !== cred.version) {
+            return { ok: true as const, value: snapshot(current) };
+          }
+          return { ok: true as const, value: await performRefresh(lockedDb, current) };
+        } catch (error) {
+          // withCodexCredentialRefreshLock uses an advisory TRANSACTION lock.
+          // performRefresh may persist `needs_relogin` before surfacing a
+          // permanent OAuth failure; throwing from this callback would roll that
+          // status write back with the outer transaction. Return the failure so
+          // the transaction commits, then rethrow after the lock is released.
+          return { ok: false as const, error };
+        }
+      })
+      .then((outcome) => {
+        if (!outcome.ok) throw outcome.error;
+        return outcome.value;
+      })
+      .finally(() => {
+        if (inflight.get(key) === promise) {
+          inflight.delete(key);
+        }
+      });
     inflight.set(key, promise);
     return promise;
   };

package/src/connection-token-resolver.ts

@@ -1,4 +1,8 @@
-import { environmentsEncryptionKeyBytes, type McpServerConnectionRef, type Settings } from "@opengeni/config";
+import {
+  environmentsEncryptionKeyBytes,
+  type McpServerConnectionRef,
+  type Settings,
+} from "@opengeni/config";
 import { Buffer } from "node:buffer";
 import { lookup } from "node:dns/promises";
 import { isIP } from "node:net";
@@ -15,15 +19,18 @@ import {
 export type ResolveConnectionCredentialResult =
   | { status: "ok"; headers: Record<string, string>; connectionId: string; expiresAt?: Date | null }
   | {
-    status: "auth_needed";
-    reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed";
-    providerDomain: string;
-    connectionId?: string;
-    scopes?: string[];
-    resource?: string;
-    authorizationUrl?: string;
-  };
-type AuthNeededReason = Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }>["reason"];
+      status: "auth_needed";
+      reason: "missing_connection" | "expired" | "insufficient_scope" | "refresh_failed";
+      providerDomain: string;
+      connectionId?: string;
+      scopes?: string[];
+      resource?: string;
+      authorizationUrl?: string;
+    };
+type AuthNeededReason = Extract<
+  ResolveConnectionCredentialResult,
+  { status: "auth_needed" }
+>["reason"];
 
 export type ResolveConnectionCredentialInput = {
   workspaceId: string;
@@ -64,7 +71,9 @@ export function buildConnectionTokenResolver(
   settings: Settings,
   deps: ConnectionBrokerDeps = defaultDeps,
 ): (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult> {
-  const load = async (input: ResolveConnectionCredentialInput): Promise<ConnectionCredentialForBroker | null> => {
+  const load = async (
+    input: ResolveConnectionCredentialInput,
+  ): Promise<ConnectionCredentialForBroker | null> => {
     const request: Parameters<typeof loadConnectionCredentialForBroker>[2] = {
       workspaceId: input.workspaceId,
       providerDomain: input.connectionRef.providerDomain,
@@ -83,7 +92,10 @@ export function buildConnectionTokenResolver(
     return deps.loadCredential(db, settings, request);
   };
 
-  const snapshot = async (cred: ConnectionCredentialForBroker, ref: McpServerConnectionRef): Promise<ResolveConnectionCredentialResult> => {
+  const snapshot = async (
+    cred: ConnectionCredentialForBroker,
+    ref: McpServerConnectionRef,
+  ): Promise<ResolveConnectionCredentialResult> => {
     if (cred.status !== "active") {
       return authNeededForStatus(cred, ref);
     }
@@ -118,7 +130,10 @@ export function buildConnectionTokenResolver(
     };
   };
 
-  const performRefresh = async (cred: ConnectionCredentialForBroker, ref: McpServerConnectionRef): Promise<ConnectionCredentialForBroker> => {
+  const performRefresh = async (
+    cred: ConnectionCredentialForBroker,
+    ref: McpServerConnectionRef,
+  ): Promise<ConnectionCredentialForBroker> => {
     const key = deps.keyBytes(settings);
     if (!key) {
       throw new Error("OPENGENI_ENVIRONMENTS_ENCRYPTION_KEY is not configured");
@@ -157,7 +172,10 @@ export function buildConnectionTokenResolver(
     throw new Error("connection credential changed during token refresh");
   };
 
-  const refreshSingleFlight = (cred: ConnectionCredentialForBroker, ref: McpServerConnectionRef): Promise<ConnectionCredentialForBroker> => {
+  const refreshSingleFlight = (
+    cred: ConnectionCredentialForBroker,
+    ref: McpServerConnectionRef,
+  ): Promise<ConnectionCredentialForBroker> => {
     const key = `${cred.id}:${cred.version}`;
     const existing = inflight.get(key);
     if (existing) {
@@ -193,10 +211,18 @@ export function buildConnectionTokenResolver(
         // Only a rejected grant may poison the connection; transient failures
         // (network errors, AS 5xx) leave it active so the next resolve retries.
         if (isPermanentRefreshError(error)) {
-          await deps.setStatus(db, input.workspaceId, "needs_reauth", error instanceof Error ? error.message : String(error), {
-            id: cred.id,
-            version: cred.version,
-          }).catch(() => undefined);
+          await deps
+            .setStatus(
+              db,
+              input.workspaceId,
+              "needs_reauth",
+              error instanceof Error ? error.message : String(error),
+              {
+                id: cred.id,
+                version: cred.version,
+              },
+            )
+            .catch(() => undefined);
         }
         return authNeeded(ref, "refresh_failed", cred.id);
       }
@@ -219,9 +245,13 @@ export class ConnectionRefreshHttpError extends Error {
 // forward. 429 (throttling) and 408 are transient despite being 4xx; network
 // failures and AS 5xx are likewise retryable.
 function isPermanentRefreshError(error: unknown): boolean {
-  return error instanceof ConnectionRefreshHttpError
-    && error.httpStatus >= 400 && error.httpStatus < 500
-    && error.httpStatus !== 408 && error.httpStatus !== 429;
+  return (
+    error instanceof ConnectionRefreshHttpError &&
+    error.httpStatus >= 400 &&
+    error.httpStatus < 500 &&
+    error.httpStatus !== 408 &&
+    error.httpStatus !== 429
+  );
 }
 
 function shouldRefresh(cred: ConnectionCredentialForBroker, force: boolean, now: Date): boolean {
@@ -237,7 +267,11 @@ function shouldRefresh(cred: ConnectionCredentialForBroker, force: boolean, now:
   return cred.expiresAt.getTime() <= now.getTime() + REFRESH_WINDOW_MS;
 }
 
-function authNeeded(ref: McpServerConnectionRef, reason: AuthNeededReason, connectionId?: string): ResolveConnectionCredentialResult {
+function authNeeded(
+  ref: McpServerConnectionRef,
+  reason: AuthNeededReason,
+  connectionId?: string,
+): ResolveConnectionCredentialResult {
   return {
     status: "auth_needed",
     reason,
@@ -248,11 +282,18 @@ function authNeeded(ref: McpServerConnectionRef, reason: AuthNeededReason, conne
   };
 }
 
-function authNeededForStatus(cred: ConnectionCredentialForBroker, ref: McpServerConnectionRef): ResolveConnectionCredentialResult {
+function authNeededForStatus(
+  cred: ConnectionCredentialForBroker,
+  ref: McpServerConnectionRef,
+): ResolveConnectionCredentialResult {
   if (cred.status === "revoked") {
     return authNeeded(ref, "missing_connection", cred.id);
   }
-  return authNeeded(ref, cred.expiresAt && cred.expiresAt.getTime() <= Date.now() ? "expired" : "refresh_failed", cred.id);
+  return authNeeded(
+    ref,
+    cred.expiresAt && cred.expiresAt.getTime() <= Date.now() ? "expired" : "refresh_failed",
+    cred.id,
+  );
 }
 
 function missingRequestedScopes(requested: string[] | undefined, granted: string[]): string[] {
@@ -263,6 +304,16 @@ function missingRequestedScopes(requested: string[] | undefined, granted: string
   return requested.filter((scope) => !grantedSet.has(scope));
 }
 
+/**
+ * Normalizes an OAuth token_type into the Authorization scheme to send. RFC 6750
+ * says the scheme is case-insensitive, but some MCP servers (e.g. Linear) reject
+ * a lowercase `bearer` — so a `bearer`/`BEARER` (or absent) token_type is sent as
+ * the canonical `Bearer`. A non-bearer scheme is passed through unchanged.
+ */
+export function normalizeBearerScheme(tokenType: string | null | undefined): string {
+  return !tokenType || /^bearer$/i.test(tokenType) ? "Bearer" : tokenType;
+}
+
 function headersForCredential(cred: ConnectionCredentialForBroker): Record<string, string> | null {
   if (cred.kind === "api_key") {
     return stringRecord((cred.credential as { headers?: unknown }).headers);
@@ -272,8 +323,9 @@ function headersForCredential(cred: ConnectionCredentialForBroker): Record<strin
     if (!accessToken) {
       return null;
     }
-    const tokenType = stringValue((cred.credential as { token_type?: unknown }).token_type) || "Bearer";
-    return { authorization: `${tokenType} ${accessToken}` };
+    return {
+      authorization: `${normalizeBearerScheme(stringValue((cred.credential as { token_type?: unknown }).token_type))} ${accessToken}`,
+    };
   }
   return stringRecord((cred.credential as { headers?: unknown }).headers);
 }
@@ -282,15 +334,23 @@ export async function refreshOAuthConnectionCredential(
   cred: ConnectionCredentialForBroker,
   ref: McpServerConnectionRef,
   settings?: Settings,
-): Promise<{ credential: Record<string, unknown>; expiresAt: Date | null; grantedScopes?: string[] }> {
+): Promise<{
+  credential: Record<string, unknown>;
+  expiresAt: Date | null;
+  grantedScopes?: string[];
+}> {
   if (cred.kind !== "oauth2") {
-    return { credential: cred.credential, expiresAt: cred.expiresAt, grantedScopes: cred.grantedScopes };
+    return {
+      credential: cred.credential,
+      expiresAt: cred.expiresAt,
+      grantedScopes: cred.grantedScopes,
+    };
   }
   const refreshToken = stringValue((cred.credential as { refresh_token?: unknown }).refresh_token);
   const tokenEndpoint =
-    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);
+    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);
   if (!refreshToken || !tokenEndpoint) {
     throw new Error("connection has no refresh token endpoint");
   }
@@ -304,11 +364,14 @@ export async function refreshOAuthConnectionCredential(
   // in the token request body (RFC 6749 §3.2.1); grant flows persist the
   // client_id they authorized with into the bundle/metadata.
   const clientId =
-    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);
+    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 authMethod = stringValue((cred.credential as { token_endpoint_auth_method?: unknown }).token_endpoint_auth_method) ?? "none";
+  const authMethod =
+    stringValue(
+      (cred.credential as { token_endpoint_auth_method?: unknown }).token_endpoint_auth_method,
+    ) ?? "none";
   if (clientId) {
     body.set("client_id", clientId);
   }
@@ -318,7 +381,8 @@ export async function refreshOAuthConnectionCredential(
   } else if (clientId && clientSecret && authMethod === "client_secret_basic") {
     headers.authorization = `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`;
   }
-  const resource = ref.resource ?? stringValue((cred.credential as { resource?: unknown }).resource);
+  const resource =
+    ref.resource ?? stringValue((cred.credential as { resource?: unknown }).resource);
   if (resource) {
     body.set("resource", resource);
   }
@@ -337,7 +401,7 @@ export async function refreshOAuthConnectionCredential(
   if (!response.ok) {
     throw new ConnectionRefreshHttpError(response.status);
   }
-  const payload = await response.json() as Record<string, unknown>;
+  const payload = (await response.json()) as Record<string, unknown>;
   const accessToken = stringValue(payload.access_token);
   if (!accessToken) {
     throw new Error("connection refresh response did not include access_token");
@@ -348,11 +412,16 @@ export async function refreshOAuthConnectionCredential(
     ...cred.credential,
     access_token: accessToken,
     refresh_token: stringValue(payload.refresh_token) ?? refreshToken,
-    token_type: stringValue(payload.token_type) ?? stringValue((cred.credential as { token_type?: unknown }).token_type) ?? "Bearer",
+    token_type:
+      stringValue(payload.token_type) ??
+      stringValue((cred.credential as { token_type?: unknown }).token_type) ??
+      "Bearer",
     ...(expiresAt ? { expires_at: expiresAt.toISOString() } : {}),
     ...(resource ? { resource } : {}),
     ...(scopeText ? { scope: scopeText } : {}),
-    ...(clientSecret ? { client_secret: clientSecret, token_endpoint_auth_method: authMethod } : {}),
+    ...(clientSecret
+      ? { client_secret: clientSecret, token_endpoint_auth_method: authMethod }
+      : {}),
   };
   return {
     credential: nextCredential,
@@ -361,7 +430,10 @@ export async function refreshOAuthConnectionCredential(
   };
 }
 
-function expiresAtFromTokenResponse(payload: Record<string, unknown>, fallback: Date | null): Date | null {
+function expiresAtFromTokenResponse(
+  payload: Record<string, unknown>,
+  fallback: Date | null,
+): Date | null {
   const expiresAt = stringValue(payload.expires_at);
   if (expiresAt) {
     const parsed = new Date(expiresAt);
@@ -393,7 +465,10 @@ function stringValue(value: unknown): string | undefined {
 }
 
 async function assertOAuthEndpointAllowed(rawUrl: string, settings: Settings): Promise<void> {
-  if (settings.integrationsAllowPrivateNetworkTargets || ["local", "test"].includes(settings.environment)) {
+  if (
+    settings.integrationsAllowPrivateNetworkTargets ||
+    ["local", "test"].includes(settings.environment)
+  ) {
     return;
   }
   const url = new URL(rawUrl);
@@ -423,14 +498,16 @@ export function isPrivateAddress(address: string): boolean {
     if (isIP(normalized) !== 6) {
       return true;
     }
-    return normalized === "::1"
-      || normalized === "::"
-      || normalized.startsWith("fc")
-      || normalized.startsWith("fd")
-      || normalized.startsWith("fe8")
-      || normalized.startsWith("fe9")
-      || normalized.startsWith("fea")
-      || normalized.startsWith("feb");
+    return (
+      normalized === "::1" ||
+      normalized === "::" ||
+      normalized.startsWith("fc") ||
+      normalized.startsWith("fd") ||
+      normalized.startsWith("fe8") ||
+      normalized.startsWith("fe9") ||
+      normalized.startsWith("fea") ||
+      normalized.startsWith("feb")
+    );
   }
   return isPrivateIpv4Address(normalized);
 }
@@ -457,7 +534,14 @@ function ipv4FromMappedIpv6(address: string): string | null {
   }
   const high = Number.parseInt(parts[0]!, 16);
   const low = Number.parseInt(parts[1]!, 16);
-  if (!Number.isInteger(high) || !Number.isInteger(low) || high < 0 || high > 0xffff || low < 0 || low > 0xffff) {
+  if (
+    !Number.isInteger(high) ||
+    !Number.isInteger(low) ||
+    high < 0 ||
+    high > 0xffff ||
+    low < 0 ||
+    low > 0xffff
+  ) {
     return null;
   }
   return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
@@ -468,14 +552,19 @@ function isPrivateIpv4Address(address: string): boolean {
     return true;
   }
   const parts = address.split(".").map((part) => Number(part));
-  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+  if (
+    parts.length !== 4 ||
+    parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
     return true;
   }
   const [a, b] = parts as [number, number, number, number];
-  return a === 0
-    || a === 10
-    || a === 127
-    || (a === 169 && b === 254)
-    || (a === 172 && b >= 16 && b <= 31)
-    || (a === 192 && b === 168);
+  return (
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168)
+  );
 }

package/src/environment-crypto.ts

@@ -13,7 +13,11 @@ export function encryptEnvironmentValue(key: Uint8Array, plaintext: string): str
   assertKey(key);
   const iv = randomBytes(IV_BYTES);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
-  const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final(), cipher.getAuthTag()]);
+  const ciphertext = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final(),
+    cipher.getAuthTag(),
+  ]);
   return `${VERSION_PREFIX}:${iv.toString("base64")}:${ciphertext.toString("base64")}`;
 }
 

package/src/event-payload-sanitizer.ts

@@ -97,13 +97,41 @@ export function sanitizeEventPayload<T>(payload: T): T {
   }
   if (payload && typeof payload === "object") {
     const entries = Object.entries(payload as Record<string, unknown>).map(
-      ([key, value]) => [sanitizeEventString(key), sanitizeSensitiveEventField(key, value)] as const,
+      ([key, value]) =>
+        [sanitizeEventString(key), sanitizeSensitiveEventField(key, value)] as const,
     );
     return Object.fromEntries(entries) as unknown as T;
   }
   return payload;
 }
 
+/**
+ * Make model-facing conversation data safe for Postgres without redacting it.
+ *
+ * Session events are an audit/UI projection and deliberately redact fields such
+ * as `token` and `authorization`. Conversation history is the replay source for
+ * the model, so applying event redaction there silently changes tool arguments
+ * and can make recovery diverge from the call that actually ran. This walker
+ * performs only the database-safety repair (NUL removal and UTF-16 repair).
+ */
+export function sanitizeModelPayload<T>(payload: T): T {
+  if (typeof payload === "string") {
+    return sanitizeEventString(payload) as unknown as T;
+  }
+  if (Array.isArray(payload)) {
+    return payload.map((item) => sanitizeModelPayload(item)) as unknown as T;
+  }
+  if (payload && typeof payload === "object") {
+    return Object.fromEntries(
+      Object.entries(payload as Record<string, unknown>).map(([key, value]) => [
+        sanitizeEventString(key),
+        sanitizeModelPayload(value),
+      ]),
+    ) as unknown as T;
+  }
+  return payload;
+}
+
 function sanitizeSensitiveEventField(key: string, value: unknown): unknown {
   if (key === "mcpServers") {
     return sanitizeSessionMcpServerList(value);