@agent-native/core 0.151.1 → 0.152.0

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

@@ -1,87 +1,31 @@
 /**
  * Cross-app SSO ("Sign in with Agent-Native") — the CLIENT side.
  *
- * Each hosted `*.agent-native.com` app has its OWN Better Auth user store
- * (a separate database per app). This module lets an app federate sign-in to
- * an identity authority (Dispatch) so a user logged in there can land in this
- * app without re-entering credentials.
+ * Each hosted app has its own Better Auth store. Dispatch is the identity
+ * authority, but the browser only ever carries a short-lived, one-time
+ * authorization code. The client keeps the PKCE verifier in an HttpOnly,
+ * callback-scoped cookie and redeems the code server-to-server. Only that
+ * server-to-server response may contain the signed identity assertion.
  *
- * 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  → 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>
- *                 &redirect_uri=<thisOrigin>/_agent-native/identity/callback
- *                 &state=<single-use CSRF state>`
- *       GET /_agent-native/identity/callback?token=<jwt>&state=<state>
- *         Verifies the hub-issued identity JWT (HS256 over the SHARED A2A
- *         secret — the exact verify path A2A / MCP `verifyAuth` use), checks
- *         `scope:"identity"`, `exp`, single-use CSRF `state`, and (best
- *         effort) `jti` replay, then JIT-links the verified email into this
- *         app's local Better Auth store and mints a normal framework session
- *         the SAME way the Google OAuth callback does.
- *
- * Crypto reuse: the hub signs with `jose.SignJWT(...).sign(A2A_SECRET)` (the
- * existing `signA2AToken` builder). We verify with the identical
- * `jose.jwtVerify(token, A2A_SECRET)` call `mcp/build-server.ts#verifyAuth`
- * uses — no new crypto, no new keys.
- *
- * Session reuse: a NEW email is created via `auth.api.signUpEmail` — the
- * exact Better Auth signup path `maybeAutoCreateDevSession` already uses, so
- * the adapter creates the `user` (+ adapter-managed credential `account`)
- * row schema-correctly and the normal `databaseHooks.user.create.after`
- * (org auto-join, analytics) fires. The framework session is then minted via
- * `createOAuthSession` — the literal Google-OAuth session-mint path
- * (`addSession` + `setFrameworkSessionCookie`). An EXISTING email is never
- * mutated: we only ADD an inert federated-provider `account` row (if absent)
- * and mint the same framework session. Removing the env returns the app to
- * its prior auth with no residue.
+ * Direct browser federation remains opt-in through
+ * `AGENT_NATIVE_IDENTITY_HUB_URL`. The packaged Desktop Canary may use the
+ * canonical Dispatch authority on canonical app origins, as established by
+ * the merged feature-flagged Desktop work. This module does not change the
+ * Desktop implementation or any ordinary auth surface.
  */
 import type { H3Event } from "h3";
-import { getIdentityHubUrl, isIdentitySsoEnabled, identitySsoLoginButtonHtml } from "./identity-sso-store.js";
-export { getIdentityHubUrl, isIdentitySsoEnabled, identitySsoLoginButtonHtml };
-/**
- * The provider id recorded on the additive `account` row we link for an
- * EXISTING local user. Must match the value the Dispatch authority agent
- * expects to interoperate with — documented in the report so the two sides
- * stay in sync. Inert when this provider is unused, so removing the env var
- * leaves no behavioural residue.
- */
+import { getIdentityHubUrl, identitySsoLoginButtonHtml, isIdentitySsoEnabled } from "./identity-sso-store.js";
+export { getIdentityHubUrl, identitySsoLoginButtonHtml, isIdentitySsoEnabled };
 export declare const IDENTITY_SSO_PROVIDER_ID = "agent-native";
-/**
- * The JWT `scope` claim the hub MUST set on the identity token. The callback
- * rejects any token whose `scope` is not exactly this value, so an A2A
- * delegation JWT (no scope, or `scope:"mcp-connect"`) can never be replayed
- * as an identity assertion.
- */
 export declare const IDENTITY_SSO_SCOPE = "identity";
 export declare const IDENTITY_SSO_DESKTOP_COMPLETE_PATH = "/_agent-native/identity/desktop-complete";
+export declare const IDENTITY_SSO_CALLBACK_PATH = "/_agent-native/identity/callback";
+export declare const IDENTITY_SSO_TOKEN_PATH = "/_agent-native/identity/token";
 /**
- * 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.
+ * The packaged Desktop SSO Canary may use Dispatch without each canonical app
+ * deploying the direct-web hub env. Ordinary browsers and self-hosted apps
+ * remain strictly env-gated.
  */
 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
- * the feature is disabled so an unset env var is a true no-op even if the
- * route somehow gets mounted.
- */
 export declare function handleIdentitySso(event: H3Event, subpath: string): Promise<Response>;
-/**
- * Whether the given (already base-path-stripped) request path is one of the
- * 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;