@k9o/gate 0.0.0-stage → 1.0.0

package/src/jwt.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 per ch06 §3.2. But the same primitives are
+ * portable: Native customers running their own services downstream of
+ * the gateway can verify Gate-issued JWTs identically.
+ */
+
+import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
+import type { GateJwtClaims, VerifyJwtFailure, VerifyJwtResult } from "./types.ts";
+import { GateError } from "./errors.ts";
+
+/**
+ * Configuration for `verifyJwt`. The verifier can resolve signing keys
+ * via either a remote JWKS URL (the typical Gate deployment shape) or
+ * an inline key set (for tests + air-gapped deployments).
+ */
+export type VerifyJwtOptions = {
+  token: string;
+  /**
+   * JWKS endpoint URL — the gateway exposes `/@<projectSlug>/gate/.well-known/jwks.json`
+   * by convention. Either `jwksUrl` or `jwks` must be set; not both.
+   */
+  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`.
+   */
+  jwks?: { keys: ReadonlyArray<Record<string, unknown>> };
+  /** Expected issuer (`iss` claim). Strict comparison. */
+  expectedIssuer?: string;
+  /** Expected audience (`aud` claim). Accepts either string or array per RFC 7519. */
+  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).
+   */
+  allowedAlgorithms?: ReadonlyArray<string>;
+  /**
+   * Clock-skew tolerance in seconds. Defaults to 30. Applies to both
+   * `exp` and `nbf` checks.
+   */
+  clockToleranceSeconds?: number;
+};
+
+const DEFAULT_ALLOWED_ALGORITHMS = ["RS256", "ES256"] as const;
+const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+
+/**
+ * Verify a Gate-issued JWT. Returns a typed result; does NOT throw on
+ * verification failure (a `valid: false` result carries the reason).
+ *
+ * Throws `GateError` only when:
+ *   - `jwksUrl` and `jwks` are both unset or both set
+ *   - the JWKS fetch fails for transport reasons (UPSTREAM_UNAVAILABLE)
+ */
+export async function verifyJwt(opts: VerifyJwtOptions): Promise<VerifyJwtResult> {
+  if (opts.jwksUrl !== undefined && opts.jwks !== undefined) {
+    throw new GateError({
+      code: "INVALID_FIELD_VALUE",
+      message: "verifyJwt: pass either jwksUrl OR jwks, not both",
+      context: {},
+      recommendation: null,
+    });
+  }
+  if (opts.jwksUrl === undefined && opts.jwks === undefined) {
+    throw new GateError({
+      code: "INVALID_FIELD_VALUE",
+      message: "verifyJwt: must pass exactly one of {jwksUrl, jwks}",
+      context: {},
+      recommendation: null,
+    });
+  }
+
+  const allowedAlgorithms = opts.allowedAlgorithms ?? DEFAULT_ALLOWED_ALGORITHMS;
+  const clockTolerance = opts.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
+
+  let keyResolver: Parameters<typeof jwtVerify>[1];
+  if (opts.jwksUrl !== undefined) {
+    keyResolver = createRemoteJWKSet(new URL(opts.jwksUrl));
+  } else {
+    // Inline JWKS — implement the resolver inline since `jose`'s
+    // `createLocalJWKSet` import path varies across versions.
+    keyResolver = makeLocalJwksResolver(opts.jwks!);
+  }
+
+  try {
+    const result = await jwtVerify(opts.token, keyResolver, {
+      ...(opts.expectedIssuer !== undefined ? { issuer: opts.expectedIssuer } : {}),
+      ...(opts.expectedAudience !== undefined ? { audience: opts.expectedAudience } : {}),
+      algorithms: allowedAlgorithms as string[],
+      clockTolerance,
+    });
+    return { valid: true, claims: result.payload as GateJwtClaims };
+  } catch (e) {
+    return { valid: false, reason: classifyJoseFailure(e) };
+  }
+}
+
+/**
+ * Extract claims from a JWT WITHOUT verifying the signature. Used by
+ * SDK consumers that want to read claim data in client code where
+ * signature verification has already happened at a trusted hop (e.g.,
+ * a reverse proxy). Caller is responsible for confirming the upstream
+ * trust path before consuming these claims for security decisions.
+ *
+ * Throws `GateError` on malformed input.
+ */
+export function extractClaims(token: string): GateJwtClaims {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    throw new GateError({
+      code: "INVALID_FIELD_VALUE",
+      message: `Malformed JWT: expected 3 dot-separated parts, got ${parts.length}`,
+      context: {},
+      recommendation: null,
+    });
+  }
+  try {
+    const payloadJson = base64UrlDecode(parts[1]!);
+    return JSON.parse(payloadJson) as GateJwtClaims;
+  } catch (e) {
+    throw new GateError({
+      code: "INVALID_FIELD_VALUE",
+      message: `Malformed JWT payload: ${e instanceof Error ? e.message : String(e)}`,
+      context: {},
+      recommendation: null,
+    });
+  }
+}
+
+/**
+ * Assert that the given claim set contains all of the required scopes.
+ * Throws `GateError` with `code: "RBAC_DENY"` if any scope is missing.
+ * Returns nothing on success — caller uses the throw-or-pass shape.
+ */
+export function requireScope(
+  claims: GateJwtClaims,
+  requiredScopes: ReadonlyArray<string>,
+): void {
+  const present = new Set(claims.scopes ?? []);
+  const missing = requiredScopes.filter((s) => !present.has(s));
+  if (missing.length > 0) {
+    throw new GateError({
+      code: "RBAC_DENY",
+      message: `Required scopes missing: ${missing.join(", ")}`,
+      context: { missingScopes: missing, presentScopes: Array.from(present) },
+      recommendation: null,
+    });
+  }
+}
+
+// ----------------------------------------------------------------------
+// Internals
+// ----------------------------------------------------------------------
+
+function classifyJoseFailure(e: unknown): VerifyJwtFailure {
+  // Map `jose`'s typed errors to our closed reason set per `VerifyJwtFailure`.
+  if (e instanceof joseErrors.JWSSignatureVerificationFailed) return "INVALID_SIGNATURE";
+  if (e instanceof joseErrors.JWTExpired) return "EXPIRED";
+  if (e instanceof joseErrors.JWTClaimValidationFailed) {
+    const claim = (e as { claim?: string }).claim;
+    if (claim === "aud") return "AUDIENCE_MISMATCH";
+    if (claim === "iss") return "ISSUER_MISMATCH";
+    if (claim === "nbf") return "NOT_YET_VALID";
+    return "MALFORMED";
+  }
+  if (e instanceof joseErrors.JOSEAlgNotAllowed) return "ALGORITHM_NOT_ALLOWED";
+  // Fallback — `jose` raises other errors (parse failures, KID mismatches,
+  // etc.) that we lump into `MALFORMED` rather than leaking the per-version
+  // taxonomy.
+  return "MALFORMED";
+}
+
+function base64UrlDecode(input: string): string {
+  // Pad to a multiple of 4 + swap urlsafe alphabet -> standard alphabet.
+  const padded = input + "=".repeat((4 - (input.length % 4)) % 4);
+  const standard = padded.replace(/-/g, "+").replace(/_/g, "/");
+  // Bun + Node 18+ + browsers all expose `atob`.
+  const binary = globalThis.atob(standard);
+  // Reassemble bytes back to UTF-8 text.
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder("utf-8").decode(bytes);
+}
+
+/**
+ * Build a key resolver compatible with `jose.jwtVerify` from an inline
+ * JWKS object. `jose` exports `createLocalJWKSet` from its main module
+ * but the import path / type shape can shift across minors; reimplement
+ * the minimal resolver here for stability.
+ */
+function makeLocalJwksResolver(
+  jwks: { keys: ReadonlyArray<Record<string, unknown>> },
+): Parameters<typeof jwtVerify>[1] {
+  // The `jose` resolver signature is `(header, token) => Promise<KeyLike>`
+  // — pull the kid from the header, match against the JWKS, and import.
+  return async (header) => {
+    const { importJWK } = await import("jose");
+    const kid = (header as { kid?: string }).kid;
+    let match: Record<string, unknown> | undefined;
+    if (kid !== undefined) {
+      match = jwks.keys.find((k) => k["kid"] === kid);
+    }
+    if (match === undefined && jwks.keys.length === 1) {
+      // Single-key JWKS — return the only key. Tests typically ship one
+      // key in the inline set and may not bother with `kid`.
+      match = jwks.keys[0];
+    }
+    if (match === undefined) {
+      throw new joseErrors.JWKSNoMatchingKey("No matching key in inline JWKS for kid");
+    }
+    const alg = (header as { alg?: string }).alg ?? (match["alg"] as string | undefined);
+    return importJWK(match as unknown as Parameters<typeof importJWK>[0], alg);
+  };
+}

package/src/magic-link-redirects.ts

@@ -0,0 +1,103 @@
+/**
+ * `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.*`.
+ */
+
+import { getGateConfig, type GateConfig } from "./mode.ts";
+import { requestWith } from "./client.ts";
+import { resolveProjectPathRoot } from "./paths.ts";
+import type { Envelope } from "./types.ts";
+
+/** A single allowlisted magic-link redirect target. */
+export type MagicLinkRedirect = {
+  id: string;
+  redirectUrl: string;
+  isDefault: boolean;
+  createdAt: string;
+};
+
+export 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;
+};
+
+export type RemoveMagicLinkRedirectResult = { removed: true; id: string };
+
+function magicLinkRedirectsPath(config: GateConfig, id?: string): string {
+  const root = `${resolveProjectPathRoot(config)}/gate/magic-link-redirects`;
+  return id !== undefined ? `${root}/${id}` : root;
+}
+
+/** Factory — produces a `magicLinkRedirects` namespace bound to the
+ *  supplied config getter. Used by both the `gate` singleton +
+ *  `createGateClient`. */
+export function makeMagicLinkRedirects(getConfig: () => GateConfig) {
+  return {
+    /** List every allowlisted redirect target for the active project. */
+    async list(): Promise<Envelope<{ redirects: MagicLinkRedirect[] }>> {
+      const config = getConfig();
+      return requestWith<{ redirects: MagicLinkRedirect[] }>(config, {
+        method: "GET",
+        path: magicLinkRedirectsPath(config),
+      });
+    },
+
+    /**
+     * Register a new redirect target. `redirectUrl` must exact-match
+     * what a customer later passes to `requestMagicLink` — the gateway
+     * enforces exact match, never a prefix or wildcard.
+     */
+    async add(input: AddMagicLinkRedirectInput): Promise<Envelope<{ redirect: MagicLinkRedirect }>> {
+      const config = getConfig();
+      return requestWith<{ redirect: MagicLinkRedirect }>(config, {
+        method: "POST",
+        path: magicLinkRedirectsPath(config),
+        body: input,
+      });
+    },
+
+    /** Remove a previously-registered redirect target by its `id`. */
+    async remove(id: string): Promise<Envelope<RemoveMagicLinkRedirectResult>> {
+      const config = getConfig();
+      return requestWith<RemoveMagicLinkRedirectResult>(config, {
+        method: "DELETE",
+        path: magicLinkRedirectsPath(config, id),
+      });
+    },
+  };
+}
+
+/** Singleton bound to the module-level `configureGate()` config. */
+export const magicLinkRedirects = makeMagicLinkRedirects(getGateConfig);
+
+export type MagicLinkRedirectsNamespace = ReturnType<typeof makeMagicLinkRedirects>;

package/src/mode.ts

@@ -0,0 +1,115 @@
+/**
+ * Standalone vs Native mode wiring per ch01 §12.4.
+ *
+ * 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
+ * per ch02; the SDK does not branch behavior at function-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 per ch01 §1)
+ *   - Error taxonomy (identical per ch01 §2)
+ */
+
+/**
+ * Two-mode discriminant. The third candidate "Hybrid" was rejected per
+ * memory `feedback_gate_iak_brand_architecture.md` — modes are
+ * orthogonal deployment shapes, not interleaved.
+ */
+export type GateMode = "standalone" | "native";
+
+/**
+ * Gate SDK configuration. Returned by `getGateConfig()` and consumed
+ * internally by the HTTP client + JWT verifier. Set via `configureGate`
+ * at process boot or per-test in unit tests.
+ */
+export type GateConfig = {
+  mode: GateMode;
+  /** Project slug per v2.5.68 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. */
+  projectSlug: string;
+  /** Gateway base URL — e.g. `https://<orgSlug>.api.k9o.io` per v2.5.68 §5.4. */
+  baseUrl: string;
+  /**
+   * Optional partner-credentialled JWT for Standalone mode — used as the
+   * default Authorization header when no per-call bearer is supplied.
+   * Not required in Native mode; the gateway resolves credentials from
+   * the standard project context per ch02.
+   */
+  partnerToken?: string;
+  /**
+   * Optional fetch override for testing + non-browser environments. The
+   * SDK defaults to global `fetch` (available in Bun + Node 18+ +
+   * browsers) when not set.
+   */
+  fetch?: typeof fetch;
+};
+
+let _config: GateConfig | null = null;
+
+/**
+ * Initialise the SDK. Must be called before any `gate.*` invocation.
+ * Re-calling replaces the prior config wholesale (no per-field merge —
+ * keeps the config-set-at-boot ergonomic clean).
+ */
+export function configureGate(config: GateConfig): void {
+  validateGateConfig(config);
+  _config = { ...config };
+}
+
+/**
+ * Validate a config shape. Exposed for `createGateClient` so per-instance
+ * configs go through identical checks as the singleton.
+ */
+export function validateGateConfig(config: GateConfig): void {
+  if (config.mode !== "standalone" && config.mode !== "native") {
+    throw new TypeError(
+      `Invalid Gate mode "${config.mode as string}"; expected "standalone" or "native"`,
+    );
+  }
+  const hasSlug = typeof config.projectSlug === "string" && config.projectSlug.length > 0;
+  if (!hasSlug) {
+    throw new TypeError(
+      `Gate config missing projectSlug (required, v2.5.68 grammar — project ids are internal-only and never customer-facing)`,
+    );
+  }
+  if (typeof config.baseUrl !== "string" || config.baseUrl.length === 0) {
+    throw new TypeError(`Invalid baseUrl "${config.baseUrl}"; expected non-empty string`);
+  }
+}
+
+/**
+ * Read the active config. Throws when called before `configureGate(...)`.
+ * Tests can call `resetGateConfig()` to clear between cases.
+ */
+export function getGateConfig(): GateConfig {
+  if (_config === null) {
+    throw new Error(
+      "@k9o/gate: SDK is not configured. Call configureGate({ mode, projectSlug, baseUrl }) before invoking gate functions.",
+    );
+  }
+  return _config;
+}
+
+/** Reset the singleton — used by tests + by app-shutdown teardown paths. */
+export function resetGateConfig(): void {
+  _config = null;
+}

