@k9o/gate 1.2.0 → 1.3.0

package/src/gate.ts

@@ -1,30 +1,15 @@
 /**
- * Marquee `gate.*` namespace.
+ * The `gate.*` namespace, bound to the end-user Gate routes (project-scoped, `<org>.api.<apex>/@<projectSlug>/gate/...`):
+ *   - `gate.signUp` POST /gate/signup
+ *   - `gate.signIn` POST /gate/signin
+ *   - `gate.signOut` POST /gate/signout
+ *   - `gate.whoami` GET /gate/whoami
+ *   - `gate.refreshToken` POST /gate/refresh
+ *   - `gate.signInWithProvider` POST /gate/idp/{provider}/authorize
+ *   - `gate.passwordless.*` POST /gate/otp/{request,verify} and /gate/magic-link/{send,redeem}
  *
- * surfaces (canonical slug routing — `<orgSlug>.api.k9o.io/@<projectSlug>/...`):
- *   - `gate.signUp` — POST /@<projectSlug>/gate/signup
- *   - `gate.signIn` — POST /@<projectSlug>/gate/signin
- *   - `gate.signOut` — POST /@<projectSlug>/gate/signout
- *   - `gate.whoami` — GET  /@<projectSlug>/gate/whoami
- *   - `gate.refreshToken` — POST /@<projectSlug>/gate/refresh
- *   - `gate.verifySession` — GET  /@<projectSlug>/gate/verify
- *   - `gate.hosted` — GET  /@<projectSlug>/gate/hosted (unauthenticated; `{ signInUrl, rpId }`)
- *
- * Sub-namespaces (passwordless / passkeys / social / mfa / password /
- * users / email / sms / federation / admin) deferred to subsequent
- * cycles per the README catalogue.
- *
- * Wire shape: every function returns the standard envelope
- * `{ data, meta }` and throws a `GateError` on non-2xx
- * gateway responses. Native vs Standalone mode does not affect SDK
- * ergonomics; the mode header is set internally by the
- * client + does not surface in the function-call ergonomics.
- *
- * Endpoint paths are reconciled to the LIVE gateway routes (verified
- * against staging): signup/signin/signout/whoami/refresh/verify under
- * `/@<projectSlug>/gate/*`, OTP under `/gate/otp/{request,verify}`,
- * Magic Link under `/gate/magic-link/{send,redeem}`, IdP under
- * `/gate/idp/:provider/{authorize,callback}`.
+ * Every function returns the standard envelope `{ data, meta }` and throws a `GateError` on a non-2xx gateway answer.
+ * The mode (native or standalone) does not change the call shapes; the client sends it as the `X-Gate-Mode` header.
  */
 
 import { getGateConfig, type GateConfig } from "./mode.ts";
@@ -35,18 +20,22 @@ import { makeMagicLinkRedirects } from "./magic-link-redirects.ts";
 import type {
   AuthResult,
   Envelope,
-  HostedGateInfo,
   MagicLinkCallbackResult,
+  RefreshResult,
   RefreshTokenInput,
+  RequestMagicLinkResult,
+  RequestOtpResult,
   RequestMagicLinkInput,
   RequestOtpInput,
   SignInCallbackResult,
   SignInInput,
   SignOutInput,
+  SignOutResult,
   SignUpInput,
   VerifyMagicLinkInput,
+  VerifyMagicLinkResult,
   VerifyOtpInput,
-  VerifySessionResult,
+  VerifyOtpResult,
   WhoamiResult,
 } from "./types.ts";
 
