@k9o/gate 1.1.1 → 1.3.0

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 import { GateConfig } from './mode.js';
 export { GateMode, configureGate, getGateConfig, resetGateConfig } from './mode.js';
-import { Envelope, SignUpInput, AuthResult, SignInInput, SignOutInput, WhoamiResult, RefreshTokenInput, VerifySessionResult, HostedGateInfo, SignInCallbackResult, RequestOtpInput, VerifyOtpInput, RequestMagicLinkInput, VerifyMagicLinkInput, MagicLinkCallbackResult } from './types.js';
+import { Envelope, SignUpInput, AuthResult, SignInInput, SignOutInput, SignOutResult, WhoamiResult, RefreshTokenInput, RefreshResult, SignInCallbackResult, RequestOtpInput, RequestOtpResult, VerifyOtpInput, VerifyOtpResult, RequestMagicLinkInput, RequestMagicLinkResult, VerifyMagicLinkInput, VerifyMagicLinkResult, MagicLinkCallbackResult } from './types.js';
 export { EndUser, GateJwtClaims, OtpPurpose, Session, VerifyJwtFailure, VerifyJwtResult } from './types.js';
-export { VerifyJwtOptions, extractClaims, requireScope, verifyJwt } from './jwt.js';
+export { VerifyJwtOptions, extractClaims, fetchJwks, requireScope, verifyJwt } from './jwt.js';
 export { GateError, GateErrorCode, KErrorWire, gateErrorFromWire } from './errors.js';
 
 /**
  * `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).
  *
@@ -80,18 +79,15 @@ type RemoveMagicLinkRedirectResult = {
  * `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.
  */
 
