@k9o/gate 1.1.1 → 1.3.0

package/dist/jwt.d.ts

@@ -1,58 +1,39 @@
 import { GateJwtClaims, VerifyJwtResult } from './types.js';
 
 /**
- * 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`.
  */
 
 /**
- * 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).
  */
 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;
 };
 /**
@@ -61,7 +42,7 @@ type VerifyJwtOptions = {
  *
  * 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
  */
 declare function verifyJwt(opts: VerifyJwtOptions): Promise<VerifyJwtResult>;
 /**
@@ -80,5 +61,13 @@ declare function extractClaims(token: string): GateJwtClaims;
  * Returns nothing on success — caller uses the throw-or-pass shape.
  */
 declare function requireScope(claims: GateJwtClaims, requiredScopes: ReadonlyArray<string>): void;
+type Jwks = {
+    keys: ReadonlyArray<Record<string, unknown>>;
+};
+/**
+ * Fetch a JWKS from the gateway. The route answers `{ data: { keys }, meta }`; a bare `{ keys }` (any other JWKS
+ * host) is accepted too.
+ */
+declare function fetchJwks(url: string, fetchImpl?: typeof globalThis.fetch | undefined): Promise<Jwks>;
 
-export { type VerifyJwtOptions, extractClaims, requireScope, verifyJwt };
+export { type VerifyJwtOptions, extractClaims, fetchJwks, requireScope, verifyJwt };

package/dist/jwt.js

@@ -1,11 +1,13 @@
 import {
   extractClaims,
+  fetchJwks,
   requireScope,
   verifyJwt
-} from "./chunk-YINWOWJC.js";
-import "./chunk-JEV37YEC.js";
+} from "./chunk-OJQYLAGZ.js";
+import "./chunk-7EED6YWR.js";
 export {
   extractClaims,
+  fetchJwks,
   requireScope,
   verifyJwt
 };

package/dist/mode.d.ts

@@ -1,37 +1,12 @@
 /**
  * Standalone vs Native mode wiring.
  *
- * The SDK surface is identical across modes; mode determines gateway-
- * side behavior (whether the end-user row scope applies on read/write paths),
- * not SDK ergonomics. The mode boundary is a deployment-time decision
- *; the SDK does not branch behavior at function-call time.
+ * The SDK surface is identical across modes; the mode only tells the gateway how to route consumption. The SDK
+ * records it on every request in the `X-Gate-Mode` header and does not branch on it at call time.
  *
- * What mode affects (today + forward):
- *
- *   - **Billing-identity routing** (commission callout):
- *     Standalone customers are billed under the partner-credentialled
- *     contract (Gate as Auth0/Clerk/Okta alternative — Trojan Horse
- *     motion); Native customers compose with the broader Kilimanjaro
- *     billing model. The SDK records the mode on every wire request via
- *     the `X-Gate-Mode` header so the gateway routes consumption to the
- *     correct billing surface without per-function branching.
- *   - **Auto-scoping expectations** in marketing copy + docs hub copy
- *     (per memory `feedback_gate_iak_brand_architecture.md` marketing-
- *     honesty discipline). Standalone mode delivers Sovereign Ingress +
- *     Hardware-Attested Identity + Forensic Attribution + Unlimited MAUs;
- *     Native mode adds Automatic Identity-Aware Scoping on top.
- *
- * What mode does NOT affect:
- *
- *   - Function names + signatures (identical across modes)
- *   - Wire-envelope shape (identical)
- *   - Error taxonomy (identical)
- */
-/**
- * Two-mode discriminant. The third candidate "Hybrid" was rejected per
- * memory `feedback_gate_iak_brand_architecture.md` — modes are
- * orthogonal deployment shapes, not interleaved.
+ * Function names, signatures, response envelope and error taxonomy are the same in both modes.
  */
