@agent-native/core 0.18.0 → 0.19.0

package/dist/server/auth.d.ts

@@ -178,6 +178,23 @@ export declare function safeReturnPath(raw: string | null | undefined): string;
  * proceeds. Mirrors the rawPath/getLoginHtml resolution in the auth guard.
  */
 export declare function getConfiguredLoginHtml(event: H3Event): string | null;
+/**
+ * True only when the request originates from the local machine — the raw
+ * socket peer is `127.0.0.0/8`, `::1`, or the IPv4-mapped `::ffff:127.0.0.1`
+ * (an optional IPv6 zone id like `fe80::1%en0` is stripped first).
+ *
+ * `getRequestIP(event)` is called WITHOUT `{ xForwardedFor: true }`, so it
+ * returns the real connection peer and never an attacker-controlled
+ * `X-Forwarded-For` value — a remote client cannot spoof its way past this.
+ * Used to scope local-only conveniences (the desktop SSO broker and the dev
+ * auto-account) so a directly network-reachable dev server never exposes
+ * them to a remote visitor. NOTE: a reverse proxy / tunnel that connects to
+ * the dev server over localhost still appears as loopback, so this is a
+ * necessary but not sufficient gate — callers pair it with NODE_ENV and,
+ * for the dev account, a throwaway per-DB password.
+ */
+export declare function isLoopbackAddress(ip: string | undefined): boolean;
+export declare function isExpectedAuthFailure(error: unknown): boolean;
 /**
  * Create a new session in the legacy sessions table.
  * Used by google-oauth.ts for mobile deep linking.

package/dist/server/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"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"}

package/dist/server/auth.js

@@ -47,6 +47,10 @@ import { extractOAuthStateAppId } from "../shared/oauth-state.js";
 import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
 import { normalizeWorkspaceAppAudience, workspaceAppAudienceFromEnv, workspaceAppRouteAccessFromEnv, } from "../shared/workspace-app-audience.js";
 import { BUILDER_CONNECT_OWNER_COOKIE, BUILDER_CONNECT_PARAM, BUILDER_STATE_PARAM, verifyBuilderCallbackStateAndGetOwner, verifyBuilderConnectTokenAndGetOwner, } from "./builder-browser.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";
 /**
  * Get the configured session max age. Desktop SSO broker writes from
  * OAuth flows read this so expiration stays consistent with the cookie.
@@ -310,6 +314,39 @@ export function getConfiguredLoginHtml(event) {
     const rawPath = queryStart >= 0 ? url.slice(0, queryStart) : url;
     return config.getLoginHtml?.(event, rawPath) ?? config.loginHtml ?? null;
 }
+/**
+ * True only when the request originates from the local machine — the raw
+ * socket peer is `127.0.0.0/8`, `::1`, or the IPv4-mapped `::ffff:127.0.0.1`
+ * (an optional IPv6 zone id like `fe80::1%en0` is stripped first).
+ *
+ * `getRequestIP(event)` is called WITHOUT `{ xForwardedFor: true }`, so it
+ * returns the real connection peer and never an attacker-controlled
+ * `X-Forwarded-For` value — a remote client cannot spoof its way past this.
+ * Used to scope local-only conveniences (the desktop SSO broker and the dev
+ * auto-account) so a directly network-reachable dev server never exposes
+ * them to a remote visitor. NOTE: a reverse proxy / tunnel that connects to
+ * the dev server over localhost still appears as loopback, so this is a
+ * necessary but not sufficient gate — callers pair it with NODE_ENV and,
+ * for the dev account, a throwaway per-DB password.
+ */
+export function isLoopbackAddress(ip) {
+    // Strip an optional IPv6 zone id (e.g. "fe80::1%en0") before comparing.
+    const normalised = (ip ?? "").split("%")[0];
+    return (normalised === "127.0.0.1" ||
+        normalised === "::1" ||
+        normalised === "::ffff:127.0.0.1" ||
+        normalised.startsWith("127."));
+}
+function isLoopbackRequest(event) {
+    let ip;
+    try {
+        ip = getRequestIP(event) ?? undefined;
+    }
+    catch {
+        ip = undefined;
+    }
+    return isLoopbackAddress(ip);
+}
 /**
  * Read the desktop-SSO broker file, but only if the request is plausibly
  * from the Electron desktop app *and* coming from the local machine.
@@ -329,21 +366,7 @@ async function readDesktopSsoSafely(event) {
         return null;
     if (!isElectronRequest(event))
         return null;
-    // Loopback-only: 127.0.0.1, ::1, and the IPv4-mapped form.
-    let ip;
-    try {
-        ip = getRequestIP(event) ?? undefined;
-    }
-    catch {
-        ip = undefined;
-    }
-    // Strip an optional zone id (e.g. "fe80::1%en0") before comparing.
-    const normalised = (ip ?? "").split("%")[0];
-    const isLoopback = normalised === "127.0.0.1" ||
-        normalised === "::1" ||
-        normalised === "::ffff:127.0.0.1" ||
-        normalised.startsWith("127.");
-    if (!isLoopback)
+    if (!isLoopbackRequest(event))
         return null;
     return await readDesktopSso();
 }
@@ -452,7 +475,7 @@ const EXPECTED_AUTH_FAILURE_PATTERNS = [
     /already\s+(exists|registered|in\s+use)/i,
     /not\s+verified/i,
 ];
-function isExpectedAuthFailure(error) {
+export function isExpectedAuthFailure(error) {
     const msg = error?.message;
     if (typeof msg !== "string")
         return false;
@@ -901,6 +924,54 @@ function createAuthGuardFn() {
         if (p === "/_agent-native/a2a") {
             return;
         }
+        // MCP protocol endpoint. `mountMCP` runs its own `verifyAuth` (Bearer
+        // ACCESS_TOKEN/ACCESS_TOKENS or A2A_SECRET JWT, open in dev) and is the
+        // authoritative gate — exactly like A2A above. Without this bypass the
+        // guard's blanket 401-for-/_agent-native/* below shadows that check, so
+        // an external coding agent (Claude Code / Codex / Cowork) connecting via
+        // the stdio proxy or HTTP can never reach it. Exact path only: the MCP
+        // handler returns early for `/_agent-native/mcp/*` management subroutes,
+        // which keep their normal session auth.
+        if (p === "/_agent-native/mcp") {
+            return;
+        }
+        // MCP connect — frictionless external-agent connection. Like /open
+        // above, the connect *page* resolves the browser session itself and
+        // serves its own login form when unauthenticated (so the post-login
+        // reload returns to the same URL, carrying the device user_code in the
+        // query). The two unauthenticated device endpoints below are the CLI's
+        // OAuth-style polling pair: `device/start` (mint a device+user code) and
+        // `device/poll` (exchange an approved code for the token) — both must be
+        // reachable without a browser session because the CLI has none. They are
+        // protected by short-TTL, single-use, crypto-random codes + a creation
+        // rate-limit, not cookies.
+        //
+        // Everything that MINTS or MUTATES on behalf of the user — `/token`,
+        // `/device/authorize`, `/tokens`, `/tokens/revoke` — is intentionally
+        // NOT bypassed: the guard's default 401-for-/_agent-native/* is the
+        // correct gate for them. Those are POSTed by the in-page fetch, which
+        // carries the session cookie, so the guard (which only 401s when there
+        // is no session) lets the authenticated same-origin request through and
+        // the handler then re-checks the session itself (defense in depth).
+        if (p === "/_agent-native/mcp/connect" ||
+            p === "/_agent-native/mcp/connect/device/start" ||
+            p === "/_agent-native/mcp/connect/device/poll") {
+            return;
+        }
+        // Cross-app SSO ("Sign in with Agent-Native") — CLIENT side. Both the
+        // `/login` entry point and the `/callback` (hit by a user who is, by
+        // 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")) {
+            return;
+        }
         // Internal processor endpoint for the A2A async-mode fanout. Mirrors the
         // integration webhook fanout: when `message/send` is called with
         // `async: true`, the JSON-RPC handler enqueues to a2a_tasks and self-
@@ -1000,8 +1071,8 @@ function createAuthGuardFn() {
             return { error: "Unauthorized" };
         }
         // Local-dev convenience: on the first page GET of a freshly-scaffolded
-        // app, transparently create + sign in `dev@local` instead of showing the
-        // sign-up form. Gated on NODE_ENV=development AND no real users in the
+        // app, transparently create + sign in `dev@local.test` instead of
+        // showing the sign-up form. Gated on NODE_ENV=development AND no real users in the
         // DB, so production and any app that has ever had a real signup are
         // unaffected. See maybeAutoCreateDevSession for full conditions.
         if (getMethod(event) === "GET") {
@@ -1015,69 +1086,105 @@ function createAuthGuardFn() {
         });
     };
 }
-const AUTO_DEV_ACCOUNT_EMAIL = "dev@local";
-const AUTO_DEV_ACCOUNT_PASSWORD = "local-dev-account";
+// `.test` is an RFC 6761 reserved TLD that never resolves, so this stays a
+// safe local-only address while still passing better-auth's `z.email()`
+// validator (a bare `dev@local` has no TLD and is rejected as INVALID_EMAIL,
+// which silently broke the zero-setup auto-sign-in on every fresh dev DB).
+const AUTO_DEV_ACCOUNT_EMAIL = "dev@local.test";
+// No fixed password: maybeAutoCreateDevSession mints a random one per DB
+// and prints it to the console once (see there).
+// Pre-fix local dev DBs may already contain a `dev@local` user. Treat that
+// legacy address as the dev account too, so the "any real users?" check
+// below doesn't mistake the old auto-account for a real signup (which would
+// permanently disable auto-create) and the post-logout guard still fires.
+const LEGACY_AUTO_DEV_ACCOUNT_EMAIL = "dev@local";
 /**
  * Local-dev convenience: skip the sign-up wall on first run.
  *
  * When NODE_ENV=development AND the `user` table has no rows for any
- * email other than `dev@local`, transparently sign up (or sign back in
+ * email other than the dev account (`dev@local.test`, or the legacy
+ * `dev@local` on pre-fix DBs), transparently sign up (or sign back in
  * to) the auto-managed dev account and return a 302 to the original URL
  * with a session cookie set. A developer who just ran `pnpm dev` lands
  * in the app immediately instead of being asked to fill in name + email
  * + password to try the framework.
  *
- * Auto-create fires exactly once per local DB: as soon as `dev@local`
- * (or any real user) exists in the `user` table, the helper returns
- * null and the normal login flow takes over. Signing out then leaves
- * the user on the regular sign-in form; without this guard the
+ * Auto-create fires exactly once per local DB: as soon as the dev
+ * account (or any real user) exists in the `user` table, the helper
+ * returns null and the normal login flow takes over. Signing out then
+ * leaves the user on the regular sign-in form; without this guard the
  * post-logout reload would silently re-create the session.
  *
- * The fixed password is intentional: it means a developer who signs
- * out can sign back in with `dev@local` / `local-dev-account` from
- * the regular login form. To get the auto-flow back, drop the user
- * row or wipe the local DB. Set
- * `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` to opt out entirely
- * (useful for tests that exercise the unauthenticated branch). This
- * is local-only — the helper is gated on NODE_ENV.
+ * Hardening (this is a convenience, not an auth bypass — it uses the
+ * real Better Auth sign-up/sign-in, but a known-credential local account
+ * is still worth not shipping):
+ *  - **Loopback only.** Gated on `isLoopbackRequest`, so a tunnelled /
+ *    reverse-proxied / misconfigured-non-prod dev server never auto-signs
+ *    in a directly-remote visitor (mirrors the desktop SSO broker).
+ *  - **Random per-DB password.** The account password is freshly
+ *    generated on creation and printed to the server console exactly
+ *    once — there is no source-code-known credential. After logout the
+ *    auto-flow won't refire (dev row exists), so signing back in uses
+ *    that printed password; lost it ⇒ drop the row or wipe the local DB.
+ *  - **NODE_ENV.** Still gated on development/test.
+ *
+ * Set `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` to opt out entirely
+ * (useful for tests that exercise the unauthenticated branch).
  */
 async function maybeAutoCreateDevSession(event, redirectTo) {
     if (!isDevEnvironment())
         return null;
     if (process.env.AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT === "1")
         return null;
+    // Local machine only: never auto-sign-in a remote visitor, even if a
+    // dev server is exposed (tunnel, reverse proxy, misconfigured NODE_ENV).
+    if (!isLoopbackRequest(event))
+        return null;
     try {
         const db = getDbExec();
+        // Exclude BOTH the current and the legacy dev-account email so a
+        // pre-fix local DB that still holds a `dev@local` row isn't treated
+        // as having a "real user" (which would permanently disable
+        // auto-create on that DB).
         const { rows: realUsers } = await db.execute({
-            sql: 'SELECT 1 FROM "user" WHERE email != ? LIMIT 1',
-            args: [AUTO_DEV_ACCOUNT_EMAIL],
+            sql: 'SELECT 1 FROM "user" WHERE email NOT IN (?, ?) LIMIT 1',
+            args: [AUTO_DEV_ACCOUNT_EMAIL, LEGACY_AUTO_DEV_ACCOUNT_EMAIL],
         });
         if (realUsers.length > 0)
             return null;
-        // If `dev@local` already exists, this is not a freshly-scaffolded
+        // If the dev account already exists, this is not a freshly-scaffolded
         // app — the user has been through the auto-create flow at least
         // once. Skip auto-create so signing out actually works: without
         // this guard, the post-logout reload immediately re-creates the
-        // session and the user is stuck in dev@local forever (or has to
-        // set AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1). To get the demo
-        // experience back, drop the row or wipe the local DB.
+        // session and the user is stuck in the dev account forever (or has
+        // to set AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1). To get the demo
+        // experience back, drop the row or wipe the local DB. The legacy
+        // `dev@local` address is matched too so pre-fix DBs still suppress
+        // re-create after logout.
         const { rows: devUsers } = await db.execute({
-            sql: 'SELECT 1 FROM "user" WHERE email = ? LIMIT 1',
-            args: [AUTO_DEV_ACCOUNT_EMAIL],
+            sql: 'SELECT 1 FROM "user" WHERE email IN (?, ?) LIMIT 1',
+            args: [AUTO_DEV_ACCOUNT_EMAIL, LEGACY_AUTO_DEV_ACCOUNT_EMAIL],
         });
         if (devUsers.length > 0)
             return null;
         const auth = await getBetterAuth();
         if (!auth)
             return null;
-        // Idempotent sign-up: succeeds on first run, throws an "already exists"
-        // failure on subsequent runs (which we swallow before falling through
-        // to the sign-in path below).
+        // Random per-DB password — there is no source-code-known credential
+        // for this account. Printed once below so the developer can sign back
+        // in after logout (the auto-flow won't refire while the dev row
+        // exists).
+        const devPassword = crypto.randomBytes(18).toString("base64url");
+        // The dev account does not exist at this point (the devUsers check
+        // above returned early otherwise). The "already exists" swallow only
+        // matters under a rare concurrent first-hit race — in that case the
+        // sign-in below fails the password check and we return null, leaving
+        // the racing request that already won to keep the session.
         try {
             await auth.api.signUpEmail({
                 body: {
                     email: AUTO_DEV_ACCOUNT_EMAIL,
-                    password: AUTO_DEV_ACCOUNT_PASSWORD,
+                    password: devPassword,
                     name: "Dev",
                 },
             });
@@ -1089,17 +1196,26 @@ async function maybeAutoCreateDevSession(event, redirectTo) {
         const result = await auth.api.signInEmail({
             body: {
                 email: AUTO_DEV_ACCOUNT_EMAIL,
-                password: AUTO_DEV_ACCOUNT_PASSWORD,
+                password: devPassword,
             },
         });
         if (!result?.token)
             return null;
         setFrameworkSessionCookie(event, result.token);
         await addSession(result.token, AUTO_DEV_ACCOUNT_EMAIL);
-        return new Response("", {
-            status: 302,
-            headers: { Location: redirectTo },
-        });
+        // Print the throwaway credential exactly once so the developer can
+        // sign back in manually after logout (auto-flow won't refire once the
+        // dev row exists). Local console only — never Sentry.
+        console.log(`\n[agent-native] Local dev auto-login ready.\n` +
+            `  email:    ${AUTO_DEV_ACCOUNT_EMAIL}\n` +
+            `  password: ${devPassword}\n` +
+            `  (random, this DB only — needed to sign back in after logout.\n` +
+            `   Set AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1 to disable.)\n`);
+        // Emit the session cookie ON the 302 itself. Returning a bare
+        // `new Response(...)` here drops the cookie staged on event.node.res
+        // (see redirectWithStagedCookies), so the developer would 302 to the
+        // app and immediately bounce back to the login form.
+        return redirectWithStagedCookies(event, redirectTo);
     }
     catch (e) {
         // Local-dev only — log to console for debugging, but don't surface
@@ -1252,6 +1368,33 @@ export function setFrameworkSessionCookie(event, token) {
         maxAge: sessionMaxAge,
     });
 }
+/**
+ * Build a redirect `Response` that carries whatever `Set-Cookie` headers were
+ * just staged on the event (e.g. by `setFrameworkSessionCookie`).
+ *
+ * h3 v2's `setCookie` appends the cookie onto `event.res.headers`. When a
+ * handler returns a plain object/string, h3's `prepareResponse` merges those
+ * staged headers into the synthesized response, so the cookie survives. But
+ * when a handler returns a web `Response`, `prepareResponse` only merges the
+ * staged headers if the Response is 2xx — its `!val.ok` early-return hands a
+ * non-2xx Response (like a 302) straight back WITHOUT merging. A bare
+ * `new Response("", { status: 302, headers: { Location } })` therefore 302s
+ * the browser with no session cookie, so the zero-setup dev auto-sign-in
+ * bounces straight back to the login form.
+ *
+ * Mirroring the staged cookies onto the redirect Response's own headers makes
+ * them part of the Response that's returned as-is, so the 302 actually
+ * carries the session cookie. (`event.res.headers` is also left intact for
+ * any non-Response continuation path; h3 only skips the merge for the
+ * Response branch, so there's no double-emit.)
+ */
+function redirectWithStagedCookies(event, location, status = 302) {
+    const headers = new Headers({ Location: location });
+    const staged = event.res?.headers?.getSetCookie?.() ?? [];
+    for (const cookie of staged)
+        headers.append("set-cookie", cookie);
+    return new Response("", { status, headers });
+}
 function isHttpsRequest(event) {
     try {
         const xfProto = getHeader(event, "x-forwarded-proto");