@agent-native/core 0.163.3 → 0.164.1

package/dist/server/auth-marketing.d.ts

@@ -16,4 +16,5 @@ export interface ResolveBuiltInAuthMarketingOptions {
 }
 export declare const BUILT_IN_AUTH_MARKETING: Record<string, AuthMarketingContent>;
 export declare function resolveBuiltInAuthMarketing(opts?: ResolveBuiltInAuthMarketingOptions): AuthMarketingContent | undefined;
+export declare function resolveBuiltInAuthMarketingSlug(opts?: ResolveBuiltInAuthMarketingOptions): string | undefined;
 export declare function resolveBuiltInAuthMarketingByName(value: string | undefined): AuthMarketingContent | undefined;

package/dist/server/auth-marketing.js

@@ -33,6 +33,7 @@ export const BUILT_IN_AUTH_MARKETING = {
         features: [
             "One-click screen recording with automatic titles, summaries, and chapters",
             "Calendar-synced meeting notes with live transcripts and action items",
+            "Push-to-talk voice dictation with clean text from anywhere",
             "One searchable library across recordings, meetings, and dictations",
         ],
     },
@@ -121,6 +122,34 @@ export const BUILT_IN_AUTH_MARKETING = {
             "Use the built-in app-agent loop or plug in your own agent backend",
         ],
     },
