@cboxdk/id-js 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -0,0 +1,213 @@
+# 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).
+
+## [Unreleased]
+
+## [0.21.0] - 2026-11-08
+
+### Added
+
+- `@cboxdk/id-js/agent`: OpenID CIBA (poll mode) and the RFC 8628 device grant for agents and
+  CLIs, so they no longer need their own polling loop. `startBackchannel` / `pollBackchannel` /
+  `waitForBackchannelToken`, `startDeviceAuthorization` / `pollDeviceAuthorization` /
+  `waitForDeviceToken` and `refreshAgentTokens`. The wait helpers use the server's `interval`,
+  add 5 s on `slow_down` (and on 429, waiting at least `Retry-After`), keep polling on
+  `authorization_pending`, stop at `expires_in`, and take an `AbortSignal` and an injectable
+  `sleep`. `resource` (RFC 8707) is re-sent on every poll. No `user_code` is ever sent.
+- `registerAgentClient()`: RFC 7591 dynamic registration with `private_key_jwt` (an ES256 or
+  RS256 key from `generateClientKeyPair()`, sent inline as `jwks`) or `none`.
+  `createClientAssertion()` signs the RFC 7523 assertion (`aud` = token endpoint, single-use
+  `jti`, at most 60 s). `startBackchannel` also accepts a keyless `none` client (sends
+  `client_id` only), which Cbox ID allows only where the resource permits it.
+- `discoverAuthorizationServer()` reads `/.well-known/oauth-authorization-server` and checks
+  the issuer.
+- `createBindingCode()`: a short code from an alphabet without look-alike characters, for the
+  `binding_message` that Cbox ID requires from self-registered clients.
+- Typed errors: `AccessDeniedError`, `ExpiredTokenError`, `InvalidGrantError`,
+  `InvalidTargetError`, `InvalidClientError`, `UnknownUserIdError`,
+  `InvalidBindingMessageError`, `SlowDownError` (with `retryAfter`), all subclasses of
+  `AgentGrantError` (an `AuthenticationError`), plus `GrantCancelledError`.
+- Guide: `docs/ciba-and-device-grant.md`.
+
+## [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,14 @@ 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
 
@@ -274,6 +276,33 @@ 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.
 
+### Agents and self-registering CLIs (CIBA and device grant)
+
+`@cboxdk/id-js/agent` is for a CLI or an agent that registers itself (RFC 7591) and gets a
+token for a person without a redirect: OpenID CIBA, where the person taps Approve in Cbox ID,
+or the device grant. It generates a `private_key_jwt` key with WebCrypto, signs the client
+assertions, and polls following the server's rules (`interval`, `slow_down`, 429
+`Retry-After`, expiry, Ctrl-C). Refusals are typed errors.
+
+```ts
+import { startBackchannel, waitForBackchannelToken, createBindingCode } from '@cboxdk/id-js/agent';
+
+const code = createBindingCode(); // e.g. "K7QM", shown beside Approve
+const authorization = await startBackchannel({
+  issuer, client, loginHint: 'ada@acme.com', scope: 'openid mcp:read',
+  bindingMessage: `Brain CLI: ${code}`, resource: 'https://app.cboxbrain.com/mcp',
+});
+console.log(`Approve in Cbox ID. Check that it shows ${code}.`);
+const tokens = await waitForBackchannelToken({ issuer, client, authorization });
+```
+
+Self-registered clients must send `resource` and `binding_message`. Register with
+`private_key_jwt` for CIBA: a keyless (`none`) client can use CIBA only where the resource
+allows it, and is otherwise refused with `invalid_target`.
+
+See [docs/ciba-and-device-grant.md](docs/ciba-and-device-grant.md) for when to use each flow,
+a complete Node CLI and the error table.
+
 ## In the browser (publishable keys)
 
 Everything above needs a server: it holds your client secret. A **publishable key** is the
@@ -619,8 +648,27 @@ the hosted connect page, preselected to your app; they come back with
 
 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';

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.