@cboxdk/id-js 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+All notable changes to `@cboxdk/id-js` are recorded here. Earlier releases are described
+in their [GitHub releases](https://github.com/cboxdk/id-js/releases).
+
+## [0.20.0] - 2026-11-07
+
+### Upgrade
+
+Workspace team.remove requires its body with roles_version. Team writes use roles arrays and current CAS versions. Re-read state on conflicts. Live permission checks bind subject, organization and app; access-token role projections alone do not authorize sensitive actions.
+
+### Added
+
+- `checkPermissions()` and `PermissionDecision` for current server authorization, bound to the exact subject, organization and app. Decisions are never cached; malformed, redirected, oversized or unavailable responses fail closed.
+- Updated management clients for multiple app roles, independent role and environment-access versions, scoped invitations and nullable member email.
+
+### Changed
+
+- Manifest publication requires a complete acknowledgement for the submitted client, version and checksum, including valid publication counts. Publishing definitions never assigns access.
+- Workspace member removal now requires `roles_version` and removes native ID app roles only. Role edits require `roles` and `roles_version`; environment access uses its separate version.
+
+## [0.19.0] - 2026-10-10
+
+Needs laravel-id 1.24 / the Cbox ID release with feature flags, fine-grained
+authorization, Pipes and SMS as a second factor. Against an older instance the new claim
+reads as absent and the new endpoints answer 404.
+
+### Added
+
+- Feature flags: `featureFlags(source)` and `hasFeature(source, key)` read the
+  `feature_flags` claim from a signed-in user or a verified claim set, and
+  `CboxUser.featureFlags` carries it (`null` when the scope was not requested, `[]` when
+  nothing is on). `FEATURE_FLAGS_SCOPE` is the scope to request.
+- Management API regenerated from the current specs: `env.featureFlags.*` (including
+  `evaluate({ user_id, organization_id })`), `env.fga.*` (check, `checkBatch`, tuples
+  write/delete/list, resources and subjects lists, schema get/update/validate, with
+  `consistency_token` on every read), `env.pipes.*` (pipe setup, grants, connections),
+  `env.radar.*`, `env.signin.sms.*`, the environment sign-in methods (`env.signin.social.*`
+  update/enable/disable/inherit/offered, `environment_wide` / `organization_id` on social
+  set, the auth policy's method fields), `env.branding.appearance.set()` taking the logo and
+  favicon as base64 data URIs, `env.users.mfa.sms.remove()`, the HRIS directory
+  routes (`env.directories.*`), and on the account plane `me.mfa.sms.remove()` and
+  `me.pipes.disconnect()`. `fgaTuple()` writes a tuple in the notation the batch check takes.
+- Pipes: `VaultClient.leasePipeToken(provider, { userId?, purpose })` leases a fresh token
+  for a person's connected account. Refusals are typed: `PipeNotConnectedError` and
+  `PipeReauthorizationRequiredError` carry `connectUrl` (and `connectUrlWith({ clientId,
+  returnTo })`), `PipeTemporarilyUnavailableError` carries `retryAfter`,
+  `PipeLeaseDeniedError` is the 403. `client.pipeConnectUrl(provider, returnTo)` and
+  `pipeConnectUrl()` build the hosted connect page.
+- `CboxIdFrontend.config({ organization })`: the sign-in document for one organization (by
+  id or slug), whose `social` list is exactly what that organization's hosted page offers.
+  Each organization is cached on its own. `FrontendConfig.methods` says whether passkeys and
+  magic links are switched on.
+- Embedded sign-in: `mfa_required` lists the `factors` the person can answer with,
+  `CboxIdFrontend.sendSmsCode(mfaToken)` texts the code, and `submitSecondFactor()` accepts
+  `'sms'`.
+
+### Changed
+
+- The generator reads an action's own `202 Accepted` body (documented as `oneOf` it and the
+  approval body), so `env.directories.sync()` now returns the directory.
+
+## [0.18.0] - 2026-10-08
+
+### Added
+
+- `verifyStandardWebhook()`: verifies deliveries from an endpoint on the `standard_webhooks`
+  signature scheme (`webhook-id` / `webhook-timestamp` / `webhook-signature`, any valid `v1`
+  signature, 5-minute window). Takes a `whsec_…` secret or an endpoint's 64-hex Cbox secret.
+  Tested against the Standard Webhooks specification's vector.
+
+- `@cboxdk/id-js/management`: typed clients for Cbox ID's management planes, generated from
+  the OpenAPI documents the server publishes. `EnvironmentClient` (an environment's own host,
+  `cbid_env_…` key or delegated token), `WorkspaceClient` (`cbid_ws_…` key), `PlatformClient`
+  (operator token) and `AccountClient` (a person's own token). Methods are named after the
+  server's actions (`env.apps.secrets.rotate(id, body)`, `workspace.environments.create(body)`),
+  with typed bodies, queries and responses.
+- Every write sends an `Idempotency-Key` (a fresh UUID unless you pass one) and is retried
+  with the same key on network failures, `5xx`, `429` and `409 idempotency_in_progress`,
+  respecting `Retry-After`. `replayed` reports `Idempotent-Replayed`.
+- Approvals: a `202 approval_required` calls `onApprovalRequired` (show the binding code),
+  polls the approval and repeats the request with `Cbox-Approval` and the same key.
+  `ApprovalDeniedError` and `ApprovalExpiredError` when it is not approved;
+  `{ approval: 'return' }` hands back the pending approval with a `resume()`.
+- `CboxIdApiError` (`status`, `error`, `message`, `errors`, `requestId` from the envelope's
+  `request_id` or `X-Request-Id`, `retryAfter`) and `ManagementNetworkError` (with the
+  `idempotencyKey` to repeat safely).
+- `environment` on `EnvironmentClient`: with a person's root access token and the platform
+  root as `baseUrl`, it sends `Cbox-Environment` so one token can drive any environment of
+  the workspace.
+- Audit Logs helpers: `AuditLogger` (buffers events and sends batches of up to 100, each
+  with its own Idempotency-Key, on size, interval and `flush()`), `exportAuditLogs()`
+  (creates an export and polls it until ready), and `verifyAuditChain()` /
+  `verifyAuditLogChain()` with `canonicalJson()` and `auditEventHash()`, which recompute an
+  organization's hash chain exactly as the server does.
+- `…All` async iterators on every paged list (cursor and page-number paging).
+- DPoP-bound access tokens: `createDPoPSigner()` and `generateDPoPKeyPair()` (ES256 on
+  WebCrypto, with `DPoP-Nonce` challenge handling).
+- Operation tables (`environmentOperations`, …) with each action's method, path, scope, danger
+  (from the spec's `x-scope` / `x-danger`) and whether it can be held for approval.
+- `npm run generate` regenerates the clients from the vendored specs in `openapi/`, and
+  `--fetch <plane>=<host>` refreshes a spec from a running server first. The test suite fails
+  when the two disagree.
+
+## [0.17.0] - 2026-09-24
+
+Organization selection and support sessions. Needs a Cbox ID instance that understands the
+`organization` / `organization_hint` authorize parameters and emits `org_role` and `act`
+(laravel-id 1.19). Against an older instance the new fields stay empty, and a switch fails
+at the callback instead of silently landing in the old organization (see below).
+
+### Added
+
+- `createAuthorizationRequest()` accepts `organization` (bind the sign-in to one
+  organization), `organizationHint` (preselect it in the hosted picker), and the prompts
+  `select_organization` and `create_organization`.
+- `client.switchOrganization(id)` and, on the Next.js adapter,
+  `cboxId.switchOrganization(id)`: a new authorization bound to another organization.
+- The organization a sign-in was bound to is echoed on the `AuthorizationRequest` and
+  verified at the callback (`stored.organization`): tokens for any other organization are
+  refused. The Next.js adapter carries it in a `cbox_id_organization` cookie, and clears
+  that cookie on a plain sign-in so an abandoned switch cannot leak its binding into it.
+- `CboxUser` gains typed `organization` (`{ id, name, role }` from `org`, `org_name`,
+  `org_role`), `roles`, `permissions` and `actor` (the RFC 8693 `act` claim).
+- Claim helpers that work on a `CboxUser` or on a claim set you verified yourself:
+  `organization()`, `actor()`, `isSupportSession()`, `roles()`, `permissions()`,
+  `hasRole()`, `hasPermission()`.
+- `client.apiKeysUrl({ clientId?, returnTo?, organization? })` (and `cboxId.apiKeysUrl()`
+  on the Next.js adapter): the hosted page where a person creates and revokes API keys for
+  your API, `/account/api-keys`, preselected to this app.
+- `ApiKeyVerifier` in a new server-only entry, `@cboxdk/id-js/server`, and
+  `cboxId.verifyApiKey(key)` on the Next.js adapter: verifies a customer API key with
+  `POST /oauth/api-keys/verify` (HTTP Basic client auth) and returns the typed answer
+  `{ active, key_id, sub, org, org_role, permissions, client_id, expires_at }`. It refuses
+  an answer for any other `client_id`, treats a key past `expires_at` as inactive, refuses
+  to run in a browser, and has an optional cache of active answers (`cacheTtlMs`, at most
+  60 s, never past the key's expiry). Not exported from the main entry.
+- `CboxUser.sessionId` and `sessionId()`: the ID Token's `sid`, the sign-in session a
+  back-channel logout token names.
+- Staff roles: `tenantAssignable: false` on a `RoleDefinition` publishes the role as
+  staff-only (`tenant_assignable: false`), which Cbox ID never offers or accepts on an
+  organization's own admin pages.
+- Self-serve permissions: `tenantAssignable: true` on a `PermissionDefinition` publishes it
+  as one an organization's administrators may put in their own custom roles
+  (`tenant_assignable: true`). Permissions stay internal by default.
+- Exported wire types `ManifestPermission` and `ManifestRole`.
+- Exported types `AuthorizationPrompt`, `AuthorizationRequestOptions`,
+  `OrganizationRole`, `CboxActiveOrganization`, `CboxActor`, `ClaimSource`,
+  `CboxOrganization`, and `SignInOptions` from `@cboxdk/id-js/nextjs`.
+
+### Fixed
+
+- `CboxIdConfig.accountPath` was documented as defaulting to `/settings`, which on Cbox ID
+  is the organization's settings page for its administrators. `profileUrl()` has actually
+  defaulted to the person's own account area, `/account`, since 0.8.0; the documentation
+  now says so. If you set `accountPath: '/settings'` because of it, remove it: members who
+  are not organization admins are redirected away from that page and lose `return_to`.
+
+### Changed
+
+- An error returned to the callback (`?error=access_denied`) now sets
+  `AuthenticationError.error` and `.errorDescription`, as the back-channel errors already
+  did. A refused organization switch is `access_denied`, and an app answers it by switching
+  back, not by signing the person out — which it could not tell apart before.
+- `prompt` is typed as `AuthorizationPrompt | AuthorizationPrompt[]` instead of `string`,
+  and `prompt: 'none'` combined with another value is refused (OIDC Core §3.1.2.1).
+  **Breaking for TypeScript callers that pass a `string` variable**; narrow it to
+  `AuthorizationPrompt`.
+- `organization` together with `prompt: 'select_organization'` or `'create_organization'`,
+  or an empty `organization` / `organizationHint`, throws `ConfigurationError` before any
+  redirect.
+- The manifest `version` now covers both `tenant_assignable` flags, byte-for-byte as the
+  PHP reference hashes them: present only in their non-default state, so a catalog that
+  never sets them keeps the version it had. The shared cross-SDK fixture gained the
+  `staff_role` and `self_serve_permission` cases.
+- `AuthzManifest.permissions` / `.roles` are typed as the wire shapes (`ManifestPermission`,
+  `ManifestRole`, snake_case flags) rather than as the declaration types.
+- `defineAuthz()` / `buildManifest()` now refuse a key that is not a lowercase
+  `feature:action` slug, and a `tenantAssignable` that is not a boolean, with a
+  `ConfigurationError` — both were refused by the server on push anyway.
+- A role that lists the same permission twice is sent and hashed with it once, as the
+  server stores it; the repeat used to give a `version` no server computes.
+- `CboxUser` has five new required fields. Code that builds a `CboxUser` by hand (test
+  fixtures) must add `organization: null, roles: [], permissions: [], actor: null,
+  sessionId: null`.

package/README.md

@@ -189,12 +189,37 @@ 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();
+const showCreateHint = hasPermission(payload, 'invoices:create');
 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.
+These are token snapshots for presentation. Protected operations require the fresh
+`checkPermissions` decision described below; hiding a control is not authorization.
+
+### Feature flags
+
+Request the `feature_flags` scope (and give the app that scope on its Scopes tab) and the
+tokens and UserInfo carry the keys of every flag that is on for the person, in the
+organization they signed in to:
+
+```ts
+import { CboxIdClient, FEATURE_FLAGS_SCOPE, hasFeature } from '@cboxdk/id-js';
+
+const client = new CboxIdClient({ ...config, scopes: ['openid', 'profile', 'email', FEATURE_FLAGS_SCOPE] });
+
+user.featureFlags;                 // ['acme-beta', 'new-dashboard'] | null
+if (hasFeature(user, 'new-dashboard')) showNewDashboard();
+hasFeature(accessTokenPayload, 'billing.v2'); // works on a verified claim set too
+```
+
+`null` means the claim is absent — the scope was not requested — and `[]` means nothing is
+on. Either way `hasFeature()` is `false`: a missing scope turns every feature off, never on.
+A token carries the flags as they were when it was issued; the next refresh picks up a
+change. To ask without a token in hand (a job, a webhook handler), use
+`env.featureFlags.evaluate({ user_id, organization_id })` from the
+[Management API](#management-api).
 
 ### Support sessions
 
@@ -266,7 +291,10 @@ const frontend = new CboxIdFrontend({
 })
 
 const config = await frontend.config()
-// → endpoints, social buttons, and the customer's theme
+// → endpoints, social buttons, which methods are on, and the customer's theme
+
+// The buttons one organization's hosted page shows (by id or slug):
+const acme = await frontend.config({ organization: 'acme' })
 
 const { user } = await frontend.session(accessToken)
 // → { id, email, name } or null
@@ -355,6 +383,22 @@ if (result.status === 'mfa_required' || result.status === 'otp_required') {
 }
 ```
 
+`mfa_required` also lists the `factors` the person can answer with — `'totp'`, `'sms'`,
+`'recovery_code'` (kinds only, never the number; absent from instances older than
+laravel-id 1.24). For a texted code, send it when the person asks, then submit it as
+`'sms'`:
+
+```ts
+if (result.status === 'mfa_required' && result.factors?.includes('sms')) {
+  // On "Text me a code" — never on page load: each send spends one of the token's five attempts.
+  const sent = await frontend.sendSmsCode(result.mfaToken)
+  if (sent.status === 'sent') showCodeField(`We texted ${sent.to}`) // '+45 ******78'
+  if (sent.status === 'rate_limited') showRetry(sent.retryAfter)
+  // later:
+  const done = await frontend.submitSecondFactor(result.mfaToken, code, 'sms')
+}
+```
+
 ### Passkeys
 
 ```ts
@@ -546,12 +590,58 @@ const lease = await agent.lease(secret.id, 'call openai');
 
 A lease with no live grant is refused — the vault is deny-by-default.
 
+### Pipes: a person's own GitHub, Google, Slack… token
+
+When a person has connected their account at a provider, lease a fresh access token for it
+with a `vault.lease` token. Cbox ID refreshes it first when it is about to expire:
+
+```ts
+import { PipeNotConnectedError, PipeReauthorizationRequiredError, PipeTemporarilyUnavailableError } from '@cboxdk/id-js';
+
+const vault = client.vault(await client.machineToken({ scopes: ['vault.lease'] }));
+
+try {
+  const { accessToken } = await vault.leasePipeToken('github', { userId, purpose: 'list-repos' });
+  // call https://api.github.com/user/repos with it, then drop it
+} catch (e) {
+  if (e instanceof PipeNotConnectedError || e instanceof PipeReauthorizationRequiredError) {
+    return redirect(e.connectUrlWith({ clientId, returnTo: 'https://app.acme.com/settings' }));
+  }
+  if (e instanceof PipeTemporarilyUnavailableError) return retryLater(e.retryAfter);
+  throw e; // PipeLeaseDeniedError: the app is not granted this pipe
+}
+```
+
+With a token issued for the person (they signed in to your app), leave `userId` out. To
+send somebody to connect before any lease, `client.pipeConnectUrl('github', returnTo)` is
+the hosted connect page, preselected to your app; they come back with
+`?provider=github&status=connected` (or `cancelled`, `failed`).
+
 ## Roles & permissions (federated RBAC)
 
 Declare your app's authorization **roles** and **permissions** in code, then push them
 to Cbox ID on deploy. Your app owns what a role *means*; Cbox ID owns identity and who
-*holds* each role — assignments arrive back in the token's `roles` / `permissions`
-claims for you to enforce. Requires the app's client to hold the `apps.manifest` scope.
+*holds* each role. Publication requires the client's `apps.manifest` scope and a
+server acknowledgement matching the client, version and full catalog checksum.
+It does not assign roles. Expansions of existing roles await explicit activation.
+
+Token role and permission claims are snapshots for presentation. Authorize protected
+server requests and queued work using a fresh decision, then enforce your own row
+ownership/organization rules. Shared organization Admin is not app Admin.
+
+```ts
+import { checkPermissions } from '@cboxdk/id-js/server';
+
+const decision = await checkPermissions(
+  { issuer, clientId }, accessToken, authenticatedSubject, selectedOrganization,
+  ['invoices:create'],
+);
+if (!decision.allowed()) throw new Error('Forbidden');
+```
+
+Derive the subject from verified authentication and authorize the selected organization;
+do not accept either as an unchecked form value. The check has no positive cache,
+refuses redirects and rejects mismatched, incomplete or unavailable decisions.
 
 ```ts
 import { defineAuthz, publishManifest } from '@cboxdk/id-js';
@@ -749,6 +839,33 @@ for await (const org of env.organizations.listAll({ status: 'active' })) {
 }
 ```
 
+### Fine-grained authorization
+
+`env.fga.*` writes relationship tuples and asks checks. Every write answers with a
+`consistency_token`; pass it to a check that must see the write:
+
+```ts
+import { fgaTuple } from '@cboxdk/id-js/management';
+
+const { data: written } = await env.fga.tuples.write({
+  tuples: [{ resource_type: 'document', resource_id: 'leave', relation: 'viewer', subject: { type: 'user', id: 'alice' } }],
+});
+
+const { data } = await env.fga.check({
+  resource_type: 'document', resource_id: 'leave', relation: 'viewer',
+  subject_type: 'user', subject_id: 'alice',
+  consistency_token: written.consistency_token,
+});
+
+// Up to 100 at once, in the tuple notation, answered in order:
+await env.fga.checkBatch({ checks: ['document:leave#viewer@user:alice', 'document:readme#editor@user:alice'] });
+```
+
+`env.fga.tuples.delete()`, `env.fga.resources.list()` (which documents can alice view),
+`env.fga.subjects.list()` (who can view this one), and `env.fga.schema.get()` /
+`.update()` / `.validate()` complete it. `fgaTuple()` writes the notation from the same
+object `tuples.write` takes.
+
 ### Audit Logs
 
 Your app records what its users did, per organization (your customer), and Cbox ID keeps

package/RELEASE-CANDIDATE.md

@@ -0,0 +1,11 @@
+# id-js 0.20.0
+
+Status: prepared local candidate. No public tag, registry publication or deployment has occurred.
+
+Add request-bound live permission decisions and catalog checksums; regenerate app catalog, role-definition activation, invitations and native management APIs.
+
+## Upgrade requirements
+
+Workspace team.remove requires its body with roles_version. Team writes use roles arrays and current CAS versions. Re-read state on conflicts. Live permission checks bind subject, organization and app; access-token role projections alone do not authorize sensitive actions.
+
+Dependency installation against public registries remains contingent on the approved release cascade. Local artifact checks prove the enclosed contents only; they do not claim public indexing.

package/dist/api-keys-BE3R3q_A.d.ts

@@ -0,0 +1,105 @@
+import { O as OrganizationRole } from './types-CC1bz68x.js';
+
+/**
+ * A customer API key Cbox ID vouches for: live, bound to YOUR app, and held by an active
+ * member of `org`.
+ *
+ * The field names are the endpoint's own, so the claim helpers read it like a token —
+ * `hasPermission(answer, 'invoices:create')`, `organization(answer)?.role`. (A type
+ * alias rather than an interface for that reason: only an alias is assignable to the
+ * helpers' record type.)
+ */
+type ActiveApiKey = {
+    active: true;
+    /** The key's id — log this, never the key. */
+    key_id: string;
+    /** The person who holds the key (their subject id). */
+    sub: string;
+    /** The organization the key acts in. */
+    org: string;
+    /** The holder's membership tier in `org`; null for a tier this SDK does not know. */
+    org_role: OrganizationRole | null;
+    /**
+     * What the key may do, already re-capped by Cbox ID: the key's own list intersected
+     * with what the holder holds for your app right now. A demoted holder's key loses the
+     * permission on the next verification, not at the next reissue.
+     */
+    permissions: string[];
+    /** Your app's client id — always, or the answer is refused. */
+    client_id: string;
+    /** ISO 8601 UTC expiry, or null for a key that does not expire. */
+    expires_at: string | null;
+};
+/**
+ * Every refusal: unknown, malformed, revoked, expired, another app's key, a holder who
+ * left. Cbox ID never says which, so the endpoint cannot be used to probe keys — and
+ * neither does this.
+ */
+interface InactiveApiKey {
+    active: false;
+}
+/** What {@link ApiKeyVerifier.verifyApiKey} returns. Narrow on `active`. */
+type ApiKeyVerification = ActiveApiKey | InactiveApiKey;
+/** Configuration for an {@link ApiKeyVerifier}. */
+interface ApiKeyVerifierConfig {
+    /** Base URL (issuer) of the Cbox ID instance. */
+    issuer: string;
+    /** Your app's OAuth client id — the app the keys were issued for. */
+    clientId: string;
+    /** Your app's client secret. Verification is a confidential-client call. */
+    clientSecret: string;
+    /** Timeout (ms) for the verification request. Defaults to `10000`. */
+    timeoutMs?: number;
+    /**
+     * Cache an ACTIVE answer for this long (ms), so a burst of requests with one key costs
+     * one round-trip. Off (`0`) by default and at most {@link MAX_API_KEY_CACHE_TTL_MS}:
+     * while an answer is cached, a revoked key keeps working, and a demoted holder keeps
+     * the permissions they lost. Never cached past the key's `expires_at`. Refusals are
+     * never cached, so a key issued a moment ago works on its first request.
+     */
+    cacheTtlMs?: number;
+}
+/** The longest {@link ApiKeyVerifierConfig.cacheTtlMs} allowed: one minute. */
+declare const MAX_API_KEY_CACHE_TTL_MS = 60000;
+/**
+ * Verifies customer API keys presented to your API: `POST {issuer}/oauth/api-keys/verify`,
+ * authenticated with your app's own client credentials.
+ *
+ * SERVER-SIDE ONLY. It holds your client secret, so it lives in the
+ * `@cboxdk/id-js/server` entry and the Next.js adapter, never in the main entry that a
+ * browser bundle pulls in — and it refuses to be constructed in a browser at all.
+ *
+ * ```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 unauthorized();
+ * if (!hasPermission(answer, 'invoices:create')) return forbidden();
+ * ```
+ */
+declare class ApiKeyVerifier {
+    private readonly config;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly cacheTtlMs;
+    private readonly cache;
+    constructor(config: ApiKeyVerifierConfig);
+    /**
+     * 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.
+     */
+    verifyApiKey(key: string): Promise<ApiKeyVerification>;
+    private request;
+    private parse;
+    private remember;
+}
+
+export { type ActiveApiKey as A, type InactiveApiKey as I, MAX_API_KEY_CACHE_TTL_MS as M, type ApiKeyVerification as a, ApiKeyVerifier as b, type ApiKeyVerifierConfig as c };

package/dist/api-keys-C8-Q4eFA.d.cts

@@ -0,0 +1,105 @@
+import { O as OrganizationRole } from './types-CC1bz68x.cjs';
+
+/**
+ * A customer API key Cbox ID vouches for: live, bound to YOUR app, and held by an active
+ * member of `org`.
+ *
+ * The field names are the endpoint's own, so the claim helpers read it like a token —
+ * `hasPermission(answer, 'invoices:create')`, `organization(answer)?.role`. (A type
+ * alias rather than an interface for that reason: only an alias is assignable to the
+ * helpers' record type.)
+ */
+type ActiveApiKey = {
+    active: true;
+    /** The key's id — log this, never the key. */
+    key_id: string;
+    /** The person who holds the key (their subject id). */
+    sub: string;
+    /** The organization the key acts in. */
+    org: string;
+    /** The holder's membership tier in `org`; null for a tier this SDK does not know. */
+    org_role: OrganizationRole | null;
+    /**
+     * What the key may do, already re-capped by Cbox ID: the key's own list intersected
+     * with what the holder holds for your app right now. A demoted holder's key loses the
+     * permission on the next verification, not at the next reissue.
+     */
+    permissions: string[];
+    /** Your app's client id — always, or the answer is refused. */
+    client_id: string;
+    /** ISO 8601 UTC expiry, or null for a key that does not expire. */
+    expires_at: string | null;
+};
+/**
+ * Every refusal: unknown, malformed, revoked, expired, another app's key, a holder who
+ * left. Cbox ID never says which, so the endpoint cannot be used to probe keys — and
+ * neither does this.
+ */
+interface InactiveApiKey {
+    active: false;
+}
+/** What {@link ApiKeyVerifier.verifyApiKey} returns. Narrow on `active`. */
+type ApiKeyVerification = ActiveApiKey | InactiveApiKey;
+/** Configuration for an {@link ApiKeyVerifier}. */
+interface ApiKeyVerifierConfig {
+    /** Base URL (issuer) of the Cbox ID instance. */
+    issuer: string;
+    /** Your app's OAuth client id — the app the keys were issued for. */
+    clientId: string;
+    /** Your app's client secret. Verification is a confidential-client call. */
+    clientSecret: string;
+    /** Timeout (ms) for the verification request. Defaults to `10000`. */
+    timeoutMs?: number;
+    /**
+     * Cache an ACTIVE answer for this long (ms), so a burst of requests with one key costs
+     * one round-trip. Off (`0`) by default and at most {@link MAX_API_KEY_CACHE_TTL_MS}:
+     * while an answer is cached, a revoked key keeps working, and a demoted holder keeps
+     * the permissions they lost. Never cached past the key's `expires_at`. Refusals are
+     * never cached, so a key issued a moment ago works on its first request.
+     */
+    cacheTtlMs?: number;
+}
+/** The longest {@link ApiKeyVerifierConfig.cacheTtlMs} allowed: one minute. */
+declare const MAX_API_KEY_CACHE_TTL_MS = 60000;
+/**
+ * Verifies customer API keys presented to your API: `POST {issuer}/oauth/api-keys/verify`,
+ * authenticated with your app's own client credentials.
+ *
+ * SERVER-SIDE ONLY. It holds your client secret, so it lives in the
+ * `@cboxdk/id-js/server` entry and the Next.js adapter, never in the main entry that a
+ * browser bundle pulls in — and it refuses to be constructed in a browser at all.
+ *
+ * ```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 unauthorized();
+ * if (!hasPermission(answer, 'invoices:create')) return forbidden();
+ * ```
+ */
+declare class ApiKeyVerifier {
+    private readonly config;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly cacheTtlMs;
+    private readonly cache;
+    constructor(config: ApiKeyVerifierConfig);
+    /**
+     * 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.
+     */
+    verifyApiKey(key: string): Promise<ApiKeyVerification>;
+    private request;
+    private parse;
+    private remember;
+}
+
+export { type ActiveApiKey as A, type InactiveApiKey as I, MAX_API_KEY_CACHE_TTL_MS as M, type ApiKeyVerification as a, ApiKeyVerifier as b, type ApiKeyVerifierConfig as c };