@zitadel/api 0.0.0

package/src/generated/model/verifyChallengeProof200.ts

@@ -0,0 +1,70 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+import type { VerifyChallengeProof200ChallengesItem } from "./verifyChallengeProof200ChallengesItem";
+import type { VerifyChallengeProof200CompletedFactorsItem } from "./verifyChallengeProof200CompletedFactorsItem";
+import type { VerifyChallengeProof200RequiredFactorsItem } from "./verifyChallengeProof200RequiredFactorsItem";
+import type { VerifyChallengeProof200State } from "./verifyChallengeProof200State";
+
+/**
+ * The current state of an authentication attempt.
+
+An attempt is an ephemeral state machine (15-minute TTL) that drives a single authentication round.
+It accepts factor challenges, verifies proofs, and completes into a handoff token.
+Clients drive the attempt by:
+1. Issuing challenges: POST /auth_attempts/{attempt_id}/challenges
+2. Verifying proofs: POST /auth_attempts/{attempt_id}/challenges/{challenge_id}/verify
+3. Completing: POST /auth_attempts/{attempt_id}/handoff
+
+ */
+export type VerifyChallengeProof200 = {
+  /**
+   * Unique identifier for this authentication attempt
+   * @pattern ^[a-zA-Z0-9_-]+$
+   */
+  attempt_id: string;
+  /** @pattern ^[a-zA-Z0-9_-]+$ */
+  project_id: string;
+  /** Overall state of the authentication attempt:
+  - `in_progress`: factors are still being collected; continue issuing challenges.
+  - `completed`: all required factors have been verified; the attempt is ready for handoff.
+  - `failed`: the attempt has failed (e.g. too many failed proofs) and cannot be continued.
+  - `expired`: the 15-minute TTL has been exceeded.
+   */
+  state: VerifyChallengeProof200State;
+  /** The session being authenticated into. Either newly created or passed in on POST.
+  For step-up (re-auth), this is the existing session_id provided on creation.
+   */
+  session_id?: string | null;
+  /** The user ID, if known at this point in the flow.
+  Null until an identifier challenge has been verified.
+   */
+  user_id?: string | null;
+  /** The authentication factor methods that the project policy requires in order
+  to complete this attempt. Computed by the server from the project's auth policy.
+  Clients should use this to determine which challenges still need to be issued.
+   */
+  required_factors?: VerifyChallengeProof200RequiredFactorsItem[];
+  /** The factors that have been successfully verified in this attempt so far.
+  Each item includes method-specific metadata in the payload field.
+
+  The flow engine uses verified_at timestamps to enforce time-based policies, such as
+  requiring password verification within the last 5 minutes for step-up auth to
+  access sensitive operations.
+
+  A factor appears here once its challenge reaches `verified` state.
+   */
+  completed_factors?: VerifyChallengeProof200CompletedFactorsItem[];
+  /** All challenges issued within this attempt, in creation order.
+  Use this to track the state of each factor challenge (pending, verified, failed, expired).
+   */
+  challenges?: VerifyChallengeProof200ChallengesItem[];
+  /** When this attempt expires (15-minute TTL from creation) */
+  expires_at?: string;
+  /** When this attempt was created */
+  created_at: string;
+};

package/src/generated/model/verifyChallengeProof200ChallengesItem.ts

