@k9o/gate 0.0.0-stage → 1.1.0

package/dist/index.js

@@ -0,0 +1,613 @@
+import {
+  extractClaims,
+  requireScope,
+  verifyJwt
+} from "./chunk-YINWOWJC.js";
+import {
+  GateError,
+  gateErrorFromWire
+} from "./chunk-JEV37YEC.js";
+import {
+  configureGate,
+  getGateConfig,
+  resetGateConfig,
+  validateGateConfig
+} from "./chunk-XP6U5QKF.js";
+
+// src/region.ts
+var REGION_FREE_ORG_HOST = /^([a-z][a-z0-9-]{1,62})\.(api|api-staging)\.k9o\.io$/;
+var REGION_CODE = /^[a-z]{2}\d{2}$/;
+var cache = /* @__PURE__ */ new WeakMap();
+function regionalOriginFromLocation(host, location, base) {
+  const m = REGION_FREE_ORG_HOST.exec(host);
+  if (m === null) return null;
+  let u;
+  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) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const configured = config.baseUrl;
+  if (typeof fetchImpl !== "function") return { origin: configured, cacheable: false };
+  let host;
+  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: "*/*" }
+    });
+    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 };
+  }
+}
+function resolveRegionalOrigin(config) {
+  const hit = cache.get(config);
+  if (hit !== void 0) return hit;
+  const p = probe(config).then((r) => {
+    if (!r.cacheable) cache.delete(config);
+    return r.origin;
+  });
+  cache.set(config, p);
+  return p;
+}
+
+// src/client.ts
+async function requestWith(config, init) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new GateError({
+      code: "INTERNAL_ERROR",
+      message: "No fetch implementation available \u2014 configure {fetch} in configureGate() for non-browser, non-Bun, non-Node-18+ environments",
+      context: {},
+      recommendation: null
+    });
+  }
+  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);
+  const headers = {
+    accept: "application/json",
+    "x-gate-mode": config.mode,
+    ...init.headers ?? {}
+  };
+  const bearer = init.bearerToken ?? config.partnerToken;
+  if (typeof bearer === "string" && bearer.length > 0) {
+    headers["authorization"] = `Bearer ${bearer}`;
+  }
+  const requestInit = {
+    method: init.method,
+    headers
+  };
+  if (init.body !== void 0) {
+    headers["content-type"] = "application/json";
+    requestInit["body"] = JSON.stringify(init.body);
+  }
+  let response;
+  try {
+    response = await fetchImpl(url, requestInit);
+  } catch (e) {
+    throw new GateError({
+      code: "UPSTREAM_UNAVAILABLE",
+      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url },
+      recommendation: null
+    });
+  }
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch (e) {
+    throw new GateError({
+      code: "INTERNAL_ERROR",
+      message: `Failed to parse JSON response from ${url}: ${e instanceof Error ? e.message : String(e)}`,
+      context: { url, status: response.status },
+      recommendation: null,
+      status: response.status
+    });
+  }
+  if (response.status >= 200 && response.status < 300) {
+    if (!isEnvelope(parsed)) {
+      throw new GateError({
+        code: "INTERNAL_ERROR",
+        message: `Malformed envelope from ${url}: expected {data, meta}`,
+        context: { url, status: response.status },
+        recommendation: null,
+        status: response.status
+      });
+    }
+    return parsed;
+  }
+  if (isKErrorWire(parsed)) {
+    throw gateErrorFromWire(parsed, response.status);
+  }
+  throw new GateError({
+    code: "INTERNAL_ERROR",
+    message: `Upstream returned ${response.status} with non-KError body`,
+    context: { url, status: response.status, body: parsed },
+    recommendation: null,
+    status: response.status
+  });
+}
+function buildUrl(baseUrl, path, query) {
+  const trimmedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const trimmedPath = path.startsWith("/") ? path : `/${path}`;
+  let url = `${trimmedBase}${trimmedPath}`;
+  if (query !== void 0) {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+      if (v !== void 0) params.set(k, String(v));
+    }
+    const qs = params.toString();
+    if (qs.length > 0) url += `?${qs}`;
+  }
+  return url;
+}
+function isEnvelope(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return "data" in v && "meta" in v && typeof v.meta === "object" && v.meta !== null;
+}
+function isKErrorWire(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.code === "string" && typeof v.message === "string";
+}
+
+// src/paths.ts
+function resolveProjectPathRoot(config) {
+  return `/@${config.projectSlug}`;
+}
+
+// src/idp-providers/identity-providers.ts
+function identityProvidersPath(config) {
+  return `${resolveProjectPathRoot(config)}/identity-providers`;
+}
+function makeIdentityProviders(getConfig) {
+  return {
+    /**
+     * 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
+     * and rejects a mismatch with `K9O_INVALID_FIELD_VALUE`.
+     */
+    async create(input) {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "POST",
+        path: identityProvidersPath(config),
+        body: input
+      });
+    },
+    /**
+     * 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.
+     */
+    async list() {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "GET",
+        path: identityProvidersPath(config)
+      });
+    },
+    /**
+     * 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.
+     */
+    async update(configId, patch) {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "PATCH",
+        path: `${identityProvidersPath(config)}/${encodeURIComponent(configId)}`,
+        body: patch
+      });
+    },
+    async testProvider(configId) {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "POST",
+        path: `${identityProvidersPath(config)}/${encodeURIComponent(configId)}/test`
+      });
+    }
+  };
+}
+var identityProviders = makeIdentityProviders(getGateConfig);
+
+// src/magic-link-redirects.ts
+function magicLinkRedirectsPath(config, id) {
+  const root = `${resolveProjectPathRoot(config)}/gate/magic-link-redirects`;
+  return id !== void 0 ? `${root}/${id}` : root;
+}
+function makeMagicLinkRedirects(getConfig) {
+  return {
+    /** List every allowlisted redirect target for the active project. */
+    async list() {
+      const config = getConfig();
+      return requestWith(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) {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "POST",
+        path: magicLinkRedirectsPath(config),
+        body: input
+      });
+    },
+    /** Remove a previously-registered redirect target by its `id`. */
+    async remove(id) {
+      const config = getConfig();
+      return requestWith(config, {
+        method: "DELETE",
+        path: magicLinkRedirectsPath(config, id)
+      });
+    }
+  };
+}
+var magicLinkRedirects = makeMagicLinkRedirects(getGateConfig);
+
+// src/gate.ts
+function gatePath(config, suffix) {
+  return `${resolveProjectPathRoot(config)}/gate/${suffix}`;
+}
+function makeGateNamespace(getConfig) {
+  return {
+    /**
+     * Create a new end-user identity for the configured project. Returns
+     * the new user record + an initial session. Emits a
+     * `data.write.auth.signup` audit event.
+     *
+     * Errors (closed taxonomy):
+     *   - `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
+     */
+    async signUp(input) {
+      return requestWith(getConfig(), {
+        method: "POST",
+        path: gatePath(getConfig(), "signup"),
+        body: input
+      });
+    },
+    /**
+     * 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)
+     */
+    async signIn(input) {
+      return requestWith(getConfig(), {
+        method: "POST",
+        path: gatePath(getConfig(), "signin"),
+        body: input
+      });
+    },
+    /**
+     * 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
+     */
+    async signOut(input = {}) {
+      return requestWith(getConfig(), {
+        method: "POST",
+        path: gatePath(getConfig(), "signout"),
+        body: input
+      });
+    },
+    /**
+     * 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
+     */
+    async whoami() {
+      return requestWith(getConfig(), {
+        method: "GET",
+        path: gatePath(getConfig(), "whoami")
+      });
+    },
+    /**
+     * 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
+     */
+    async refreshToken(input) {
+      return requestWith(getConfig(), {
+        method: "POST",
+        path: gatePath(getConfig(), "refresh"),
+        body: input
+      });
+    },
+    /**
+     * 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).
+     */
+    async verifySession() {
+      return requestWith(getConfig(), {
+        method: "GET",
+        path: gatePath(getConfig(), "verify")
+      });
+    },
+    /**
+     * 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.
+     */
+    async hosted() {
+      return requestWith(getConfig(), {
+        method: "GET",
+        path: gatePath(getConfig(), "hosted"),
+        bearerToken: ""
+      });
+    },
+    /**
+     * 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.
+     */
+    async signInWithProvider(input) {
+      const env = await requestWith(getConfig(), {
+        method: "POST",
+        path: `${resolveProjectPathRoot(getConfig())}/gate/idp/${input.provider}/authorize`,
+        body: { redirectUri: input.redirectUri }
+      });
+      const w = globalThis.window;
+      if (w !== void 0) {
+        w.location.assign(env.data.authorizationUrl);
+      } else {
+        throw new Error(
+          "signInWithProvider requires a browser environment (window.location); for server-side initiation, fetch the authorize endpoint directly."
+        );
+      }
+    },
+    /**
+     * 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) {
+      const raw = hash.startsWith("#") ? hash.slice(1) : hash;
+      const params = new URLSearchParams(raw);
+      const error = params.get("error");
+      if (error !== null) {
+        return {
+          ok: false,
+          error,
+          errorDescription: params.get("error_description") ?? error
+        };
+      }
+      const accessToken = params.get("access_token");
+      const refreshToken = params.get("refresh_token");
+      const expiresAt = params.get("expires_at");
+      if (accessToken === null || refreshToken === null || expiresAt === null) {
+        return {
+          ok: false,
+          error: "malformed_callback",
+          errorDescription: "Callback URL fragment missing one or more required fields (access_token, refresh_token, expires_at)."
+        };
+      }
+      return {
+        ok: true,
+        accessToken,
+        refreshToken,
+        expiresAt,
+        tokenType: params.get("token_type") ?? "Bearer"
+      };
+    },
+    /**
+     * Passwordless sub-namespace — 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 SDK paths match the shipped gateway routes.)
+     */
+    passwordless: {
+      /**
+       * Request a one-time passcode delivered to the supplied email.
+       * The OTP is short-lived (typically 5 min) and
+       * single-use; redemption via `verifyOtp` mints a session.
+       */
+      async requestOtp(input) {
+        return requestWith(getConfig(), {
+          method: "POST",
+          path: gatePath(getConfig(), "otp/request"),
+          body: input
+        });
+      },
+      /**
+       * 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)
+       */
+      async verifyOtp(input) {
+        return requestWith(getConfig(), {
+          method: "POST",
+          path: gatePath(getConfig(), "otp/verify"),
+          body: input
+        });
+      },
+      /**
+       * Request a magic-link emailed to the supplied address. The link
+       * carries an opaque short-lived token (typically 15 min
+       *); clicking the link lands at the customer's chosen
+       * redirect URL with the token in the query string, which the
+       * customer's frontend then exchanges via `verifyMagicLink`.
+       */
+      async requestMagicLink(input) {
+        return requestWith(getConfig(), {
+          method: "POST",
+          path: gatePath(getConfig(), "magic-link/send"),
+          body: input
+        });
+      },
+      /**
+       * 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)
+       */
+      async verifyMagicLink(input) {
+        return requestWith(getConfig(), {
+          method: "POST",
+          path: gatePath(getConfig(), "magic-link/redeem"),
+          body: input
+        });
+      },
+      /**
+       * 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) {
+        const raw = search.startsWith("?") ? search.slice(1) : search;
+        const params = new URLSearchParams(raw);
+        const error = params.get("error");
+        if (error !== null) {
+          return { ok: false, error };
+        }
+        const token = params.get("token");
+        if (token === null || token.length === 0) {
+          return { ok: false, error: "missing_token" };
+        }
+        return { ok: true, token };
+      }
+    },
+    /**
+     * Project-scoped end-user IdP provider-config management.
+     * PROJECT_ADMIN+ required; end-user JWTs rejected at the route. Only
+     * `create()` is bound — the REST create the Gate Studio
+     * `FederationPresetsPanel` routes to when it drops the `gate_flows`
+     * `__addFromPreset` sentinel. Gate-admin surface.
+     */
+    identityProviders: makeIdentityProviders(getConfig),
+    /**
+     * 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: makeMagicLinkRedirects(getConfig)
+  };
+}
+var gate = makeGateNamespace(getGateConfig);
+
+// src/client-factory.ts
+function createGateClient(config) {
+  validateGateConfig(config);
+  const frozen = { ...config };
+  return makeGateNamespace(() => frozen);
+}
+export {
+  GateError,
+  configureGate,
+  createGateClient,
+  extractClaims,
+  gate,
+  gateErrorFromWire,
+  getGateConfig,
+  regionalOriginFromLocation,
+  requireScope,
+  resetGateConfig,
+  resolveRegionalOrigin,
+  verifyJwt
+};
+//# sourceMappingURL=index.js.map