@@ -60,13 +49,12 @@ function gatePath(config: GateConfig, suffix: string): string {
 export function makeGateNamespace(getConfig: () => GateConfig) {
   return {
   /**
-   * Create a new end-user identity for the configured project. Returns
-   * the new user record + an initial session. Emits a
-   * `data.write.auth.signup` audit event.
+   * Create a new end-user for the configured project. Returns the new user and an initial session. The body is
+   * closed: `{ email, password, displayName? }`.
    *
-   * Errors (closed taxonomy):
+   * Errors:
    *   - `EMAIL_ALREADY_REGISTERED` (409) when the email collides
-   *   - `INVALID_FIELD_VALUE` (400) on schema violation (password policy, malformed email)
+   *   - `INVALID_FIELD_VALUE` (400) on a schema violation (password policy, malformed email, unknown field)
    *   - `TIER_FEATURE_GATED` (403) when the project's tier blocks email/password
    */
   async signUp(input: SignUpInput): Promise<Envelope<AuthResult>> {
@@ -78,14 +66,10 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Sign in an existing end-user with email + password. Returns the
-   * user record + a fresh session. Emits a `data.write.auth.signin`
-   * audit event.
+   * Sign in an existing end-user with email and password. Returns the user and a fresh session.
    *
    * Errors:
-   *   - `INVALID_CREDENTIALS` (401) on bad email/password (ambiguous on
-   *     purpose — does not distinguish "user not found" vs "password
-   *     wrong" to avoid enumeration)
+   *   - `INVALID_CREDENTIALS` (401) on a bad email or password (the same answer for both, on purpose)
    */
   async signIn(input: SignInInput): Promise<Envelope<AuthResult>> {
     return requestWith<AuthResult>(getConfig(), {
@@ -96,16 +80,11 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Sign out — revoke the bound refresh token (or an explicit one, if
-   * supplied). Emits a `data.write.auth.signout` audit event.
-   *
-   * Errors:
-   *   - `UNAUTHENTICATED` (401) when no session is present
-   *   - `REFRESH_TOKEN_INVALID` (400) when the supplied refresh token
-   *     doesn't match the bearer's session
+   * Sign out: revoke the session that the given refresh token belongs to. The route needs the refresh token in the
+   * body, so it is required here. Revoking an unknown or already-revoked token also answers `{ revoked: false }`.
    */
-  async signOut(input: SignOutInput = {}): Promise<Envelope<{ revoked: boolean }>> {
-    return requestWith<{ revoked: boolean }>(getConfig(), {
+  async signOut(input: SignOutInput): Promise<Envelope<SignOutResult>> {
+    return requestWith<SignOutResult>(getConfig(), {
       method: "POST",
       path: gatePath(getConfig(), "signout"),
       body: input,
@@ -113,13 +92,11 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Return the caller's identity claims from the bearer JWT. Useful in
-   * Standalone mode where the SDK consumer wants to surface the user's
-   * roles / groups without parsing the JWT itself.
+   * Return the signed-in end-user (the bearer token's subject). The answer is the user record itself, not wrapped.
    *
    * Errors:
    *   - `UNAUTHENTICATED` (401) when no bearer is present
-   *   - `SESSION_EXPIRED` (401) when the bearer's exp has passed
+   *   - `SESSION_EXPIRED` (401) when the bearer has expired or was revoked
    */
   async whoami(): Promise<Envelope<WhoamiResult>> {
     return requestWith<WhoamiResult>(getConfig(), {
@@ -129,49 +106,20 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Rotate the access token using a refresh token. Returns a fresh
-   * session pair (new access token + same refresh token; gateway may
-   * also rotate the refresh token per project policy).
+   * Exchange a refresh token for a new access token. The answer carries only the new `accessToken` and its
+   * `expiresAt`; the refresh token you hold stays valid and is not returned again.
    *
    * Errors:
-   *   - `REFRESH_TOKEN_INVALID` (400) when the refresh token is unknown,
-   *     expired, or revoked
+   *   - `INVALID_CREDENTIALS` (401) when the refresh token is unknown, used or revoked
    */
-  async refreshToken(input: RefreshTokenInput): Promise<Envelope<{ session: AuthResult["session"] }>> {
-    return requestWith<{ session: AuthResult["session"] }>(getConfig(), {
+  async refreshToken(input: RefreshTokenInput): Promise<Envelope<RefreshResult>> {
+    return requestWith<RefreshResult>(getConfig(), {
       method: "POST",
       path: gatePath(getConfig(), "refresh"),
       body: input,
     });
   },
 
-  /**
-   * Check whether the bearer's session is currently valid. Does NOT
-   * throw on expiry or invalid token — returns `{ valid: false }`
-   * inside the envelope. The intended use is health-checking a session
-   * without surfacing an error to the end-user (the SDK consumer
-   * typically wants to redirect to sign-in rather than surface a 401).
-   */
-  async verifySession(): Promise<Envelope<VerifySessionResult>> {
-    return requestWith<VerifySessionResult>(getConfig(), {
-      method: "GET",
-      path: gatePath(getConfig(), "verify"),
-    });
-  },
-
-  /**
-   * The project's hosted sign-in page URL and WebAuthn `rpId`. Unauthenticated and cacheable; no credential is sent,
-   * even when a partner token is configured. Take both values as given: an unknown org, a deleted project and a
-   * non-Gate project all answer the same `PROJECT_NOT_FOUND`, so a failure here says nothing about which.
-   */
-  async hosted(): Promise<Envelope<HostedGateInfo>> {
-    return requestWith<HostedGateInfo>(getConfig(), {
-      method: "GET",
-      path: gatePath(getConfig(), "hosted"),
-      bearerToken: "",
-    });
-  },
-
   /**
    * Initiate an external-IdP sign-in flow (Google / GitHub / Microsoft).
    * The SDK POSTs to the gateway's authorize endpoint, receives the
@@ -190,8 +138,6 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
    *   });
    *   // …user lands at /auth/callback#access_token=…&refresh_token=…
    *
-   * Generic OIDC requires authorization-endpoint discovery and is not
-   * yet wired; use a hosted provider (google/github/microsoft) for now.
    */
   async signInWithProvider(input: {
     provider: "google" | "github" | "microsoft" | "oidc" | "saml";
@@ -254,25 +200,19 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Passwordless sub-namespace — OTP + Magic Link flows
-   * for email-based authentication without a stored password.
+   * Passwordless sign-in: one-time passcode and magic link, both by email.
    *
-   * Wire endpoints (LIVE on the Gate end-user plane — verified against
-   * staging): OTP → `POST /@<projectSlug>/gate/otp/{request,verify}`
-   * (routes/otp.ts), Magic Link → `POST /@<projectSlug>/gate/magic-link/
-   * {send,redeem}` (routes/magic-link.ts). NOTE: these are the gateway's
-   * canonical paths; the SDK ergonomic method names (`requestMagicLink`/
-   * `verifyMagicLink`) do not mirror the path segments (`send`/`redeem`).
-   * (The SDK paths match the shipped gateway routes.)
+   * Routes: `POST /@<projectSlug>/gate/otp/{request,verify}` and `POST /@<projectSlug>/gate/magic-link/{send,redeem}`.
+   * The method names do not mirror the last path segment (`requestMagicLink` calls `send`, `verifyMagicLink` calls
+   * `redeem`).
    */
   passwordless: {
     /**
-     * Request a one-time passcode delivered to the supplied email.
-     * The OTP is short-lived (typically 5 min) and
-     * single-use; redemption via `verifyOtp` mints a session.
+     * Request a one-time passcode for the email. It is short-lived and single-use; redeem it with `verifyOtp`.
+     * The answer carries the code's id and expiry (`data.otp`); the code itself goes by email.
      */
-    async requestOtp(input: RequestOtpInput): Promise<Envelope<{ requested: boolean }>> {
-      return requestWith<{ requested: boolean }>(getConfig(), {
+    async requestOtp(input: RequestOtpInput): Promise<Envelope<RequestOtpResult>> {
+      return requestWith<RequestOtpResult>(getConfig(), {
         method: "POST",
         path: gatePath(getConfig(), "otp/request"),
         body: input,
@@ -280,16 +220,15 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
     },
 
     /**
-     * Verify a one-time passcode previously sent via `requestOtp`.
-     * On success returns the same `AuthResult` shape as `signIn` —
-     * a fresh session bound to the end-user identity.
+     * Verify a one-time passcode previously sent via `requestOtp`. For the default `signin` purpose the answer
+     * carries a fresh `session`; for any other purpose it only confirms (`verified: true`) and the caller continues
+     * its own flow.
      *
      * Errors:
-     *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed OTP
-     *     (ambiguous on purpose — enumeration defense)
+     *   - `INVALID_CREDENTIALS` (401) on a wrong, expired or used code
      */
-    async verifyOtp(input: VerifyOtpInput): Promise<Envelope<AuthResult>> {
-      return requestWith<AuthResult>(getConfig(), {
+    async verifyOtp(input: VerifyOtpInput): Promise<Envelope<VerifyOtpResult>> {
+      return requestWith<VerifyOtpResult>(getConfig(), {
         method: "POST",
         path: gatePath(getConfig(), "otp/verify"),
         body: input,
@@ -297,16 +236,12 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
     },
 
     /**
-     * Request a magic-link emailed to the supplied address. The link
-     * carries an opaque short-lived token (typically 15 min
-     *); clicking the link lands at the customer's chosen
-     * redirect URL with the token in the query string, which the
-     * customer's frontend then exchanges via `verifyMagicLink`.
+     * Request a magic link by email. The link carries an opaque short-lived token and lands at the project's
+     * redirect URL with the token in the query string; exchange it with `verifyMagicLink`. The answer is
+     * `data.magicLink` with `sent` and the expiry.
      */
-    async requestMagicLink(
-      input: RequestMagicLinkInput,
-    ): Promise<Envelope<{ requested: boolean }>> {
-      return requestWith<{ requested: boolean }>(getConfig(), {
+    async requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<RequestMagicLinkResult>> {
+      return requestWith<RequestMagicLinkResult>(getConfig(), {
         method: "POST",
         path: gatePath(getConfig(), "magic-link/send"),
         body: input,
@@ -314,23 +249,21 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
     },
 
     /**
-     * Verify a magic-link token previously delivered via
-     * `requestMagicLink`. On success returns the same `AuthResult`
-     * shape as `signIn`.
+     * Redeem a magic-link token previously delivered via `requestMagicLink`. The answer carries the new `session`
+     * and the `endUserId` (not the full user record; call `whoami` for that).
      *
      * Errors:
-     *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed
-     *     token (same enumeration-defense rationale as verifyOtp)
+     *   - `INVALID_CREDENTIALS` (401) on a wrong, expired or used token
      */
-    async verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<AuthResult>> {
-      return requestWith<AuthResult>(getConfig(), {
+    async verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<VerifyMagicLinkResult>> {
+      return requestWith<VerifyMagicLinkResult>(getConfig(), {
         method: "POST",
         path: gatePath(getConfig(), "magic-link/redeem"),
         body: input,
       });
     },
 
-    /**
+  /**
      * Extract the opaque magic-link token from the landing-page URL's query
      * string (the gateway redirects to `<configured-redirect>?token=…&project=…`).
      * Pure + side-effect-free — pass `window.location.search`. Feed the
@@ -356,19 +289,14 @@ export function makeGateNamespace(getConfig: () => GateConfig) {
   },
 
   /**
-   * Project-scoped end-user IdP provider-config management.
-   * PROJECT_ADMIN+ required; end-user JWTs rejected at the route. Only
-   * `create()` is bound — the REST create the Gate Studio
-   * `FederationPresetsPanel` routes to when it drops the `gate_flows`
-   * `__addFromPreset` sentinel. Gate-admin surface.
+   * Project-scoped end-user IdP provider-config management (create, list, update, test).
+   * PROJECT_ADMIN+ required; end-user JWTs are rejected at the route.
    */
   identityProviders: makeIdentityProviders(getConfig),
 
   /**
-   * Per-project magic-link redirect-URL allowlist management (blessed
-   * shape). Gate-admin surface alongside `identityProviders`
-   * — PROJECT_ADMIN+ required, distinct from the end-user-facing
-   * `passwordless.requestMagicLink`/`verifyMagicLink` send/verify flow.
+   * Per-project magic-link redirect-URL allowlist management (list, add, remove).
+   * PROJECT_ADMIN+ required; distinct from the end-user `passwordless` flow.
    */
   magicLinkRedirects: makeMagicLinkRedirects(getConfig),
   };

package/src/idp-providers/identity-providers.ts

@@ -22,12 +22,10 @@
  * `partnerToken` in config, or per-call via the client's bearer plumbing.
  *
  * 🔴 `clientSecretRef` is a RAW SECRET on the way in, not a reference.
- * Post-v105 the gateway encrypts the submitted value (AES-256-GCM under
+ * The gateway encrypts the submitted value (AES-256-GCM under
  * `K9O_SECRET_STORAGE_MASTER_KEY`) into the opaque `client_secret_enc`
  * handle and persists only that; the field name is retained for wire
- * compatibility but the create handler comment
- * (`project-identity-providers.ts`, the v105 INSERT) is authoritative —
- * there is NO Kibo custody on this path. Reads NEVER carry the secret or its
+ * compatibility and there is no Kibo custody on this path. Reads NEVER carry the secret or its
  * handle: they carry only `clientSecretSet` (a presence boolean,
  * the write-only fix). `serviceAccountKey` (directory sync) follows the same write-only rule.
  */
@@ -37,8 +35,7 @@ import { requestWith } from "../client.ts";
 import { resolveProjectPathRoot } from "../paths.ts";
 import type { Envelope } from "../types.ts";
 
-/** Closed end-user-class provider enum — 11 values since v221 (the project-plane substrate
- *  `_sys.end_user_idp_provider_configs`); the org plane carries the same 11 since v222/v223. */
+/** Closed end-user-class provider enum (11 values). */
 export type IdpProviderKind =
   | "google" | "github" | "microsoft" | "oidc" | "saml" | "scim"
   | "ldap" | "active_directory" | "apple" | "facebook" | "twitter";
@@ -60,7 +57,7 @@ export type FederationTestProviderResult = {
     | "kind_unsupported";
 };
 
-/** Per the provider→tier pairing is structurally fixed:
+/** The provider→tier pairing is structurally fixed:
  *  `free_tier_ok ∈ {google, github, microsoft, apple, facebook, twitter}`,
  *  `ridge_plus ∈ {oidc, saml, scim, ldap, active_directory}`. The gateway rejects a mismatched
  *  pairing (`K9O_INVALID_FIELD_VALUE`); the SDK forwards the caller value
@@ -74,7 +71,7 @@ export type IdpTierGating = "free_tier_ok" | "ridge_plus";
  *
  * Reads carry `clientSecretSet` (presence only), never the secret or a handle (see the module header).
  * `metadataUrl`/`updatedAt` are `null` until set; `attributeMap` defaults to `{}`; `allowedRedirectUris`
- * defaults to `[]`. The `directory*` fields are GS-F7 scheduled directory sync (Google only,):
+ * defaults to `[]`. The `directory*` fields are scheduled directory sync (Google only):
  * settings plus the scheduler's last-run status; the service-account key itself is never returned.
  */
 export type IdpConfig = {
@@ -100,7 +97,7 @@ export type IdpConfig = {
   updatedAt: string | null;
 };
 
-/** GS-F7 directory-sync write fields — accepted on create AND update (one PROJECT_ADMIN surface). */
+/** Directory-sync write fields — accepted on create AND update (one PROJECT_ADMIN surface). */
 export type DirectorySyncInput = {
   /** Enabling requires `idpProvider: "google"`, a `serviceAccountKey` (now or already stored) and an interval. */
   directoryPullEnabled?: boolean;
@@ -147,7 +144,7 @@ export type CreateIdpInput = {
  * `tierGating` are immutable after create. An empty patch returns the current config unchanged.
  *
  * 🔴 For `oidc`/`microsoft`, changing `metadataUrl` WITHOUT `clientSecretRef` in the same patch CLEARS the
- * stored client secret (the gateway's secret-invalidate-on-host-change control,): re-supply the
+ * stored client secret (the gateway's secret-invalidate-on-host-change control): re-supply the
  * secret whenever the metadata URL changes.
  */
 export type PatchIdpInput = {
@@ -216,7 +213,7 @@ export function makeIdentityProviders(getConfig: () => GateConfig) {
     /**
      * Update a provider config by id (PATCH; PROJECT_ADMIN, server-enforced). Partial: only supplied fields
      * change; `idpProvider`/`tierGating` are immutable. Returns the updated config (secrets never included).
-     * GS-F7: write directory-sync settings here and read their status back off `list()`. See `PatchIdpInput`
+     * Write directory-sync settings here and read their status back off `list()`. See `PatchIdpInput`
      * for the metadataUrl-change-clears-secret rule.
      */
     async update(configId: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>> {

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@k9o/gate` — Gate (Identity-Aware Kernel) SDK entry point.
  *
- * Re-exports the canonical surface +:
+ * Re-exports the public surface:
  *   - `gate` — marquee namespace + sub-namespaces
  *   - `configureGate` / `getGateConfig` / `resetGateConfig` — mode + config plumbing
  *   - `verifyJwt` / `extractClaims` / `requireScope` — standalone JWT primitives
@@ -11,6 +11,7 @@
 
 export { gate, type GateNamespace } from "./gate.ts";
 export { createGateClient, type GateClient } from "./client-factory.ts";
+export { parseApiHost, type ApiHost } from "./api-host.ts";
 export { resolveRegionalOrigin, regionalOriginFromLocation, type RegionConfig } from "./region.ts";
 export {
   configureGate,
@@ -19,7 +20,7 @@ export {
   type GateConfig,
   type GateMode,
 } from "./mode.ts";
-export { verifyJwt, extractClaims, requireScope, type VerifyJwtOptions } from "./jwt.ts";
+export { verifyJwt, fetchJwks, extractClaims, requireScope, type VerifyJwtOptions } from "./jwt.ts";
 export {
   GateError,
   type GateErrorCode,
@@ -32,16 +33,20 @@ export type {
   Session,
   AuthResult,
   WhoamiResult,
-  VerifySessionResult,
-  HostedGateInfo,
+  RefreshResult,
+  SignOutResult,
   SignUpInput,
   SignInInput,
   SignOutInput,
   RefreshTokenInput,
   OtpPurpose,
   RequestOtpInput,
+  RequestOtpResult,
+  VerifyOtpResult,
   VerifyOtpInput,
   RequestMagicLinkInput,
+  RequestMagicLinkResult,
+  VerifyMagicLinkResult,
   VerifyMagicLinkInput,
   SignInCallbackResult,
   MagicLinkCallbackResult,
@@ -49,8 +54,7 @@ export type {
   VerifyJwtResult,
   VerifyJwtFailure,
 } from "./types.ts";
-// GS-F6 — project-scoped end-user IdP provider-config management types
-// (gate.identityProviders.create()).
+// Project-scoped end-user IdP provider-config management types (gate.identityProviders.*).
 export type {
   IdpProviderKind,
   IdpTierGating,

package/src/jwt.ts

@@ -1,58 +1,39 @@
 /**
- * JWT verification primitives for external-app standalone consumption.
- *
- * Standalone-mode customers consume Gate-issued JWTs in their own
- * application code without needing the full SDK shape — they just need
- * to verify the signature, extract claims, and (optionally) check
- * scopes. This module is the canonical entry for that surface.
- *
- * Backed by `jose` (already a peer dependency in the gateway via the
- * same library; chose `jose` for consistency + JWK fetch support out
- * of the box).
- *
- * Native-mode customers don't typically reach for this directly — the
- * gateway verifies project-issued tokens on every request and rehydrates
- * `subject.*` claims. But the same primitives are
- * portable: Native customers running their own services downstream of
- * the gateway can verify Gate-issued JWTs identically.
+ * JWT verification primitives for apps that consume Gate-issued tokens without the rest of the SDK: verify the
+ * signature, read the claims, check scopes. Backed by `jose`.
  */
 
-import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
+import { jwtVerify, errors as joseErrors } from "jose";
 import type { GateJwtClaims, VerifyJwtFailure, VerifyJwtResult } from "./types.ts";
 import { GateError } from "./errors.ts";
 
 /**
- * Configuration for `verifyJwt`. The verifier can resolve signing keys
- * via either a remote JWKS URL (the typical Gate deployment shape) or
- * an inline key set (for tests + air-gapped deployments).
+ * Configuration for `verifyJwt`. Signing keys come from either the gateway's JWKS route (`jwksUrl`) or an inline key
+ * set (`jwks`, for tests and air-gapped deployments).
  */
 export type VerifyJwtOptions = {
   token: string;
   /**
-   * JWKS endpoint URL — the gateway exposes `/@<projectSlug>/gate/.well-known/jwks.json`
-   * by convention. Either `jwksUrl` or `jwks` must be set; not both.
+   * URL of the gateway's JWKS route: `https://<org>.api.<apex>/@<projectSlug>/auth/jwks` for a project's end-user
+   * tokens (`/auth/jwks` on the org host for org keys). The gateway wraps the key set in its response envelope
+   * (`{ data: { keys }, meta }`), which `jose` cannot read directly; this helper fetches the URL and unwraps it.
+   * Either `jwksUrl` or `jwks` must be set; not both.
    */
   jwksUrl?: string;
-  /**
-   * Inline JWK set — used by tests + integration scenarios that want to
-   * avoid the network hop. The shape is the standard JWKS `{keys: [...]}`
-   * envelope; pass through unchanged to `jose`.
-   */
+  /** Inline JWK set, the standard `{ keys: [...] }` object. */
   jwks?: { keys: ReadonlyArray<Record<string, unknown>> };
+  /** Fetch implementation used for `jwksUrl`. Defaults to the global `fetch`. */
+  fetch?: typeof globalThis.fetch;
   /** Expected issuer (`iss` claim). Strict comparison. */
   expectedIssuer?: string;
-  /** Expected audience (`aud` claim). Accepts either string or array per RFC 7519. */
+  /** Expected audience (`aud` claim). */
   expectedAudience?: string;
   /**
-   * Allowed signing algorithms. Defaults to `["RS256", "ES256"]` per the
-   * standard Gate issuer config. Reject anything outside this set
-   * (defense against alg-confusion attacks).
+   * Allowed signing algorithms. Defaults to `["RS256", "ES256"]`. Anything outside this set is rejected (defense
+   * against algorithm confusion).
    */
   allowedAlgorithms?: ReadonlyArray<string>;
-  /**
-   * Clock-skew tolerance in seconds. Defaults to 30. Applies to both
-   * `exp` and `nbf` checks.
-   */
+  /** Clock-skew tolerance in seconds. Defaults to 30. Applies to `exp` and `nbf`. */
   clockToleranceSeconds?: number;
 };
 
@@ -65,7 +46,7 @@ const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
  *
  * Throws `GateError` only when:
  *   - `jwksUrl` and `jwks` are both unset or both set
- *   - the JWKS fetch fails for transport reasons (UPSTREAM_UNAVAILABLE)
+ *   - the JWKS fetch fails (UPSTREAM_UNAVAILABLE) or answers something that is not a key set
  */
 export async function verifyJwt(opts: VerifyJwtOptions): Promise<VerifyJwtResult> {
   if (opts.jwksUrl !== undefined && opts.jwks !== undefined) {
@@ -90,10 +71,8 @@ export async function verifyJwt(opts: VerifyJwtOptions): Promise<VerifyJwtResult
 
   let keyResolver: Parameters<typeof jwtVerify>[1];
   if (opts.jwksUrl !== undefined) {
-    keyResolver = createRemoteJWKSet(new URL(opts.jwksUrl));
+    keyResolver = makeLocalJwksResolver(await fetchJwks(opts.jwksUrl, opts.fetch));
   } else {
-    // Inline JWKS — implement the resolver inline since `jose`'s
-    // `createLocalJWKSet` import path varies across versions.
     keyResolver = makeLocalJwksResolver(opts.jwks!);
   }
 
@@ -167,6 +146,50 @@ export function requireScope(
 // Internals
 // ----------------------------------------------------------------------
 
+type Jwks = { keys: ReadonlyArray<Record<string, unknown>> };
+
+function isJwks(v: unknown): v is Jwks {
+  return v !== null && typeof v === "object" && Array.isArray((v as { keys?: unknown }).keys);
+}
+
+/**
+ * Fetch a JWKS from the gateway. The route answers `{ data: { keys }, meta }`; a bare `{ keys }` (any other JWKS
+ * host) is accepted too.
+ */
+export async function fetchJwks(url: string, fetchImpl: typeof globalThis.fetch | undefined = globalThis.fetch): Promise<Jwks> {
+  if (typeof fetchImpl !== "function") {
+    throw new GateError({
+      code: "INTERNAL_ERROR",
+      message: "No fetch implementation available to read the JWKS",
+      context: { url },
+      recommendation: null,
+    });
+  }
+  let body: unknown;
+  let status: number;
+  try {
+    const res = await fetchImpl(url, { method: "GET", headers: { accept: "application/json" } });
+    status = res.status;
+    body = await res.json();
+  } catch (e) {
+    throw new GateError({
+      code: "UPSTREAM_UNAVAILABLE",
+      message: `Could not read the JWKS at ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url },
+      recommendation: null,
+    });
+  }
+  const inner = body !== null && typeof body === "object" ? (body as { data?: unknown }).data : undefined;
+  if (isJwks(inner)) return inner;
+  if (isJwks(body)) return body;
+  throw new GateError({
+    code: "UPSTREAM_UNAVAILABLE",
+    message: `The JWKS route at ${url} answered ${status} without a key set`,
+    context: { url, status },
+    recommendation: null,
+  });
+}
+
 function classifyJoseFailure(e: unknown): VerifyJwtFailure {
   // Map `jose`'s typed errors to our closed reason set per `VerifyJwtFailure`.
   if (e instanceof joseErrors.JWSSignatureVerificationFailed) return "INVALID_SIGNATURE";
@@ -197,12 +220,7 @@ function base64UrlDecode(input: string): string {
   return new TextDecoder("utf-8").decode(bytes);
 }
 
-/**
- * Build a key resolver compatible with `jose.jwtVerify` from an inline
- * JWKS object. `jose` exports `createLocalJWKSet` from its main module
- * but the import path / type shape can shift across minors; reimplement
- * the minimal resolver here for stability.
- */
+/** Build a key resolver for `jose.jwtVerify` from a JWKS object. */
 function makeLocalJwksResolver(
   jwks: { keys: ReadonlyArray<Record<string, unknown>> },
 ): Parameters<typeof jwtVerify>[1] {

package/src/magic-link-redirects.ts

@@ -1,7 +1,6 @@
 /**
  * `gate.magicLinkRedirects` sub-namespace — the per-project magic-link
- * redirect-URL allowlist, PROJECT_ADMIN+ managed. Blessed shape (
- * 2026-07-16): `list()`/`add()`/`remove()`, mirroring the
+ * redirect-URL allowlist, PROJECT_ADMIN+ managed. `list()`/`add()`/`remove()`, mirroring the
  * `gate.idpProviders.*` sub-namespace convention (gate-admin surface,
  * not the end-user-facing `passwordless.*` send/verify flow).
  *