-/** 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). */
 type IdpProviderKind = "google" | "github" | "microsoft" | "oidc" | "saml" | "scim" | "ldap" | "active_directory" | "apple" | "facebook" | "twitter";
 /**
  * The result of a provider connectivity test (`testProvider`). `ok` is the reachability + metadata-validity
@@ -104,7 +100,7 @@ type FederationTestProviderResult = {
     ok: boolean;
     reason?: "endpoint_unreachable" | "endpoint_forbidden" | "metadata_invalid" | "secret_not_provisioned" | "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
@@ -117,7 +113,7 @@ 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.
  */
 type IdpConfig = {
@@ -142,7 +138,7 @@ type IdpConfig = {
     createdAt: string;
     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). */
 type DirectorySyncInput = {
     /** Enabling requires `idpProvider: "google"`, a `serviceAccountKey` (now or already stored) and an interval. */
     directoryPullEnabled?: boolean;
@@ -187,7 +183,7 @@ 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.
  */
 type PatchIdpInput = {
@@ -235,7 +231,7 @@ declare 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.
      */
     update(configId: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>>;
@@ -248,75 +244,43 @@ type IdentityProvidersNamespace = ReturnType<typeof makeIdentityProviders>;
  *  and `createGateClient(config)` (config supplied at construction time). */
 declare function makeGateNamespace(getConfig: () => GateConfig): {
     /**
-     * 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
      */
     signUp(input: SignUpInput): Promise<Envelope<AuthResult>>;
     /**
-     * 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)
      */
     signIn(input: SignInInput): Promise<Envelope<AuthResult>>;
     /**
-     * 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 }`.
      */
-    signOut(input?: SignOutInput): Promise<Envelope<{
-        revoked: boolean;
-    }>>;
+    signOut(input: SignOutInput): Promise<Envelope<SignOutResult>>;
     /**
-     * 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
      */
     whoami(): Promise<Envelope<WhoamiResult>>;
     /**
-     * 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
-     */
-    refreshToken(input: RefreshTokenInput): Promise<Envelope<{
-        session: AuthResult["session"];
-    }>>;
-    /**
-     * 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).
-     */
-    verifySession(): Promise<Envelope<VerifySessionResult>>;
-    /**
-     * 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.
+     *   - `INVALID_CREDENTIALS` (401) when the refresh token is unknown, used or revoked
      */
-    hosted(): Promise<Envelope<HostedGateInfo>>;
+    refreshToken(input: RefreshTokenInput): Promise<Envelope<RefreshResult>>;
     /**
      * Initiate an external-IdP sign-in flow (Google / GitHub / Microsoft).
      * The SDK POSTs to the gateway's authorize endpoint, receives the
@@ -335,8 +299,6 @@ declare 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.
      */
     signInWithProvider(input: {
         provider: "google" | "github" | "microsoft" | "oidc" | "saml";
@@ -354,74 +316,56 @@ declare function makeGateNamespace(getConfig: () => GateConfig): {
      */
     parseSignInCallback(hash: string): SignInCallbackResult;
     /**
-     * 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.
          */
-        requestOtp(input: RequestOtpInput): Promise<Envelope<{
-            requested: boolean;
-        }>>;
+        requestOtp(input: RequestOtpInput): Promise<Envelope<RequestOtpResult>>;
         /**
-         * 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
          */
-        verifyOtp(input: VerifyOtpInput): Promise<Envelope<AuthResult>>;
+        verifyOtp(input: VerifyOtpInput): Promise<Envelope<VerifyOtpResult>>;
         /**
-         * 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.
          */
-        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<{
-            requested: boolean;
-        }>>;
+        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<RequestMagicLinkResult>>;
         /**
-         * 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
          */
-        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<AuthResult>>;
+        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<VerifyMagicLinkResult>>;
         /**
-         * 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
-         * returned `token` to `verifyMagicLink({ token })` to mint the session.
-         *
-         * This is the magic-link counterpart to `parseSignInCallback` (which parses
-         * the SSO *hash fragment* for session tokens) — magic-link delivers an
-         * opaque token in the *query string*, so the two are not interchangeable.
-         */
+           * 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
+           * returned `token` to `verifyMagicLink({ token })` to mint the session.
+           *
+           * This is the magic-link counterpart to `parseSignInCallback` (which parses
+           * the SSO *hash fragment* for session tokens) — magic-link delivers an
+           * opaque token in the *query string*, so the two are not interchangeable.
+           */
         parseMagicLinkCallback(search: string): MagicLinkCallbackResult;
     };
     /**
-     * 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: {
         create(input: CreateIdpInput): Promise<Envelope<IdpConfig>>;
@@ -430,10 +374,8 @@ declare function makeGateNamespace(getConfig: () => GateConfig): {
         testProvider(configId: string): Promise<Envelope<FederationTestProviderResult>>;
     };
     /**
-     * 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: {
         list(): Promise<Envelope<{
@@ -449,75 +391,43 @@ declare function makeGateNamespace(getConfig: () => GateConfig): {
  *  Per-instance clients: `createGateClient(config)`. */
 declare const gate: {
     /**
-     * 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
      */
     signUp(input: SignUpInput): Promise<Envelope<AuthResult>>;
     /**
-     * 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)
      */
     signIn(input: SignInInput): Promise<Envelope<AuthResult>>;
     /**
-     * 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 }`.
      */
-    signOut(input?: SignOutInput): Promise<Envelope<{
-        revoked: boolean;
-    }>>;
+    signOut(input: SignOutInput): Promise<Envelope<SignOutResult>>;
     /**
-     * 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
      */
     whoami(): Promise<Envelope<WhoamiResult>>;
     /**
-     * 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
      */
-    refreshToken(input: RefreshTokenInput): Promise<Envelope<{
-        session: AuthResult["session"];
-    }>>;
-    /**
-     * 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).
-     */
-    verifySession(): Promise<Envelope<VerifySessionResult>>;
-    /**
-     * 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.
-     */
-    hosted(): Promise<Envelope<HostedGateInfo>>;
+    refreshToken(input: RefreshTokenInput): Promise<Envelope<RefreshResult>>;
     /**
      * Initiate an external-IdP sign-in flow (Google / GitHub / Microsoft).
      * The SDK POSTs to the gateway's authorize endpoint, receives the
@@ -536,8 +446,6 @@ declare const gate: {
      *   });
      *   // …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.
      */
     signInWithProvider(input: {
         provider: "google" | "github" | "microsoft" | "oidc" | "saml";
@@ -555,74 +463,56 @@ declare const gate: {
      */
     parseSignInCallback(hash: string): SignInCallbackResult;
     /**
-     * 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.
          */
-        requestOtp(input: RequestOtpInput): Promise<Envelope<{
-            requested: boolean;
-        }>>;
+        requestOtp(input: RequestOtpInput): Promise<Envelope<RequestOtpResult>>;
         /**
-         * 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
          */
-        verifyOtp(input: VerifyOtpInput): Promise<Envelope<AuthResult>>;
+        verifyOtp(input: VerifyOtpInput): Promise<Envelope<VerifyOtpResult>>;
         /**
-         * 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.
          */
-        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<{
-            requested: boolean;
-        }>>;
+        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<RequestMagicLinkResult>>;
         /**
-         * 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
          */
-        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<AuthResult>>;
+        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<VerifyMagicLinkResult>>;
         /**
-         * 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
-         * returned `token` to `verifyMagicLink({ token })` to mint the session.
-         *
-         * This is the magic-link counterpart to `parseSignInCallback` (which parses
-         * the SSO *hash fragment* for session tokens) — magic-link delivers an
-         * opaque token in the *query string*, so the two are not interchangeable.
-         */
+           * 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
+           * returned `token` to `verifyMagicLink({ token })` to mint the session.
+           *
+           * This is the magic-link counterpart to `parseSignInCallback` (which parses
+           * the SSO *hash fragment* for session tokens) — magic-link delivers an
+           * opaque token in the *query string*, so the two are not interchangeable.
+           */
         parseMagicLinkCallback(search: string): MagicLinkCallbackResult;
     };
     /**
-     * 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: {
         create(input: CreateIdpInput): Promise<Envelope<IdpConfig>>;
@@ -631,10 +521,8 @@ declare const gate: {
         testProvider(configId: string): Promise<Envelope<FederationTestProviderResult>>;
     };
     /**
-     * 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: {
         list(): Promise<Envelope<{
@@ -661,11 +549,8 @@ type GateNamespace = ReturnType<typeof makeGateNamespace>;
  * incoming request's resolved tenant) or for apps that maintain both a
  * Standalone and Native binding against the same SDK instance.
  *
- * Per the URL grammar, supply `projectSlug` for
- * canonical `/@<slug>/gate/...` routing. Slug is the only customer-facing
- * project addressing form — project ids are internal-only
- * (`feedback_slug_addressing_v2_5_68`); the retired `/v2/projects/...`
- * mounts were dropped at pass17 (`feedback_v2_path_is_an_error`).
+ * Supply `projectSlug` for
+ * `/@<slug>/gate/...` routing. The slug is the only project addressing form.
  *
  * Example:
  *   const client = createGateClient({
@@ -683,26 +568,51 @@ type GateClient = ReturnType<typeof makeGateNamespace>;
  *  re-read process-level state. Throws `TypeError` on invalid config. */
 declare function createGateClient(config: GateConfig): GateClient;
 
+/**
+ * Reads the structure of a gateway API host without knowing its apex.
+ *
+ * The gateway label is `api` or `api-staging`, optionally followed by `-<rgn>` (a 4-character region code). The label
+ * before it is the org slug and whatever follows it is the apex, which is never matched against a list: a public-cloud,
+ * internal-apex, air-gapped or localhost deployment all work.
+ */
+/** The structure of a gateway API host, read from the host itself. */
+type ApiHost = {
+    /** First label of an org host (`acme` in `acme.api.corp.internal`); null for a platform host (`api.corp.internal`). */
+    orgSlug: string | null;
+    /** `api` or `api-staging`: the label that marks a gateway host. */
+    family: "api" | "api-staging";
+    /** 4-character region code when the host is regional (`api-de01`), else null (region-free). */
+    region: string | null;
+    /** Everything after the gateway label (`corp.internal`, `k9o.io`). */
+    apex: string;
+};
+/**
+ * Returns null for any other shape (localhost, an IP, a single-label host, a host with no gateway label), which callers
+ * use exactly as given.
+ */
+declare function parseApiHost(host: string): ApiHost | null;
+
 /**
  * Regional host resolution.
  *
- * The region-free org host `<org>.api[-staging].k9o.io` redirects GET/HEAD only and REFUSES a request that carries a
- * body, an `Authorization` header or a cookie (`400 K9O_INVALID_REQUEST_SHAPE`, `region_free_host_takes_no_credentials`),
- * so credentials must go to `<org>.api[-staging]-<rgn>.k9o.io`. An SDK learns the region with ONE unauthenticated
- * `HEAD https://<org>.api[-staging].k9o.io/`, takes the `308` `Location`, and caches the regional origin.
+ * A region-free org host `<org>.api.<rest>` (or `<org>.api-staging.<rest>`) redirects GET/HEAD only and REFUSES a
+ * request that carries a body, an `Authorization` header or a cookie (`400 K9O_INVALID_REQUEST_SHAPE`,
+ * `region_free_host_takes_no_credentials`), so credentials must go to `<org>.api-<rgn>.<rest>`. The client learns the
+ * region with ONE unauthenticated `HEAD` to the configured host, takes the `308` `Location`, and caches the regional
+ * origin.
  *
- * Properties this module holds:
- *   - Only a region-free org host (shape `<org>.api.k9o.io` or `<org>.api-staging.k9o.io`) is ever probed. A regional,
- *     custom, self-hosted or dev baseUrl is used exactly as given.
+ * Nothing here knows an apex. The host comes from the configured baseUrl; `<rest>` is whatever follows the second
+ * label, so a public-cloud, internal-apex, air-gapped or localhost deployment all work. Properties:
+ *   - Only a host shaped `<org>.api.<rest>` / `<org>.api-staging.<rest>` is probed. A regional, single-label, IP,
+ *     localhost or any other baseUrl is used exactly as given.
  *   - The probe carries NO credential and none of the configured default headers (they may hold one).
- *   - The `Location` is trusted only if it is `https`, has no userinfo/port, and its host is exactly the SAME org on
- *     the SAME apex family with a 4-character region code. Anything else is ignored and the configured baseUrl stays,
- *     so a hostile redirect can never receive a credential.
- *   - Not a redirect (the platform has not cut over, or the host answers directly), or any failure: the configured
- *     baseUrl stays and the server's own refusal, if any, is what the caller sees. A definite answer is cached for the
- *     life of the client's config; a network failure is not cached.
+ *   - The `Location` is trusted only if it is `https`, has no userinfo/port, and its host is exactly the SAME org and
+ *     SAME remainder with a 4-character region code appended to the second label. Anything else is ignored and the
+ *     configured baseUrl stays, so a hostile redirect can never receive a credential.
+ *   - Not a redirect, or any failure: the configured baseUrl stays and the server's own refusal, if any, is what the
+ *     caller sees. A definite answer is cached for the life of the client's config; a network failure is not cached.
  */
-/** The slice of a client config this module needs (structural, so core and gate share one implementation). */
+/** The slice of a client config this module needs. */
 type RegionConfig = {
     baseUrl: string;
     fetch?: typeof globalThis.fetch | undefined;
@@ -712,4 +622,4 @@ declare function regionalOriginFromLocation(host: string, location: string, base
 /** The origin requests for this client go to: the cached regional origin once learned, else the configured baseUrl. */
 declare function resolveRegionalOrigin(config: RegionConfig): Promise<string>;
 
-export { AuthResult, type CreateIdpInput, type DirectorySyncInput, Envelope, type GateClient, GateConfig, type GateNamespace, HostedGateInfo, type IdentityProvidersNamespace, type IdpConfig, type IdpProviderKind, type IdpTierGating, MagicLinkCallbackResult, type PatchIdpInput, RefreshTokenInput, type RegionConfig, RequestMagicLinkInput, RequestOtpInput, SignInCallbackResult, SignInInput, SignOutInput, SignUpInput, VerifyMagicLinkInput, VerifyOtpInput, VerifySessionResult, WhoamiResult, createGateClient, gate, regionalOriginFromLocation, resolveRegionalOrigin };
+export { type ApiHost, AuthResult, type CreateIdpInput, type DirectorySyncInput, Envelope, type GateClient, GateConfig, type GateNamespace, type IdentityProvidersNamespace, type IdpConfig, type IdpProviderKind, type IdpTierGating, MagicLinkCallbackResult, type PatchIdpInput, RefreshResult, RefreshTokenInput, type RegionConfig, RequestMagicLinkInput, RequestMagicLinkResult, RequestOtpInput, RequestOtpResult, SignInCallbackResult, SignInInput, SignOutInput, SignOutResult, SignUpInput, VerifyMagicLinkInput, VerifyMagicLinkResult, VerifyOtpInput, VerifyOtpResult, WhoamiResult, createGateClient, gate, parseApiHost, regionalOriginFromLocation, resolveRegionalOrigin };