@@ -0,0 +1,43 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+import type { VerifyChallengeProof200ChallengesItemMethod } from "./verifyChallengeProof200ChallengesItemMethod";
+import type { VerifyChallengeProof200ChallengesItemPayload } from "./verifyChallengeProof200ChallengesItemPayload";
+import type { VerifyChallengeProof200ChallengesItemState } from "./verifyChallengeProof200ChallengesItemState";
+
+/**
+ * A factor challenge issued within an authentication attempt.
+
+A challenge presents a single-factor verification prompt (password entry, TOTP code, passkey assertion, etc.).
+The client verifies the proof by POST /auth_attempts/{attempt_id}/challenges/{challenge_id}/verify.
+
+ */
+export type VerifyChallengeProof200ChallengesItem = {
+  /**
+   * Unique identifier for this challenge
+   * @pattern ^[a-zA-Z0-9_-]+$
+   */
+  challenge_id: string;
+  /** An authentication factor method. */
+  method: VerifyChallengeProof200ChallengesItemMethod;
+  /** Current state of this challenge:
+  - `pending`: awaiting proof submission
+  - `failed`: proof rejected (invalid credential, wrong code, etc.)
+  - `expired`: challenge TTL exceeded without verification
+   */
+  state: VerifyChallengeProof200ChallengesItemState;
+  /** When this challenge was issued */
+  created_at: string;
+  /** When this challenge expires */
+  expires_at?: string | null;
+  /** Method-specific challenge data. Structure depends on the `method` field.
+  - `identifier`, `password`: null (no additional data needed)
+  - `passkey`: WebAuthn challenge and credential options
+  - `idp`: Authorization URL and provider information
+   */
+  payload?: VerifyChallengeProof200ChallengesItemPayload;
+};

package/src/generated/model/verifyChallengeProof200ChallengesItemMethod.ts

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * An authentication factor method.
+ */
+export type VerifyChallengeProof200ChallengesItemMethod =
+  (typeof VerifyChallengeProof200ChallengesItemMethod)[keyof typeof VerifyChallengeProof200ChallengesItemMethod];
+
+export const VerifyChallengeProof200ChallengesItemMethod = {
+  identifier: "identifier",
+  password: "password",
+  passkey: "passkey",
+} as const;

package/src/generated/model/verifyChallengeProof200ChallengesItemPayload.ts

@@ -0,0 +1,36 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * Method-specific challenge data. Structure depends on the `method` field.
+- `identifier`, `password`: null (no additional data needed)
+- `passkey`: WebAuthn challenge and credential options
+- `idp`: Authorization URL and provider information
+
+ */
+export type VerifyChallengeProof200ChallengesItemPayload =
+  | { [key: string]: unknown }
+  | {
+      /** Contains the options for the Assertion Generation (dictionary PublicKeyCredentialRequestOptions).
+  See also: https://www.w3.org/TR/webauthn/#dictdef-publickeycredentialrequestoptions
+   */
+      public_key: {
+        /** Base64-encoded WebAuthn challenge */
+        challenge: string;
+        /** List of credential IDs that can be used for this authentication */
+        allowed_credentials?: {
+          /** Base64-encoded credential ID */
+          id: string;
+          type: "public-key";
+        }[];
+        /** User verification requirement for this challenge */
+        user_verification?: "required" | "preferred" | "discouraged";
+        /** Relying Party ID for WebAuthn */
+        rp_id?: string;
+      };
+    };

package/src/generated/model/verifyChallengeProof200ChallengesItemState.ts

@@ -0,0 +1,23 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * Current state of this challenge:
+- `pending`: awaiting proof submission
+- `failed`: proof rejected (invalid credential, wrong code, etc.)
+- `expired`: challenge TTL exceeded without verification
+
+ */
+export type VerifyChallengeProof200ChallengesItemState =
+  (typeof VerifyChallengeProof200ChallengesItemState)[keyof typeof VerifyChallengeProof200ChallengesItemState];
+
+export const VerifyChallengeProof200ChallengesItemState = {
+  pending: "pending",
+  failed: "failed",
+  expired: "expired",
+} as const;

package/src/generated/model/verifyChallengeProof200CompletedFactorsItem.ts

