@cboxdk/id-js 0.15.1 → 0.18.0

package/README.md

@@ -90,6 +90,167 @@ const user = await client.authenticate({
 });
 ```
 
+## Organizations
+
+A sign-in can be bound to one organization. The tokens then carry `org`, `org_name`, the
+person's membership tier in it (`org_role`), and the app `roles` / `permissions` they hold
+**there** — so switching organization means a new authorization, not a flag on the old
+session.
+
+```ts
+// Bind to an organization you already know (the person must be an active member):
+await client.createAuthorizationRequest({ organization: 'org_2x…' });
+
+// Always show the hosted organization picker, with your guess preselected:
+await client.createAuthorizationRequest({
+  prompt: 'select_organization',
+  organizationHint: 'org_2x…',
+});
+
+// Hosted "create a team" step; the person becomes its owner and the sign-in
+// continues bound to the new organization:
+await client.createAuthorizationRequest({ prompt: 'create_organization' });
+```
+
+| Option | Sent as | Meaning |
+|---|---|---|
+| `organization` | `organization` | Bind the sign-in to this organization. |
+| `organizationHint` | `organization_hint` | Preselect it in the picker; the person may choose another. |
+| `prompt: 'select_organization'` | `prompt=select_organization` | Always show the picker. |
+| `prompt: 'create_organization'` | `prompt=create_organization` | Create an organization first. |
+
+`organization` cannot be combined with either organization prompt — it has already made
+the choice they ask the person to make — and the SDK refuses the combination rather than
+sending it. Use `organizationHint` with the picker instead.
+
+### Switching
+
+`switchOrganization(id)` is `createAuthorizationRequest({ organization: id })` under a name
+that says what it is for. Persist and redirect exactly as for a sign-in; Cbox ID already
+has the person's session, so they normally come straight back without seeing a form.
+
+```ts
+// app/auth/switch-organization/route.ts (Next.js)
+import { NextResponse, type NextRequest } from 'next/server';
+import { cboxId } from '@/lib/cbox';
+
+export async function GET(request: NextRequest) {
+  const org = request.nextUrl.searchParams.get('org');
+  if (!org) return NextResponse.redirect(new URL('/', request.url));
+  return cboxId.switchOrganization(org);
+}
+```
+
+**The binding is checked, not trusted.** The request echoes `organization`; persist it with
+`state`, `codeVerifier` and `nonce` and pass it back as `stored.organization`, and
+`authenticate()` refuses tokens for any other organization. (The Next.js adapter does this
+in a cookie for you.) An instance that predates organization selection ignores the
+parameter and answers for whichever organization the session already had — without the
+check, your app would show the new organization's name over the old one's data.
+
+Replace your session with the user the callback returns rather than patching the old one:
+`org_role`, `roles` and `permissions` can all differ between organizations. A person who
+is not (or no longer) an active member comes back with `error=access_denied`:
+
+```ts
+import { AuthenticationError } from '@cboxdk/id-js';
+
+try {
+  user = await cboxId.callback(request);
+} catch (e) {
+  if (e instanceof AuthenticationError && e.error === 'access_denied') {
+    // Not a member of that organization — send them back to the one they were in.
+  }
+}
+```
+
+### Listing a person's organizations
+
+Request the `organizations` scope and `user.organizations` lists every organization the
+person is an active member of — `{ id, name, role }` — for an organization switcher. It is
+a separate scope because it discloses memberships across unrelated customers; a plain
+`profile` sign-in does not get it.
+
+### Reading the claims
+
+The signed-in user carries them typed:
+
+```ts
+user.organization; // { id, name, role } | null — role is 'owner' | 'admin' | 'developer' | 'member' | 'viewer' | null
+user.roles;        // string[]
+user.permissions;  // string[]
+user.actor;        // { sub, actor } | null — see support sessions below
+user.sessionId;    // the id_token's `sid` | null — keep it to match a back-channel logout
+```
+
+The same helpers work on the user and on a claim set you verified yourself, such as an
+access token's payload on a resource server:
+
+```ts
+import { organization, hasPermission, hasRole, isSupportSession } from '@cboxdk/id-js';
+
+if (!hasPermission(payload, 'invoices:create')) return forbidden();
+if (organization(user)?.role === 'owner') showBilling();
+```
+
+Matching is exact — `invoices:*` does not grant `invoices:delete`. An `org_role` this SDK
+version does not recognise reads as `null`, never as a tier it would have to guess.
+
+### Support sessions
+
+A staff member can act as one of your users for a limited time (at most an hour, no refresh
+token, with a recorded reason). Those tokens carry the RFC 8693 `act` claim naming the
+staff member, and `isSupportSession()` reports it:
+
+```ts
+if (isSupportSession(user)) {
+  // Show a banner, and refuse what a helper should never do on someone's behalf:
+  // changing their password, their email, their payout details.
+}
+```
+
+It is **fail-closed**: any `act` claim counts, including one whose shape the SDK cannot
+read (`user.actor.sub` is then `null`). A claim it cannot parse is not evidence that nobody
+else is at the keyboard.
+
+## From a CLI (device flow)
+
+A command-line tool has no browser to redirect, and neither does a CI job, a container or
+a TV app. The device authorization grant (RFC 8628) is for all of them: your program
+prints a short code, the person approves it on whatever device is already in their hand,
+and your program collects the tokens.
+
+Register the app as **"CLI or device"** in the console. It is issued **no secret** — a
+binary on somebody's laptop cannot keep one — and has **no redirect URI**, so neither
+appears here:
+
+```ts
+import { CboxIdClient } from '@cboxdk/id-js';
+
+const cbox = new CboxIdClient({
+  issuer: process.env.CBOX_ID_ISSUER!,
+  clientId: process.env.CBOX_ID_CLIENT_ID!,
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
+});
+
+const auth = await cbox.requestDeviceAuthorization();
+console.log(`Open ${auth.verificationUri} and enter ${auth.userCode}`);
+
+// Blocks until they approve. Honours the server's interval, backs off on `slow_down`,
+// and stops on a decline or an expired code. Pass an AbortSignal so Ctrl-C works.
+const user = await cbox.pollDeviceToken(auth);
+console.log(`Signed in as ${user.email}`);
+// Persist user.refreshToken (mode 0600) so the next run does not ask again.
+```
+
+The scopes are bounded by what the app is **registered** for: a device request naming one
+outside that ceiling is refused with `invalid_scope` rather than quietly reduced, because
+no browser is in front of it to notice a smaller grant. Keep `offline_access` unless you
+want the person re-approving every hour.
+
+See [Sign in from a CLI](https://github.com/cboxdk/cbox-id/blob/main/docs/getting-started/sign-in-from-a-cli.md)
+for the protocol itself and where to store the tokens.
+
 ## In the browser (publishable keys)
 
 Everything above needs a server: it holds your client secret. A **publishable key** is the
@@ -239,6 +400,47 @@ everywhere" needs. `machineToken`, `introspect` and `revoke` authenticate as the
 client, so they require a `clientSecret`; `userinfo` authenticates with the user's
 own access token and does not.
 
+## API keys for your API
+
+Your customers can create API keys for **your** API on Cbox ID's hosted page, and your API
+asks Cbox ID whether a key it was handed is good. Link people to the page:
+
+```ts
+client.apiKeysUrl({ returnTo: 'https://app.acme.com/settings' });
+// → {issuer}/account/api-keys?client_id=<your client>&return_to=…
+// options: clientId (another of your apps), returnTo, organization (which of theirs)
+```
+
+Verify a key on your server — never in a browser, since it uses your client secret. It
+lives in its own entry, `@cboxdk/id-js/server`, so a browser bundle never pulls it in:
+
+```ts
+import { ApiKeyVerifier } from '@cboxdk/id-js/server';
+import { hasPermission } from '@cboxdk/id-js';
+
+const keys = new ApiKeyVerifier({ issuer, clientId, clientSecret, cacheTtlMs: 10_000 });
+
+const answer = await keys.verifyApiKey(request.headers.get('x-api-key') ?? '');
+if (!answer.active) return new Response(null, { status: 401 });
+if (!hasPermission(answer, 'invoices:create')) return new Response(null, { status: 403 });
+// answer: { active, key_id, sub, org, org_role, permissions, client_id, expires_at }
+```
+
+On Next.js the adapter does the same with its own configuration:
+`await cboxId.verifyApiKey(key)` and `cboxId.apiKeysUrl()`.
+
+- Every bad key — unknown, revoked, expired, another app's, a holder who left the
+  organization — is `{ active: false }`, with no reason. That is Cbox ID's design, so the
+  endpoint cannot be used to probe keys.
+- `permissions` is already re-capped to what the holder holds for your app **now**; a
+  demotion takes effect on the next verification.
+- An answer naming another app's `client_id` is refused with an `AuthenticationError`, as
+  is a failed call (wrong client credentials, instance unreachable). Treat a throw as "do
+  not let this request in".
+- `cacheTtlMs` (off by default, at most 60 seconds) caches **active** answers per key, never
+  past the key's `expires_at`. While an answer is cached, a revoked key keeps working —
+  keep it short. Refusals are never cached.
+
 ## Migrating off an old login
 
 Bulk-importing users with their existing hashes is the first answer, and the better one.
@@ -304,6 +506,26 @@ const ok = await verifyWebhook({
 });
 ```
 
