@verne-software/sdk 1.3.0 → 1.4.0

package/dist/index.js

@@ -12,31 +12,89 @@ var VerneAPIError = class _VerneAPIError extends VerneError {
     code,
     message,
     status,
-    requestId
+    requestId,
+    details,
+    retryAfter,
+    body
   }) {
     super(message);
     this.name = "VerneAPIError";
     this.code = code;
     this.status = status;
     this.requestId = requestId;
+    this.details = details ?? {};
+    this.retryAfter = retryAfter;
+    this.body = body;
   }
-  static fromResponse(status, body) {
+  /**
+   * Builds an error from a parsed response body of *unknown* shape.
+   *
+   * Every API route answers with the envelope `{ error: { code, message, request_id,
+   * ...extra } }`. Other shapes are still read, as a fallback that costs nothing: the
+   * string form `{ error: "<sentence>" }` Clockwork used before October 2026, and an
+   * identity-service body whose `code` is a number (still what Kratos' own `/auth/*`
+   * self-service routes answer). Anything unrecognised degrades — to code `'unknown'`,
+   * to `HTTP <status>` — rather than throwing: an error path must never be the thing
+   * that fails.
+   */
+  static fromResponse(status, body, retryAfter) {
+    const envelope = isRecord(body) && isRecord(body.error) ? body.error : void 0;
+    const details = {};
+    if (envelope) {
+      for (const [key, value] of Object.entries(envelope)) {
+        if (key !== "code" && key !== "message" && key !== "request_id") details[key] = value;
+      }
+    }
     return new _VerneAPIError({
-      code: body.error.code,
-      message: body.error.message,
+      code: typeof envelope?.code === "string" ? envelope.code : "unknown",
+      message: extractMessage(body, status),
       status,
-      requestId: body.error.request_id
+      requestId: typeof envelope?.request_id === "string" ? envelope.request_id : void 0,
+      details,
+      retryAfter,
+      body
     });
   }
 };