@@ -0,0 +1,27 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+import type { VerifyChallengeProof200CompletedFactorsItemMethod } from "./verifyChallengeProof200CompletedFactorsItemMethod";
+import type { VerifyChallengeProof200CompletedFactorsItemPayload } from "./verifyChallengeProof200CompletedFactorsItemPayload";
+
+/**
+ * A successfully verified authentication factor with verification metadata.
+Method-specific details are included in the `payload` field.
+
+ */
+export type VerifyChallengeProof200CompletedFactorsItem = {
+  /** An authentication factor method. */
+  method: VerifyChallengeProof200CompletedFactorsItemMethod;
+  /** When this factor was successfully verified */
+  verified_at: string;
+  /** Method-specific factor metadata. Structure depends on the `method` field.
+  - `identifier`: includes user_id
+  - `password`: no additional data
+  - `passkey`: includes credential details and verification flags
+   */
+  payload?: VerifyChallengeProof200CompletedFactorsItemPayload;
+};

package/src/generated/model/verifyChallengeProof200CompletedFactorsItemMethod.ts

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * An authentication factor method.
+ */
+export type VerifyChallengeProof200CompletedFactorsItemMethod =
+  (typeof VerifyChallengeProof200CompletedFactorsItemMethod)[keyof typeof VerifyChallengeProof200CompletedFactorsItemMethod];
+
+export const VerifyChallengeProof200CompletedFactorsItemMethod = {
+  identifier: "identifier",
+  password: "password",
+  passkey: "passkey",
+} as const;

package/src/generated/model/verifyChallengeProof200CompletedFactorsItemPayload.ts

@@ -0,0 +1,33 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * Method-specific factor metadata. Structure depends on the `method` field.
+- `identifier`: includes user_id
+- `password`: no additional data
+- `passkey`: includes credential details and verification flags
+
+ */
+export type VerifyChallengeProof200CompletedFactorsItemPayload =
+  | {
+      /** @pattern ^user_[a-zA-Z0-9_-]+$ */
+      user_id: string;
+    }
+  | { [key: string]: unknown }
+  | {
+      /** The credential ID that was used */
+      credential_id: string;
+      /** Whether user verification was performed (PIN/biometric) */
+      user_verified: boolean;
+      /** Whether the credential is backup eligible (can be synced) */
+      backup_eligible?: boolean;
+      /** Whether the credential is currently backed up */
+      backup_state?: boolean;
+      /** Authenticator attachment modality */
+      authenticator_attachment?: "platform" | "cross-platform";
+    };

package/src/generated/model/verifyChallengeProof200RequiredFactorsItem.ts

@@ -0,0 +1,19 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * An authentication factor method.
+ */
+export type VerifyChallengeProof200RequiredFactorsItem =
+  (typeof VerifyChallengeProof200RequiredFactorsItem)[keyof typeof VerifyChallengeProof200RequiredFactorsItem];
+
+export const VerifyChallengeProof200RequiredFactorsItem = {
+  identifier: "identifier",
+  password: "password",
+  passkey: "passkey",
+} as const;

package/src/generated/model/verifyChallengeProof200State.ts

@@ -0,0 +1,25 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * Overall state of the authentication attempt:
+- `in_progress`: factors are still being collected; continue issuing challenges.
+- `completed`: all required factors have been verified; the attempt is ready for handoff.
+- `failed`: the attempt has failed (e.g. too many failed proofs) and cannot be continued.
+- `expired`: the 15-minute TTL has been exceeded.
+
+ */
+export type VerifyChallengeProof200State =
+  (typeof VerifyChallengeProof200State)[keyof typeof VerifyChallengeProof200State];
+
+export const VerifyChallengeProof200State = {
+  in_progress: "in_progress",
+  completed: "completed",
+  failed: "failed",
+  expired: "expired",
+} as const;

package/src/generated/model/verifyChallengeProofBody.ts

