@k9o/gate 0.0.0-stage → 1.1.0

package/src/gate.ts

@@ -0,0 +1,384 @@
+/**
+ * Marquee `gate.*` namespace.
+ *
+ * surfaces (canonical slug routing — `<orgSlug>.api.k9o.io/@<projectSlug>/...`):
+ *   - `gate.signUp` — POST /@<projectSlug>/gate/signup
+ *   - `gate.signIn` — POST /@<projectSlug>/gate/signin
+ *   - `gate.signOut` — POST /@<projectSlug>/gate/signout
+ *   - `gate.whoami` — GET  /@<projectSlug>/gate/whoami
+ *   - `gate.refreshToken` — POST /@<projectSlug>/gate/refresh
+ *   - `gate.verifySession` — GET  /@<projectSlug>/gate/verify
+ *   - `gate.hosted` — GET  /@<projectSlug>/gate/hosted (unauthenticated; `{ signInUrl, rpId }`)
+ *
+ * Sub-namespaces (passwordless / passkeys / social / mfa / password /
+ * users / email / sms / federation / admin) deferred to subsequent
+ * cycles per the README catalogue.
+ *
+ * Wire shape: every function returns the standard envelope
+ * `{ data, meta }` and throws a `GateError` on non-2xx
+ * gateway responses. Native vs Standalone mode does not affect SDK
+ * ergonomics; the mode header is set internally by the
+ * client + does not surface in the function-call ergonomics.
+ *
+ * Endpoint paths are reconciled to the LIVE gateway routes (verified
+ * against staging): signup/signin/signout/whoami/refresh/verify under
+ * `/@<projectSlug>/gate/*`, OTP under `/gate/otp/{request,verify}`,
+ * Magic Link under `/gate/magic-link/{send,redeem}`, IdP under
+ * `/gate/idp/:provider/{authorize,callback}`.
+ */
+
+import { getGateConfig, type GateConfig } from "./mode.ts";
+import { requestWith } from "./client.ts";
+import { resolveProjectPathRoot } from "./paths.ts";
+import { makeIdentityProviders } from "./idp-providers/identity-providers.ts";
+import { makeMagicLinkRedirects } from "./magic-link-redirects.ts";
+import type {
+  AuthResult,
+  Envelope,
+  HostedGateInfo,
+  MagicLinkCallbackResult,
+  RefreshTokenInput,
+  RequestMagicLinkInput,
+  RequestOtpInput,
+  SignInCallbackResult,
+  SignInInput,
+  SignOutInput,
+  SignUpInput,
+  VerifyMagicLinkInput,
+  VerifyOtpInput,
+  VerifySessionResult,
+  WhoamiResult,
+} from "./types.ts";
+
+function gatePath(config: GateConfig, suffix: string): string {
+  return `${resolveProjectPathRoot(config)}/gate/${suffix}`;
+}
+
+/** 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). */
+export function makeGateNamespace(getConfig: () => GateConfig) {
+  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: SignUpInput): Promise<Envelope<AuthResult>> {
+    return requestWith<AuthResult>(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: SignInInput): Promise<Envelope<AuthResult>> {
+    return requestWith<AuthResult>(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: SignOutInput = {}): Promise<Envelope<{ revoked: boolean }>> {
+    return requestWith<{ revoked: boolean }>(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(): Promise<Envelope<WhoamiResult>> {
+    return requestWith<WhoamiResult>(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: RefreshTokenInput): Promise<Envelope<{ session: AuthResult["session"] }>> {
+    return requestWith<{ session: AuthResult["session"] }>(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(): Promise<Envelope<VerifySessionResult>> {
+    return requestWith<VerifySessionResult>(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(): Promise<Envelope<HostedGateInfo>> {
+    return requestWith<HostedGateInfo>(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: {
+    provider: "google" | "github" | "microsoft" | "oidc" | "saml";
+    redirectUri: string;
+  }): Promise<void> {
+    const env = await requestWith<{ authorizationUrl: string }>(getConfig(), {
+      method: "POST",
+      path: `${resolveProjectPathRoot(getConfig())}/gate/idp/${input.provider}/authorize`,
+      body: { redirectUri: input.redirectUri },
+    });
+    const w = (globalThis as { window?: { location: { assign: (url: string) => void } } }).window;
+    if (w !== undefined) {
+      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: string): SignInCallbackResult {
+    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: RequestOtpInput): Promise<Envelope<{ requested: boolean }>> {
+      return requestWith<{ requested: boolean }>(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: VerifyOtpInput): Promise<Envelope<AuthResult>> {
+      return requestWith<AuthResult>(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: RequestMagicLinkInput,
+    ): Promise<Envelope<{ requested: boolean }>> {
+      return requestWith<{ requested: boolean }>(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: VerifyMagicLinkInput): Promise<Envelope<AuthResult>> {
+      return requestWith<AuthResult>(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: string): MagicLinkCallbackResult {
+      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),
+  };
+}
+
+/** Singleton bound to the module-level `configureGate()` config.
+ *  Per-instance clients: `createGateClient(config)`. */
+export const gate = makeGateNamespace(getGateConfig);
+
+/** Convenience type alias mirroring the `gate` runtime export.
+ *  Identical shape as the per-instance `GateClient` returned from
+ *  `createGateClient`. */
+export type GateNamespace = ReturnType<typeof makeGateNamespace>;

package/src/idp-providers/identity-providers.ts

@@ -0,0 +1,244 @@
+/**
+ * `gate.identityProviders` namespace — project-scoped end-user IdP
+ * provider-config management.
+ *
+ * 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.
+ */
+
+import { getGateConfig, type GateConfig } from "../mode.ts";
+import { requestWith } from "../client.ts";
+import { resolveProjectPathRoot } from "../paths.ts";
+import type { Envelope } from "../types.ts";
+
+/** Closed end-user-class provider enum — 11 values since v221 (the project-plane substrate
+ *  `_sys.end_user_idp_provider_configs`); the org plane carries the same 11 since v222/v223. */
+export 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).
+ */
+export type FederationTestProviderResult = {
+  ok: boolean;
+  reason?:
+    | "endpoint_unreachable"
+    | "endpoint_forbidden"
+    | "metadata_invalid"
+    | "secret_not_provisioned"
+    | "kind_unsupported";
+};
+
+/** Per 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. */
+export 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,):
+ * settings plus the scheduler's last-run status; the service-account key itself is never returned.
+ */
+export 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). */
+export 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.
+ */
+export 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,): re-supply the
+ * secret whenever the metadata URL changes.
+ */
+export 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;
+
+function identityProvidersPath(config: GateConfig): string {
+  return `${resolveProjectPathRoot(config)}/identity-providers`;
+}
+
+/** Factory — produces an `identityProviders` namespace bound to the supplied
+ *  config getter. Used by both the `gate` singleton + `createGateClient`. */
+export function makeIdentityProviders(getConfig: () => GateConfig) {
+  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: CreateIdpInput): Promise<Envelope<IdpConfig>> {
+      const config = getConfig();
+      return requestWith<IdpConfig>(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(): Promise<Envelope<IdpConfig[]>> {
+      const config = getConfig();
+      return requestWith<IdpConfig[]>(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: string, patch: PatchIdpInput): Promise<Envelope<IdpConfig>> {
+      const config = getConfig();
+      return requestWith<IdpConfig>(config, {
+        method: "PATCH",
+        path: `${identityProvidersPath(config)}/${encodeURIComponent(configId)}`,
+        body: patch,
+      });
+    },
+
+    async testProvider(configId: string): Promise<Envelope<FederationTestProviderResult>> {
+      const config = getConfig();
+      return requestWith<FederationTestProviderResult>(config, {
+        method: "POST",
+        path: `${identityProvidersPath(config)}/${encodeURIComponent(configId)}/test`,
+      });
+    },
+  };
+}
+
+/** Singleton bound to the module-level `configureGate()` config. */
+export const identityProviders = makeIdentityProviders(getGateConfig);
+
+export type IdentityProvidersNamespace = ReturnType<typeof makeIdentityProviders>;

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * `@k9o/gate` — Gate (Identity-Aware Kernel) SDK entry point.
+ *
+ * Re-exports the canonical surface +:
+ *   - `gate` — marquee namespace + sub-namespaces
+ *   - `configureGate` / `getGateConfig` / `resetGateConfig` — mode + config plumbing
+ *   - `verifyJwt` / `extractClaims` / `requireScope` — standalone JWT primitives
+ *   - `GateError` + `GateErrorCode` — KError-compatible error surface
+ *   - All public types via `* from "./types.ts"`
+ */
+
+export { gate, type GateNamespace } from "./gate.ts";
+export { createGateClient, type GateClient } from "./client-factory.ts";
+export { resolveRegionalOrigin, regionalOriginFromLocation, type RegionConfig } from "./region.ts";
+export {
+  configureGate,
+  getGateConfig,
+  resetGateConfig,
+  type GateConfig,
+  type GateMode,
+} from "./mode.ts";
+export { verifyJwt, extractClaims, requireScope, type VerifyJwtOptions } from "./jwt.ts";
+export {
+  GateError,
+  type GateErrorCode,
+  type KErrorWire,
+  gateErrorFromWire,
+} from "./errors.ts";
+export type {
+  Envelope,
+  EndUser,
+  Session,
+  AuthResult,
+  WhoamiResult,
+  VerifySessionResult,
+  HostedGateInfo,
+  SignUpInput,
+  SignInInput,
+  SignOutInput,
+  RefreshTokenInput,
+  OtpPurpose,
+  RequestOtpInput,
+  VerifyOtpInput,
+  RequestMagicLinkInput,
+  VerifyMagicLinkInput,
+  SignInCallbackResult,
+  MagicLinkCallbackResult,
+  GateJwtClaims,
+  VerifyJwtResult,
+  VerifyJwtFailure,
+} from "./types.ts";
+// GS-F6 — project-scoped end-user IdP provider-config management types
+// (gate.identityProviders.create()).
+export type {
+  IdpProviderKind,
+  IdpTierGating,
+  IdpConfig,
+  CreateIdpInput,
+  PatchIdpInput,
+  DirectorySyncInput,
+  IdentityProvidersNamespace,
+} from "./idp-providers/identity-providers.ts";