+/** Two orthogonal deployment shapes; they are not interleaved. */
 type GateMode = "standalone" | "native";
 /**
  * Gate SDK configuration. Returned by `getGateConfig()` and consumed
@@ -40,11 +15,9 @@ type GateMode = "standalone" | "native";
  */
 type GateConfig = {
     mode: GateMode;
-    /** Project slug per the URL grammar (e.g. `partner-console-staging`).
-     *  The only customer-facing project addressing form; routes resolve to
-     *  `/@<slug>/gate/...` (`feedback_slug_addressing_v2_5_68`). Required. */
+    /** Project slug (e.g. `partner-console-staging`). Routes resolve to `/@<slug>/gate/...`. Required. */
     projectSlug: string;
-    /** Gateway base URL — e.g. `https://<orgSlug>.api.k9o.io` per the URL grammar */
+    /** Gateway base URL, e.g. `https://<orgSlug>.api.<apex>` */
     baseUrl: string;
     /**
      * Optional partner-credentialled JWT for Standalone mode — used as the

package/dist/mode.js

@@ -3,7 +3,7 @@ import {
   getGateConfig,
   resetGateConfig,
   validateGateConfig
-} from "./chunk-XP6U5QKF.js";
+} from "./chunk-RPE5N37W.js";
 export {
   configureGate,
   getGateConfig,

package/dist/types.d.ts

@@ -1,32 +1,15 @@
 /**
- * `@k9o/gate` — public type surface.
- *
- * The shapes here track verbatim. End-user IDs carry the `eu_`
- * prefix; role and group identifiers compose against the
- * role lattice (Trust-Zone-separate `PROJECT_END_USER` for project-
- * level end-user identities). Sessions, passkeys, MFA factors, federation
- * links, and the rest of the Gate-managed resources receive their per-
- * resource prefixes as the end-user table family is specified.
- *
- * Envelope shape (`data` + `meta`) matches; failures land via
- * the `GateError` family per `errors.ts`, which is `KError`-compatible
- *.
- */
-/**
- * Standard envelope. Generic over the `data` shape per function.
- * Returned by every successful SDK call.
+ * `@k9o/gate` public types. They mirror what the end-user Gate routes answer; failures arrive as a `GateError`
+ * (see `errors.ts`).
  */
+/** The gateway's response envelope, generic over the `data` shape. Returned by every successful SDK call. */
 type Envelope<T> = {
     data: T;
     meta: Record<string, unknown>;
 };
-/**
- * Project-level end-user identity (the customers OF the customer as
- * the `PROJECT_END_USER` 7th canonical role). End-user IDs carry the
- * `eu_<base62>` prefix.
- */
+/** A project end-user (the customers of the project's customer). Ids carry the `eu_` prefix. */
 type EndUser = {
-    /** `eu_<base62>` — see. */
+    /** `eu_<base62>`. */
     id: string;
     email: string;
     status: "active" | "pending" | "disabled";
@@ -35,15 +18,12 @@ type EndUser = {
     lastSigninAt: string | null;
     /** Project-level roles; `PROJECT_END_USER` is the floor membership. */
     roles: ReadonlyArray<string>;
-    /** Project-level group memberships `_sys.end_user_groups`. */
+    /** Project-level group memberships. */
     groups: ReadonlyArray<string>;
 };
 /**
- * Session tokens returned by sign-up / sign-in / refresh flows. Both
- * tokens are opaque to consumers; `accessToken` carries the JWT shape
- * for downstream Gate-aware services; `refreshToken` is opaque to the
- * SDK consumer and is presented back to `gate.refreshToken({...})` to
- * rotate the access token.
+ * Session tokens returned by sign-up, sign-in, OTP and magic-link redemption. The access token is a JWT; the refresh
+ * token is opaque and is presented to `gate.refreshToken` and `gate.signOut`.
  */
 type Session = {
     accessToken: string;
@@ -51,41 +31,26 @@ type Session = {
     /** ISO 8601 instant the access token expires. */
     expiresAt: string;
 };
-/**
- * Marquee sign-up / sign-in shape:
- *   `{ user, session }`
- */
+/** Sign-up and sign-in answer: `{ user, session }`. */
 type AuthResult = {
     user: EndUser;
     session: Session;
 };
-/**
- * `gate.whoami()` shape:
- *   `{ user }` — no fresh session is minted by `whoami` (it reflects the
- *   caller's current session).
- */
-type WhoamiResult = {
-    user: EndUser;
+/** `gate.whoami()` answers the end-user record itself (no wrapper). */
+type WhoamiResult = EndUser;
+/** `gate.refreshToken()` answers a new access token only; the refresh token in hand stays valid. */
+type RefreshResult = {
+    accessToken: string;
+    /** ISO 8601 instant the new access token expires. */
+    expiresAt: string;
 };
-/**
- * `gate.verifySession()` shape — boolean plus the surfaced session
- * details if valid. Returns `{ valid: false, user: null, session: null }`
- * when the bearer session is missing or expired (no throw on invalid;
- * throw only on transport / upstream failures).
- */
-type VerifySessionResult = {
-    valid: true;
-    user: EndUser;
-    session: Session;
-} | {
-    valid: false;
-    user: null;
-    session: null;
+/** `gate.signOut()` answer. `revoked` is false when the token was unknown or already revoked. */
+type SignOutResult = {
+    revoked: boolean;
 };
 /**
- * Marquee request shapes. `gate.signUp` takes a CLOSED body: `{ email, password, displayName? }`.
- * `displayName` is stored with the end user's PII (1 to 128 characters); any other field is refused by the
- * gateway with `K9O_INVALID_FIELD_VALUE` (`context.reason: "unknown_field"`), so this type has no escape hatch.
+ * `gate.signUp` takes a CLOSED body: `{ email, password, displayName? }`. `displayName` is 1 to 128 characters; any
+ * other field is refused by the gateway with `INVALID_FIELD_VALUE` (`context.reason: "unknown_field"`).
  */
 type SignUpInput = {
     email: string;
@@ -98,36 +63,39 @@ type SignInInput = {
     password: string;
 };
 type SignOutInput = {
-    /**
-     * Optional refresh token to revoke. When omitted the gateway revokes
-     * the access token's bound refresh token only; explicit refresh tokens
-     * let callers revoke a specific device/session.
-     */
-    refreshToken?: string;
+    /** The refresh token of the session to revoke (required by the route). */
+    refreshToken: string;
 };
 type RefreshTokenInput = {
     refreshToken: string;
 };
-/**
- * OTP purpose — scopes the one-time code to a flow. The gateway validates
- * against this closed set (otp.ts) and defaults to "signin" when omitted.
- */
+/** OTP purpose: scopes the one-time code to a flow. The gateway defaults to `"signin"` when omitted. */
 type OtpPurpose = "signin" | "magic_link" | "password_reset" | "mfa_challenge";
-/**
- * `gate.passwordless.requestOtp` input — emails an OTP code to the
- * given address. Idempotent at the per-email rate-limit ceiling per
- * the platform anti-abuse policy.
- */
+/** `gate.passwordless.requestOtp` input: emails a one-time code to the address. */
 type RequestOtpInput = {
     email: string;
     /** OTP purpose; defaults to "signin" server-side when omitted. */
     purpose?: OtpPurpose;
 };
+/** `gate.passwordless.verifyOtp` input: the 6-character code from the email plus the address it went to. */
+/** `gate.passwordless.requestOtp` answer. */
+type RequestOtpResult = {
+    otp: {
+        id: string;
+        expiresAt: string;
+    };
+    /** Only present on a deployment configured to return the code in the response (development). */
+    debugCode?: string;
+};
 /**
- * `gate.passwordless.verifyOtp` input — caller supplies the OTP code
- * received via email plus the originating email address so the
- * gateway can resolve the right OTP row.
+ * `gate.passwordless.verifyOtp` answer. `session` and `endUserId` are present for the `signin` purpose; other
+ * purposes only confirm the code (`endUserId` when the email belongs to an end-user).
  */
+type VerifyOtpResult = {
+    verified: true;
+    session?: Session;
+    endUserId?: string;
+};
 type VerifyOtpInput = {
     email: string;
     code: string;
@@ -135,11 +103,7 @@ type VerifyOtpInput = {
      *  so the gateway resolves the right OTP row. */
     purpose?: OtpPurpose;
 };
-/**
- * `gate.passwordless.requestMagicLink` input — emails a magic-link
- * token to the given address; the customer's frontend handles the
- * post-redirect exchange via `verifyMagicLink`.
- */
+/** `gate.passwordless.requestMagicLink` input: emails a magic link to the address. */
 type RequestMagicLinkInput = {
     email: string;
     /**
@@ -150,10 +114,22 @@ type RequestMagicLinkInput = {
      */
     redirectUrl?: string;
 };
-/**
- * `gate.passwordless.verifyMagicLink` input — caller supplies the
- * opaque token from the magic-link query string.
- */
+/** `gate.passwordless.verifyMagicLink` input: the opaque token from the magic-link query string. */
+/** `gate.passwordless.requestMagicLink` answer. The same shape comes back for an unknown email. */
+type RequestMagicLinkResult = {
+    magicLink: {
+        sent: true;
+        expiresAt?: string;
+    };
+    /** Only present on a deployment configured to return the link in the response (development). */
+    debugLink?: string;
+};
+/** `gate.passwordless.verifyMagicLink` answer: the new session and the end-user's id. */
+type VerifyMagicLinkResult = {
+    redeemed: true;
+    session: Session;
+    endUserId: string;
+};
 type VerifyMagicLinkInput = {
     token: string;
 };
@@ -171,10 +147,8 @@ type MagicLinkCallbackResult = {
     error: string;
 };
 /**
- * JWT claim shape that `verifyJwt` resolves. Mirrors `subject.*`
- * exposure for project-level JWTs plus the Gate-issued audience / issuer
- * standard claims. Customer apps in Standalone mode consume this via the
- * `verifyJwt` helper without needing the full SDK shape.
+ * Claims of a Gate access token that `verifyJwt` resolves. Custom claims arrive FLAT under keys of the form
+ * `ext.<namespace>.<name>`; they are available through the index signature.
  */
 type GateJwtClaims = {
     /** Issuer — the Kilimanjaro gateway base URL or project-bound issuer. */
@@ -193,7 +167,7 @@ type GateJwtClaims = {
     roles?: ReadonlyArray<string>;
     /** Project-level group memberships. */
     groups?: ReadonlyArray<string>;
-    /** Project-level scope strings — used by `requireScope`. */
+    /** Scope strings, when the token carries them; used by `requireScope`. */
     scopes?: ReadonlyArray<string>;
     /** Email of the underlying end-user; convenience copy of the database column. */
     email?: string;
@@ -236,15 +210,5 @@ type SignInCallbackResult = {
     error: string;
     errorDescription: string;
 };
-/**
- * The project's hosted sign-in page and WebAuthn relying party (`GET /@<projectSlug>/gate/hosted`). Both values come from the platform: an SDK never composes a Gate host from a slug (the label is a hash of
- * ids the SDK does not hold).
- */
-type HostedGateInfo = {
-    /** Absolute hosted sign-in URL: the verified custom domain's when there is one, else the project's Gate host. */
-    signInUrl: string;
-    /** The WebAuthn relying-party id (the project's Gate host). Use it as given; never hard-code it. */
-    rpId: string;
-};
 
-export type { AuthResult, EndUser, Envelope, GateJwtClaims, HostedGateInfo, MagicLinkCallbackResult, OtpPurpose, RefreshTokenInput, RequestMagicLinkInput, RequestOtpInput, Session, SignInCallbackResult, SignInInput, SignOutInput, SignUpInput, VerifyJwtFailure, VerifyJwtResult, VerifyMagicLinkInput, VerifyOtpInput, VerifySessionResult, WhoamiResult };
+export type { AuthResult, EndUser, Envelope, GateJwtClaims, MagicLinkCallbackResult, OtpPurpose, RefreshResult, RefreshTokenInput, RequestMagicLinkInput, RequestMagicLinkResult, RequestOtpInput, RequestOtpResult, Session, SignInCallbackResult, SignInInput, SignOutInput, SignOutResult, SignUpInput, VerifyJwtFailure, VerifyJwtResult, VerifyMagicLinkInput, VerifyMagicLinkResult, VerifyOtpInput, VerifyOtpResult, WhoamiResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/gate",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Gate — Identity-Aware Kernel SDK (standalone Auth0-parity surface; Native composition via @k9o/core re-export)",
   "type": "module",
   "main": "./dist/index.js",

package/src/api-host.ts

@@ -0,0 +1,43 @@
+/**
+ * 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. */
+export 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;
+};
+
+const API_LABEL = /^(api|api-staging)(?:-([a-z]{2}\d{2}))?$/;
+const SLUG_RE = /^[a-z][a-z0-9-]{1,62}$/;
+
+/**
+ * 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.
+ */
+export function parseApiHost(host: string): ApiHost | null {
+  const labels = host.toLowerCase().split(".");
+  if (labels.some((l) => l.length === 0)) return null;
+  const mk = (gatewayLabel: string, orgSlug: string | null, rest: string[]): ApiHost | null => {
+    const m = API_LABEL.exec(gatewayLabel);
+    if (m === null || rest.length === 0) return null;
+    return { orgSlug, family: m[1] as "api" | "api-staging", region: m[2] ?? null, apex: rest.join(".") };
+  };
+  // Org host first: `<org>.<api[-rgn]>.<apex>`.
+  if (labels.length >= 3 && SLUG_RE.test(labels[0]!) && !labels[0]!.endsWith("-") && API_LABEL.test(labels[1]!)) {
+    return mk(labels[1]!, labels[0]!, labels.slice(2));
+  }
+  // Platform host: `api.<apex>`.
+  if (labels.length >= 2 && API_LABEL.test(labels[0]!)) return mk(labels[0]!, null, labels.slice(1));
+  return null;
+}

package/src/client-factory.ts

@@ -8,11 +8,8 @@
  * 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({

package/src/client.ts

@@ -3,8 +3,8 @@
  *
  * Centralises:
  *   - URL construction against the configured `baseUrl` + per-call path
- *   - the standard envelope unwrap on success
- *   - the standard `KError` rehydration on failure via `gateErrorFromWire`
+ *   - the standard response envelope check on success
+ *   - the `KError` rehydration on failure via `gateErrorFromWire`
  *   - mode-routing via the `X-Gate-Mode` header (so the gateway routes
  *     consumption to the right billing surface without per-function
  *     branching at the SDK)
@@ -47,7 +47,7 @@ export type RequestInit = {
  *     keeps the SDK portable across Bun + Node 18+ + browsers + test
  *     fixtures that supply a stub.
  *   - JSON parsing of non-JSON responses throws — gateway always returns
- *     JSON +, so a parse failure is an upstream defect.
+ *     JSON, so a parse failure is an upstream defect.
  */
 export async function request<T>(init: RequestInit): Promise<Envelope<T>> {
   return requestWith<T>(getGateConfig(), init);

package/src/errors.ts

@@ -36,7 +36,7 @@ export type GateErrorCode =
 
 /**
  * Surface error thrown by the SDK. Mirrors the gateway's `KError` shape
- * — `code` (closed taxonomy), `message` (human-readable),
+ * `code` (closed taxonomy), `message` (human-readable),
  * `context` (structured per-code payload), `recommendation` (action the
  * caller can take, or null when there's no canonical recommendation).
  */