@@ -0,0 +1,31 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+/**
+ * Proof for verifying a factor challenge.
+
+The exact format depends on the challenge method. The proof object should contain
+only the credential/code/assertion relevant to the challenge method being verified.
+
+ */
+export type VerifyChallengeProofBody =
+  | {
+      /** The login name or email being identified */
+      login_name: string;
+    }
+  | {
+      /** The password being verified */
+      password: string;
+    }
+  | {
+      /** WebAuthn passkey assertion */
+      passkey: {
+        /** The WebAuthn AssertionResponse object */
+        assertion: { [key: string]: unknown };
+      };
+    };

package/src/generated/model/verifyChallengeProofDefault.ts

@@ -0,0 +1,79 @@
+/**
+ * Generated by orval v8.10.0 🍺
+ * Do not edit manually.
+ * Zitadel NextGen
+ * This is the next generation of the Zitadel identity platform.
+ * OpenAPI spec version: 0.0.1
+ */
+
+export type VerifyChallengeProofDefault =
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.not_found";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.stale_challenge";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.invalid_request";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.proof_rejected";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.invalid_state";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "att.already_completed";
+    })
+  | ({
+      /** Stable machine-readable error code. */
+      code: string;
+      /** Human-readable explanation of the error. */
+      message: string;
+      /** Additional error-specific context. */
+      details?: { [key: string]: unknown };
+    } & {
+      code: "internal";
+    });

package/src/runtime/api-factory.ts

@@ -0,0 +1,80 @@
+/**
+ * Factory for the typed Zitadel client every consumer reaches for.
+ *
+ * Wraps the orval-generated endpoints in a {@link Proxy} so each
+ * generated function sees the right base URL and (optionally) the
+ * right bearer token at call time — without the caller having to
+ * thread either through every operation, and without exposing the
+ * module-globals (`setProxyPath` / `setApiAuthToken`) as part of the
+ * public API.
+ *
+ * Per-instance isolation: multiple clients can coexist in one process
+ * (different servers, different tokens). Their Proxy `get` traps set
+ * the globals synchronously before invoking the underlying generated
+ * function, which reads them at the top of `customFetch` before any
+ * `await`. Two clients running interleaved within a single JS turn
+ * are safe; two clients running in parallel across awaits could
+ * clobber each other — not a pattern any current consumer uses.
+ */
+import * as endpoints from "../generated/endpoints/zitadelNextGen";
+
+import { setApiAuthToken } from "./auth";
+import { setProxyPath } from "./base-url";
+
+/**
+ * Typed Zitadel client returned by {@link createZitadelClient}.
+ * Mirrors the orval-generated endpoints module 1:1.
+ */
+export type ZitadelClient = typeof endpoints;
+
+/** Re-exported under the legacy name some consumers (`runtime/config.ts`) still import. */
+export type ZitadelApi = ZitadelClient;
+
+/** Options for {@link createZitadelClient}. */
+export type ZitadelClientOptions = {
+  /** Base URL of the Zitadel server. Trailing slashes are stripped. */
+  baseUrl: string;
+  /**
+   * Bearer token sent on every request. Optional — omit for the
+   * unauthenticated `POST /projects` call; set it (typically to the
+   * project secret returned by that call) before any subsequent
+   * mutation.
+   */
+  token?: string;
+};
+
+/**
+ * Build a typed Zitadel client pre-bound to a base URL and (optionally)
+ * a bearer token. Every method on the returned object mirrors a
+ * generated orval function:
+ *
+ *     const client = createZitadelClient({ baseUrl, token });
+ *     await client.createProject({ previewOrigins: [] });
+ *     await client.createSchema(body, { project_id });
+ */
+export function createZitadelClient(opts: ZitadelClientOptions): ZitadelClient {
+  const baseUrl = opts.baseUrl.replace(/\/+$/, "");
+  return new Proxy(endpoints as ZitadelClient, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") {
+        return value;
+      }
+      return (...args: unknown[]) => {
+        setProxyPath(baseUrl);
+        setApiAuthToken(opts.token);
+        return (value as (...a: unknown[]) => unknown)(...args);
+      };
+    },
+  });
+}
+
+/**
+ * Legacy entry point: builds a client with only the base URL set, no
+ * token. Components and SDKs that don't carry an auth token (browser
+ * flows authenticated by platform cookies) still consume this name.
+ * Equivalent to `createZitadelClient({ baseUrl: apiBase })`.
+ */
+export function createApi(apiBase: string): ZitadelClient {
+  return createZitadelClient({ baseUrl: apiBase });
+}