package/src/paths.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared path-resolution helper for project-scoped routes.
+ *
+ * v2.5.68 URL grammar: project-scoped resources address
+ * via `/@<projectSlug>/...` against the org subdomain. Slug addressing is
+ * the only customer-facing form — project ids are internal-only and never
+ * appear in customer paths (`feedback_slug_addressing_v2_5_68`); the
+ * retired `/v2/projects/<bareId>/...` form was dropped at pass17
+ * (`feedback_v2_path_is_an_error`).
+ *
+ * Caller is expected to validate that the config carries a `projectSlug`
+ * at construction time (see `validateGateConfig`).
+ */
+
+import type { GateConfig } from "./mode.ts";
+
+/** Return the project-scoped path root for the supplied config, e.g.
+ *  `/@partner-console-staging`. */
+export function resolveProjectPathRoot(config: GateConfig): string {
+  return `/@${config.projectSlug}`;
+}

package/src/region.ts

@@ -0,0 +1,85 @@
+/**
+ * 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). */
+export type RegionConfig = { baseUrl: string; fetch?: typeof globalThis.fetch | undefined };
+
+const REGION_FREE_ORG_HOST = /^([a-z][a-z0-9-]{1,62})\.(api|api-staging)\.k9o\.io$/;
+const REGION_CODE = /^[a-z]{2}\d{2}$/;
+
+const cache = new WeakMap<RegionConfig, Promise<string>>();
+
+/** The regional origin a `Location` may name for `host`, or null if it is not exactly that. Pure. */
+export function regionalOriginFromLocation(host: string, location: string, base: string): string | null {
+  const m = REGION_FREE_ORG_HOST.exec(host);
+  if (m === null) return null;
+  let u: URL;
+  try {
+    u = new URL(location, base);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "https:" || u.username !== "" || u.password !== "" || u.port !== "") return null;
+  const [, org, apex] = m;
+  const want = new RegExp(`^${org}\\.${apex}-([a-z0-9]+)\\.k9o\\.io$`);
+  const r = want.exec(u.hostname);
+  if (r === null || !REGION_CODE.test(r[1]!)) return null;
+  return `https://${u.hostname}`;
+}
+
+async function probe(config: RegionConfig): Promise<{ origin: string; cacheable: boolean }> {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const configured = config.baseUrl;
+  if (typeof fetchImpl !== "function") return { origin: configured, cacheable: false };
+  let host: string;
+  try {
+    host = new URL(configured).hostname;
+  } catch {
+    return { origin: configured, cacheable: true };
+  }
+  if (!REGION_FREE_ORG_HOST.test(host)) return { origin: configured, cacheable: true };
+  try {
+    const res = await fetchImpl(`${configured.replace(/\/+$/, "")}/`, {
+      method: "HEAD",
+      redirect: "manual",
+      headers: { accept: "*/*" },
+    } as Parameters<typeof fetchImpl>[1]);
+    if (res.status === 308) {
+      const loc = res.headers.get("location");
+      const origin = loc === null ? null : regionalOriginFromLocation(host, loc, configured);
+      if (origin !== null) return { origin, cacheable: true };
+    }
+    return { origin: configured, cacheable: true };
+  } catch {
+    return { origin: configured, cacheable: false };
+  }
+}
+
+/** The origin requests for this client go to: the cached regional origin once learned, else the configured baseUrl. */
+export function resolveRegionalOrigin(config: RegionConfig): Promise<string> {
+  const hit = cache.get(config);
+  if (hit !== undefined) return hit;
+  const p = probe(config).then((r) => {
+    if (!r.cacheable) cache.delete(config);
+    return r.origin;
+  });
+  cache.set(config, p);
+  return p;
+}