+    crm: {
+        appName: "Agent-Native CRM",
+        tagline: "A complete Native SQL CRM or a connected companion grounded in its source system.",
+        features: [
+            "Run accounts, people, opportunities, tasks, and cadence on Native SQL",
+            "Connect scoped HubSpot or Salesforce records without copying credentials",
+            "Work with the same safe actions from the UI or your CRM agent",
+        ],
+    },
+    factory: {
+        appName: "Agent-Native Factory",
+        tagline: "Build agent factories: work in one end, shipped changes out the other, with gates you control.",
+        features: [
+            "Inspect Slack and pull-request signals in one queue",
+            "Tune rules with prompts and reviewable feedback",
+            "Approve bounded agent work with a durable audit trail",
+        ],
+    },
+    tasks: {
+        appName: "Agent-Native Tasks",
+        tagline: "Manage your personal tasks: triage in the inbox, finish from the list. Use an agent that can do all of that for you.",
+        features: [
+            "Inbox triage — capture ideas and drafts as they come, then promote them to tasks when they are ready",
+            "Task management — create, reorder, and complete tasks in a list that stays in the order you put it in",
+            "Track what you care about with custom fields — text, numbers, currency, dates, and color-coded selects",
+            "Anything you can do here, the agent can do too — and it sees what is on your screen, so “finish these” means the rows you actually selected",
+        ],
+    },
 };
 const SLUG_ALIASES = {
     "agent-native": "",
@@ -204,12 +233,12 @@ function candidateSlugs(opts = {}) {
     return candidates.filter((slug) => !!slug);
 }
 export function resolveBuiltInAuthMarketing(opts = {}) {
-    for (const slug of candidateSlugs(opts)) {
-        const marketing = BUILT_IN_AUTH_MARKETING[slug];
-        if (marketing)
-            return cloneMarketing(marketing);
-    }
-    return undefined;
+    const slug = resolveBuiltInAuthMarketingSlug(opts);
+    const marketing = slug ? BUILT_IN_AUTH_MARKETING[slug] : undefined;
+    return marketing ? cloneMarketing(marketing) : undefined;
+}
+export function resolveBuiltInAuthMarketingSlug(opts = {}) {
+    return candidateSlugs(opts).find((slug) => !!BUILT_IN_AUTH_MARKETING[slug]);
 }
 export function resolveBuiltInAuthMarketingByName(value) {
     const slug = normalizeSlug(value);

package/dist/server/auth.js

@@ -61,7 +61,7 @@ import { getAppProductionUrl } from "./app-url.js";
 import { readAnalyticsAnonymousId, readFirstTouchAttribution, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
 import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
-import { BUILDER_CONNECT_OWNER_COOKIE, BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, BUILDER_STATE_PARAM, verifyBuilderCallbackStateAndGetOwner, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
+import { BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
 import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { readDesktopSso, writeDesktopSso, clearDesktopSso, } from "./desktop-sso.js";
@@ -1521,9 +1521,6 @@ export function shouldBypassAuthForBuilderConnect(event, p) {
     if (p === "/_agent-native/builder/callback") {
         const url = event.node?.req?.url ?? event.path ?? "/";
         const queryStart = url.indexOf("?");
-        const state = queryStart >= 0
-            ? new URLSearchParams(url.slice(queryStart + 1)).get(BUILDER_STATE_PARAM)
-            : null;
         const relayState = queryStart >= 0
             ? new URLSearchParams(url.slice(queryStart + 1)).get(BUILDER_RELAY_STATE_PARAM)
             : null;
@@ -1536,19 +1533,9 @@ export function shouldBypassAuthForBuilderConnect(event, p) {
                 // Dedicated relay secret missing: let the auth guard fail closed.
             }
         }
-        // The signed `_an_state` authenticates this specific Builder callback
-        // flow back to our app. A stale localhost session cookie can otherwise
-        // make the global guard reject the callback before the handler gets to
-        // validate the state and owner. This only bypasses to the callback route;
-        // the callback handler still verifies the signed owner / pending flow.
-        if (verifyBuilderCallbackStateAndGetOwner(state))
-            return true;
-        // The legacy owner cookie is broader and can be stale across shared
-        // browser sessions, so keep it limited to the session-lost popup case.
-        const hasSession = getFrameworkSessionCookieValues(event).length > 0;
-        if (hasSession)
-            return false;
-        return Boolean(verifyBuilderConnectTokenAndGetOwner(getCookie(event, BUILDER_CONNECT_OWNER_COOKIE)));
+        // Builder OAuth callback requires the signed-in session that started the
+        // flow; the handler verifies state + pending row + session owner. Do not
+        // bypass on legacy CLI `_an_state` or owner cookies.
     }
     return false;
 }

package/dist/server/builder-browser.d.ts

@@ -35,6 +35,28 @@ export interface BuilderRelayRequestBody {
     relayState: string;
     credentials: BuilderRelayCredentials;
 }
+/**
+ * Opaque OAuth `state` for Builder connect. Bound to the app auth secret so a
+ * pending row cannot be forged from another deployment that shares a database.
+ */
+export declare function createBuilderConnectState(): string;
+export declare function isSignedBuilderConnectState(value: string | null | undefined): boolean;
+/**
+ * Railway-safe Builder OAuth callback URL check: same origin as this request
+ * (via `isAllowedOAuthRedirectUri`), under `/_agent-native/`, HTTPS in
+ * production, and loopback HTTP only outside production. No fixed domain
+ * allowlist — any deploy origin (including `*.up.railway.app`) works when the
+ * redirect URI is this app's own callback.
+ */
+export declare function isBuilderConnectCallbackUrlAllowed(candidate: string, event: H3Event): boolean;
+/**
+ * Build this request's Builder OAuth callback URL from the current origin +
+ * `getAppBasePath()` + `BUILDER_CALLBACK_PATH`. Intentionally ignores any
+ * `?redirect_uri=` query override — connect always returns to this app's own
+ * callback. Validated with `isBuilderConnectCallbackUrlAllowed` (Railway-safe,
+ * no fixed domain allowlist).
+ */
+export declare function resolveBuilderConnectCallbackUrl(event: H3Event): string | null;
 export declare function isSafeBuilderRelayTargetOrigin(value: string): boolean;
 export declare function isTrustedBuilderRelayTargetOrigin(value: string): boolean;
 /**

package/dist/server/builder-browser.js

@@ -3,7 +3,7 @@ import { getHeader } from "h3";
 import { getSetting } from "../settings/store.js";
 import { applyBuilderUtmTrackingParams } from "../shared/builder-link-tracking.js";
 import { getAuthSecret, resolveSignupTrackingIdentity, } from "./better-auth-instance.js";
-import { getAppBasePath, getOrigin } from "./google-oauth.js";
+import { getAppBasePath, getOrigin, isAllowedOAuthRedirectUri, } from "./google-oauth.js";
 import { getRequestOrgId, getRequestUserEmail } from "./request-context.js";
 const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
 const DEFAULT_BUILDER_API_HOST = "https://api.builder.io";
@@ -47,6 +47,82 @@ function safeEqualText(expected, actual) {
     return (expectedBuffer.length === actualBuffer.length &&
         timingSafeEqual(expectedBuffer, actualBuffer));
 }
+/**
+ * Opaque OAuth `state` for Builder connect. Bound to the app auth secret so a
+ * pending row cannot be forged from another deployment that shares a database.
+ */
+export function createBuilderConnectState() {
+    const stateNonce = randomBytes(32).toString("base64url");
+    const signature = createHmac("sha256", `builder-connect-state:${getAuthSecret()}`)
+        .update(stateNonce)
+        .digest("base64url");
+    return `${stateNonce}.${signature}`;
+}
+export function isSignedBuilderConnectState(value) {
+    if (!value)
+        return false;
+    const [nonce, signature, ...rest] = value.split(".");
+    if (!nonce ||
+        !signature ||
+        rest.length ||
+        !/^[A-Za-z0-9_-]{43}$/.test(nonce) ||
+        !/^[A-Za-z0-9_-]{43}$/.test(signature)) {
+        return false;
+    }
+    const expected = createHmac("sha256", `builder-connect-state:${getAuthSecret()}`)
+        .update(nonce)
+        .digest("base64url");
+    return safeEqualText(expected, signature);
+}
+/**
+ * Railway-safe Builder OAuth callback URL check: same origin as this request
+ * (via `isAllowedOAuthRedirectUri`), under `/_agent-native/`, HTTPS in
+ * production, and loopback HTTP only outside production. No fixed domain
+ * allowlist — any deploy origin (including `*.up.railway.app`) works when the
+ * redirect URI is this app's own callback.
+ */
+export function isBuilderConnectCallbackUrlAllowed(candidate, event) {
+    if (!isAllowedOAuthRedirectUri(candidate, event))
+        return false;
+    let url;
+    try {
+        url = new URL(candidate);
+    }
+    catch {
+        // coercion-ok: malformed callback strings are not allowed redirects.
+        return false;
+    }
+    if (url.username || url.password)
+        return false;
+    const hostname = url.hostname.toLowerCase();
+    const loopback = hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "::1" ||
+        hostname === "[::1]";
+    if (loopback) {
+        return url.protocol === "http:" && process.env.NODE_ENV !== "production";
+    }
+    return url.protocol === "https:";
+}
+/**
+ * Build this request's Builder OAuth callback URL from the current origin +
+ * `getAppBasePath()` + `BUILDER_CALLBACK_PATH`. Intentionally ignores any
+ * `?redirect_uri=` query override — connect always returns to this app's own
+ * callback. Validated with `isBuilderConnectCallbackUrlAllowed` (Railway-safe,
+ * no fixed domain allowlist).
+ */
+export function resolveBuilderConnectCallbackUrl(event) {
+    const withBase = `${getOrigin(event)}${getAppBasePath()}${BUILDER_CALLBACK_PATH}`;
+    if (isBuilderConnectCallbackUrlAllowed(withBase, event))
+        return withBase;
+    // Match google-oauth default-redirect behavior when the request is not under
+    // APP_BASE_PATH: fall back to the root `/_agent-native/...` callback.
+    const root = `${getOrigin(event)}${BUILDER_CALLBACK_PATH}`;
+    if (root !== withBase && isBuilderConnectCallbackUrlAllowed(root, event)) {
+        return root;
+    }
+    return null;
+}
 function normalizeBuilderRelayBasePath(value) {
     if (!value)
         return "";

package/dist/server/builder-oauth.d.ts

@@ -0,0 +1,50 @@
+export declare const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
+export declare const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
+export declare const BUILDER_OAUTH_PROTECTED_RESOURCE_METADATA = "https://mcp.builder.io/.well-known/oauth-protected-resource/api";
+export declare const BUILDER_OAUTH_AUTHORIZATION_METADATA = "https://mcp.builder.io/.well-known/oauth-authorization-server";
+export declare const BUILDER_OAUTH_AUTHORIZATION_ENDPOINT = "https://mcp.builder.io/oauth/authorize";
+export declare const BUILDER_OAUTH_TOKEN_ENDPOINT = "https://mcp.builder.io/oauth/token";
+export declare const BUILDER_OAUTH_REGISTRATION_ENDPOINT = "https://mcp.builder.io/oauth/register";
+export declare const BUILDER_OAUTH_REVOCATION_ENDPOINT = "https://mcp.builder.io/oauth/revoke";
+export declare const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
+export declare const BUILDER_OAUTH_SCOPES: readonly ["builder:ai:invoke"];
+export type BuilderOAuthPendingFlow = {
+    codeVerifier: string;
+    clientInformation: unknown;
+    discoveryState?: unknown;
+    redirectUri: string;
+};
+export type BuilderOAuthSession = {
+    accessToken: string;
+    expiresAt?: number;
+    scopes: string[];
+};
+export type BuilderOAuthRequestAccess = BuilderOAuthSession & {
+    ownerEmail: string;
+};
+export declare function startBuilderOAuthAuthorization(input: {
+    ownerEmail: string;
+    redirectUri: string;
+    state: string;
+}): Promise<{
+    authorizationUrl: string;
+    pending: BuilderOAuthPendingFlow;
+}>;
+export declare function finishBuilderOAuthAuthorization(input: {
+    ownerEmail: string;
+    code: string;
+    iss?: string;
+    pending: BuilderOAuthPendingFlow;
+}): Promise<void>;
+export declare function markBuilderOAuthReconnectRequired(ownerEmail: string): Promise<void>;
+export declare function builderOAuthReconnectRequired(ownerEmail: string): Promise<boolean>;
+export declare function getBuilderOAuthSession(ownerEmail: string): Promise<BuilderOAuthSession | null>;
+export declare function hasBuilderOAuthSession(ownerEmail: string): Promise<boolean>;
+export declare function resolveBuilderOAuthRequestAccess(input: {
+    ownerEmail: string;
+    requiredScope: string;
+}): Promise<BuilderOAuthRequestAccess | null>;
+export declare function deleteBuilderOAuthSession(ownerEmail: string): Promise<{
+    localDeleted: boolean;
+    remoteRevoked: boolean;
+}>;

package/dist/server/builder-oauth.js

@@ -0,0 +1,263 @@
+import { finishMcpOAuthAuthorization, getMcpOAuthAccessToken, readMcpOAuthCredentials, revokeMcpOAuthCredentials, saveMcpOAuthCredentials, startMcpOAuthAuthorization, validateMcpOAuthCallbackIssuer, } from "../mcp-client/oauth-client.js";
+import { getOAuthTokens } from "../oauth-tokens/store.js";
+import { getSetting, mutateSetting, putSetting } from "../settings/store.js";
+export const BUILDER_OAUTH_ISSUER = "https://mcp.builder.io";
+export const BUILDER_OAUTH_RESOURCE = "https://api.builder.io";
+export const BUILDER_OAUTH_PROTECTED_RESOURCE_METADATA = "https://mcp.builder.io/.well-known/oauth-protected-resource/api";
+export const BUILDER_OAUTH_AUTHORIZATION_METADATA = "https://mcp.builder.io/.well-known/oauth-authorization-server";
+export const BUILDER_OAUTH_AUTHORIZATION_ENDPOINT = "https://mcp.builder.io/oauth/authorize";
+export const BUILDER_OAUTH_TOKEN_ENDPOINT = "https://mcp.builder.io/oauth/token";
+export const BUILDER_OAUTH_REGISTRATION_ENDPOINT = "https://mcp.builder.io/oauth/register";
+export const BUILDER_OAUTH_REVOCATION_ENDPOINT = "https://mcp.builder.io/oauth/revoke";
+export const BUILDER_OAUTH_SCOPE = "builder:ai:invoke";
+export const BUILDER_OAUTH_SCOPES = [BUILDER_OAUTH_SCOPE];
+const BUILDER_OAUTH_KEY = "builder-general-resource-v1";
+const REFRESH_SKEW_MS = 60_000;
+const REFRESH_LEASE_MS = 15_000;
+const REFRESH_WAIT_MS = 50;
+function ownerOptions(ownerEmail) {
+    const scopeId = ownerEmail.trim().toLowerCase();
+    if (!scopeId)
+        throw new Error("Builder OAuth owner email is required");
+    return {
+        key: BUILDER_OAUTH_KEY,
+        scope: "user",
+        scopeId,
+        serverUrl: BUILDER_OAUTH_RESOURCE,
+    };
+}
+function refreshLeaseKey(ownerEmail) {
+    return `builder-oauth-refresh:user:${ownerOptions(ownerEmail).scopeId}`;
+}
+function reconnectKey(ownerEmail) {
+    return `builder-oauth-reconnect:user:${ownerOptions(ownerEmail).scopeId}`;
+}
+function discoveryState() {
+    return {
+        authorizationServerUrl: BUILDER_OAUTH_ISSUER,
+        authorizationServerMetadata: {
+            issuer: BUILDER_OAUTH_ISSUER,
+            authorization_endpoint: BUILDER_OAUTH_AUTHORIZATION_ENDPOINT,
+            token_endpoint: BUILDER_OAUTH_TOKEN_ENDPOINT,
+            registration_endpoint: BUILDER_OAUTH_REGISTRATION_ENDPOINT,
+            revocation_endpoint: BUILDER_OAUTH_REVOCATION_ENDPOINT,
+            // MCP SDK auth() reads these from the provided discovery blob and throws
+            // if they are missing — do not omit them when skipping live metadata fetch.
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            code_challenge_methods_supported: ["S256"],
+        },
+        resourceMetadataUrl: BUILDER_OAUTH_PROTECTED_RESOURCE_METADATA,
+        resourceMetadata: {
+            resource: BUILDER_OAUTH_RESOURCE,
+            authorization_servers: [BUILDER_OAUTH_ISSUER],
+        },
+    };
+}
+function scopesFrom(credentials) {
+    const declared = credentials.tokens.scope;
+    if (typeof declared !== "string")
+        return [...BUILDER_OAUTH_SCOPES];
+    return declared.split(/\s+/).filter(Boolean);
+}
+function resourceUrlsMatch(left, right) {
+    try {
+        return new URL(left).href === new URL(right).href;
+    }
+    catch {
+        return left === right;
+    }
+}
+function isBuilderDiscoveryState(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const discovery = value;
+    const authorizationServers = discovery.resourceMetadata?.authorization_servers;
+    const responseTypes = discovery.authorizationServerMetadata?.response_types_supported;
+    const grantTypes = discovery.authorizationServerMetadata?.grant_types_supported;
+    const challengeMethods = discovery.authorizationServerMetadata?.code_challenge_methods_supported;
+    const resource = typeof discovery.resourceMetadata?.resource === "string"
+        ? discovery.resourceMetadata.resource
+        : null;
+    return (discovery?.authorizationServerUrl === BUILDER_OAUTH_ISSUER &&
+        discovery.authorizationServerMetadata?.issuer === BUILDER_OAUTH_ISSUER &&
+        discovery.authorizationServerMetadata?.authorization_endpoint ===
+            BUILDER_OAUTH_AUTHORIZATION_ENDPOINT &&
+        discovery.authorizationServerMetadata?.token_endpoint ===
+            BUILDER_OAUTH_TOKEN_ENDPOINT &&
+        discovery.authorizationServerMetadata?.registration_endpoint ===
+            BUILDER_OAUTH_REGISTRATION_ENDPOINT &&
+        discovery.authorizationServerMetadata?.revocation_endpoint ===
+            BUILDER_OAUTH_REVOCATION_ENDPOINT &&
+        Array.isArray(responseTypes) &&
+        responseTypes.includes("code") &&
+        Array.isArray(grantTypes) &&
+        grantTypes.includes("authorization_code") &&
+        Array.isArray(challengeMethods) &&
+        challengeMethods.includes("S256") &&
+        discovery.resourceMetadataUrl ===
+            BUILDER_OAUTH_PROTECTED_RESOURCE_METADATA &&
+        !!resource &&
+        resourceUrlsMatch(resource, BUILDER_OAUTH_RESOURCE) &&
+        Array.isArray(authorizationServers) &&
+        authorizationServers.includes(BUILDER_OAUTH_ISSUER));
+}
+function isBuilderCredential(credentials) {
+    return (resourceUrlsMatch(credentials.serverUrl, BUILDER_OAUTH_RESOURCE) &&
+        credentials.clientInformation.issuer === BUILDER_OAUTH_ISSUER &&
+        credentials.tokens.issuer === BUILDER_OAUTH_ISSUER &&
+        isBuilderDiscoveryState(credentials.discoveryState));
+}
+function sessionFrom(credentials) {
+    if (!isBuilderCredential(credentials))
+        return null;
+    const accessToken = credentials.tokens.access_token;
+    if (typeof accessToken !== "string" || !accessToken)
+        return null;
+    return {
+        accessToken,
+        expiresAt: credentials.tokenExpiresAt,
+        scopes: scopesFrom(credentials),
+    };
+}
+export async function startBuilderOAuthAuthorization(input) {
+    ownerOptions(input.ownerEmail);
+    const started = await startMcpOAuthAuthorization({
+        serverUrl: BUILDER_OAUTH_RESOURCE,
+        redirectUrl: input.redirectUri,
+        state: input.state,
+        scope: BUILDER_OAUTH_SCOPE,
+        discoveryState: discoveryState(),
+    });
+    return {
+        authorizationUrl: started.authorizationUrl.toString(),
+        pending: {
+            codeVerifier: started.codeVerifier,
+            clientInformation: started.clientInformation,
+            discoveryState: started.discoveryState,
+            redirectUri: input.redirectUri,
+        },
+    };
+}
+export async function finishBuilderOAuthAuthorization(input) {
+    if (!isBuilderDiscoveryState(input.pending.discoveryState)) {
+        throw new Error("Builder OAuth pending flow has an invalid discovery binding");
+    }
+    validateMcpOAuthCallbackIssuer(input.pending.discoveryState, input.iss);
+    const result = await finishMcpOAuthAuthorization({
+        serverUrl: BUILDER_OAUTH_RESOURCE,
+        redirectUrl: input.pending.redirectUri,
+        state: "callback-state-validated-by-route",
+        codeVerifier: input.pending.codeVerifier,
+        clientInformation: input.pending.clientInformation,
+        discoveryState: input.pending.discoveryState,
+        authorizationCode: input.code,
+        iss: input.iss,
+    });
+    if (!isBuilderCredential(result.credentials)) {
+        throw new Error("Builder OAuth exchange returned credentials for another resource");
+    }
+    await saveMcpOAuthCredentials({
+        ...ownerOptions(input.ownerEmail),
+        credentials: result.credentials,
+    });
+    await putSetting(reconnectKey(input.ownerEmail), {
+        required: false,
+        at: Date.now(),
+    }).catch(() => {
+        // coercion-ok: reconnect flag clear is best-effort after a successful grant.
+    });
+}
+export async function markBuilderOAuthReconnectRequired(ownerEmail) {
+    await putSetting(reconnectKey(ownerEmail), {
+        required: true,
+        at: Date.now(),
+    });
+}
+export async function builderOAuthReconnectRequired(ownerEmail) {
+    const row = await getSetting(reconnectKey(ownerEmail));
+    return row?.required === true;
+}
+export async function getBuilderOAuthSession(ownerEmail) {
+    if (await builderOAuthReconnectRequired(ownerEmail))
+        return null;
+    const credentials = await readMcpOAuthCredentials(ownerOptions(ownerEmail));
+    if (!credentials || !isBuilderCredential(credentials))
+        return null;
+    if (typeof credentials.tokenExpiresAt === "number" &&
+        credentials.tokenExpiresAt - Date.now() <= REFRESH_SKEW_MS) {
+        return refreshBuilderOAuthSession(ownerEmail);
+    }
+    return sessionFrom(credentials);
+}
+export async function hasBuilderOAuthSession(ownerEmail) {
+    const options = ownerOptions(ownerEmail);
+    const stored = await getOAuthTokens("mcp", options.key, `${options.scope}:${options.scopeId}`);
+    return stored !== null;
+}
+export async function resolveBuilderOAuthRequestAccess(input) {
+    const session = await getBuilderOAuthSession(input.ownerEmail);
+    if (!session)
+        return null;
+    if (!session.scopes.includes(input.requiredScope)) {
+        throw new Error(`Builder OAuth connection does not grant ${input.requiredScope}`);
+    }
+    return { ...session, ownerEmail: ownerOptions(input.ownerEmail).scopeId };
+}
+async function refreshBuilderOAuthSession(ownerEmail) {
+    const owner = crypto.randomUUID();
+    const leaseKey = refreshLeaseKey(ownerEmail);
+    const lease = await mutateSetting(leaseKey, (current) => {
+        if (typeof current?.expiresAt !== "number" ||
+            current.expiresAt <= Date.now()) {
+            return { owner, expiresAt: Date.now() + REFRESH_LEASE_MS };
+        }
+        return current;
+    });
+    if (lease.owner !== owner)
+        return waitForRefreshedSession(ownerEmail);
+    try {
+        const options = ownerOptions(ownerEmail);
+        const accessToken = await getMcpOAuthAccessToken(options);
+        const next = await readMcpOAuthCredentials(options);
+        if (!accessToken || !next || !isBuilderCredential(next)) {
+            throw new Error("Builder OAuth refresh failed");
+        }
+        return sessionFrom(next);
+    }
+    catch {
+        await markBuilderOAuthReconnectRequired(ownerEmail);
+        return null;
+    }
+    finally {
+        await mutateSetting(leaseKey, (current) => current?.owner === owner ? { owner: "", expiresAt: 0 } : (current ?? {}));
+    }
+}
+async function waitForRefreshedSession(ownerEmail) {
+    for (let waited = 0; waited < REFRESH_LEASE_MS; waited += REFRESH_WAIT_MS) {
+        await new Promise((resolve) => setTimeout(resolve, REFRESH_WAIT_MS));
+        const credentials = await readMcpOAuthCredentials(ownerOptions(ownerEmail));
+        if (!credentials || !isBuilderCredential(credentials))
+            return null;
+        if (typeof credentials.tokenExpiresAt !== "number" ||
+            credentials.tokenExpiresAt - Date.now() <= REFRESH_SKEW_MS) {
+            continue;
+        }
+        return sessionFrom(credentials);
+    }
+    return null;
+}
+export async function deleteBuilderOAuthSession(ownerEmail) {
+    const options = ownerOptions(ownerEmail);
+    const result = await revokeMcpOAuthCredentials(options);
+    await putSetting(reconnectKey(ownerEmail), {
+        required: false,
+        at: Date.now(),
+    }).catch(() => {
+        // coercion-ok: reconnect flag clear is best-effort after local revoke.
+    });
+    return {
+        localDeleted: result.local === "deleted",
+        remoteRevoked: result.remote === "succeeded",
+    };
+}

package/dist/server/core-routes-plugin.d.ts

@@ -1,5 +1,6 @@
 import type { H3Event } from "h3";
 import { type DatabaseSchemaHealthResult } from "../db/runtime-diagnostics.js";
+import { getSetting, deleteSetting, mutateSetting, listSettingsByPrefix } from "../settings/store.js";
 import { type AuthSession } from "./auth.js";
 import { type BuilderConnectTrackingParams, type BuilderRelayCredentials } from "./builder-browser.js";
 import type { EnvKeyConfig } from "./create-server.js";
@@ -162,6 +163,16 @@ export declare function buildBuilderWaitlistFormPayload(event: H3Event, sessionE
 };
 export declare const AVATAR_RASTER_MIME: RegExp;
 export declare function resolveAvatarEmailParam(pathname: string, appBasePath?: string): string;
+export declare function isBuilderConnectCallbackOwner(pendingOwner: string, sessionOwner: string | undefined): boolean;
+export declare function consumeBuilderConnectPendingState(state: string, dependencies?: {
+    mutate: typeof mutateSetting;
+    remove: typeof deleteSetting;
+}): Promise<Record<string, unknown> | null>;
+export declare function readBuilderConnectPendingState(state: string, read?: typeof getSetting): Promise<Record<string, unknown> | null>;
+export declare function purgeExpiredBuilderConnectPendingStates(now?: number, dependencies?: {
+    list: typeof listSettingsByPrefix;
+    remove: typeof deleteSetting;
+}): Promise<number>;
 type BuilderAnonymousOwnerResolver = (event: H3Event) => string | null | Promise<string | null>;
 export type BuilderOwnerContext = {
     email: string | undefined;