package/src/runtime/auth.ts

@@ -0,0 +1,19 @@
+/**
+ * Module-global bearer token used by the orval-generated client's
+ * custom fetch. Set once at command boot (the same lifecycle pattern
+ * as `base-url.ts`); every generated request reads from here.
+ *
+ * Keeping the token here means the CLI doesn't have to thread an
+ * `Authorization` header through every generated call site; orval's
+ * `mutator` wires `runtime/fetch.ts` in, and that file pulls the token
+ * from this module.
+ */
+let apiAuthToken: string | undefined;
+
+export function getApiAuthToken(): string | undefined {
+  return apiAuthToken;
+}
+
+export function setApiAuthToken(token: string | undefined): void {
+  apiAuthToken = token;
+}

package/src/runtime/base-url.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "vitest";
+
+import { getProxyPath } from "./base-url";
+
+test("getProxyPath returns empty string by default", () => {
+  expect(getProxyPath()).toBe("");
+});

package/src/runtime/base-url.ts

@@ -0,0 +1,9 @@
+let proxyPath = "";
+
+export function getProxyPath(): string {
+  return proxyPath;
+}
+
+export function setProxyPath(path: string): void {
+  proxyPath = path;
+}

package/src/runtime/config.spec.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import { getProxyPath } from "./base-url";
+import {
+  configureZitadel,
+  getApi,
+  getZitadelConfig,
+  _resetConfigForTesting,
+} from "./config";
+
+afterEach(() => {
+  _resetConfigForTesting();
+});
+
+describe("configureZitadel", () => {
+  test("sets config and syncs proxyPath", () => {
+    const project = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+
+    expect(project.proxyPath).toBe("/__nextgen");
+    expect(project.projectId).toBe("proj_1");
+    expect(getProxyPath()).toBe("/__nextgen");
+  });
+
+  test("returns null before configuration", () => {
+    expect(getZitadelConfig()).toBeNull();
+  });
+
+  test("freezes the returned project object", () => {
+    const project = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    expect(() => {
+      (project as unknown as Record<string, unknown>).proxyPath = "/hacked";
+    }).toThrow();
+  });
+
+  test("same-value re-call is a no-op", () => {
+    const p1 = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    const p2 = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    expect(p1).toBe(p2);
+  });
+
+  test("different-value re-call warns and is ignored", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(vi.fn());
+    const p1 = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    const p2 = configureZitadel({ proxyPath: "/other", projectId: "proj_2" });
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy.mock.calls[0]![0]).toContain("already called with different values");
+    expect(p2).toBe(p1);
+    expect(p2.proxyPath).toBe("/__nextgen");
+    warnSpy.mockRestore();
+  });
+
+  test("getZitadelConfig returns the same project handle", () => {
+    const project = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    expect(getZitadelConfig()).toBe(project);
+  });
+});
+
+describe("getApi", () => {
+  test("returns a typed API client with all generated functions", () => {
+    const project = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    const api = getApi(project);
+
+    expect(api).toBeDefined();
+    expect(typeof api.createFlow).toBe("function");
+    expect(typeof api.endSession).toBe("function");
+    expect(typeof api.getMySession).toBe("function");
+  });
+
+  test("returns the same instance for the same project handle", () => {
+    const project = configureZitadel({ proxyPath: "/__nextgen", projectId: "proj_1" });
+    const api1 = getApi(project);
+    const api2 = getApi(project);
+    expect(api1).toBe(api2);
+  });
+});