+### Standard Webhooks
+
+An endpoint registered with `signature_scheme: 'standard_webhooks'` (or switched with
+`env.webhooks.signatureScheme.change(id, { signature_scheme: 'standard_webhooks' })`) is
+signed the [Standard Webhooks](https://www.standardwebhooks.com/) way: `webhook-id`,
+`webhook-timestamp` and `webhook-signature`. Verify it with `verifyStandardWebhook`:
+
+```ts
+import { verifyStandardWebhook } from '@cboxdk/id-js';
+
+const ok = await verifyStandardWebhook({
+  payload: rawBody,            // the exact bytes received
+  headers: request.headers,    // a Headers object or a plain record
+  secret: process.env.CBOX_ID_WEBHOOK_SECRET!, // whsec_…, or the endpoint's old 64-hex secret
+});
+```
+
+It accepts any valid `v1` signature among several (sent while a secret rotates), uses the same
+5-minute freshness window, and never throws.
+
 ## Token Vault
 
 Broker downstream credentials (API keys for OpenAI, GitHub, …) through the instance's
@@ -334,8 +556,8 @@ claims for you to enforce. Requires the app's client to hold the `apps.manifest`
 ```ts
 import { defineAuthz, publishManifest } from '@cboxdk/id-js';
 
-// Declare the catalog (validated: keys are `feature:action`, roles must reference
-// declared permissions). Keep this next to the code that enforces it.
+// Declare the catalog (validated: keys are lowercase `feature:action` slugs, and roles
+// must reference declared permissions). Keep this next to the code that enforces it.
 export const authz = defineAuthz({
   permissions: [
     { key: 'invoices:create', description: 'Create invoices' },
@@ -360,11 +582,239 @@ const summary = await publishManifest(
 // → { unchanged, roles_declared, permissions_declared, ... }
 ```
 
+### Staff roles and self-serve permissions
+
+Two flags decide who may hand something out:
+
+- **`tenantAssignable: false` on a role** makes it a **staff role** — for your own support
+  or operations people, held environment-wide across every customer. Cbox ID never lists
+  or accepts it on an organization's own admin pages; only an environment administrator
+  can grant it. Roles default to `true`.
+- **`tenantAssignable: true` on a permission** lets an organization's administrators put it
+  in custom roles they build themselves. Permissions default to `false`: internal unless
+  you opt in.
+
+```ts
+export const authz = defineAuthz({
+  permissions: [
+    { key: 'parcels:read', description: 'View parcels', tenantAssignable: true },
+    // Lets a staff member start a support session in this app (see "Support sessions").
+    { key: 'support:impersonate', description: 'Act as a customer' },
+  ],
+  roles: [
+    { key: 'viewer', name: 'Viewer', permissions: ['parcels:read'] },
+    { key: 'support', name: 'Support', description: 'Our support team',
+      permissions: ['support:impersonate', 'parcels:read'], tenantAssignable: false },
+  ],
+});
+```
+
+On the wire the flags are `tenant_assignable`, and only their non-default state is sent
+(`false` on a role, `true` on a permission). Both are part of the manifest's `version`, so
+marking a role staff-only in a new deploy re-syncs it rather than being skipped as
+unchanged. A value that is not a real boolean — the string `"false"` from a YAML file, say
+— is refused, because it would otherwise read as the opposite of what it says.
+
 `publishManifest` mints a client-credentials token (`scope=apps.manifest`) and POSTs
 the manifest to `{issuer}/api/v1/apps/manifest`. It is a server-side operation — keep
 your `clientSecret` off the browser. The wire format matches the PHP SDK
 (`cboxdk/laravel-id-client`), so any SDK can publish the same catalog.
 
+## Management API
+
+`@cboxdk/id-js/management` is a typed client for Cbox ID's management planes. It is
+generated from the OpenAPI documents the server publishes, so every method, path, scope and
+type matches the server you generated it from. Use it from server code only: every client
+holds a management credential.
+
+| Client | Plane | Credential | `baseUrl` |
+| --- | --- | --- | --- |
+| `EnvironmentClient` | One environment's tenancy: organizations, users, apps, roles, SSO, audit logs… | `cbid_env_…` key, or a delegated access token | The environment's own host, or the platform root with `environment` |
+| `WorkspaceClient` | The workspace above its environments: projects, environments, team, keys | `cbid_ws_…` key, or a person's root token | `https://api.cboxid.com` (default) |
+| `PlatformClient` | The deployment itself, for operators | Delegated operator token only | `https://api.cboxid.com` (default) |
+| `AccountClient` | A person's own account | Delegated token only | The environment's own host |
+
+Method names are the server's action names: `apps.secrets.rotate` is
+`env.apps.secrets.rotate(...)`, and `sso.connections.require_sso` is
+`env.sso.connections.requireSso(...)`. Path parameters come first, in path order, then the body
+(or the query, for a read), then per-call options. Every call resolves to
+`{ data, meta, body, status, replayed, idempotencyKey, requestId, headers }`.
+
+### Create an app and rotate its secret
+
+```ts
+import { EnvironmentClient, CboxIdApiError, ApprovalDeniedError } from '@cboxdk/id-js/management';
+
+const env = new EnvironmentClient({
+  baseUrl: 'https://acme.cboxid.com',
+  apiKey: process.env.CBOX_ID_ENV_KEY!, // cbid_env_…
+  onApprovalRequired: (approval, { action }) => {
+    console.log(`Approve ${action} on your device. Code: ${approval.binding_code}`);
+  },
+});
+
+const { data: app } = await env.apps.create({
+  name: 'Billing',
+  type: 'web',
+  redirect_uris: ['https://billing.acme.com/callback'],
+});
+// app.client_secret is in this response and in no other. Store it now.
+
+try {
+  const { data: secret } = await env.apps.secrets.rotate(app.id, { grace_seconds: 3600 });
+  // secret.client_secret: the new secret, shown once.
+} catch (e) {
+  if (e instanceof ApprovalDeniedError) console.log('Rotation was declined.');
+  else if (e instanceof CboxIdApiError && e.isValidationError) console.log(e.errors);
+  else throw e;
+}
+```
+
+When a key's policy holds an action for a person's approval, the server answers
+`202 approval_required`. By default the client calls `onApprovalRequired` (show the
+`binding_code` so the person can match it on their device), polls the approval, and repeats the
+request with `Cbox-Approval: <id>` and the same `Idempotency-Key` once it is approved.
+`ApprovalDeniedError` and `ApprovalExpiredError` are thrown when it is denied or expires. If you
+do not want to wait in the same call, pass `{ approval: 'return' }`:
+
+```ts
+const outcome = await env.apps.secrets.rotate(app.id, { grace_seconds: 0 }, { approval: 'return' });
+if (outcome.pending) {
+  console.log(`Code: ${outcome.approval.binding_code}`);
+  const { data } = await outcome.resume(); // polls, then repeats the request
+}
+```
+
+### Bootstrap an environment from a workspace key
+
+```ts
+import { WorkspaceClient, EnvironmentClient } from '@cboxdk/id-js/management';
+
+const workspace = new WorkspaceClient({ apiKey: process.env.CBOX_ID_WS_KEY! }); // cbid_ws_…
+
+const { data: created } = await workspace.environments.create({
+  name: 'Staging',
+  type: 'sandbox',
+  initial_key: { name: 'bootstrap', scopes: ['apps:write', 'organizations:write'] },
+});
+
+// The first management key, returned once. On an idempotent replay it is null.
+const env = new EnvironmentClient({ baseUrl: created!.issuer!, apiKey: created!.initial_key!.token! });
+await env.organizations.create({ name: 'Acme', slug: 'acme' });
+```
+
+### Idempotency, retries and errors
+
+- Every `POST`, `PUT`, `PATCH` and `DELETE` sends an `Idempotency-Key`, a fresh UUID unless you
+  pass `{ idempotencyKey }`. Network failures, `5xx`, `429` and `409 idempotency_in_progress` are
+  retried with the **same** key (`retry: { maxRetries, baseDelayMs, maxDelayMs }`; default 3
+  retries). `Retry-After` is respected; one longer than `maxDelayMs` is thrown instead of waited
+  out. `replayed` is `true` when the server returned the first request's stored answer
+  (`Idempotent-Replayed`). A secret in a replayed answer is `null`.
+- A failed call throws `CboxIdApiError` with `status`, `error` (the stable code), `message`,
+  `errors` (field-keyed, on `validation_failed`), `requestId` (the envelope's `request_id`,
+  else the `X-Request-Id` header; quote it when reporting a problem) and `retryAfter`. A call that never
+  got an answer throws `ManagementNetworkError`, which carries the `idempotencyKey` so you can
+  repeat the request safely.
+- The client never logs. Secrets in responses are returned as they arrive, and request bodies
+  are never put in an error.
+
+### One token for every environment
+
+A person's access token issued at the platform root reaches the workspace, account and
+operator planes there, and any environment of their workspace when the request names it with
+`Cbox-Environment`. Pass `environment` (an id or slug) and the root host as `baseUrl`:
+
+```ts
+const staging = new EnvironmentClient({
+  baseUrl: 'https://api.cboxid.com',
+  accessToken: () => tokens.current(), // the person's root token
+  environment: 'acme-staging',         // sent as Cbox-Environment on every request
+});
+await staging.organizations.portalLinks.create(orgId, { intents: ['sso', 'dsync'] });
+```
+
+What the token may do there is bounded by the person's role and the token's scopes. A
+`cbid_env_…` key is bound to its own environment's host, so `environment` is refused with one.
+
+### Lists
+
+Every paged list also has an `…All` variant that iterates every item, fetching pages as you
+reach them. It follows `meta.next_cursor` on the environment plane and `meta.next_page` on the
+workspace plane:
+
+```ts
+for await (const org of env.organizations.listAll({ status: 'active' })) {
+  console.log(org.id, org.name);
+}
+```
+
+### Audit Logs
+
+Your app records what its users did, per organization (your customer), and Cbox ID keeps
+each organization's events in a tamper-evident hash chain. `AuditLogger` buffers events and
+sends them in batches of up to 100, each batch under its own `Idempotency-Key`. It sends a
+batch when it is full, every `flushIntervalMs` (default 5 s), and on `flush()` / `close()`. A
+batch that fails stays queued with the same key, so sending it again never records an event
+twice:
+
+```ts
+import { AuditLogger, exportAuditLogs, verifyAuditLogChain } from '@cboxdk/id-js/management';
+
+const audit = new AuditLogger(env, { onError: (e) => console.error('audit flush failed', e) });
+
+audit.record({
+  organization_id: org.id,
+  action: 'invoice.voided',
+  actor: { id: user.id, type: 'user', name: user.name },
+  targets: [{ id: invoice.id, type: 'invoice' }],
+  context: { location: request.ip, user_agent: request.headers['user-agent'] },
+  metadata: { reason: 'duplicate' },
+}); // occurred_at defaults to now
+
+await audit.close(); // on shutdown: stop the timer and send what is left
+```
+
+Read events with `env.auditLogs.events.listAll({ organization_id, actions, range_start })`.
+To get a CSV, `exportAuditLogs(env, filters)` starts an export and polls it until it is ready.
+Its `url` is signed and short-lived. To check the chain yourself instead of trusting the
+server's `env.auditLogs.verify()`, call `verifyAuditLogChain(env, { organization_id })` or
+`verifyAuditChain(events)`. They recompute `sha256(prev_hash + canonical JSON)` exactly as
+the server does: keys sorted at every depth, and slashes and Unicode unescaped. They report
+`{ valid, reason, broken_at_sequence, … }`. Keep floats out of metadata you want to verify:
+`1.0` and `1` arrive as the same JavaScript number.
+
+### Delegated tokens and DPoP
+
+Pass `accessToken` (a string, or a function that is called before every request so it can
+refresh) instead of `apiKey`. For a DPoP-bound token, pass a signer built from the key pair the
+token was bound to:
+
+```ts
+import { AccountClient, createDPoPSigner } from '@cboxdk/id-js/management';
+
+const me = new AccountClient({
+  baseUrl: 'https://acme.cboxid.com',
+  accessToken: () => tokens.current(),
+  dpop: await createDPoPSigner(keyPair), // ES256, WebCrypto
+});
+await me.sessions.revokeOthers();
+```
+
+### Types, metadata and regenerating
+
+Schema and operation types are exported per plane as namespaces (`EnvironmentApi.App`,
+`WorkspaceApi.EnvironmentsCreateBody`). The operation tables (`environmentOperations`, …) list
+each action's method, path, scope, danger and whether it can be held for approval, which is
+useful for showing a confirmation before a `critical` action. `env.request(method, path, input)`
+calls a route that is not generated.
+
+The specs are vendored in `openapi/`. `npm run generate` (Node 22.6 or later) regenerates
+`src/management/generated/` from them, and
+`npm run generate -- --fetch environment=https://acme.cboxid.com` (or `workspace=`, `platform=`,
+`account=`, `all=`) refreshes a vendored spec from a running server first. The test suite fails
+when the generated code and the vendored specs disagree.
+
 ## Security & scope
 
 Login is hardened by default — PKCE, `state`, nonce, and full `id_token` verification
@@ -372,8 +822,9 @@ Login is hardened by default — PKCE, `state`, nonce, and full `id_token` verif
 freshness window. Keep `clientSecret` and webhook secrets server-side.
 
 This is a **client**. It authenticates users and calls a Cbox ID instance's standard
-endpoints; it does not configure SSO, run SCIM, or manage organizations — those are
-platform capabilities of [`cboxdk/laravel-id`](https://github.com/cboxdk/laravel-id).
+endpoints. The management planes (organizations, apps, SSO, keys…) are reached through
+[`@cboxdk/id-js/management`](#management-api), which only calls the instance's published API;
+the capabilities themselves live in [`cboxdk/laravel-id`](https://github.com/cboxdk/laravel-id).
 
 Report vulnerabilities via this repo's GitHub **Private Vulnerability Reporting**.
 

package/dist/chunk-2E25IPBA.js

@@ -0,0 +1,155 @@
+import { assertSecureIssuer } from './chunk-QQW63PGU.js';
+import { ConfigurationError, AuthenticationError, oauthError } from './chunk-SEUD4TE4.js';
+
+// src/api-keys.ts
+var MAX_API_KEY_CACHE_TTL_MS = 6e4;
+var MAX_CACHE_ENTRIES = 1e3;
+var ORGANIZATION_ROLES = /* @__PURE__ */ new Set([
+  "owner",
+  "admin",
+  "developer",
+  "member",
+  "viewer"
+]);
+var ApiKeyVerifier = class {
+  constructor(config) {
+    this.config = config;
+    if (typeof globalThis.document !== "undefined") {
+      throw new ConfigurationError(
+        "API key verification uses your client secret and must run on your server, never in a browser."
+      );
+    }
+    if (!config.issuer || !config.clientId || !config.clientSecret) {
+      throw new ConfigurationError("Verifying API keys needs issuer, clientId and clientSecret.");
+    }
+    assertSecureIssuer(config.issuer);
+    const cacheTtlMs = config.cacheTtlMs ?? 0;
+    if (!Number.isFinite(cacheTtlMs) || cacheTtlMs < 0 || cacheTtlMs > MAX_API_KEY_CACHE_TTL_MS) {
+      throw new ConfigurationError(
+        `cacheTtlMs must be between 0 and ${MAX_API_KEY_CACHE_TTL_MS}: a cached answer keeps a revoked key working for that long.`
+      );
+    }
+    this.endpoint = `${config.issuer.replace(/\/$/, "")}/oauth/api-keys/verify`;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+    this.cacheTtlMs = cacheTtlMs;
+  }
+  config;
+  endpoint;
+  timeoutMs;
+  cacheTtlMs;
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Ask Cbox ID whether `key` is good for this app, and what it may do.
+   *
+   * Resolves `{ active: false }` for every kind of bad key, without a request for an empty
+   * one. Throws `AuthenticationError` when the call itself fails (wrong client
+   * credentials, an unreachable instance) or when the answer cannot be trusted — one that
+   * names another app's `client_id`, or does not have the promised shape. Both mean "do
+   * not let this request in"; the difference is that a throw is something to look at.
+   */
+  async verifyApiKey(key) {
+    if (typeof key !== "string" || key.trim() === "") {
+      return { active: false };
+    }
+    const cacheKey = this.cacheTtlMs > 0 ? await digest(key) : null;
+    if (cacheKey !== null) {
+      const hit = this.cache.get(cacheKey);
+      if (hit && hit.until > Date.now()) {
+        return hit.answer;
+      }
+      this.cache.delete(cacheKey);
+    }
+    const answer = this.parse(await this.request(key));
+    if (cacheKey !== null && answer.active) {
+      this.remember(cacheKey, answer);
+    }
+    return answer;
+  }
+  async request(key) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          authorization: `Basic ${btoa(`${this.config.clientId}:${this.config.clientSecret}`)}`,
+          accept: "application/json",
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        body: new URLSearchParams({ key }),
+        signal: controller.signal
+      });
+    } catch (error) {
+      throw new AuthenticationError(`API key verification request failed: ${String(error)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) {
+      throw await oauthError(response, "API key verification failed");
+    }
+    return response.json().catch(() => null);
+  }
+  parse(body) {
+    if (typeof body !== "object" || body === null) {
+      throw new AuthenticationError("API key verification returned a body that is not a JSON object.");
+    }
+    const record = body;
+    if (record["active"] !== true) {
+      return { active: false };
+    }
+    const keyId = record["key_id"];
+    const sub = record["sub"];
+    const org = record["org"];
+    const clientId = record["client_id"];
+    const expiresAt = record["expires_at"];
+    const permissions = record["permissions"];
+    if (!nonEmpty(keyId) || !nonEmpty(sub) || !nonEmpty(org) || !nonEmpty(clientId) || !Array.isArray(permissions) || expiresAt !== null && expiresAt !== void 0 && typeof expiresAt !== "string") {
+      throw new AuthenticationError("API key verification returned an active answer without the promised fields.");
+    }
+    if (clientId !== this.config.clientId) {
+      throw new AuthenticationError(
+        `API key verification answered for client ${clientId}, not this app (${this.config.clientId}); refusing it.`
+      );
+    }
+    if (typeof expiresAt === "string") {
+      const expiry = Date.parse(expiresAt);
+      if (Number.isNaN(expiry) || expiry <= Date.now()) {
+        return { active: false };
+      }
+    }
+    const role = record["org_role"];
+    return {
+      active: true,
+      key_id: keyId,
+      sub,
+      org,
+      org_role: typeof role === "string" && ORGANIZATION_ROLES.has(role) ? role : null,
+      permissions: permissions.filter((value) => nonEmpty(value)),
+      client_id: clientId,
+      expires_at: typeof expiresAt === "string" ? expiresAt : null
+    };
+  }
+  remember(cacheKey, answer) {
+    const expiry = answer.expires_at === null ? Number.POSITIVE_INFINITY : Date.parse(answer.expires_at);
+    const until = Math.min(Date.now() + this.cacheTtlMs, expiry);
+    if (this.cache.size >= MAX_CACHE_ENTRIES) {
+      const oldest = this.cache.keys().next();
+      if (!oldest.done) {
+        this.cache.delete(oldest.value);
+      }
+    }
+    this.cache.set(cacheKey, { answer, until });
+  }
+};
+function nonEmpty(value) {
+  return typeof value === "string" && value !== "";
+}
+async function digest(key) {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(key));
+  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+export { ApiKeyVerifier, MAX_API_KEY_CACHE_TTL_MS };
+//# sourceMappingURL=chunk-2E25IPBA.js.map
+//# sourceMappingURL=chunk-2E25IPBA.js.map