+var VerneTokenError = class extends VerneError {
+  constructor(reason, message) {
+    super(message);
+    this.name = "VerneTokenError";
+    this.reason = reason;
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function extractMessage(body, status) {
+  if (isRecord(body)) {
+    const envelope = body.error;
+    if (isRecord(envelope) && typeof envelope.message === "string") {
+      return envelope.message;
+    }
+    if (typeof envelope === "string" && envelope.trim() !== "") {
+      return envelope;
+    }
+    const { detail } = body;
+    if (typeof detail === "string") return detail;
+    if (Array.isArray(detail)) {
+      const messages = detail.map((item) => isRecord(item) && typeof item.msg === "string" ? item.msg : null).filter((msg) => msg !== null);
+      if (messages.length > 0) return messages.join("; ");
+    }
+    if (typeof body.message === "string") return body.message;
+  }
+  return `HTTP ${status}`;
+}
 
 // src/core/http.ts
 var DEFAULT_BASE_URL = "https://api.vernesoft.com";
 var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_AUTO_RETRY_AFTER_SECONDS = 60;
+var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["RELAY_MESSAGE_LIMIT_REACHED"]);
 var HttpClient = class {
   constructor(config) {
     this.apiKey = config.apiKey;
-    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
   async get(path, options) {
@@ -55,16 +113,29 @@ var HttpClient = class {
     return this.request("DELETE", path, options);
   }
   async request(method, path, options = {}, attempt = 1) {
-    const { skipAuth, body, signal, headers: extraHeaders, timeoutMs } = options;
-    const url = `${this.baseUrl}${path}`;
+    const {
+      skipAuth,
+      body,
+      signal,
+      headers: extraHeaders,
+      timeoutMs,
+      query,
+      sessionToken
+    } = options;
+    const qs = buildQuery(query);
+    const url = `${this.baseUrl}${path}${qs ? (path.includes("?") ? "&" : "?") + qs : ""}`;
     const timeout = timeoutMs ?? this.timeoutMs;
     const headers = {
       "Content-Type": "application/json",
+      Accept: "application/json",
       ...extraHeaders
     };
     if (!skipAuth) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
     }
+    if (sessionToken !== void 0) {
+      headers["X-Session-Token"] = sessionToken;
+    }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     const combinedSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
@@ -85,20 +156,21 @@ var HttpClient = class {
     } finally {
       clearTimeout(timeoutId);
     }
-    if (response.status === 429 && attempt === 1 && method === "POST") {
-      const retryAfter = response.headers.get("Retry-After");
-      const waitMs = retryAfter ? parseFloat(retryAfter) * 1e3 : 1e3;
-      await sleep(waitMs);
-      return this.request(method, path, options, 2);
-    }
     if (!response.ok) {
+      const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
       let errorBody;
       try {
         errorBody = await response.json();
       } catch {
-        throw new VerneError(`HTTP ${response.status}: ${method} ${path}`);
+        throw VerneAPIError.fromResponse(response.status, void 0, retryAfter);
       }
-      throw VerneAPIError.fromResponse(response.status, errorBody);
+      const error = VerneAPIError.fromResponse(response.status, errorBody, retryAfter);
+      const wait = retryAfter ?? 1;
+      if (response.status === 429 && attempt === 1 && method === "POST" && wait <= MAX_AUTO_RETRY_AFTER_SECONDS && !NON_RETRYABLE_429_CODES.has(error.code)) {
+        await sleep(wait * 1e3);
+        return this.request(method, path, options, 2);
+      }
+      throw error;
     }
     if (response.status === 204) {
       return void 0;
@@ -106,6 +178,26 @@ var HttpClient = class {
     return response.json();
   }
 };
+function parseRetryAfter(raw) {
+  if (raw === null || raw.trim() === "") return void 0;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+  const at = Date.parse(raw);
+  if (!Number.isNaN(at)) return Math.max(0, Math.ceil((at - Date.now()) / 1e3));
+  return void 0;
+}
+function buildQuery(params) {
+  if (!params) return "";
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    search.set(key, value instanceof Date ? value.toISOString() : String(value));
+  }
+  return search.toString();
+}
+function seg(value) {
+  return encodeURIComponent(value);
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -203,6 +295,34 @@ var Clockwork = class {
     this.jobs = new ClockworkJobsResource(this.http);
     this.delayed = new ClockworkDelayedResource(this.http);
   }
+  /**
+   * How many jobs exist against the plan's limits. Creating a job over a limit, or
+   * resuming a paused one, is refused with `402` (`UPGRADE_REQUIRED` or
+   * `JOB_LIMIT_REACHED`) — never retried.
+   */
+  async usage(options) {
+    return this.http.get("/v1/clockwork/usage", options);
+  }
+};
+
+// src/resources/gate/audit-log.ts
+var AuditLogResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * One page of entries, newest first. Filters combine; keep the same filters while
+   * paging with `cursor`.
+   *
+   * @example
+   * const page = await gate.auditLog.list({ action: 'identity.login', actor_id: userId });
+   */
+  async list(params, options) {
+    return this.http.get("/v1/gate/audit-log", {
+      query: { ...params },
+      ...options
+    });
+  }
 };
 
 // src/resources/gate/identities.ts
@@ -211,50 +331,52 @@ var IdentitiesResource = class {
     this.http = http;
   }
   /**
-   * Creates a new identity (end-user) bound to your tenant.
-   * The `traits.tenant_id` is injected automatically by the Edge Gateway.
+   * Creates a new identity (end user) bound to your tenant. Answers `201`.
+   *
+   * A `409 conflict` means you already have an end user with this address; the same
+   * address at another tenant is a different person and does not conflict. Traits are
+   * `email` and `locale` only — keep your own fields in custom metadata.
    */
   async create(params, options) {
     return this.http.post("/v1/gate/identities", { body: params, ...options });
   }
   /**
-   * Returns an identity by ID.
-   * The Gateway will reject the request if the identity does not belong to your tenant.
+   * Returns an identity by ID. An identity of another tenant is refused.
    */
   async get(identityId, options) {
-    return this.http.get(`/v1/gate/identities/${identityId}`, options);
+    return this.http.get(`/v1/gate/identities/${seg(identityId)}`, options);
   }
   /**
    * Partially updates an identity using a JSON Patch document (RFC 6902).
    *
    * @example
    * await gate.identities.patch('identity_123', [
-   *   { op: 'replace', path: '/traits/custom_data/role', value: 'admin' }
+   *   { op: 'replace', path: '/traits/email', value: 'new@example.com' },
    * ]);
    */
   async patch(identityId, ops, options) {
-    return this.http.patch(`/v1/gate/identities/${identityId}`, {
+    return this.http.patch(`/v1/gate/identities/${seg(identityId)}`, {
       body: ops,
       ...options
     });
   }
   /**
-   * Deletes an identity from Kratos.
-   * The Gateway will reject the request if the identity does not belong to your tenant.
+   * Deletes an identity, its sessions and its memberships. Fires `identity.deleted`.
    */
   async delete(identityId, options) {
-    return this.http.delete(`/v1/gate/identities/${identityId}`, options);
+    return this.http.delete(`/v1/gate/identities/${seg(identityId)}`, options);
   }
   /**
-   * Activates or deactivates an identity. An `inactive` identity cannot log in —
-   * Kratos rejects its credentials automatically — until it is reactivated.
-   * The identity is not deleted. Fires the `identity.state_changed` webhook event.
+   * Activates or deactivates an identity. An `inactive` identity cannot sign in, its
+   * sessions stop working (until it is active again), its access tokens introspect as
+   * `active: false`, and no signed token is issued for it. Nothing is deleted. Fires the
+   * `identity.state_changed` webhook event.
    *
    * @example
    * await gate.identities.setState('identity_123', 'inactive');
    */
   async setState(identityId, state, options) {
-    return this.http.patch(`/v1/gate/identities/${identityId}/state`, {
+    return this.http.patch(`/v1/gate/identities/${seg(identityId)}/state`, {
       body: { state },
       ...options
     });
@@ -274,9 +396,272 @@ var IdentitiesResource = class {
    */
   async resendVerification(identityId, options) {
     return this.http.post(
-      `/v1/gate/identities/${identityId}/resend-verification`,
+      `/v1/gate/identities/${seg(identityId)}/resend-verification`,
+      options
+    );
+  }
+  /**
+   * Reads an identity's custom metadata (`metadata_public`) — the place for your own
+   * fields about a user. `{}` when nothing is set.
+   */
+  async getMetadata(identityId, options) {
+    const res = await this.http.get(
+      `/v1/gate/identities/${seg(identityId)}/metadata`,
       options
     );
+    return res.metadata_public;
+  }
+  /**
+   * Merges `patch` into an identity's custom metadata and returns the result. Keys you
+   * leave out are kept; a key set to `null` is removed.
+   *
+   * @example
+   * await gate.identities.updateMetadata(id, { plan: 'pro', seats: null });
+   */
+  async updateMetadata(identityId, patch, options) {
+    const res = await this.http.patch(
+      `/v1/gate/identities/${seg(identityId)}/metadata`,
+      { body: patch, ...options }
+    );
+    return res.metadata_public;
+  }
+  /**
+   * The organizations of the key's project that an end user belongs to, with the role
+   * held in each and its permissions — live, oldest membership first, cursor-paged. This
+   * is the complete list that `orgs_truncated: true` (in a token, an introspection or a
+   * session check) points to.
+   */
+  async listOrganizations(identityId, params, options) {
+    return this.http.get(
+      `/v1/gate/identities/${seg(identityId)}/organizations`,
+      { query: { limit: params?.limit, cursor: params?.cursor }, ...options }
+    );
+  }
+};
+
+// src/resources/gate/lifecycle.ts
+var rulePath = (kind) => `/v1/gate/lifecycle/rules/${seg(kind)}`;
+var LifecycleResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** All four rules of the key's project, set up or not, and the plan. */
+  async listRules(options) {
+    return this.http.get("/v1/gate/lifecycle/rules", options);
+  }
+  /**
+   * Creates, changes, or switches a rule on or off. Leave `params` out to keep the saved
+   * settings. Switching off or changing settings cancels what the rule had scheduled.
+   *
+   * @example
+   * await gate.lifecycle.setRule('delete_unverified', {
+   *   enabled: true,
+   *   params: { delete_after_days: 14, warn_before_days: 3 },
+   * });
+   */
+  async setRule(kind, params, options) {
+    const body = { enabled: params.enabled };
+    if (params.params !== void 0) body.params = params.params;
+    return this.http.put(rulePath(kind), { body, ...options });
+  }
+  /** Removes a rule and cancels what it scheduled. Succeeds also when there was none. */
+  async deleteRule(kind, options) {
+    return this.http.delete(rulePath(kind), options);
+  }
+  /**
+   * How many people a rule with these settings would affect right now. Writes nothing;
+   * works whether or not the rule is on or in your plan. `expire_roles` takes `{}`.
+   */
+  async previewRule(kind, params, options) {
+    return this.http.post(`${rulePath(kind)}/preview`, {
+      body: { params },
+      ...options
+    });
+  }
+  /** What the rules have scheduled and done, oldest first, cursor-paged. */
+  async listActions(params, options) {
+    return this.http.get("/v1/gate/lifecycle/actions", {
+      query: { ...params },
+      ...options
+    });
+  }
+};
+
+// src/resources/gate/organizations.ts
+var orgPath = (orgId) => `/v1/gate/organizations/${seg(orgId)}`;
+var pageQuery = (params) => ({ limit: params?.limit, cursor: params?.cursor });
+var isoOrNull = (value) => value instanceof Date ? value.toISOString() : value;
+var OrganizationsResource = class {
+  constructor(http) {
+    this.http = http;
+    this.roles = new RolesResource(http);
+    this.members = new MembersResource(http);
+  }
+  /** Creates an organization. `name` is free text, 1–120 characters, not unique. */
+  async create(params, options) {
+    return this.http.post("/v1/gate/organizations", { body: params, ...options });
+  }
+  /** Lists the project's organizations, oldest first, cursor-paged. */
+  async list(params, options) {
+    return this.http.get("/v1/gate/organizations", {
+      query: pageQuery(params),
+      ...options
+    });
+  }
+  async get(orgId, options) {
+    return this.http.get(orgPath(orgId), options);
+  }
+  /** Renames an organization. */
+  async update(orgId, params, options) {
+    return this.http.patch(orgPath(orgId), { body: params, ...options });
+  }
+  /** Deletes an organization with its roles and memberships. */
+  async delete(orgId, options) {
+    return this.http.delete(orgPath(orgId), options);
+  }
+  /**
+   * *May this end user do this in this organization?* — answered from the role the user
+   * holds there and its permissions, as they are now. `permission` must match exactly
+   * (no wildcards). An organization of another project looks like a missing one
+   * (`no_such_organization`). An invalid permission (upper case, `*`, the `nautilus:`
+   * prefix) is a `400` error, never `allowed: false`. Not billed, not audited.
+   */
+  async authorize(orgId, identityId, permission, options) {
+    return this.http.post("/v1/gate/authorize", {
+      body: { subject: identityId, action: permission, resource: `organization:${orgId}` },
+      ...options
+    });
+  }
+  /**
+   * `true` when the end user holds `permission` in the organization — the boolean of
+   * {@link authorize}. Errors are thrown, not turned into `false`.
+   *
+   * @example
+   * if (!(await gate.organizations.can(orgId, userId, 'invoices:write'))) {
+   *   throw new Error('Forbidden');
+   * }
+   */
+  async can(orgId, identityId, permission, options) {
+    const decision = await this.authorize(orgId, identityId, permission, options);
+    return decision.allowed === true;
+  }
+};
+var RolesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Defines a role. `409 conflict` if the name is taken in the organization,
+   * `409 limit_reached` past 100 roles.
+   */
+  async create(orgId, params, options) {
+    return this.http.post(`${orgPath(orgId)}/roles`, { body: params, ...options });
+  }
+  async list(orgId, params, options) {
+    return this.http.get(`${orgPath(orgId)}/roles`, {
+      query: pageQuery(params),
+      ...options
+    });
+  }
+  async get(orgId, roleId, options) {
+    return this.http.get(`${orgPath(orgId)}/roles/${seg(roleId)}`, options);
+  }
+  /**
+   * Renames a role and/or **replaces** its permissions. Everyone who holds it has the new
+   * permissions the next time they are read.
+   */
+  async update(orgId, roleId, params, options) {
+    return this.http.patch(`${orgPath(orgId)}/roles/${seg(roleId)}`, {
+      body: params,
+      ...options
+    });
+  }
+  /** Deletes a role. A role someone holds is refused with `409 conflict`. */
+  async delete(orgId, roleId, options) {
+    return this.http.delete(`${orgPath(orgId)}/roles/${seg(roleId)}`, options);
+  }
+};
+var MembersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Gives an end user a role in the organization. `404` if the identity is not one of
+   * your end users, `409` if they already are a member (change the role with
+   * {@link update}).
+   */
+  async add(orgId, params, options) {
+    const body = {
+      identity_id: params.identity_id,
+      role_id: params.role_id
+    };
+    if (params.expires_at !== void 0) body.expires_at = isoOrNull(params.expires_at);
+    return this.http.post(`${orgPath(orgId)}/members`, { body, ...options });
+  }
+  async list(orgId, params, options) {
+    return this.http.get(`${orgPath(orgId)}/members`, {
+      query: pageQuery(params),
+      ...options
+    });
+  }
+  /**
+   * Changes a member's role and/or deadline. `expires_at`: leave it out to keep the
+   * deadline, `null` to remove it, a time to set it.
+   */
+  async update(orgId, identityId, params, options) {
+    const body = {};
+    if (params.role_id !== void 0) body.role_id = params.role_id;
+    if (params.expires_at !== void 0) body.expires_at = isoOrNull(params.expires_at);
+    return this.http.patch(`${orgPath(orgId)}/members/${seg(identityId)}`, {
+      body,
+      ...options
+    });
+  }
+  /** Removes the membership. The person stays your end user. */
+  async remove(orgId, identityId, options) {
+    return this.http.delete(`${orgPath(orgId)}/members/${seg(identityId)}`, options);
+  }
+};
+
+// src/resources/gate/sessions.ts
+var SessionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** The active sessions of one of your end users (a bare array, not paged). */
+  async list(identityId, options) {
+    return this.http.get(`/v1/gate/identities/${seg(identityId)}/sessions`, options);
+  }
+  /**
+   * Revokes every session of an end user — "log out everywhere". Signed tokens already
+   * issued keep verifying until their own `exp` (at most 15 minutes).
+   *
+   * Idempotent: a user of yours with no session at all is a success too. An id that is not
+   * one of your users — another account's, unknown, or one you deleted — is
+   * `403 forbidden`. `404 not_found` is rare: a user removed from the identity service
+   * other than through `identities.delete()`, which Gate still remembered as yours.
+   */
+  async revokeAll(identityId, options) {
+    return this.http.delete(`/v1/gate/identities/${seg(identityId)}/sessions`, options);
+  }
+  /**
+   * Revokes one session by its id. Revoking an already revoked session of your user is a
+   * success too; an id that is not one of your users' sessions is `404`.
+   */
+  async revoke(sessionId, options) {
+    return this.http.delete(`/v1/gate/sessions/${seg(sessionId)}`, options);
+  }
+  /**
+   * Whether an end user's session meets what your tenant requires — the one call to
+   * gate your own routes on. Gate on `mfa_satisfied`. Also lists the user's
+   * organizations in the key's project, read now.
+   *
+   * Throws `VerneAPIError` with `status 401` for a dead, foreign or unknown session, and
+   * `code 'mfa_required'` (`403`) when a second factor is owed: start a step-up flow with
+   * `gate.createLoginFlow({ aal: 'aal2', session_token })`.
+   */
+  async check(sessionToken, options) {
+    return this.http.get("/v1/gate/auth/session", { sessionToken, ...options });
   }
 };
 
@@ -286,7 +671,8 @@ var SettingsResource = class {
     this.http = http;
   }
   /**
-   * Returns the tenant's security settings (passwordless / MFA).
+   * Returns the tenant's security settings (passwordless / MFA). With `mfa_enabled`,
+   * `sessions.check()` refuses a session without a second factor (`403 mfa_required`).
    */
   async getSecurity(options) {
     return this.http.get("/v1/gate/settings/security", options);
@@ -333,29 +719,258 @@ var SettingsResource = class {
     );
     return res.providers;
   }
+  /**
+   * The project's social-login return URLs — the addresses on your backend that receive
+   * the user (with a one-time `code`) after a social login. The first is the default.
+   */
+  async getReturnUrls(options) {
+    const res = await this.http.get(
+      "/v1/gate/settings/return-urls",
+      options
+    );
+    return res.return_urls;
+  }
+  /**
+   * Replaces the project's return URLs (at most 10; an empty list switches the feature
+   * off) and returns them as they will be matched — exactly, never by prefix. `https`
+   * only, except `http://localhost` and `http://127.0.0.1`; no query, fragment, `@` or
+   * wildcard (`400 invalid_payload` names the entry).
+   */
+  async updateReturnUrls(urls, options) {
+    const res = await this.http.put("/v1/gate/settings/return-urls", {
+      body: { return_urls: urls },
+      ...options
+    });
+    return res.return_urls;
+  }
 };
 
+// src/resources/gate/verifier.ts
+var DEFAULT_JWKS_MAX_AGE_MS = 3e5;
+var MIN_REFETCH_INTERVAL_MS = 3e4;
+var DEFAULT_CLOCK_TOLERANCE_SECONDS = 10;
+var DEFAULT_TIMEOUT_MS2 = 1e4;
+var GateTokenVerifier = class {
+  constructor(config) {
+    this.keys = /* @__PURE__ */ new Map();
+    this.fetchedAt = 0;
+    this.maxAgeMs = DEFAULT_JWKS_MAX_AGE_MS;
+    if (!config.tenantId) {
+      throw new VerneError("GateTokenVerifier needs your tenantId.");
+    }
+    const base = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.issuer = `${base}/auth/${config.tenantId}`;
+    this.jwksUrl = `${this.issuer}/.well-known/jwks.json`;
+    this.toleranceSeconds = config.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+  }
+  /**
+   * Verifies `token` and returns its claims. Throws {@link VerneTokenError} (with a
+   * `reason`) when the token must not be trusted.
+   */
+  async verify(token) {
+    const parts = typeof token === "string" ? token.split(".") : [];
+    if (parts.length !== 3) {
+      throw new VerneTokenError("malformed", "Not a compact JWT.");
+    }
+    const [rawHeader, rawPayload, rawSignature] = parts;
+    const header = decodeJson(rawHeader, "header");
+    const payload = decodeJson(rawPayload, "payload");
+    if (header.alg !== "ES256") {
+      throw new VerneTokenError(
+        "unsupported_alg",
+        `Token algorithm ${JSON.stringify(header.alg)} is not accepted; Gate signs with ES256.`
+      );
+    }
+    if (typeof header.kid !== "string" || header.kid === "") {
+      throw new VerneTokenError("malformed", "Token header has no `kid`.");
+    }
+    const key = await this.keyFor(header.kid);
+    const signature = base64UrlDecode(rawSignature);
+    if (!signature || signature.length !== 64) {
+      throw new VerneTokenError("bad_signature", "Token signature is not a P-256 signature.");
+    }
+    const subtle = await subtleCrypto();
+    const valid = await subtle.verify(
+      { name: "ECDSA", hash: "SHA-256" },
+      key,
+      signature,
+      new TextEncoder().encode(`${rawHeader}.${rawPayload}`)
+    );
+    if (!valid) {
+      throw new VerneTokenError("bad_signature", "Token signature does not verify.");
+    }
+    if (payload.iss !== this.issuer) {
+      throw new VerneTokenError(
+        "wrong_issuer",
+        `Token issuer ${JSON.stringify(payload.iss)} is not ${this.issuer}.`
+      );
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (typeof payload.exp !== "number") {
+      throw new VerneTokenError("missing_claim", "Token has no `exp`.");
+    }
+    if (now > payload.exp + this.toleranceSeconds) {
+      throw new VerneTokenError("expired", "Token has expired.");
+    }
+    if (typeof payload.nbf === "number" && payload.nbf > now + this.toleranceSeconds) {
+      throw new VerneTokenError("not_yet_valid", "Token is not valid yet.");
+    }
+    if (typeof payload.sub !== "string" || payload.sub === "") {
+      throw new VerneTokenError("missing_claim", "Token has no `sub`.");
+    }
+    return payload;
+  }
+  async keyFor(kid) {
+    const stale = Date.now() - this.fetchedAt > this.maxAgeMs;
+    if (stale) {
+      await this.refresh(this.keys.size === 0);
+    }
+    let key = this.keys.get(kid);
+    if (!key && Date.now() - this.fetchedAt >= MIN_REFETCH_INTERVAL_MS) {
+      await this.refresh(true);
+      key = this.keys.get(kid);
+    }
+    if (!key) {
+      throw new VerneTokenError("unknown_kid", `No key ${kid} in ${this.jwksUrl}.`);
+    }
+    return key;
+  }
+  /**
+   * Fetches the key set. With `required` false a failure keeps the keys already cached
+   * (a stale key set is still the right one unless a token says otherwise).
+   */
+  async refresh(required) {
+    this.inflight ?? (this.inflight = this.load().finally(() => {
+      this.inflight = void 0;
+    }));
+    try {
+      await this.inflight;
+    } catch (err) {
+      if (required) throw err;
+    }
+  }
+  async load() {
+    let response;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      response = await fetch(this.jwksUrl, {
+        headers: { Accept: "application/json" },
+        signal: controller.signal
+      });
+    } catch (err) {
+      throw new VerneTokenError(
+        "jwks_unavailable",
+        `Could not fetch ${this.jwksUrl}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      throw new VerneTokenError(
+        "jwks_unavailable",
+        `${this.jwksUrl} answered HTTP ${response.status}.`
+      );
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new VerneTokenError("jwks_unavailable", `${this.jwksUrl} did not answer JSON.`);
+    }
+    const jwks = body.keys;
+    if (!Array.isArray(jwks)) {
+      throw new VerneTokenError("jwks_unavailable", `${this.jwksUrl} has no \`keys\`.`);
+    }
+    const subtle = await subtleCrypto();
+    const keys = /* @__PURE__ */ new Map();
+    for (const jwk of jwks) {
+      if (jwk.kty !== "EC" || jwk.crv !== "P-256" || typeof jwk.kid !== "string") continue;
+      if (jwk.use !== void 0 && jwk.use !== "sig") continue;
+      const { kty, crv, x, y } = jwk;
+      try {
+        keys.set(
+          jwk.kid,
+          await subtle.importKey(
+            "jwk",
+            { kty, crv, x, y },
+            { name: "ECDSA", namedCurve: "P-256" },
+            false,
+            ["verify"]
+          )
+        );
+      } catch {
+      }
+    }
+    this.keys = keys;
+    this.fetchedAt = Date.now();
+    this.maxAgeMs = maxAgeMs(response.headers.get("Cache-Control"));
+  }
+};
+function maxAgeMs(cacheControl) {
+  const match = cacheControl ? /max-age=(\d+)/i.exec(cacheControl) : null;
+  return match ? Number(match[1]) * 1e3 : DEFAULT_JWKS_MAX_AGE_MS;
+}
+function decodeJson(segment, what) {
+  const bytes = base64UrlDecode(segment);
+  if (bytes) {
+    try {
+      const value = JSON.parse(new TextDecoder().decode(bytes));
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+      }
+    } catch {
+    }
+  }
+  throw new VerneTokenError("malformed", `Token ${what} is not base64url JSON.`);
+}
+function base64UrlDecode(segment) {
+  if (!/^[A-Za-z0-9_-]*$/.test(segment)) return null;
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+  try {
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+var subtlePromise;
+function subtleCrypto() {
+  subtlePromise ?? (subtlePromise = (async () => {
+    const global = globalThis.crypto;
+    if (global?.subtle) return global.subtle;
+    const nodeCrypto = await import('crypto');
+    return nodeCrypto.webcrypto.subtle;
+  })());
+  return subtlePromise;
+}
+
 // src/resources/gate/tokens.ts
 var TokensResource = class {
-  constructor(http, apiKey) {
+  constructor(http) {
     this.http = http;
-    this.apiKey = apiKey;
+    this.verifiers = /* @__PURE__ */ new Map();
   }
   /**
-   * Exchanges the Gate API key for a short-lived access token.
+   * Exchanges the Gate API key for a short-lived access token (`gat_live_…`), for
+   * `subject` — a user or a service account. Answers `201`.
    *
-   * Note: This endpoint does not use the Authorization header — the API key
-   * is passed in the request body per the Gate API specification.
+   * The key travels in the `Authorization` header like on every other call. (Until 1.4.0
+   * this SDK sent it in the body without the header, which the API refuses with `401`.)
    */
   async create(params, options) {
-    return this.http.post("/v1/gate/tokens", {
-      body: { api_key: this.apiKey, ...params },
-      skipAuth: true,
-      ...options
-    });
+    return this.http.post("/v1/gate/tokens", { body: params, ...options });
   }
   /**
-   * Validates a Gate access token and returns its decoded attributes.
+   * Validates a Gate access token and returns its attributes. An unknown, expired or
+   * foreign token, or one whose user you deactivated or deleted, is `{ active: false }`.
+   *
+   * When the subject is an end user, `orgs` lists their organizations in the key's
+   * project, read at the moment you ask.
    */
   async introspect(accessToken, options) {
     return this.http.post("/v1/gate/tokens/introspect", {
@@ -363,6 +978,51 @@ var TokensResource = class {
       ...options
     });
   }
+  /**
+   * Gets a **signed JWT** (ES256) for a signed-in end user's session, for a platform that
+   * verifies signatures instead of calling Gate (Supabase, an API gateway). The session
+   * token is the credential: no API key is sent.
+   *
+   * The token is valid for 15 minutes and **cannot be revoked**; its `orgs` claim is as old
+   * as the token. Every call mints a new one — ask again before the one you hold expires.
+   * A revoked or expired session, or a deactivated user, is a `401`.
+   *
+   * @example
+   * const { token } = await gate.tokens.createSigned(sessionToken);
+   */
+  async createSigned(sessionToken, options) {
+    const res = await this.http.get("/auth/sessions/whoami", {
+      query: { tokenize_as: "gate_jwt" },
+      sessionToken,
+      skipAuth: true,
+      ...options
+    });
+    const { tokenized, ...session } = res;
+    return { token: tokenized, session };
+  }
+  /**
+   * Verifies a Gate signed token offline against your tenant's public keys (fetched once
+   * and cached) and returns its claims. Throws `VerneTokenError` when the token must not
+   * be trusted — wrong issuer (another tenant), bad signature, expired, any algorithm but
+   * ES256. See {@link GateTokenVerifier} to verify without a Gate client.
+   *
+   * @example
+   * const claims = await gate.tokens.verifySigned(token, { tenantId: 'your-tenant-id' });
+   * claims.sub;  // the end user's id
+   */
+  async verifySigned(token, options) {
+    const cacheKey = `${options.tenantId}|${options.clockToleranceSeconds ?? ""}`;
+    let verifier = this.verifiers.get(cacheKey);
+    if (!verifier) {
+      verifier = new GateTokenVerifier({
+        tenantId: options.tenantId,
+        baseUrl: this.http.baseUrl,
+        clockToleranceSeconds: options.clockToleranceSeconds
+      });
+      this.verifiers.set(cacheKey, verifier);
+    }
+    return verifier.verify(token);
+  }
 };
 
 // src/resources/gate/gate.ts
@@ -374,20 +1034,31 @@ var Gate = class {
       timeoutMs: config.timeoutMs
     });
     this.identities = new IdentitiesResource(this.http);
-    this.tokens = new TokensResource(this.http, config.apiKey);
+    this.tokens = new TokensResource(this.http);
     this.settings = new SettingsResource(this.http);
+    this.organizations = new OrganizationsResource(this.http);
+    this.sessions = new SessionsResource(this.http);
+    this.auditLog = new AuditLogResource(this.http);
+    this.lifecycle = new LifecycleResource(this.http);
   }
   /**
-   * Checks whether a given subject is allowed to perform an action on a resource.
-   * This is the core building block for enforcing authorization in your services.
+   * Asks whether a subject may perform an action on a resource. The answer is a decision;
+   * your service enforces it.
+   *
+   * - `resource: 'organization:<id>'` — may this end user do `action` (a permission) in
+   *   that organization? `reason` is one of a fixed set and `role` is the role they hold.
+   *   Prefer `gate.organizations.authorize()` / `can()`, which build the resource.
+   * - any other resource — only *is `subject` one of your active end users?*; `reason` is
+   *   `owned_by_tenant` (allowed), `subject_inactive`, `not_owned_by_tenant` or
+   *   `not_a_known_identity`, and `message` says it in a sentence for your logs.
    *
    * @example
-   * const result = await gate.authorize({
-   *   subject: 'usr_123',
-   *   action: 'relay.messages.read',
-   *   resource: 'tenant:ten_001',
+   * const decision = await gate.authorize({
+   *   subject: userId,
+   *   action: 'invoices:write',
+   *   resource: `organization:${orgId}`,
    * });
-   * if (!result.allowed) throw new Error('Forbidden');
+   * if (!decision.allowed) throw new Error('Forbidden');
    */
   async authorize(params, options) {
     return this.http.post("/v1/gate/authorize", { body: params, ...options });
@@ -403,23 +1074,47 @@ var Gate = class {
    */
   async getEnabledProviders(tenantId, options) {
     const res = await this.http.get(
-      `/public/gate/providers/${encodeURIComponent(tenantId)}`,
+      `/public/gate/providers/${seg(tenantId)}`,
       { skipAuth: true, ...options }
     );
     return res.providers;
   }
   /**
-   * Initializes a Kratos login flow using your Gate API key. Call this from
-   * your server and pass the returned flow JSON to your browser-side code to
-   * render social login buttons. The flow already contains only the providers
-   * your tenant has enabled.
+   * Starts a Kratos login flow with your Gate API key and returns it; render its
+   * `ui.nodes` or post credentials to its `ui.action`. With a return URL registered,
+   * pass `return_to` and always a `state` for social login. A step-up (second factor) is
+   * `{ aal: 'aal2', session_token }`.
    *
    * @example
-   * const flow = await gate.createLoginFlow();
-   * // send `flow` to the browser as JSON
+   * const flow = await gate.createLoginFlow({ state: csrfBoundValue });
    */
-  async createLoginFlow(options) {
-    return this.http.get("/v1/gate/auth/login", options);
+  async createLoginFlow(params, options) {
+    return this.http.get("/v1/gate/auth/login", {
+      query: { return_to: params?.return_to, state: params?.state, aal: params?.aal },
+      sessionToken: params?.session_token,
+      ...options
+    });
+  }
+  /**
+   * Starts a Kratos registration flow. Refused with `402 ACTIVE_USER_LIMIT_REACHED` when
+   * the account is past its active-user limit and the month to move up has ended.
+   */
+  async createRegistrationFlow(params, options) {
+    return this.http.get("/v1/gate/auth/registration", {
+      query: { return_to: params?.return_to, state: params?.state },
+      ...options
+    });
+  }
+  /**
+   * Exchanges the one-time `code` your return URL received after a social login for the
+   * user's session. The code works once, for about 60 seconds, and only with a key of the
+   * project that started the login (otherwise `404`). Keep the session token server-side.
+   */
+  async exchangeOidcCode(code, options) {
+    return this.http.post("/v1/gate/auth/oidc/exchange", {
+      body: { code },
+      ...options
+    });
   }
 };
 
@@ -448,6 +1143,10 @@ var Passepartout = class {
    * Returns the current state of a login attempt. While the user hasn't
    * finished, `status` is `pending`; once done it becomes `completed` and
    * carries the `access_token` and `user`.
+   *
+   * Throws `VerneAPIError` with `403 account_disabled` when the person is deactivated,
+   * and `402 ACTIVE_USER_LIMIT_REACHED` when a *new* person signs in past the account's
+   * active-user limit (retrying does not help; existing users are unaffected).
    */
   async loginStatus(nonce, options) {
     return this.http.get(
@@ -474,7 +1173,13 @@ var MessagesResource = class {
   }
   /**
    * Publish an event to all endpoints subscribed to the given event_type.
-   * Automatically retries once on 429 (respects Retry-After header).
+   * Retries once on a short `429` (a `Retry-After` of a minute or less). The monthly
+   * message limit (`429 RELAY_MESSAGE_LIMIT_REACHED`, `Retry-After` until the 1st) is
+   * thrown at once, with `retryAfter` on the error.
+   *
+   * Safe to retry beyond that, if you pass an `idempotency_key`: a repeat
+   * returns the originally accepted message rather than creating a second event
+   * or failing.
    *
    * @returns The accepted message with its assigned ID and timestamp.
    */
@@ -485,12 +1190,12 @@ var MessagesResource = class {
    * Returns a paginated list of previously sent events for the current tenant.
    */
   async list(params, options) {
-    const query = buildQuery(params);
+    const query = buildQuery2(params);
     const path = query ? `/v1/relay/messages?${query}` : "/v1/relay/messages";
     return this.http.get(path, options);
   }
 };
-function buildQuery(params) {
+function buildQuery2(params) {
   if (!params) return "";
   const searchParams = new URLSearchParams();
   for (const [k, v] of Object.entries(params)) {
@@ -512,75 +1217,56 @@ var Relay = class {
 };
 
 // src/verne.ts
+var SERVICE_LABELS = {
+  relay: "Relay",
+  gate: "Gate",
+  passepartout: "Passepartout",
+  clockwork: "Clockwork"
+};
 var Verne = class {
   constructor(config) {
-    if (!config.relay && !config.gate && !config.passepartout && !config.clockwork) {
+    if (!config.apiKey && !config.relay && !config.gate && !config.passepartout && !config.clockwork) {
       throw new VerneError(
-        "At least one service key (relay, gate, passepartout, or clockwork) must be provided."
+        "No API key provided. Pass `apiKey` (or a per-service key: relay, gate, passepartout, clockwork)."
       );
     }
     this.config = config;
   }
   get relay() {
-    if (!this.config.relay) {
-      throw new VerneError(
-        "Relay API key not provided. Pass `relay` in the Verne constructor config."
-      );
-    }
-    this._relay ?? (this._relay = new Relay({
-      apiKey: this.config.relay,
-      baseUrl: this.config.baseUrl,
-      timeoutMs: this.config.timeoutMs
-    }));
+    this._relay ?? (this._relay = new Relay(this.serviceConfig("relay")));
     return this._relay;
   }
   get gate() {
-    if (!this.config.gate) {
-      throw new VerneError(
-        "Gate API key not provided. Pass `gate` in the Verne constructor config."
-      );
-    }
-    this._gate ?? (this._gate = new Gate({
-      apiKey: this.config.gate,
-      baseUrl: this.config.baseUrl,
-      timeoutMs: this.config.timeoutMs
-    }));
+    this._gate ?? (this._gate = new Gate(this.serviceConfig("gate")));
     return this._gate;
   }
   get passepartout() {
-    if (!this.config.passepartout) {
-      throw new VerneError(
-        "Passepartout API key not provided. Pass `passepartout` in the Verne constructor config."
-      );
-    }
-    this._passepartout ?? (this._passepartout = new Passepartout({
-      apiKey: this.config.passepartout,
-      baseUrl: this.config.baseUrl,
-      timeoutMs: this.config.timeoutMs
-    }));
+    this._passepartout ?? (this._passepartout = new Passepartout(this.serviceConfig("passepartout")));
     return this._passepartout;
   }
   get clockwork() {
-    if (!this.config.clockwork) {
+    this._clockwork ?? (this._clockwork = new Clockwork(this.serviceConfig("clockwork")));
+    return this._clockwork;
+  }
+  serviceConfig(service) {
+    const apiKey = this.config[service] ?? this.config.apiKey;
+    if (!apiKey) {
       throw new VerneError(
-        "Clockwork API key not provided. Pass `clockwork` in the Verne constructor config."
+        `${SERVICE_LABELS[service]} API key not provided. Pass \`apiKey\` (or \`${service}\`) in the Verne constructor config.`
       );
     }
-    this._clockwork ?? (this._clockwork = new Clockwork({
-      apiKey: this.config.clockwork,
-      baseUrl: this.config.baseUrl,
-      timeoutMs: this.config.timeoutMs
-    }));
-    return this._clockwork;
+    return { apiKey, baseUrl: this.config.baseUrl, timeoutMs: this.config.timeoutMs };
   }
 };
 
 exports.Clockwork = Clockwork;
 exports.Gate = Gate;
+exports.GateTokenVerifier = GateTokenVerifier;
 exports.Passepartout = Passepartout;
 exports.Relay = Relay;
 exports.Verne = Verne;
 exports.VerneAPIError = VerneAPIError;
 exports.VerneError = VerneError;
+exports.VerneTokenError = VerneTokenError;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map