@agent-native/core 0.149.5 → 0.151.0

package/dist/progress/routes.d.ts

@@ -15,6 +15,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -77,7 +77,7 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
 }, z.core.$strip>>, {
     id?: undefined;
     deleted?: undefined;
-    provider?: undefined;
+    message?: undefined;
     providers: {
         id: string;
         label: string;
@@ -88,45 +88,45 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         updatedAt: number;
     }[];
     count: number;
+    provider?: undefined;
     found?: undefined;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
+    count?: undefined;
     id?: undefined;
     deleted?: undefined;
-    count?: undefined;
+    message?: undefined;
     providers?: undefined;
     found: boolean;
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
-    deleted?: undefined;
     count?: undefined;
-    provider?: undefined;
+    deleted?: undefined;
+    message?: undefined;
     providers?: undefined;
+    provider?: undefined;
     found: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
     count?: undefined;
-    provider?: undefined;
+    message?: undefined;
     providers?: undefined;
+    provider?: undefined;
     found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
-    message?: undefined;
 } | {
-    deleted?: undefined;
     count?: undefined;
-    provider?: undefined;
+    deleted?: undefined;
     providers?: undefined;
+    provider?: undefined;
     found?: undefined;
     registered: boolean;
     id: string;

package/dist/provider-api/actions/provider-api.d.ts

@@ -311,8 +311,8 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        message?: undefined;
         id?: undefined;
+        provider?: undefined;
         deleted?: undefined;
         providers: {
             id: string;
@@ -324,12 +324,11 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
-        provider?: undefined;
         found?: undefined;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         count?: undefined;
         id?: undefined;
         deleted?: undefined;
@@ -338,31 +337,32 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         provider: import("../custom-registry.js").CustomProviderConfig;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         count?: undefined;
+        provider?: undefined;
         deleted?: undefined;
         providers?: undefined;
-        provider?: undefined;
         found: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
-    } | {
         message?: undefined;
+    } | {
         count?: undefined;
-        providers?: undefined;
         provider?: undefined;
+        providers?: undefined;
         found?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
+        message?: undefined;
     } | {
         count?: undefined;
+        provider?: undefined;
         deleted?: undefined;
         providers?: undefined;
-        provider?: undefined;
         found?: undefined;
         registered: boolean;
         id: string;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/browser-team-tools.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { getActiveFileUploadProviderForRequest } from "../../file-upload/registry.js";
 import { areBuiltinMcpCapabilitiesSupported, buildMergedConfig, setBuiltinMcpCapabilityEnabled, } from "../../mcp-client/index.js";
 import { getBuilderBrowserConnectUrlForOwner, resolveBuilderBranchProjectId, } from "../builder-browser.js";
 import { getRequestUserEmail } from "../request-context.js";
@@ -73,6 +74,25 @@ export function createBuilderBrowserTool(deps) {
         return { ok: true, enabledIds: enabledIds ?? [] };
     };
     const entries = {
+        "connect-file-storage": {
+            tool: {
+                description: "Render the inline file-storage setup card when an image or file attachment could not be durably uploaded. The card lets the user connect Builder for managed object storage or open the same custom-key setup used by onboarding. Call it immediately when the attachment context says storage is missing; do not ask the user to upload the file again.",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            run: async () => {
+                const activeProvider = await getActiveFileUploadProviderForRequest();
+                const ownerEmail = deps.getOwner?.() ?? getRequestUserEmail();
+                return JSON.stringify({
+                    kind: "connect-file-storage-card",
+                    configured: !!activeProvider,
+                    provider: activeProvider?.name ?? null,
+                    connectUrl: getBuilderBrowserConnectUrlForOwner(deps.getOrigin(), ownerEmail),
+                });
+            },
+        },
         "connect-builder": {
             tool: {
                 description: `Render a Builder.io card inline in the chat. Call this as the first step (no code exploration or planning needed) when the user asks to modify the APP'S OWN SOURCE CODE: add a feature, change the UI chrome, edit a React component, add a route, add an integration, fix a bug in the app itself, or anything else that requires source-file edits while in hosted/production mode. ${extensionRequestGuidance}Do NOT call this for content the app is meant to produce — creating a video, generating a design, drafting an email, building a slide deck, making a dashboard, etc. — those run through the app's own domain actions, not Builder. Do NOT mention 'click Send to Builder' in your response unless this card is already in the conversation. The tool result includes \`builderEnabled\`; treat \`true\` as "Builder Cloud Agents can take the code-change handoff" and \`false\` as "this still needs a code change, but no Builder Cloud Agent can run here." If Builder is connected and Builder Cloud Agents are available, the card shows a 'Send to Builder' button that hands the work off to Builder's cloud agent and returns a branch URL. If \`builderEnabled\` is false, the card still renders but shows the code-change fallback: "This requires a code change. Edit locally or use Builder.io to edit this code in the cloud and continue customizing the app any way you like." Never tell the user to enable Builder Cloud Agents in Builder org settings or beta settings, and do not claim the Builder card has everything, is pre-loaded for handoff, or can run the cloud agent when \`builderEnabled\` is false. When you call this for a code-change request, pass the user's request verbatim as the \`prompt\` arg so the card can forward it to Builder unchanged when cloud agents are available.`,

package/dist/server/agent-chat-plugin.js

@@ -951,9 +951,18 @@ export function createAgentChatPlugin(options) {
             const corpusToolNames = loadCorpusToolsInitially
                 ? corpusToolNamesTaughtByPrompt(corpusPromptRegistry)
                 : [];
-            const effectiveInitialToolNames = corpusToolNames.length > 0
-                ? [...new Set([...templateInitialToolNames, ...corpusToolNames])]
-                : templateInitialToolNames;
+            const effectiveInitialToolNames = [
+                ...new Set([
+                    ...templateInitialToolNames,
+                    ...corpusToolNames,
+                    // Attachment setup is a recovery action, but it must be available on
+                    // the first request so a missing provider renders the CTA immediately
+                    // instead of spending another turn in tool-search.
+                    ...(browserTools["connect-file-storage"]
+                        ? ["connect-file-storage"]
+                        : []),
+                ]),
+            ];
             const resolveExtraContext = async (event, owner) => {
                 if (!options?.extraContext)
                     return "";

package/dist/server/auth.js

@@ -55,6 +55,7 @@ import { normalizeWorkspaceAppAudience, workspaceAppAudienceFromEnv, workspaceAp
 import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
 import { injectAnalyticsIntoHtml } from "./analytics.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
+import { getAppProductionUrl } from "./app-url.js";
 import { readAnalyticsAnonymousId, signupAttributionFromCookieHeader, } from "./attribution.js";
 import { getAuthLoginMode } from "./auth-login-mode.js";
 import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
@@ -64,10 +65,7 @@ import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js
 import { readDesktopSso, writeDesktopSso, clearDesktopSso, } from "./desktop-sso.js";
 import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
 import { isElectron as isElectronRequest, getAppBasePath, getAppUrl, getOrigin, encodeOAuthState, decodeOAuthState, createOAuthSession, oauthCallbackResponse, oauthDesktopExchangePage, oauthErrorPage, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, } from "./google-oauth.js";
-// Pure env-read feature switch from a leaf module (no dependency back on
-// auth.ts), so the guard and the SSO route handler share one validator and
-// can never disagree about whether federated SSO is enabled.
-import { isIdentitySsoEnabled } from "./identity-sso-store.js";
+import { isCanonicalAgentNativeAppRequest, isDesktopSsoCanaryUserAgent, isIdentitySsoEnabled, } from "./identity-sso-store.js";
 import { ensureCanonicalUserForLegacySession } from "./legacy-auth-migration.js";
 import { safeOAuthReturnUrl } from "./oauth-return-url.js";
 import { getOnboardingHtml, getResetPasswordHtml, } from "./onboarding-html.js";
@@ -312,6 +310,23 @@ export function isDevEnvironment() {
 export function safeReturnPath(raw) {
     return normalizeAppPath(raw) ?? "/";
 }
+// Better Auth's relative callback validator is stricter than normalizeAppPath:
+// query values such as UTM labels may contain characters that are safe here but
+// invalid as a Better Auth relative callback. Promote those paths to the
+// canonical app origin so the callback remains same-origin and valid there.
+const BETTER_AUTH_RELATIVE_CALLBACK_PATH_RE = /^\/(?!\/|\\|%2f|%5c)[\w\-.\+/@]*(?:\?[\w\-.\+/=&%@]*)?$/i;
+function betterAuthCallbackURL(raw, forceAbsolute = false, event) {
+    const safePath = safeReturnPath(raw);
+    if (!forceAbsolute && BETTER_AUTH_RELATIVE_CALLBACK_PATH_RE.test(safePath)) {
+        return safePath;
+    }
+    try {
+        return new URL(safePath, getAppProductionUrl(event)).toString();
+    }
+    catch {
+        return "/";
+    }
+}
 /**
  * Return the configured login HTML for this request, or `null` when no auth
  * guard is installed. Used by the `/_agent-native/open` deep-link route to
@@ -1693,13 +1708,16 @@ function createAuthGuardFn() {
         // definition, NOT yet signed in to THIS app) must bypass the blanket
         // 401-for-/_agent-native/*: they resolve / mint the browser session
         // themselves and verify a signature-bound, single-use, CSRF-stated
-        // hub token — not a cookie. This bypass is GATED on the opt-in env var
-        // so an unset `AGENT_NATIVE_IDENTITY_HUB_URL` is a true no-op (the
-        // guard's behaviour is byte-for-byte unchanged when SSO is off). The
-        // handler itself 404s when disabled as defence in depth.
-        if (isIdentitySsoEnabled() &&
-            (p === "/_agent-native/identity/login" ||
-                p === "/_agent-native/identity/callback")) {
+        // hub token — not a cookie. The handler fails closed with 404 unless
+        // direct web SSO is configured or this is the packaged SSO Canary on a
+        // canonical app origin. Keeping the bypass exact lets that request-scoped
+        // decision happen without exposing any other identity subpath.
+        const isIdentitySsoEntryPath = p === "/_agent-native/identity/login" ||
+            p === "/_agent-native/identity/callback";
+        const isDesktopCanaryIdentityRequest = isDesktopSsoCanaryUserAgent(getHeader(event, "user-agent")) &&
+            isCanonicalAgentNativeAppRequest(getHeader(event, "host"), getHeader(event, "x-forwarded-proto"));
+        if (isIdentitySsoEntryPath &&
+            (isIdentitySsoEnabled() || isDesktopCanaryIdentityRequest)) {
             return;
         }
         // Internal processor endpoint for the A2A async-mode fanout. Mirrors the
@@ -2971,6 +2989,7 @@ async function mountBetterAuthRoutes(app, options) {
     // need for a separate "Connect Google" page.
     const betterAuthConfig = {
         ...(options.betterAuth ?? {}),
+        ...(options.maxAge !== undefined ? { sessionMaxAge: options.maxAge } : {}),
         ...(options.googleScopes ? { googleScopes: options.googleScopes } : {}),
     };
     const auth = await getBetterAuth(betterAuthConfig);
@@ -3046,10 +3065,13 @@ async function mountBetterAuthRoutes(app, options) {
             }
         }
         // The signup wrapper sanitizes callbackURL before calling Better Auth,
-        // but the resend endpoint is exposed directly so users can request a
-        // fresh link while unauthenticated. Keep that path equally strict:
-        // only same-origin relative return paths survive into the email.
-        if (isSendVerificationEmail || isMagicLinkRequest) {
+        // but the direct email and magic-link endpoints are also reachable from
+        // the browser. Keep every callback path valid for Better Auth's own
+        // stricter relative URL validator before it is embedded in an email.
+        if (isSendVerificationEmail ||
+            isMagicLinkRequest ||
+            reqPath.includes("/sign-up/email") ||
+            reqPath.includes("/sign-in/email")) {
             try {
                 const body = (await authRequest
                     .clone()
@@ -3064,7 +3086,7 @@ async function mountBetterAuthRoutes(app, options) {
                     for (const key of callbackKeys) {
                         if (typeof body[key] !== "string")
                             continue;
-                        const callbackURL = safeReturnPath(body[key]);
+                        const callbackURL = betterAuthCallbackURL(body[key], false, event);
                         if (callbackURL !== body[key]) {
                             sanitizedBody[key] = callbackURL;
                             changed = true;
@@ -3273,7 +3295,7 @@ async function mountBetterAuthRoutes(app, options) {
         const body = await readBody(event);
         const rawEmail = typeof body?.email === "string" ? body.email : "";
         const email = normalizeAuthEmail(rawEmail);
-        let callbackURL = typeof body?.callbackURL === "string"
+        let callbackPath = typeof body?.callbackURL === "string"
             ? safeReturnPath(body.callbackURL)
             : "/";
         let desktopFlow;
@@ -3286,15 +3308,17 @@ async function mountBetterAuthRoutes(app, options) {
             return { error: GOOGLE_AUTH_REQUIRED_MESSAGE };
         }
         try {
-            if (isDesktopMagicLinkCallbackPath(callbackURL)) {
+            if (isDesktopMagicLinkCallbackPath(callbackPath)) {
                 desktopFlow = await issueDesktopMagicLinkFlow();
-                callbackURL = withDesktopMagicLinkFlow(callbackURL, desktopFlow);
+                callbackPath = withDesktopMagicLinkFlow(callbackPath, desktopFlow);
             }
+            const callbackURL = betterAuthCallbackURL(callbackPath, false, event);
+            const newUserCallbackPath = `${getAppBasePath()}/_agent-native/auth/magic-link/new-user?return=${encodeURIComponent(callbackPath)}`;
             await auth.api.signInMagicLink({
                 body: {
                     email,
                     callbackURL,
-                    newUserCallbackURL: `${getAppBasePath()}/_agent-native/auth/magic-link/new-user?return=${encodeURIComponent(callbackURL)}`,
+                    newUserCallbackURL: betterAuthCallbackURL(newUserCallbackPath, callbackURL !== callbackPath, event),
                 },
                 headers: event.headers,
             });
@@ -3323,7 +3347,7 @@ async function mountBetterAuthRoutes(app, options) {
         const email = normalizeAuthEmail(rawEmail);
         const password = body?.password;
         const callbackURL = typeof body?.callbackURL === "string"
-            ? safeReturnPath(body.callbackURL)
+            ? betterAuthCallbackURL(body.callbackURL, false, event)
             : "/";
         if (!email) {
             setResponseStatus(event, 400);

package/dist/server/better-auth-instance.d.ts

@@ -118,6 +118,8 @@ export interface BetterAuthInstance {
 export interface BetterAuthConfig {
     /** Base path for Better Auth routes. Default: "/_agent-native/auth/ba" */
     basePath?: string;
+    /** Session max age in seconds. Defaults to the framework's 30-day lifetime. */
+    sessionMaxAge?: number;
     /** Additional social providers beyond what env vars auto-detect */
     socialProviders?: BetterAuthOptions["socialProviders"];
     /** Additional Better Auth plugins */

package/dist/server/better-auth-instance.js

@@ -1048,8 +1048,8 @@ async function createBetterAuthInstance(config) {
             },
         },
         session: {
-            expiresIn: 60 * 60 * 24 * 30, // 30 days
-            updateAge: 60 * 60 * 24, // refresh daily
+            expiresIn: config?.sessionMaxAge ?? 60 * 60 * 24 * 30,
+            updateAge: Math.min(60 * 60 * 24, config?.sessionMaxAge ?? 60 * 60 * 24 * 30), // refresh daily, or sooner for short custom sessions
             cookieCache: {
                 enabled: true,
                 maxAge: 5 * 60, // 5 min cache

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

@@ -293,6 +293,7 @@ export declare function readLegacyCoreRouteInitSettings(readSetting?: CoreRouteS
  * their cold-start budget on legacy cleanup or best-effort table warmups.
  */
 export declare function shouldRunCoreRouteBootDatabaseWork(env?: NodeJS.ProcessEnv): boolean;
+export declare function ensureS3FileUploadProvider(): void;
 export declare function createCoreRoutesPlugin(options?: CoreRoutesPluginOptions): NitroPluginDef;
 /**
  * Default core routes plugin — mount with no configuration needed.

package/dist/server/core-routes-plugin.js

@@ -11,7 +11,8 @@ import { mountDbAdminRoutes } from "../db-admin/routes.js";
 import { getDbExec, isProductionServerlessFunctionRuntime, } from "../db/client.js";
 import { getDatabaseRuntimeFingerprint, getRuntimeDebugFingerprint, runDatabaseSchemaHealthCheck, } from "../db/runtime-diagnostics.js";
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
-import { uploadFile, getActiveFileUploadProviderForRequest, listFileUploadProviders, } from "../file-upload/index.js";
+import { uploadFile, getActiveFileUploadProviderForRequest, listFileUploadProviders, registerFileUploadProvider, } from "../file-upload/index.js";
+import { s3FileUploadProvider } from "../file-upload/s3.js";
 import { handleMcpConnect } from "../mcp/connect-route.js";
 import { handleMcpOAuth, handleMcpOAuthAuthorizationServerMetadata, handleMcpOAuthProtectedResourceMetadata, } from "../mcp/oauth-route.js";
 import { MCP_ROUTE_PREFIXES } from "../mcp/route-paths.js";
@@ -51,7 +52,6 @@ import { createGatewayAccessCheckHandler } from "./gateway-access-check.js";
 import { getAppBasePath, getOrigin } from "./google-oauth.js";
 import { createGoogleRealtimeSessionHandler } from "./google-realtime-session.js";
 import { readBody, DEFAULT_UPLOAD_MAX_FILE_BYTES, isAllowedUploadMimeType, } from "./h3-helpers.js";
-import { isIdentitySsoEnabled } from "./identity-sso-store.js";
 import { handleIdentitySso } from "./identity-sso.js";
 import { createOpenRouteHandler } from "./open-route.js";
 import { createPollEventsHandler } from "./poll-events.js";
@@ -889,6 +889,12 @@ function wireRouteErrorCapture(nitroApp) {
         }
     });
 }
+export function ensureS3FileUploadProvider() {
+    if (listFileUploadProviders().some((provider) => provider.id === s3FileUploadProvider.id)) {
+        return;
+    }
+    registerFileUploadProvider(s3FileUploadProvider);
+}
 export function createCoreRoutesPlugin(options = {}) {
     return async (nitroApp) => {
         markDefaultPluginProvided(nitroApp, "core-routes");
@@ -905,6 +911,12 @@ export function createCoreRoutesPlugin(options = {}) {
         });
         try {
             const P = FRAMEWORK_ROUTE_PREFIX;
+            // Keep the framework-owned S3-compatible provider available even when an
+            // app does not mount the optional onboarding plugin. The settings CTA and
+            // the upload route share this registry. An app may register its own
+            // provider under the conventional `s3` id, so preserve that explicit
+            // registration instead of replacing it during core bootstrap.
+            ensureS3FileUploadProvider();
             // This response is a side-effect-free static contract used by the SSR
             // shell. Mount it before optional default-plugin/bootstrap work so a
             // browser's automatic rules fetch cannot inherit the cold-start wait.
@@ -3077,22 +3089,20 @@ export function createCoreRoutesPlugin(options = {}) {
                     }));
                 }
             }
-            // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Mounted
-            // ONLY when `AGENT_NATIVE_IDENTITY_HUB_URL` is set, so an unset env var
-            // means the route is never even registered: zero new surface, existing
-            // auth byte-for-byte unchanged. `/login` 302s to the identity hub;
+            // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. `/login`
+            // 302s to the identity hub;
             // `/callback` verifies the hub-issued A2A-signed identity JWT and JIT-
             // links the verified email into this app's local Better Auth store. The
-            // handler 404s if disabled (defence in depth). The auth guard bypasses
-            // these two exact paths under the same env gate.
-            if (isIdentitySsoEnabled()) {
-                getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
-                    // Framework strips the mount prefix; what remains is the subpath
-                    // after `/identity` (e.g. `/login`, `/callback`).
-                    const subpath = event.url?.pathname || "";
-                    return handleIdentitySso(event, subpath);
-                }));
-            }
+            // handler fails closed unless direct web SSO is configured or the
+            // packaged Desktop SSO Canary requests a canonical Agent Native app.
+            // Mounting the handler unconditionally lets that request-scoped decision
+            // work.
+            getH3App(nitroApp).use(`${P}/identity`, defineEventHandler(async (event) => {
+                // Framework strips the mount prefix; what remains is the subpath
+                // after `/identity` (e.g. `/login`, `/callback`).
+                const subpath = event.url?.pathname || "";
+                return handleIdentitySso(event, subpath);
+            }));
             if (!options.disableOpenRoute) {
                 // Stable deep-link route. External agents (MCP/A2A) surface
                 // `/_agent-native/open?app=…&view=…&<recordId>=…` links; this resolves

package/dist/server/identity-sso-store.d.ts

@@ -35,6 +35,9 @@ export declare function getIdentityHubUrl(): string | undefined;
  * env-unset-no-op invariant is asserted against.
  */
 export declare function isIdentitySsoEnabled(): boolean;
+export declare function isDesktopSsoCanaryUserAgent(userAgent: string | undefined): boolean;
+export declare function isCanonicalAgentNativeAppOrigin(origin: string | undefined): boolean;
+export declare function isCanonicalAgentNativeAppRequest(host: string | undefined, forwardedProtocol: string | undefined): boolean;
 /**
  * The conditional "Sign in with Agent-Native" entry injected into the login
  * page — ONLY when the feature is enabled. Returns an empty string when

package/dist/server/identity-sso-store.js

@@ -25,6 +25,25 @@ import { randomBytes } from "node:crypto";
 import { getDbExec, isConnectionError, intType, isPostgres, } from "../db/client.js";
 import { ensureTableExists } from "../db/ddl-guard.js";
 let _initPromise;
+const DESKTOP_SSO_CANARY_USER_AGENT = /AgentNativeDesktopSsoCanary\//i;
+const CANONICAL_IDENTITY_SSO_APP_ORIGINS = new Set([
+    "https://analytics.agent-native.com",
+    "https://assets.agent-native.com",
+    "https://brain.agent-native.com",
+    "https://calendar.agent-native.com",
+    "https://chat.agent-native.com",
+    "https://clips.agent-native.com",
+    "https://content.agent-native.com",
+    "https://crm.agent-native.com",
+    "https://design.agent-native.com",
+    "https://dispatch.agent-native.com",
+    "https://forms.agent-native.com",
+    "https://macros.agent-native.com",
+    "https://mail.agent-native.com",
+    "https://plan.agent-native.com",
+    "https://slides.agent-native.com",
+    "https://tasks.agent-native.com",
+]);
 // ---------------------------------------------------------------------------
 // Feature switch — the SINGLE source of truth for whether the federated-SSO
 // client is active. Lives here (a leaf module with no dependency on auth.ts)
@@ -61,6 +80,32 @@ export function getIdentityHubUrl() {
 export function isIdentitySsoEnabled() {
     return !!getIdentityHubUrl();
 }
+export function isDesktopSsoCanaryUserAgent(userAgent) {
+    return DESKTOP_SSO_CANARY_USER_AGENT.test(userAgent ?? "");
+}
+export function isCanonicalAgentNativeAppOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        const parsed = new URL(origin);
+        return (parsed.protocol === "https:" &&
+            !parsed.username &&
+            !parsed.password &&
+            parsed.pathname === "/" &&
+            !parsed.search &&
+            !parsed.hash &&
+            CANONICAL_IDENTITY_SSO_APP_ORIGINS.has(parsed.origin));
+    }
+    catch {
+        return false;
+    }
+}
+export function isCanonicalAgentNativeAppRequest(host, forwardedProtocol) {
+    if (!host || forwardedProtocol !== "https") {
+        return false;
+    }
+    return isCanonicalAgentNativeAppOrigin(`https://${host}`);
+}
 /**
  * The conditional "Sign in with Agent-Native" entry injected into the login
  * page — ONLY when the feature is enabled. Returns an empty string when

package/dist/server/identity-sso.d.ts

@@ -6,12 +6,15 @@
  * an identity authority (Dispatch) so a user logged in there can land in this
  * app without re-entering credentials.
  *
- * Opt-in, OFF by default, fully reversible. Everything here is gated on the
- * single env var `AGENT_NATIVE_IDENTITY_HUB_URL`:
+ * Opt-in, OFF by default, fully reversible. Direct web federation is gated on
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`; the packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority on canonical hosted apps, where Dispatch's
+ * default-off feature flag controls rollout:
  *
- *   - UNSET  → `isIdentitySsoEnabled()` is false. The route handler 404s, the
- *     auth-guard bypass does not apply, and the login page renders no SSO
- *     button. Existing auth is byte-for-byte unchanged.
+ *   - UNSET  → normal browser requests remain protected and the login page
+ *     renders no SSO button. Packaged Canary requests on canonical app origins
+ *     may reach the flow, but Dispatch refuses them unless its rollout flag
+ *     allows the user.
  *   - SET    (e.g. `https://dispatch.agent-native.com`) → two routes mount:
  *       GET /_agent-native/identity/login
  *         302 → `<HUB>/_agent-native/identity/authorize?app=<id>
@@ -59,6 +62,15 @@ export declare const IDENTITY_SSO_PROVIDER_ID = "agent-native";
  * as an identity assertion.
  */
 export declare const IDENTITY_SSO_SCOPE = "identity";
+export declare const IDENTITY_SSO_DESKTOP_COMPLETE_PATH = "/_agent-native/identity/desktop-complete";
+/**
+ * Direct web federation stays explicitly configured through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop SSO Canary may use the
+ * canonical Dispatch authority without per-app deployment configuration, but
+ * only for canonical HTTPS Agent Native app origins. Dispatch's default-off
+ * feature flag remains the authoritative rollout gate.
+ */
+export declare function resolveIdentityHubUrl(event: H3Event): string | undefined;
 /**
  * Handle a `/_agent-native/identity/*` request. `subpath` is the part after
  * `/identity` (e.g. `/login`, `/callback`). Returns a 404 Response whenever
@@ -68,10 +80,8 @@ export declare const IDENTITY_SSO_SCOPE = "identity";
 export declare function handleIdentitySso(event: H3Event, subpath: string): Promise<Response>;
 /**
  * Whether the given (already base-path-stripped) request path is one of the
- * SSO routes that must bypass the blanket auth guard. Both routes resolve /
- * mint the browser session themselves: `/login` is the unauthenticated entry
- * point, and `/callback` is hit by a user who is (by definition) not yet
- * signed in to THIS app. Returns false when the feature is disabled, so the
- * guard's behaviour is unchanged with the env unset.
+ * two SSO routes that must bypass the blanket auth guard. The handler makes
+ * the request-scoped enablement decision and fails closed with 404; no other
+ * identity subpath bypasses authentication.
  */
 export declare function isIdentitySsoBypassPath(p: string): boolean;