@k9o/gate-react-native 1.1.1 → 1.3.0

package/README.md

@@ -3,6 +3,9 @@
 Kilimanjaro Gate for React Native. Sign end users in with email and password and refresh their session.
 The refresh token stays in the device keychain.
 
+Kilimanjaro is the AI-native foundation for building critical applications. Its products are Keep (AI Security and Governance),
+Pulse (Data Intelligence), Gate (Customer Identity and Access Management) and Kibo (Keys and Secrets Management).
+
 ## Contents
 
 - [Links](#links)
@@ -13,6 +16,11 @@ The refresh token stays in the device keychain.
 - [Custom claims](#custom-claims)
 - [Handle errors](#handle-errors)
 - [Appendix](#appendix)
+  - [Requirements](#requirements)
+  - [Client options](#client-options)
+  - [Methods](#methods)
+  - [Error codes](#error-codes)
+  - [Related packages](#related-packages)
 
 ## Links
 
@@ -20,11 +28,6 @@ The refresh token stays in the device keychain.
 - Documentation / Developer Hub: <https://docs.kilimanjaro.dev>
 - Platform API: <https://api.k9o.io>
 - Platform Console: <https://console.k9o.io>
-  - [Requirements](#requirements)
-  - [Client options](#client-options)
-  - [Methods](#methods)
-  - [Error codes](#error-codes)
-  - [Related packages](#related-packages)
 
 ## Install
 
@@ -65,15 +68,18 @@ The result has a `user` and a `session`. See [methods](#methods).
 
 ## Refresh and sign out
 
-With no arguments, `refreshToken` reads the stored token and saves the new one.
+With no arguments, `refreshToken` reads the stored refresh token and returns a new access token.
+The refresh token is not rotated, so the keychain is left as it is.
 
 ```ts
 const refreshed = await gate.refreshToken();
 
-console.log(refreshed.session.expiresAt);
+console.log(refreshed.accessToken.length > 0);
+console.log(refreshed.expiresAt);
 ```
 
 ```text
+true
 2026-01-15T11:30:00.000Z
 ```
 
@@ -118,7 +124,8 @@ const gate = new GateClient({
 
 ## Custom claims
 
-Claims added by extensions appear on the access token under their namespace. Decoding does not verify the signature.
+The token carries each extension claim as a flat key, `ext.<namespace>.<name>`.
+`customClaims` groups them as `{ namespace: { name: value } }`. Decoding does not verify the signature.
 
 ```ts
 import { AccessToken } from "@k9o/gate-react-native";
@@ -181,7 +188,7 @@ See [error codes](#error-codes) for all of them.
 
 | Option | Required | Meaning |
 |---|---|---|
-| `orgBaseUrl` | Yes | Your organization's API host, such as `https://acme.api.k9o.io` |
+| `orgBaseUrl` | Yes | Your organization's API host, such as `https://acme.api.k9o.io`; any apex works |
 | `projectSlug` | Yes | The project users sign in to |
 | `tokenStore` | No | Where the refresh token is kept; the keychain by default |
 
@@ -190,14 +197,15 @@ See [error codes](#error-codes) for all of them.
 | Method | What it does |
 |---|---|
 | `signIn({ email, password })` | Sign in; resolves to `{ user, session }` |
-| `refreshToken({ refreshToken?, projectHint? })` | Rotate the session; uses the stored token when none is passed |
-| `signOut({ refreshToken? })` | End the session and clear the stored token |
+| `refreshToken({ refreshToken? })` | Resolves to `{ accessToken, expiresAt }`; uses the stored token when none is passed |
+| `signOut({ refreshToken? })` | Revoke the session and clear the stored token; does nothing without a token |
 | `AccessToken.decode(jwt)` | Read an access token's claims; `null` if it is not a JWT |
 
 | Result field | Contents |
 |---|---|
 | `user` | `id`, `email`, `status`, `roles`, `groups`, timestamps |
 | `session` | `accessToken`, `refreshToken`, `expiresAt` |
+| refresh result | `accessToken`, `expiresAt` |
 
 ### Error codes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k9o/gate-react-native",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Kilimanjaro Gate IAK SDK for React Native",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/GateAuthClient.ts

@@ -1,5 +1,6 @@
 import { GateError, gateErrorFromResponse } from "./GateError";
 import { parseEnvelope } from "./Models";
+import { resolveRegionalOrigin } from "./region";
 
 /**
  * Internal fetch-based transport layer for @k9o/gate-react-native.
@@ -8,25 +9,38 @@ import { parseEnvelope } from "./Models";
 export class GateAuthClient {
   private readonly baseUrl: string;
   private readonly projectSlug: string;
+  private origin: Promise<string> | null = null;
 
   constructor(orgBaseUrl: string, projectSlug: string) {
     this.baseUrl = orgBaseUrl.replace(/\/$/, "");
     this.projectSlug = projectSlug;
   }
 
-  private url(suffix: string): string {
-    return `${this.baseUrl}/@${this.projectSlug}/gate/${suffix}`;
+  /** The origin credentials go to: the regional host when the base URL is a region-free org host, else the base URL. */
+  private resolveOrigin(): Promise<string> {
+    if (this.origin === null) {
+      const p = resolveRegionalOrigin(this.baseUrl).then((r) => {
+        if (!r.cacheable) this.origin = null;
+        return r.origin;
+      });
+      this.origin = p;
+    }
+    return this.origin;
+  }
+
+  private async url(suffix: string): Promise<string> {
+    return `${await this.resolveOrigin()}/@${this.projectSlug}/gate/${suffix}`;
   }
 
   async post<T>(path: string, body: Record<string, unknown>): Promise<T> {
     let response: Response;
     try {
-      response = await fetch(this.url(path), {
+      response = await fetch(await this.url(path), {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           Accept: "application/json",
-          "User-Agent": "k9o-react-native-sdk/0.3.0",
+          "User-Agent": "k9o-react-native-sdk",
         },
         body: JSON.stringify(body),
       });

package/src/GateClient.ts

@@ -1,13 +1,14 @@
 import { GateError } from "./GateError";
-import { AuthResult } from "./Models";
+import { AuthResult, RefreshResult } from "./Models";
 import { GateAuthClient } from "./GateAuthClient";
 import { KeychainTokenStore, TokenStore } from "./KeychainTokenStore";
 
 /**
- * Kilimanjaro Gate IAK React Native SDK — v0.3.0
+ * Kilimanjaro Gate React Native SDK
  *
  * `GateClient` is the primary entry point. Initialise once per project
- * and call `signIn`, `refreshToken`, or `signOut`.
+ * and call `signIn`, `refreshToken`, or `signOut`. `orgBaseUrl` is the org's gateway host; a region-free host
+ * (`<org>.api.<apex>`) is resolved once to its regional host before credentials are sent.
  *
  * Refresh tokens are automatically persisted via `tokenStore` (defaults
  * to `KeychainTokenStore` backed by `react-native-keychain`).
@@ -58,28 +59,17 @@ export class GateClient {
   }
 
   /**
-   * Rotate the access token using the stored (or supplied) refresh token.
+   * Get a new access token using the stored (or supplied) refresh token.
    *
-   * If `refreshToken` is omitted, loads the token from the store.
-   * Updates the store with the new refresh token on success.
-   *
-   * `projectHint` is optional; omit for most configurations.
+   * If `refreshToken` is omitted, loads the token from the store. The gateway answers a new `accessToken` and its
+   * `expiresAt` only; the refresh token stays valid, so the store is left as it is.
    *
    * Mirrors: `POST /@<projectSlug>/gate/refresh`
    */
-  async refreshToken(input?: {
-    refreshToken?: string;
-    projectHint?: string;
-  }): Promise<AuthResult> {
+  async refreshToken(input?: { refreshToken?: string }): Promise<RefreshResult> {
     const token = input?.refreshToken ?? (await this.tokenStore.load());
     if (!token) throw GateError.unauthenticated();
-
-    const body: Record<string, unknown> = { refreshToken: token };
-    if (input?.projectHint) body["projectHint"] = input.projectHint;
-
-    const result = await this.client.post<AuthResult>("refresh", body);
-    await this.tokenStore.save(result.session.refreshToken);
-    return result;
+    return this.client.post<RefreshResult>("refresh", { refreshToken: token });
   }
 
   /**
@@ -93,7 +83,7 @@ export class GateClient {
   async signOut(input?: { refreshToken?: string }): Promise<void> {
     const token = input?.refreshToken ?? (await this.tokenStore.load());
     if (!token) return;
-    await this.client.post<Record<string, never>>("signout", { refreshToken: token });
+    await this.client.post<{ revoked: boolean }>("signout", { refreshToken: token });
     await this.tokenStore.delete();
   }
 }

package/src/GateError.ts

@@ -67,10 +67,9 @@ export class GateError extends Error {
 
 // MARK: - Wire error parsing
 
-// The gateway emits a KError at the ROOT of the error body:
-// `{ code, message, context?, recommendation? }` — NOT wrapped in `{ error: … }`.
-// Codes are platform-namespaced (`K9O_*`), so the
-// prefix is stripped before matching the SDK's typed enum.
+// The gateway emits a KError at the ROOT of the error body: `{ code, message, context?, recommendation? }`, not
+// wrapped in `{ error: … }`. Codes are platform-namespaced (`K9O_*`), so the prefix is stripped before matching
+// the SDK's typed enum.
 interface WireKError {
   code?: string;
   message?: string;

package/src/Models.ts

@@ -1,6 +1,6 @@
 /**
  * Core model types for @k9o/gate-react-native.
- * Mirror the @k9o/gate TypeScript types verbatim for cross-SDK ergonomic parity.
+ * Mirror the @k9o/gate TypeScript types.
  */
 
 /** Project-level end-user identity. IDs carry the `eu_` prefix. */
@@ -15,7 +15,7 @@ export interface EndUser {
   groups: readonly string[];
 }
 
-/** Session tokens returned by sign-in, sign-up, or refresh flows. */
+/** Session tokens returned by sign-in. */
 export interface Session {
   accessToken: string;
   refreshToken: string;
@@ -23,13 +23,20 @@ export interface Session {
   expiresAt: string;
 }
 
-/** Returned by signIn and refreshToken. */
+/** Returned by signIn. */
 export interface AuthResult {
   user: EndUser;
   session: Session;
 }
 
-/** Standard response envelope. */
+/** Returned by refreshToken: a new access token only. The refresh token in hand stays valid. */
+export interface RefreshResult {
+  accessToken: string;
+  /** ISO 8601 instant the new access token expires. */
+  expiresAt: string;
+}
+
+/** The gateway's response envelope. */
 interface Envelope<T> {
   data: T;
   meta?: Record<string, unknown>;
@@ -52,9 +59,7 @@ export function parseEnvelope<T>(body: string): T {
 // MARK: - Lightweight JWT access-token decoder
 
 /**
- * Lightweight access-token decoder. Decodes the JWT payload without
- * signature verification. Exposes `ext.<namespace>.<name>` custom-claim
- * flatten from.
+ * Lightweight access-token decoder. Decodes the JWT payload without signature verification.
  */
 export class AccessToken {
   readonly subject: string | undefined;
@@ -72,16 +77,19 @@ export class AccessToken {
   }
 
   /**
-   * Custom claims namespaced under `ext.<namespace>` per.
-   * `customClaims['partners']?.['partner_role']` → "extension_org_admin"
+   * Custom claims, grouped by namespace. The token carries each one as a FLAT key `ext.<namespace>.<name>`, so
+   * `ext.partners.partner_role = "extension_org_admin"` reads as
+   * `customClaims["partners"]?.["partner_role"]` and gives `"extension_org_admin"`.
    */
   get customClaims(): Record<string, Record<string, unknown>> {
     const result: Record<string, Record<string, unknown>> = {};
     for (const [key, val] of Object.entries(this.allClaims)) {
-      if (key.startsWith("ext.") && val !== null && typeof val === "object") {
-        const ns = key.slice("ext.".length);
-        result[ns] = val as Record<string, unknown>;
-      }
+      if (!key.startsWith("ext.")) continue;
+      const rest = key.slice("ext.".length);
+      const dot = rest.indexOf(".");
+      if (dot <= 0 || dot === rest.length - 1) continue;
+      const ns = rest.slice(0, dot);
+      (result[ns] ??= {})[rest.slice(dot + 1)] = val;
     }
     return result;
   }

package/src/index.ts

@@ -1,4 +1,5 @@
 export { GateClient } from "./GateClient";
 export { GateError, type GateErrorCode } from "./GateError";
 export { KeychainTokenStore, type TokenStore } from "./KeychainTokenStore";
-export { AccessToken, type AuthResult, type Session, type EndUser } from "./Models";
+export { AccessToken, type AuthResult, type RefreshResult, type Session, type EndUser } from "./Models";
+export { parseApiHost, regionalOriginFromLocation, type ApiHost } from "./region";

package/src/region.ts

@@ -0,0 +1,98 @@
+/**
+ * Regional host resolution for React Native.
+ *
+ * A region-free org host `<org>.api.<rest>` (or `<org>.api-staging.<rest>`) refuses a request that carries a body or an
+ * `Authorization` header, so credentials must go to the regional host `<org>.api-<rgn>.<rest>`. The client learns the
+ * region with ONE unauthenticated `HEAD` to the configured host and caches the regional origin.
+ *
+ * Nothing here knows an apex: the host comes from the configured base URL, so a public-cloud, internal-apex,
+ * air-gapped or localhost deployment all work. Only a host shaped `<org>.api.<rest>` is probed; any other base URL is
+ * used exactly as given. The regional origin is trusted only if it is `https`, has no userinfo or port, and is exactly
+ * the same org, gateway family and apex with a region code. Anything else is ignored, so a hostile redirect can never
+ * receive a credential.
+ *
+ * React Native's `fetch` follows redirects itself and does not honour `redirect: "manual"`, so the probe reads either the
+ * `308` `Location` (where the runtime exposes it) or the final `response.url` after the redirect was followed.
+ *
+ * URLs are read with a small parser rather than the `URL` class, which React Native only partly implements.
+ */
+
+export type ApiHost = {
+  /** First label of an org host; null for a platform host (`api.<apex>`). */
+  orgSlug: string | null;
+  family: "api" | "api-staging";
+  /** 4-character region code when the host is regional (`api-de01`), else null. */
+  region: string | null;
+  /** Everything after the gateway label. */
+  apex: string;
+};
+
+const API_LABEL = /^(api|api-staging)(?:-([a-z]{2}\d{2}))?$/;
+const SLUG_RE = /^[a-z][a-z0-9-]{1,62}$/;
+
+/** Read the org slug and region out of a gateway host without knowing its apex; null for any other shape. */
+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(".") };
+  };
+  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));
+  }
+  if (labels.length >= 2 && API_LABEL.test(labels[0]!)) return mk(labels[0]!, null, labels.slice(1));
+  return null;
+}
+
+type Origin = { protocol: string; userinfo: boolean; hostname: string; port: string };
+
+/** Parse an absolute http(s) URL's origin parts; null when it is not one. */
+function parseOrigin(url: string): Origin | null {
+  const m = /^(https?):\/\/([^/?#]*)/i.exec(url);
+  if (m === null) return null;
+  let authority = m[2]!;
+  const at = authority.lastIndexOf("@");
+  const userinfo = at >= 0;
+  if (userinfo) authority = authority.slice(at + 1);
+  if (authority.startsWith("[")) return null; // IPv6 literal: not a gateway host
+  const colon = authority.indexOf(":");
+  const hostname = (colon >= 0 ? authority.slice(0, colon) : authority).toLowerCase();
+  const port = colon >= 0 ? authority.slice(colon + 1) : "";
+  if (hostname.length === 0) return null;
+  return { protocol: m[1]!.toLowerCase() + ":", userinfo, hostname, port };
+}
+
+/** The regional origin a URL may name for `host`, or null if it is not exactly that. Pure. */
+export function regionalOriginFromLocation(host: string, location: string): string | null {
+  const from = parseApiHost(host);
+  if (from === null || from.orgSlug === null || from.region !== null) return null;
+  const u = parseOrigin(location);
+  if (u === null || u.protocol !== "https:" || u.userinfo || u.port !== "") return null;
+  const to = parseApiHost(u.hostname);
+  if (to === null || to.region === null) return null;
+  if (to.orgSlug !== from.orgSlug || to.family !== from.family || to.apex !== from.apex) return null;
+  return `https://${u.hostname}`;
+}
+
+/** The origin requests go to: the regional origin when the configured one is region-free and redirects, else as given. */
+export async function resolveRegionalOrigin(
+  baseUrl: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ origin: string; cacheable: boolean }> {
+  const configured = baseUrl.replace(/\/+$/, "");
+  const parsed = parseOrigin(configured);
+  if (parsed === null) return { origin: configured, cacheable: true };
+  const host = parseApiHost(parsed.hostname);
+  if (host === null || host.orgSlug === null || host.region !== null) return { origin: configured, cacheable: true };
+  try {
+    const res = await fetchImpl(`${configured}/`, { method: "HEAD", redirect: "manual", headers: { Accept: "*/*" } });
+    const location = res.status === 308 ? res.headers?.get?.("location") ?? null : null;
+    const named = location ?? (typeof res.url === "string" && res.url.length > 0 ? res.url : null);
+    const origin = named === null ? null : regionalOriginFromLocation(parsed.hostname, named);
+    return { origin: origin ?? configured, cacheable: true };
+  } catch {
+    return { origin: configured, cacheable: false };
+  }
+}