@k9o/gate 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,717 @@
+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';
+export { EndUser, GateJwtClaims, OtpPurpose, Session, VerifyJwtFailure, VerifyJwtResult } from './types.js';
+export { VerifyJwtOptions, extractClaims, 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
+ * `gate.idpProviders.*` sub-namespace convention (gate-admin surface,
+ * not the end-user-facing `passwordless.*` send/verify flow).
+ *
+ * Wraps the live gateway routes (`services/gateway/src/routes/
+ * gate-magic-link-redirects.ts`):
+ *
+ *   GET    /@<projectSlug>/gate/magic-link-redirects
+ *   POST   /@<projectSlug>/gate/magic-link-redirects        { redirectUrl, isDefault? }
+ *   DELETE /@<projectSlug>/gate/magic-link-redirects/:id
+ *
+ * One deliberate deviation from the shorthand in the original blessing
+ * relay ("remove(redirectUrl)"): the shipped route deletes by the
+ * redirect row's `id`, not by re-presenting its `redirectUrl` value —
+ * verified directly against the route, not assumed from the relay's
+ * informal shape sketch. `remove(id)` matches what the gateway actually
+ * does; a `redirectUrl`-keyed removal would need an extra `list()`
+ * round-trip to resolve the id first, which the SDK should not do
+ * silently on the caller's behalf.
+ *
+ * Auth: operator JWT with PROJECT_ADMIN+ (or ORG_ADMIN/ORG_OWNER) role —
+ * the gateway rejects end-user JWTs and lower-role operators alike
+ * (K9O_RBAC_DENY). The allowlist is a security control: registering a
+ * redirect target is an admin act, same posture as `idpProviders.*`.
+ */
+
+/** A single allowlisted magic-link redirect target. */
+type MagicLinkRedirect = {
+    id: string;
+    redirectUrl: string;
+    isDefault: boolean;
+    createdAt: string;
+};
+type AddMagicLinkRedirectInput = {
+    redirectUrl: string;
+    /**
+     * When true, this target becomes the default the gateway falls back to
+     * when a `requestMagicLink` call doesn't specify one. The gateway
+     * atomically demotes any previously-default entry — never two
+     * simultaneous defaults.
+     */
+    isDefault?: boolean;
+};
+type RemoveMagicLinkRedirectResult = {
+    removed: true;
+    id: string;
+};
+
+/**
+ * `gate.identityProviders` namespace — project-scoped end-user IdP
+ * provider-config management (ch04 §1.6).
+ *
+ * Wraps the live gateway route family shipped in
+ * `services/gateway/src/routes/project-identity-providers.ts`, mounted on
+ * the project plane (`<orgSlug>.api.k9o.io/@<projectSlug>/identity-providers`):
+ *
+ *   POST   /@<projectSlug>/identity-providers          — create (PROJECT_ADMIN)
+ *   GET    /@<projectSlug>/identity-providers          — list   (READ_ROLES)
+ *   PATCH  /@<projectSlug>/identity-providers/:epcId   — update (PROJECT_ADMIN)
+ *   POST   /@<projectSlug>/identity-providers/:epcId/test — testProvider (PROJECT_ADMIN)
+ *
+ * `create()` + `list()` back the Gate Studio `FederationPresetsPanel`; `update()` backs its
+ * `DirectorySyncPanel` (directory-sync settings are read off `list()` and written via `update()`, replacing
+ * the unanswered `federation.getDirectorySync`/`updateDirectorySync` bridge messages). Read-one/delete stay
+ * unbound until a caller needs them (the SDK does not speculatively surface routes).
+ *
+ * Auth: operator JWT with PROJECT_ADMIN+ role, server-enforced by the
+ * gateway RBAC layer (`requireProjectAdmin`); end-user JWTs (`eu_`-prefixed
+ * subjects) are rejected at the route. The bearer is taken from
+ * `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
+ * `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
+ * 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 per ch04 §1.6 — 11 values since v221 (the project-plane substrate
+ *  `_sys.end_user_idp_provider_configs`); the org plane carries the same 11 since v222/v223. */
+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
+ * verdict; `reason` (present only when `!ok`) is a CLOSED-enum machine code, NEVER the upstream response body
+ * or any credential material. v1 is a NO-SECRET probe: it validates the issuer/metadata
+ * endpoint is reachable + structurally valid; it never transmits the stored client secret. `credentials_rejected`
+ * is deliberately NOT a v1 reason — the secret is never used, so it cannot be validated (a v2 concern).
+ */
+type FederationTestProviderResult = {
+    ok: boolean;
+    reason?: "endpoint_unreachable" | "endpoint_forbidden" | "metadata_invalid" | "secret_not_provisioned" | "kind_unsupported";
+};
+/** Per ch04 §1.6 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
+ *  verbatim rather than second-guessing it. */
+type IdpTierGating = "free_tier_ok" | "ridge_plus";
+/**
+ * The provider-config metadata shape returned by every read surface and
+ * mutation response (`shapeIdpConfig`). Mirrors the gateway wire shape
+ * one-to-one.
+ *
+ * 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, ch03 §5.11):
+ * settings plus the scheduler's last-run status; the service-account key itself is never returned.
+ */
+type IdpConfig = {
+    id: string;
+    projectId: string;
+    idpProvider: IdpProviderKind;
+    displayName: string;
+    clientId: string;
+    /** Whether a client secret is stored. The secret (and any handle to it) is write-only. */
+    clientSecretSet: boolean;
+    redirectUri: string;
+    metadataUrl: string | null;
+    attributeMap: Record<string, unknown>;
+    tierGating: IdpTierGating;
+    enabled: boolean;
+    allowedRedirectUris: string[];
+    directoryPullEnabled: boolean;
+    directorySyncSubject: string | null;
+    directorySyncIntervalMins: number | null;
+    directorySyncLastRunAt: string | null;
+    directorySyncLastStatus: string | null;
+    createdAt: string;
+    updatedAt: string | null;
+};
+/** GS-F7 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;
+    directorySyncIntervalMins?: number;
+    /** The raw Google service-account key JSON. Write-only: encrypted at rest server-side, never returned. */
+    serviceAccountKey?: string;
+    /** The Workspace admin user the service account impersonates (domain-wide delegation subject). */
+    directorySyncSubject?: string;
+};
+/**
+ * Create-request body — mirrors the gateway `CreateIdpBody` (t.Object)
+ * exactly, including which fields are optional.
+ */
+type CreateIdpInput = {
+    idpProvider: IdpProviderKind;
+    displayName: string;
+    clientId: string;
+    /**
+     * The OAuth2 client secret. Sent over TLS; encrypted-at-rest server-side
+     * (AES-256-GCM) and never returned. Named `clientSecretRef` for wire
+     * compatibility — it is NOT a reference on the way in (see module header).
+     */
+    clientSecretRef: string;
+    redirectUri: string;
+    /** Optional; `null`/omitted for providers that don't use discovery metadata. */
+    metadataUrl?: string | null;
+    /** Optional claim→attribute mapping; defaults to `{}` server-side. */
+    attributeMap?: Record<string, string>;
+    tierGating: IdpTierGating;
+    /** Defaults to `false` server-side — a provider is created disabled. */
+    enabled?: boolean;
+    /**
+     * Customer SPA origins the SDK gate flow (`gate.signInWithProvider`) may
+     * hand session tokens back to. Origin-matched + fail-closed at authorize,
+     * so an empty/omitted list means SDK sign-in is disabled for this provider
+     * until an origin is registered. Defaults to `[]` server-side.
+     */
+    allowedRedirectUris?: string[] | null;
+} & DirectorySyncInput;
+/**
+ * Update-request body — mirrors the gateway `PatchIdpBody` exactly: every field optional; `idpProvider` and
+ * `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, ch04 §1.6): re-supply the
+ * secret whenever the metadata URL changes.
+ */
+type PatchIdpInput = {
+    displayName?: string;
+    clientId?: string;
+    /** The raw client secret (write-only; see the module header). */
+    clientSecretRef?: string;
+    redirectUri?: string;
+    metadataUrl?: string | null;
+    attributeMap?: Record<string, string>;
+    enabled?: boolean;
+    allowedRedirectUris?: string[] | null;
+} & DirectorySyncInput;
+/** Factory — produces an `identityProviders` namespace bound to the supplied
+ *  config getter. Used by both the `gate` singleton + `createGateClient`. */
+declare function makeIdentityProviders(getConfig: () => GateConfig): {
+    /**
+     * Register a new end-user IdP provider config for the configured
+     * project. PROJECT_ADMIN+ required (server-enforced). The plaintext
+     * client secret is encrypted-at-rest server-side; the returned config
+     * carries only the opaque secret handle.
+     *
+     * The gateway validates the `idpProvider`→`tierGating` pairing per ch04
+     * §1.6 and rejects a mismatch with `K9O_INVALID_FIELD_VALUE`.
+     */
+    create(input: CreateIdpInput): Promise<Envelope<IdpConfig>>;
+    /**
+     * List the configured end-user IdP provider configs for the project.
+     * READ_ROLES-gated server-side (PROJECT_ADMIN/EDITOR/MEMBER/VIEWER/AUTHOR/
+     * ANALYST) — the SAME shape + roles as the existing GET route
+     * (`listProviders` returns the existing route's shape, no
+     * confidentiality-narrower endpoint). Each `IdpConfig` carries the opaque
+     * secret handle, never the secret. Callers that only need the summary
+     * (`id`/`idpProvider`/`displayName`/`enabled`/`tierGating`) pick fields off
+     * the result — no server change needed for that shaping.
+     */
+    list(): Promise<Envelope<IdpConfig[]>>;
+    /**
+     * Test connectivity to a configured provider by id — a NO-SECRET reachability + metadata-validity probe
+     * (no-secret): the gateway resolve-and-pins the issuer/metadata endpoint (SSRF-fenced) and
+     * validates it structurally, WITHOUT decrypting or transmitting the stored client secret. Returns
+     * `{ok, reason?}`; the `reason` is a closed machine code, never the upstream body or any credential.
+     * PROJECT_ADMIN required (server-enforced) — it triggers live external egress on the platform's behalf.
+     */
+    /**
+     * 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`
+     * for the metadataUrl-change-clears-secret rule.
+     */
+    update(configId: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>>;
+    testProvider(configId: string): Promise<Envelope<FederationTestProviderResult>>;
+};
+type IdentityProvidersNamespace = ReturnType<typeof makeIdentityProviders>;
+
+/** Factory — produces a `gate.*` namespace bound to the supplied config getter.
+ *  Used by both the module-level `gate` singleton (config from `configureGate`)
+ *  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 per ch01 §12.2. Emits a
+     * `data.write.auth.signup` audit event per ch01 §12.5.
+     *
+     * Errors (closed taxonomy per ch01 §2):
+     *   - `EMAIL_ALREADY_REGISTERED` (409) when the email collides
+     *   - `INVALID_FIELD_VALUE` (400) on schema violation (password policy, malformed email)
+     *   - `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.
+     *
+     * Errors:
+     *   - `INVALID_CREDENTIALS` (401) on bad email/password (ambiguous on
+     *     purpose — does not distinguish "user not found" vs "password
+     *     wrong" to avoid enumeration)
+     */
+    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
+     */
+    signOut(input?: SignOutInput): Promise<Envelope<{
+        revoked: boolean;
+    }>>;
+    /**
+     * 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.
+     *
+     * Errors:
+     *   - `UNAUTHENTICATED` (401) when no bearer is present
+     *   - `SESSION_EXPIRED` (401) when the bearer's exp has passed
+     */
+    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).
+     *
+     * 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.
+     */
+    hosted(): Promise<Envelope<HostedGateInfo>>;
+    /**
+     * Initiate an external-IdP sign-in flow (Google / GitHub / Microsoft).
+     * The SDK POSTs to the gateway's authorize endpoint, receives the
+     * provider's authorization URL with a signed-state JWT (carrying PKCE
+     * verifier + the supplied `redirectUri`), and redirects the browser.
+     *
+     * After the user authenticates with the IdP, the gateway processes the
+     * callback and redirects the browser back to `redirectUri` with session
+     * tokens in the URL fragment. Use `parseSignInCallback()` on the
+     * destination page to extract them.
+     *
+     * Example:
+     *   await gate.signInWithProvider({
+     *     provider: 'google',
+     *     redirectUri: 'https://app.example.com/auth/callback',
+     *   });
+     *   // …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";
+        redirectUri: string;
+    }): Promise<void>;
+    /**
+     * Parse session tokens out of the URL fragment delivered by an
+     * IdP callback redirect. Returns the session payload on success or an
+     * error object on failure. Pass `window.location.hash` (or any
+     * `#`-prefixed string) — leading `#` is stripped automatically.
+     *
+     * Side-effect-free: does not call the gateway and does not mutate
+     * any session storage. The consumer is responsible for persisting
+     * the returned tokens (e.g. via the app's auth context).
+     */
+    parseSignInCallback(hash: string): SignInCallbackResult;
+    /**
+     * Passwordless sub-namespace per ch01 §12.1 — OTP + Magic Link flows
+     * for email-based authentication without a stored password.
+     *
+     * 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 earlier `passwordless/*` SDK paths were interface-first scaffold
+     * that never matched the shipped gateway routes — reconciled here.)
+     */
+    passwordless: {
+        /**
+         * Request a one-time passcode delivered to the supplied email.
+         * The OTP is short-lived (typically 5 min per ch03 §3.4) and
+         * single-use; redemption via `verifyOtp` mints a session.
+         */
+        requestOtp(input: RequestOtpInput): Promise<Envelope<{
+            requested: boolean;
+        }>>;
+        /**
+         * 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.
+         *
+         * Errors:
+         *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed OTP
+         *     (ambiguous on purpose — enumeration defense)
+         */
+        verifyOtp(input: VerifyOtpInput): Promise<Envelope<AuthResult>>;
+        /**
+         * Request a magic-link emailed to the supplied address. The link
+         * carries an opaque short-lived token (typically 15 min per ch03
+         * §3.3); 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`.
+         */
+        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<{
+            requested: boolean;
+        }>>;
+        /**
+         * Verify a magic-link token previously delivered via
+         * `requestMagicLink`. On success returns the same `AuthResult`
+         * shape as `signIn`.
+         *
+         * Errors:
+         *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed
+         *     token (same enumeration-defense rationale as verifyOtp)
+         */
+        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<AuthResult>>;
+        /**
+         * 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 (ch04 §1.6).
+     * 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.
+     */
+    identityProviders: {
+        create(input: CreateIdpInput): Promise<Envelope<IdpConfig>>;
+        list(): Promise<Envelope<IdpConfig[]>>;
+        update(configId: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>>;
+        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.
+     */
+    magicLinkRedirects: {
+        list(): Promise<Envelope<{
+            redirects: MagicLinkRedirect[];
+        }>>;
+        add(input: AddMagicLinkRedirectInput): Promise<Envelope<{
+            redirect: MagicLinkRedirect;
+        }>>;
+        remove(id: string): Promise<Envelope<RemoveMagicLinkRedirectResult>>;
+    };
+};
+/** Singleton bound to the module-level `configureGate()` config.
+ *  v0.4.0+: per-instance clients via `createGateClient(config)`. */
+declare const gate: {
+    /**
+     * Create a new end-user identity for the configured project. Returns
+     * the new user record + an initial session per ch01 §12.2. Emits a
+     * `data.write.auth.signup` audit event per ch01 §12.5.
+     *
+     * Errors (closed taxonomy per ch01 §2):
+     *   - `EMAIL_ALREADY_REGISTERED` (409) when the email collides
+     *   - `INVALID_FIELD_VALUE` (400) on schema violation (password policy, malformed email)
+     *   - `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.
+     *
+     * Errors:
+     *   - `INVALID_CREDENTIALS` (401) on bad email/password (ambiguous on
+     *     purpose — does not distinguish "user not found" vs "password
+     *     wrong" to avoid enumeration)
+     */
+    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
+     */
+    signOut(input?: SignOutInput): Promise<Envelope<{
+        revoked: boolean;
+    }>>;
+    /**
+     * 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.
+     *
+     * Errors:
+     *   - `UNAUTHENTICATED` (401) when no bearer is present
+     *   - `SESSION_EXPIRED` (401) when the bearer's exp has passed
+     */
+    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).
+     *
+     * 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.
+     */
+    hosted(): Promise<Envelope<HostedGateInfo>>;
+    /**
+     * Initiate an external-IdP sign-in flow (Google / GitHub / Microsoft).
+     * The SDK POSTs to the gateway's authorize endpoint, receives the
+     * provider's authorization URL with a signed-state JWT (carrying PKCE
+     * verifier + the supplied `redirectUri`), and redirects the browser.
+     *
+     * After the user authenticates with the IdP, the gateway processes the
+     * callback and redirects the browser back to `redirectUri` with session
+     * tokens in the URL fragment. Use `parseSignInCallback()` on the
+     * destination page to extract them.
+     *
+     * Example:
+     *   await gate.signInWithProvider({
+     *     provider: 'google',
+     *     redirectUri: 'https://app.example.com/auth/callback',
+     *   });
+     *   // …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";
+        redirectUri: string;
+    }): Promise<void>;
+    /**
+     * Parse session tokens out of the URL fragment delivered by an
+     * IdP callback redirect. Returns the session payload on success or an
+     * error object on failure. Pass `window.location.hash` (or any
+     * `#`-prefixed string) — leading `#` is stripped automatically.
+     *
+     * Side-effect-free: does not call the gateway and does not mutate
+     * any session storage. The consumer is responsible for persisting
+     * the returned tokens (e.g. via the app's auth context).
+     */
+    parseSignInCallback(hash: string): SignInCallbackResult;
+    /**
+     * Passwordless sub-namespace per ch01 §12.1 — OTP + Magic Link flows
+     * for email-based authentication without a stored password.
+     *
+     * 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 earlier `passwordless/*` SDK paths were interface-first scaffold
+     * that never matched the shipped gateway routes — reconciled here.)
+     */
+    passwordless: {
+        /**
+         * Request a one-time passcode delivered to the supplied email.
+         * The OTP is short-lived (typically 5 min per ch03 §3.4) and
+         * single-use; redemption via `verifyOtp` mints a session.
+         */
+        requestOtp(input: RequestOtpInput): Promise<Envelope<{
+            requested: boolean;
+        }>>;
+        /**
+         * 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.
+         *
+         * Errors:
+         *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed OTP
+         *     (ambiguous on purpose — enumeration defense)
+         */
+        verifyOtp(input: VerifyOtpInput): Promise<Envelope<AuthResult>>;
+        /**
+         * Request a magic-link emailed to the supplied address. The link
+         * carries an opaque short-lived token (typically 15 min per ch03
+         * §3.3); 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`.
+         */
+        requestMagicLink(input: RequestMagicLinkInput): Promise<Envelope<{
+            requested: boolean;
+        }>>;
+        /**
+         * Verify a magic-link token previously delivered via
+         * `requestMagicLink`. On success returns the same `AuthResult`
+         * shape as `signIn`.
+         *
+         * Errors:
+         *   - INVALID_CREDENTIALS (401) on wrong / expired / consumed
+         *     token (same enumeration-defense rationale as verifyOtp)
+         */
+        verifyMagicLink(input: VerifyMagicLinkInput): Promise<Envelope<AuthResult>>;
+        /**
+         * 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 (ch04 §1.6).
+     * 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.
+     */
+    identityProviders: {
+        create(input: CreateIdpInput): Promise<Envelope<IdpConfig>>;
+        list(): Promise<Envelope<IdpConfig[]>>;
+        update(configId: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>>;
+        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.
+     */
+    magicLinkRedirects: {
+        list(): Promise<Envelope<{
+            redirects: MagicLinkRedirect[];
+        }>>;
+        add(input: AddMagicLinkRedirectInput): Promise<Envelope<{
+            redirect: MagicLinkRedirect;
+        }>>;
+        remove(id: string): Promise<Envelope<RemoveMagicLinkRedirectResult>>;
+    };
+};
+/** Convenience type alias mirroring the `gate` runtime export.
+ *  Identical shape as the per-instance `GateClient` returned from
+ *  `createGateClient`. */
+type GateNamespace = ReturnType<typeof makeGateNamespace>;
+
+/**
+ * `createGateClient(config)` — per-instance Gate SDK factory (v0.4.0).
+ *
+ * Returns a self-contained `GateClient` that does not depend on the
+ * module-level `configureGate()` singleton. Multiple clients can coexist
+ * in the same process, each scoped to its own project + baseUrl + mode —
+ * useful for multi-tenant Backends-For-Frontends (one client per
+ * incoming request's resolved tenant) or for apps that maintain both a
+ * Standalone and Native binding against the same SDK instance.
+ *
+ * Per v2.5.68 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`).
+ *
+ * Example:
+ *   const client = createGateClient({
+ *     baseUrl: 'https://formelo.api.k9o.io',
+ *     projectSlug: 'partner-console-staging',
+ *     mode: 'native',
+ *   });
+ *   await client.signIn({ email, password });
+ */
+
+/** Shape of the per-instance client returned by `createGateClient`. */
+type GateClient = ReturnType<typeof makeGateNamespace>;
+/** Construct a Gate client bound to the supplied config. The config is
+ *  validated up-front and stored on the instance; subsequent calls do not
+ *  re-read process-level state. Throws `TypeError` on invalid config. */
+declare function createGateClient(config: GateConfig): GateClient;
+
+/**
+ * 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.
+ *
+ * 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.
+ *   - 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 slice of a client config this module needs (structural, so core and gate share one implementation). */
+type RegionConfig = {
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch | undefined;
+};
+/** The regional origin a `Location` may name for `host`, or null if it is not exactly that. Pure. */
+declare function regionalOriginFromLocation(host: string, location: string, base: string): string | null;
+/** 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 };