@cauthyhq/node 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## 1.2.0
+
+One variable for every application: `CAUTHY_KEY`.
+
+### Added
+
+- **`CAUTHY_KEY`** (`key/cauthy-key.md` of the spec): Cauthy's address, the application's client and a 32-byte secret in one value, made by Cauthy's dashboard in the browser. `createCauthy()` reads it and nothing else: the session-cookie keys and an Ed25519 key are derived from it, the application authenticates with `private_key_jwt` (`EdDSA`) on every token and revoke call, never with a client secret, and asks Cauthy who it is (`GET /v1/connect/self`: workspace, system, addresses), revalidated every 5 minutes. The `key` option takes it in code.
+- **Startup**: a damaged key throws `CauthyKeyError` at once with its reason (`key_format`, `key_version`, `key_checksum`, `key_issuer`, `key_client`, `key_secret`, `key_contract_issuer`, `key_previous_mismatch`), never the value. Cauthy unreachable: the server starts and `/api/auth/*` answers `503 unavailable` until Cauthy answers. Cauthy refusing the key: `503 misconfigured`, logged once with the `kid`. `auth.ready()` awaits the identity.
+- **The redirect URI** comes from the request's origin when it is one of the application's addresses in Cauthy, else the only one; otherwise `400 unknown_origin`.
+- **A contract on top of the key**: `createCauthy({ contract: { graph, system } })` with `CAUTHY_KEY` needs no key store and no table. The key proves the link's service client; the JWKS route publishes the key's Ed25519 public half (and the previous key's during a rotation). The key must name the graph's Cauthy.
+- **`CAUTHY_KEY_PREVIOUS`** (`keyPrevious`) for rotations: its sessions are read, never written. `CAUTHY_SECRET` and `PACT_ROOT_KEY` beside the key are read-only too while an application moves (one warning each); with `PACT_ROOT_KEY`, a contract and `keys`, the old RS256 keys stay published beside the new one.
+- **`createVerifierFromEnv()`**: a token verifier from `CAUTHY_KEY` alone (issuer, audience and workspace from Cauthy).
+- `verifyWebhook` takes the issuer from `CAUTHY_KEY` when it is set.
+- `parseKey`, `composeKey`, `KEY_REPLACES`, `CauthyKeyError`, and the types `CauthyKey`, `CauthyKeyReason`, `Identity`.
+- **`@cauthyhq/node/testing`**: `FakeCauthy.issueKey(issuer?, { clientId? })`, `revokeKey(kid)`, `registeredKids()`, `appUrls`, `system`, `tenantId`, `contract`, `oauthRequests`. The fake checks Ed25519 assertions (signature, `kid`, `iss`/`sub`/`aud`, lifetime, replay) and answers `GET /v1/connect/self`, with `ETag`.
+
+### Refused beside `CAUTHY_KEY`
+
+`CAUTHY_ISSUER`, `CAUTHY_CLIENT_ID`, `CAUTHY_CLIENT_SECRET`, `CAUTHY_SYSTEM`, `CAUTHY_TENANT`, `CAUTHY_SYSTEM_KEY`, `CAUTHY_SYSTEM_KEY_ID`, `CAUTHY_BASE_URL`, `CAUTHY_AUDIENCE`, `CAUTHY_TENANT_ID`, and the options `issuer`, `clientId`, `clientSecret`, `secret`, `system`, `tenant`, `audience`, `tenantId`, `systemKey`, `rootKey` (and `keys`, except beside `PACT_ROOT_KEY` with a contract while moving).
+
+### Deprecated (removed in 2.0)
+
+One `DeprecationWarning` (code `CAUTHY_DEPRECATED`) per process each: configuring with the `CAUTHY_*` variables or their options; `PACT_ROOT_KEY[_PREVIOUS]` and the `keys` store; a verifier reading `CAUTHY_ISSUER`, `CAUTHY_AUDIENCE` or `CAUTHY_TENANT_ID`. They keep working through 1.x.
+
+### Unchanged
+
+Applications on the 1.1 variables or on `PACT_ROOT_KEY` work as before, apart from the warning. The MCP variables (`CAUTHY_MCP_*`) are not part of this change.
+
+## 1.1.0 — security release
+
+Cauthy now marks the tokens a machine holds, and names the client a person's token was issued through. This release makes `verifyToken` use those marks. Refusing a machine's token where a person is expected is a fix, not a break, so it ships as a minor version: upgrade.
+
+### Security
+
+- **A client's own token no longer passes as a person's.** A `client_credentials` token carries `token_use: "client"` and the client's public `client_id`. `verifyToken`, `createTokenVerifier`, `auth.verifyToken` and `auth.tokenVerifier` now refuse it with the reason `client_token` (rule R13 of the spec's `verification/rules.md`), by the claim's presence, whatever its value. In 1.0 such a token was accepted as a person whose `userId` was the client's id.
+- **By contract, a person's token issued through another client is refused** with `wrong_client` (rule R15): `auth.verifyToken` and `auth.tokenVerifier` check the token's `azp` against the link's sign-in client. A token with no `azp` passes. A call that names another `clientId` in contract mode is a `CauthyConfigError`.
+- `token_use` and `azp`, when present, must be strings (`invalid_claim` otherwise, rule R8).
+
+### Backends that serve machines
+
+If an endpoint is called by machines with a `client_credentials` token, pass `allowClientTokens: true` to the verifier that guards it:
+
+```ts
+const verifyMachine = auth.tokenVerifier({ allowClientTokens: true })
+const who = await verifyMachine(request)
+who.clientId // the client's public id; who.userId is its internal id
+```
+
+Without it those calls get `client_token` (answer 401) after the upgrade.
+
+### Added
+
+- `TokenIdentity.authorizedParty`: the token's `azp`, the client a person's token was issued through; absent when none was named.
+- `TokenIdentity.clientId`: the token's `client_id` (a client's own token, with `allowClientTokens`; an AI agent's).
+- `VerifyTokenOptions.allowClientTokens` (default `false`) and `VerifyTokenOptions.clientId` (default none; by contract, the link's sign-in client).
+- `TokenRefusal` gains `client_token` and `wrong_client`.
+
+### Notes
+
+- Cauthy now answers its JWKS with `max-age=300` and publishes a key at least that long before it signs with it. Nothing changes here: the keys are kept for the answer's `max-age` and fetched again on an unknown `kid`.
+- A session that began through a client renews only through it. The SDK already renews with the `clientId` it signed in with, and sends that `clientId` on its own screens' calls: keep one `clientId` per deployment.
+
+### Development
+
+- vitest 4.1.12, fastify 5.12.8 (tests), and postcss 8.5.32 and esbuild 0.28.2 by override: every open advisory was in development dependencies only. `npm audit` reports none.
+
+## 1.0.0
+
+First release: the server half of `cauthy-auth` 0.42 (see the README, "Moving from cauthy-auth").

package/README.md

@@ -12,25 +12,20 @@ Node 20 or later. ESM and CommonJS. One dependency: `jose`.
 
 ## The five-minute path
 
-**1. Register the application in Cauthy's dashboard** (Applications, New application) and add this redirect URI: `${CAUTHY_BASE_URL}/api/auth/callback`, e.g. `http://localhost:3000/api/auth/callback`. The dashboard shows the client id.
+**1. Connect the application in Cauthy's dashboard** (**Integrate → Applications → Connect an application**), with its address, e.g. `http://localhost:3000`. The dashboard makes the application's key in your browser and shows it once, as one line.
 
-**2. Set the environment** (the CLI that writes this for you, `cauthy init`, is coming; until then it is five variables):
+**2. Put that line in `.env`** (keep it out of git):
 
-| Variable | Where it comes from |
-| --- | --- |
-| `CAUTHY_ISSUER` | Your Cauthy's address, e.g. `https://id.example.com` |
-| `CAUTHY_CLIENT_ID` | The client id the dashboard showed in step 1 |
-| `CAUTHY_CLIENT_SECRET` | Only if you registered the application as a confidential client in the dashboard: the client secret it showed once. Public clients need none, and neither does contract mode |
-| `CAUTHY_SECRET` | You make it: `openssl rand -base64 32`. It encrypts the session cookie; keep it out of git |
-| `CAUTHY_TENANT` | Your workspace's slug in Cauthy, e.g. `acme`, for the sign-in screens your application draws itself |
-| `CAUTHY_BASE_URL` | Your application's public address, e.g. `http://localhost:3000` |
+    CAUTHY_KEY=cauthy1.…
+
+That is the whole environment: Cauthy's address, the application's client and its secret are in the key; the workspace, the system and the application's addresses are asked of Cauthy when it starts. The [five-minute guide](https://cauthy.docs.vennet.dev/en/guide/get-started/) walks through it.
 
 **3. Create it and mount it.**
 
 ```ts
 // auth.ts
 import { createCauthy } from '@cauthyhq/node'
-export const auth = createCauthy()   // reads the variables above
+export const auth = createCauthy()   // reads CAUTHY_KEY
 ```
 
 ```ts
@@ -80,6 +75,45 @@ await auth.organizations(session)                                  // the person
 
 See [`examples/acme-crm`](examples/acme-crm) for a whole application.
 
+## CAUTHY_KEY
+
+One value: Cauthy's address, the application's client and a 32-byte secret,
+with a checksum (`cauthy1.<issuer>.<client>.<secret>.<check>`, specified in
+the spec's [`key/cauthy-key.md`](https://github.com/vennet-developers/cauthy-sdk-spec/blob/main/key/cauthy-key.md)).
+The SDK derives the session-cookie keys and an Ed25519 key from it, proves
+itself to Cauthy with that key (`private_key_jwt`, a fresh assertion on every
+token and revoke call; no client secret is ever sent), and asks Cauthy who it
+is (`GET /v1/connect/self`). Cauthy keeps only the public half.
+
+| When | What happens |
+| --- | --- |
+| `createCauthy()` | The key is parsed at once: a damaged paste throws `CauthyKeyError` naming the reason (`key_format`, `key_checksum`, …), never the key. Then Cauthy is asked who the application is, in the background |
+| Cauthy not reachable yet | The server starts; `/api/auth/*` answers `503 unavailable` until the answer comes (retried from 1 to 30 seconds) |
+| Cauthy refuses the key (revoked, never registered) | Logged once with the key's `kid`; `/api/auth/*` answers `503 misconfigured` |
+| Running | The answer is kept and asked again every 5 minutes; while Cauthy is down the last one stands |
+| `await auth.ready()` | The identity, waited for: call it at startup to fail early |
+
+The redirect URI is built from the request's origin when it is one of the
+application's addresses in Cauthy, from the only one when there is just one,
+and the request is refused with `400 unknown_origin` otherwise. `baseURL`
+still overrides it. Beside `CAUTHY_KEY` the variables it replaces
+(`CAUTHY_ISSUER`, `CAUTHY_CLIENT_ID`, `CAUTHY_CLIENT_SECRET`, `CAUTHY_SYSTEM`,
+`CAUTHY_TENANT`, `CAUTHY_SYSTEM_KEY`, `CAUTHY_SYSTEM_KEY_ID`, `CAUTHY_BASE_URL`,
+`CAUTHY_AUDIENCE`, `CAUTHY_TENANT_ID`) and the options they stand for are
+refused at startup, naming them.
+
+**Lost or leaked:** make a new key on the application's card and revoke the
+old one. **Rotating:** move the current value to `CAUTHY_KEY_PREVIOUS`, put
+the new one in `CAUTHY_KEY`, deploy, and remove `CAUTHY_KEY_PREVIOUS` after
+the window: sessions made with the previous key are still read, and nothing
+new is written with it.
+
+**Moving from the variables of 1.1:** on the application's card, **Move to
+CAUTHY_KEY**. Deploy with `CAUTHY_KEY` and keep `CAUTHY_SECRET` for the window
+(old sessions stay readable; one warning says to remove it), remove the other
+variables, then **Remove the secret**. The variables of 1.1 and `PACT_ROOT_KEY`
+still work in 1.x with one `DeprecationWarning` per process and leave in 2.0.
+
 ## Verifying a token
 
 For an API that receives Cauthy access tokens from somewhere other than the browser's cookie:
@@ -88,14 +122,22 @@ For an API that receives Cauthy access tokens from somewhere other than the brow
 import { auth } from './auth'
 
 // Where each value comes from:
-//   issuer   the instance's own (CAUTHY_ISSUER, or the contract)
-//   tenantId by contract, the link's tenant_id; otherwise the `tenantId` option or CAUTHY_TENANT_ID
-//   audience the `audience` option or CAUTHY_AUDIENCE: your Cauthy's JWT_AUDIENCE (Cauthy has no default for it)
+//   issuer   the instance's own (CAUTHY_KEY, or the contract; deprecated: CAUTHY_ISSUER)
+//   tenantId by contract, the link's tenant_id; on CAUTHY_KEY, Cauthy's answer; otherwise `tenantId` or CAUTHY_TENANT_ID (deprecated)
+//   audience on CAUTHY_KEY, Cauthy's answer; otherwise `audience` or CAUTHY_AUDIENCE (deprecated): your Cauthy's JWT_AUDIENCE
+//   clientId by contract, the link's sign-in client: a person's token issued through another is refused (wrong_client)
 const verify = auth.tokenVerifier()          // throws CauthyConfigError now if one is missing
 const who = await verify(request)            // or: await auth.verifyToken(request)
 ```
 
-Standalone, with no instance, everything is explicit:
+On `CAUTHY_KEY`, the issuer, the audience and the workspace are Cauthy's answer: `auth.tokenVerifier()` waits for it. With no instance:
+
+```ts
+import { createVerifierFromEnv } from '@cauthyhq/node'
+const verify = await createVerifierFromEnv()   // reads CAUTHY_KEY; asks Cauthy once
+```
+
+Standalone, with no instance and no key, everything is explicit:
 
 ```ts
 import { createTokenVerifier } from '@cauthyhq/node'
@@ -106,6 +148,8 @@ const verify = createTokenVerifier({ issuer: 'https://id.example.com', audience:
 
 - **The audience and the workspace are required.** Without them a token issued for another application or workspace would be accepted.
 - A system's own token (`sys` claim, whatever its value) and a guest's token (`anon: true`) are refused where a person is expected. Pass `allowSystem` or `allowAnonymous` for an endpoint that takes them.
+- A client's own token (a `client_credentials` grant: `token_use: "client"`, whatever the value) is refused with `client_token` where a person is expected. A backend that serves machines too passes `allowClientTokens: true`; the identity then carries `clientId`, the client's public id (its `userId` is the client's internal id).
+- `authorizedParty` is the token's `azp`: the client a person's token was issued through, absent when none was named. With `clientId` (by contract, always the link's sign-in client), a token whose `azp` names another client is refused with `wrong_client`; a token with no `azp` passes.
 - Clock tolerance is 30 seconds (`leeway`, 0 to 60). A token over 8192 bytes, with a repeated JSON name, a fractional date or a wrongly typed claim is refused.
 - Keys are fetched from `<issuer>/.well-known/jwks.json` with no redirect, within 5 seconds, at most 64 KiB, and kept for the answer's `max-age`.
 
@@ -117,8 +161,10 @@ const verify = createTokenVerifier({ issuer: 'https://id.example.com', audience:
 | --- | --- |
 | `cauthy-auth` | `@cauthyhq/node` |
 | `cauthy-auth/express`, `/fastify`, `/hono`, `/next`, `/mcp`, `/keys`, `/theme` | `@cauthyhq/node/express`, … (same names) |
-| `cauthy-auth/react`, `/client`, `/vue`, `/svelte`, `/styles.css` | Keep `cauthy-auth` 0.43 in the browser until `@cauthyhq/js` and `@cauthyhq/react` ship |
-| `npx cauthy-auth …` | The `cauthy` CLI (coming) |
+| `cauthy-auth/react`, `/styles.css` | `@cauthyhq/react`, `@cauthyhq/react/styles.css` |
+| `cauthy-auth/client` | `@cauthyhq/js` |
+| `cauthy-auth/vue`, `/svelte` | No 1.0 wrapper yet: keep `cauthy-auth` 0.43 in the browser (security fixes until 2027-02-06) |
+| `npx cauthy-auth …` | The `cauthy` CLI: `npx @cauthyhq/cli …` |
 
 Everything that behaves differently from 0.42:
 
@@ -138,19 +184,20 @@ Everything that behaves differently from 0.42:
 
 ## Contract mode
 
-With a Pact link, everything comes from the vendored graph and one secret, `PACT_ROOT_KEY`:
+A contract is a layer on top of an application that runs on `CAUTHY_KEY`: the environment stays that one line, and the vendored graph adds the link (system proof, drift, the link's policies). No key store and no table:
 
 ```ts
 import { createCauthy } from '@cauthyhq/node'
-import { postgresKeyStore } from '@cauthyhq/node/keys'
 import graph from './contracts/graph.json'
 
-export const auth = createCauthy({ contract: { graph, system: 'acme-crm' }, keys: postgresKeyStore(query), audience: 'cauthy' })
+export const auth = createCauthy({ contract: { graph, system: 'acme-crm' } })   // and CAUTHY_KEY in the environment
 ```
 
-By contract the application also publishes its own key at the contract's `jwks_url` path (`/.well-known/pact-jwks.json` by default). The Express, Hono and Fastify adapters route that path to the handler as they do `/api/auth`, so those need no route of their own for it. **Next.js and TanStack Start still need a route file** for it that calls `auth.handler(request)`.
+The key proves the link's service client (`pact.<link>.service`); people sign in through its public client (`pact.<link>`). The key must name the graph's Cauthy (`key_contract_issuer` otherwise). The application publishes the key's public half at the contract's `jwks_url` path (`/.well-known/pact-jwks.json` by default), and the previous key's too during a rotation. The Express, Hono and Fastify adapters route that path to the handler as they do `/api/auth`, so those need no route of their own for it. **Next.js and TanStack Start still need a route file** for it that calls `auth.handler(request)`.
 
-It refuses to start when any `CAUTHY_*` variable of the standard mode is also set, when the link names its workspace by slug and the graph has no `tenant_id` for it yet, when a workspace named by id is pinned to a different `tenant_id`, when `system_proof` is not `off`, `auto` or `required`, or when the link asks for a system proof without a `service` block. When the link sets `require_verified_email`, a person whose address is not confirmed gets no session. See [`contract/pact.md`](https://github.com/vennet-developers/cauthy-sdk-spec/blob/main/contract/pact.md).
+The 1.1 way (`PACT_ROOT_KEY` and `keys: postgresKeyStore(query)`) keeps working through 1.x with a deprecation warning. Moving: generate `CAUTHY_KEY` on the application's card, deploy it with `PACT_ROOT_KEY` and the `keys` option still beside it for the window (old sessions stay readable, its RS256 keys stay published beside the new Ed25519 key), then remove `PACT_ROOT_KEY`, the option and the table.
+
+It refuses to start when any variable `CAUTHY_KEY` replaces is also set, when the link names its workspace by slug and the graph has no `tenant_id` for it yet, when a workspace named by id is pinned to a different `tenant_id`, when `system_proof` is not `off`, `auto` or `required`, or when the link asks for a system proof without a `service` block. When the link sets `require_verified_email`, a person whose address is not confirmed gets no session. See [`contract/pact.md`](https://github.com/vennet-developers/cauthy-sdk-spec/blob/main/contract/pact.md).
 
 ## Options added in 1.0
 
@@ -164,13 +211,23 @@ It refuses to start when any `CAUTHY_*` variable of the standard mode is also se
 
 ## Testing your application
 
-`@cauthyhq/node/testing` is a Cauthy that lives in memory (`FakeCauthy`) and a browser that keeps cookies (`Browser`), for the tests of your own application. **Test-only**: it signs in whoever it was told about and checks nothing a real Cauthy does. Do not import it from production code.
+`@cauthyhq/node/testing` is a Cauthy that lives in memory (`FakeCauthy`) and a browser that keeps cookies (`Browser`), for the tests of your own application. **Test-only**: it signs in whoever it was told about and checks little a real Cauthy does. Do not import it from production code.
+
+```ts
+const fake = new FakeCauthy()
+fake.appUrls = ['http://localhost:3000']
+const auth = createCauthy({ key: await fake.issueKey(), fetch: fake.fetch })
+```
+
+`issueKey(issuer?)` makes a `CAUTHY_KEY` for `fake.clientId` and registers its public half, as the dashboard does; from then on that client must prove itself with the key's assertion on every token and revoke call. `revokeKey(kid)` revokes it. `serveFakeCauthy(fake, port)` serves it over HTTP; issue the key with that address (`http://127.0.0.1:<port>`) for a process outside yours.
 
 ## Conformance
 
-CI runs the auth-bff conformance suite at level `strict` against `examples/acme-crm` on an in-memory Cauthy, and the spec's token vectors against `verifyToken`:
+The auth-bff conformance suite runs at level `strict` against `examples/acme-crm` on an in-memory Cauthy, the application on `CAUTHY_KEY` alone (with the runner's `key.*` checks); the spec's token vectors run against `verifyToken`, and its `CAUTHY_KEY` vectors against the parser and the derivation:
 
     SPEC_DIR=../cauthy-sdk-spec LEVEL=strict npm run conformance
+    SPEC_DIR=../cauthy-sdk-spec LEVEL=switches npm run conformance   # also the dashboard switches, on the in-memory Cauthy
+    SPEC_DIR=../cauthy-sdk-spec MODE=variables npm run conformance   # the 1.1 way, for a runner without --key-env
     SPEC_DIR=../cauthy-sdk-spec npm run vectors
 
 ## Security

package/dist/{cauthy-B6Sm3T8M.d.ts → cauthy-C7gZ-pbv.d.ts}

@@ -1,6 +1,7 @@
 import { K as KeyStore, P as PactKeys } from './keys-D5k0omTb.js';
 import { JWTVerifyGetKey, JWK } from 'jose';
 import { CauthyTheme } from './theme.js';
+import { I as Identity } from './identity-BTJ8NB_w.js';
 
 /** What createCauthy is given to run by contract. */
 interface ContractOptions {
@@ -110,7 +111,7 @@ declare class CauthyWebhookError extends Error {
     constructor(reason: string);
 }
 interface VerifyWebhookOptions {
-    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    /** Cauthy's address. Default: the one `CAUTHY_KEY` names, else `CAUTHY_ISSUER`. */
     issuer?: string;
     /**
      * This endpoint's own public address, exactly as it is registered in Cauthy.
@@ -150,6 +151,17 @@ declare function verifyWebhook(request: Request, options?: VerifyWebhookOptions)
 
 /** How an application is set up to sign its people in with Cauthy. */
 interface CauthyOptions {
+    /**
+     * The application's CAUTHY_KEY, made in Cauthy's dashboard: Cauthy's
+     * address, the application's client and its secret, in one value. Default:
+     * `CAUTHY_KEY`. With it nothing else is read: the workspace, the system and
+     * the application's addresses come from Cauthy (`GET /v1/connect/self`),
+     * and passing `issuer`, `clientId`, `clientSecret`, `secret`, `system`,
+     * `tenant`, `audience`, `tenantId`, `systemKey` or `rootKey` is refused.
+     */
+    key?: string;
+    /** The key being replaced, during a rotation: read, never written with. Default: `CAUTHY_KEY_PREVIOUS`. */
+    keyPrevious?: string;
     /** Cauthy's public address, e.g. `https://id.example.com`. Default: `CAUTHY_ISSUER`. */
     issuer?: string;
     /** The application's OAuth client id. Default: `CAUTHY_CLIENT_ID`. */
@@ -398,6 +410,13 @@ type SessionStatus = 'authenticated' | 'unauthenticated' | 'expired';
 declare class CauthyConfigError extends Error {
     constructor(message: string);
 }
+/** Why a CAUTHY_KEY was refused (key/cauthy-key.md §3, §8, §9). */
+type CauthyKeyReason = 'key_format' | 'key_version' | 'key_checksum' | 'key_issuer' | 'key_client' | 'key_secret' | 'key_contract_issuer' | 'key_previous_mismatch';
+/** A refused CAUTHY_KEY. The message names the reason, never the key. */
+declare class CauthyKeyError extends CauthyConfigError {
+    readonly reason: CauthyKeyReason;
+    constructor(reason: CauthyKeyReason, message: string);
+}
 
 /** The part of an organization that says what its member may do. */
 interface Permitted {
@@ -637,6 +656,18 @@ declare function pushCatalog(o: Omit<PushPolicyOptions, 'roles' | 'catalog'> & {
     resources: CatalogResource[];
 }): Promise<CatalogResource[]>;
 
+type PublicJwk = {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+};
+interface Signer {
+    kid: string;
+    publicJwk: PublicJwk;
+    /** §6's assertion. iat in seconds; jti a fresh UUID v4. */
+    assertion(clientId: string, tokenEndpoint: string, jti?: string, iat?: number): Promise<string>;
+}
+
 /** The key an application signs its assertions with. */
 interface SystemKey {
     /** The private key: PKCS#8 PEM, or a JWK (as an object or its JSON). RSA, for RS256. */
@@ -679,6 +710,17 @@ interface SystemOptions {
     keys?: PactKeys;
     /** The client the keys prove: the system's own, beside the sign-in client. */
     keysClientId?: string;
+    /**
+     * CAUTHY_KEY's Ed25519 key (key/cauthy-key.md §6) and the client it proves:
+     * every token is asked with an EdDSA assertion. Takes the place of `key`,
+     * `keys` and the secret.
+     */
+    signer?: {
+        clientId: string;
+        signer: Promise<Signer>;
+    };
+    /** The system `check` asks about when it is known only later (CAUTHY_KEY: from Cauthy's answer). */
+    currentSystem?: () => string;
     fetch?: typeof fetch;
     /** How long a call to Cauthy may take before it fails with `503 unavailable`, in milliseconds. Default: 2000. */
     timeoutMs?: number;
@@ -832,13 +874,20 @@ interface TokenIdentity {
     system?: string;
     /** Set when the token is a guest's (only with `allowAnonymous`). */
     anonymous?: true;
+    /** The client a person's token was issued through (`azp`); absent when none was named. */
+    authorizedParty?: string;
+    /**
+     * The token's `client_id`: on a client's own token (only with
+     * `allowClientTokens`), the client's public id; on an AI agent's, the agent's.
+     */
+    clientId?: string;
     /** UTC, ISO 8601. */
     expiresAt: string;
     /** The token as it arrived, to pass on. */
     token: string;
 }
 /** Why a token was refused: the closed list of verification/rules.md, and `no_token` when none was given. */
-type TokenRefusal = 'no_token' | 'too_large' | 'malformed' | 'alg_not_allowed' | 'unsupported_header' | 'missing_kid' | 'unknown_kid' | 'weak_key' | 'bad_signature' | 'missing_claim' | 'invalid_claim' | 'wrong_issuer' | 'wrong_audience' | 'expired' | 'not_yet_valid' | 'issued_in_future' | 'wrong_tenant' | 'system_token' | 'anonymous_token';
+type TokenRefusal = 'no_token' | 'too_large' | 'malformed' | 'alg_not_allowed' | 'unsupported_header' | 'missing_kid' | 'unknown_kid' | 'weak_key' | 'bad_signature' | 'missing_claim' | 'invalid_claim' | 'wrong_issuer' | 'wrong_audience' | 'expired' | 'not_yet_valid' | 'issued_in_future' | 'wrong_tenant' | 'system_token' | 'client_token' | 'anonymous_token' | 'wrong_client';
 /**
  * Cauthy's keys could not be fetched (or are not a key set): the token may be
  * good, and the application cannot tell. Answer 503, not 401. It is not a
@@ -880,6 +929,20 @@ interface VerifyTokenOptions {
     allowSystem?: boolean;
     /** Accept a guest's token (`anon: true`). Default: false (rule R14). */
     allowAnonymous?: boolean;
+    /**
+     * Accept a client's own token (a `token_use` claim, from a
+     * `client_credentials` grant) too: for a backend that serves machines as
+     * well as people. Default: false, so a machine never passes as a person
+     * (rule R13). The identity then carries `clientId`.
+     */
+    allowClientTokens?: boolean;
+    /**
+     * The client this backend signs people in through. When set, a person's
+     * token issued through another client (an `azp` naming another) is refused
+     * with `wrong_client` (rule R15); a token with no `azp` passes. In contract
+     * mode it is the link's sign-in client. Default: none, and `azp` is not checked.
+     */
+    clientId?: string;
 }
 /**
  * Cauthy's published keys (K1 to K5 of verification/rules.md): fetched with a
@@ -904,6 +967,19 @@ declare function createTokenVerifier(options?: VerifyTokenOptions): (from: strin
  * which checks them once, at startup).
  */
 declare function verifyToken(from: string | Request | Headers, options?: VerifyTokenOptions): Promise<TokenIdentity>;
+/**
+ * A verifier made from the environment. With `CAUTHY_KEY` the issuer, the
+ * audience and the workspace are Cauthy's answer to `GET /v1/connect/self`
+ * (asked with the key's assertion, once); nothing else is read, and any of
+ * `issuer`, `audience`, `tenantId` given beside it is refused. Without it,
+ * `CAUTHY_ISSUER`, `CAUTHY_AUDIENCE` and `CAUTHY_TENANT_ID`, deprecated.
+ *
+ *   const verify = await createVerifierFromEnv()
+ *   const who = await verify(request)
+ */
+declare function createVerifierFromEnv(options?: Omit<VerifyTokenOptions, 'issuers'> & {
+    key?: string;
+}): Promise<(from: string | Request | Headers) => Promise<TokenIdentity>>;
 
 /**
  * Where the probes go: the running application's origin
@@ -922,6 +998,13 @@ interface Resolved {
 interface Cauthy {
     /** Serves the routes under `basePath`: login, callback, session, refresh, logout, account. */
     handler(request: Request): Promise<Response>;
+    /**
+     * Who the application is. On CAUTHY_KEY, Cauthy's answer to
+     * `GET /v1/connect/self`, waited for: it rejects with `CauthyApiError`
+     * `503 misconfigured` when Cauthy refuses the key. Otherwise what is
+     * configured, at once (`key: null`). Await it at startup to fail early.
+     */
+    ready(): Promise<Identity>;
     /**
      * Checks that this handler is what answers under `basePath` in the running
      * application, and throws `CauthyConfigError` naming the route when another
@@ -990,6 +1073,8 @@ interface Cauthy {
      * an API of this application: `verifyToken` with this instance's issuer, its
      * workspace (by contract, the link's `tenant_id`; otherwise `tenantId` or
      * `CAUTHY_TENANT_ID`) and its audience (`audience` or `CAUTHY_AUDIENCE`).
+     * By contract it also refuses a person's token issued through another
+     * client than the link's (`wrong_client`).
      */
     verifyToken(from: string | Request | Headers, options?: Partial<VerifyTokenOptions>): Promise<TokenIdentity>;
     /** The same, built once: throws `CauthyConfigError` now if the audience or the workspace is missing. */
@@ -1032,4 +1117,4 @@ interface CauthyPact {
 }
 declare function createCauthy(given?: CauthyOptions): Cauthy;
 
-export { createTokenVerifier as $, type AttributeType as A, type PushPolicyOptions as B, type Cauthy as C, type Resolved as D, type ResolvedContract as E, type RoleOf as F, STANDARD_VARIABLES as G, type SessionOrganization as H, type SessionStatus as I, type JsonValue as J, type SessionUser as K, type SystemKey as L, type MountTarget as M, type NewMember as N, type Organization as O, type PactItem as P, type SystemOptions as Q, type ReplayStore as R, type Session as S, type SystemPolicy as T, type TokenIdentity as U, type TokenRefusal as V, type VerifyTokenOptions as W, type VerifyWebhookOptions as X, can as Y, createCauthy as Z, createSystem as _, type CatalogResource as a, definePolicy as a0, failClosed as a1, memoryReplayStore as a2, policySource as a3, pullCatalog as a4, pullPolicy as a5, pushCatalog as a6, pushPolicy as a7, readContract as a8, remoteKeys as a9, verifyToken as aa, verifyWebhook as ab, CauthyApiError as b, CauthyConfigError as c, type CauthyEvent as d, type CauthyOptions as e, type CauthyPact as f, type CauthySystem as g, CauthyTokenError as h, CauthyUnavailableError as i, CauthyWebhookError as j, type CheckOf as k, type CheckQuestion as l, type CheckResult as m, type CheckRule as n, type ConditionalPermission as o, type ContractOptions as p, type OrganizationMember as q, type OrganizationRef as r, type PactStatus as s, type PermissionOf as t, type Permitted as u, type Policy as v, type PolicyDefinition as w, type PolicyPermission as x, type PolicyRole as y, type PublicSession as z };
+export { createCauthy as $, type AttributeType as A, type PolicyRole as B, type Cauthy as C, type PublicSession as D, type PushPolicyOptions as E, type Resolved as F, type ResolvedContract as G, type RoleOf as H, STANDARD_VARIABLES as I, type JsonValue as J, type SessionOrganization as K, type SessionStatus as L, type MountTarget as M, type NewMember as N, type Organization as O, type PactItem as P, type SessionUser as Q, type ReplayStore as R, type Session as S, type SystemKey as T, type SystemOptions as U, type SystemPolicy as V, type TokenIdentity as W, type TokenRefusal as X, type VerifyTokenOptions as Y, type VerifyWebhookOptions as Z, can as _, type CatalogResource as a, createSystem as a0, createTokenVerifier as a1, createVerifierFromEnv as a2, definePolicy as a3, failClosed as a4, memoryReplayStore as a5, policySource as a6, pullCatalog as a7, pullPolicy as a8, pushCatalog as a9, pushPolicy as aa, readContract as ab, remoteKeys as ac, verifyToken as ad, verifyWebhook as ae, CauthyApiError as b, CauthyConfigError as c, type CauthyEvent as d, CauthyKeyError as e, type CauthyKeyReason as f, type CauthyOptions as g, type CauthyPact as h, type CauthySystem as i, CauthyTokenError as j, CauthyUnavailableError as k, CauthyWebhookError as l, type CheckOf as m, type CheckQuestion as n, type CheckResult as o, type CheckRule as p, type ConditionalPermission as q, type ContractOptions as r, type OrganizationMember as s, type OrganizationRef as t, type PactStatus as u, type PermissionOf as v, type Permitted as w, type Policy as x, type PolicyDefinition as y, type PolicyPermission as z };

package/dist/{cauthy-ClP5orP4.d.mts → cauthy-CCSSj3Lg.d.mts}

@@ -1,6 +1,7 @@
 import { K as KeyStore, P as PactKeys } from './keys-D5k0omTb.mjs';
 import { JWTVerifyGetKey, JWK } from 'jose';
 import { CauthyTheme } from './theme.mjs';
+import { I as Identity } from './identity-BTJ8NB_w.mjs';
 
 /** What createCauthy is given to run by contract. */
 interface ContractOptions {
@@ -110,7 +111,7 @@ declare class CauthyWebhookError extends Error {
     constructor(reason: string);
 }
 interface VerifyWebhookOptions {
-    /** Cauthy's address. Default: `CAUTHY_ISSUER`. */
+    /** Cauthy's address. Default: the one `CAUTHY_KEY` names, else `CAUTHY_ISSUER`. */
     issuer?: string;
     /**
      * This endpoint's own public address, exactly as it is registered in Cauthy.
@@ -150,6 +151,17 @@ declare function verifyWebhook(request: Request, options?: VerifyWebhookOptions)
 
 /** How an application is set up to sign its people in with Cauthy. */
 interface CauthyOptions {
+    /**
+     * The application's CAUTHY_KEY, made in Cauthy's dashboard: Cauthy's
+     * address, the application's client and its secret, in one value. Default:
+     * `CAUTHY_KEY`. With it nothing else is read: the workspace, the system and
+     * the application's addresses come from Cauthy (`GET /v1/connect/self`),
+     * and passing `issuer`, `clientId`, `clientSecret`, `secret`, `system`,
+     * `tenant`, `audience`, `tenantId`, `systemKey` or `rootKey` is refused.
+     */
+    key?: string;
+    /** The key being replaced, during a rotation: read, never written with. Default: `CAUTHY_KEY_PREVIOUS`. */
+    keyPrevious?: string;
     /** Cauthy's public address, e.g. `https://id.example.com`. Default: `CAUTHY_ISSUER`. */
     issuer?: string;
     /** The application's OAuth client id. Default: `CAUTHY_CLIENT_ID`. */
@@ -398,6 +410,13 @@ type SessionStatus = 'authenticated' | 'unauthenticated' | 'expired';
 declare class CauthyConfigError extends Error {
     constructor(message: string);
 }
+/** Why a CAUTHY_KEY was refused (key/cauthy-key.md §3, §8, §9). */
+type CauthyKeyReason = 'key_format' | 'key_version' | 'key_checksum' | 'key_issuer' | 'key_client' | 'key_secret' | 'key_contract_issuer' | 'key_previous_mismatch';
+/** A refused CAUTHY_KEY. The message names the reason, never the key. */
+declare class CauthyKeyError extends CauthyConfigError {
+    readonly reason: CauthyKeyReason;
+    constructor(reason: CauthyKeyReason, message: string);
+}
 
 /** The part of an organization that says what its member may do. */
 interface Permitted {
@@ -637,6 +656,18 @@ declare function pushCatalog(o: Omit<PushPolicyOptions, 'roles' | 'catalog'> & {
     resources: CatalogResource[];
 }): Promise<CatalogResource[]>;
 
+type PublicJwk = {
+    kty: 'OKP';
+    crv: 'Ed25519';
+    x: string;
+};
+interface Signer {
+    kid: string;
+    publicJwk: PublicJwk;
+    /** §6's assertion. iat in seconds; jti a fresh UUID v4. */
+    assertion(clientId: string, tokenEndpoint: string, jti?: string, iat?: number): Promise<string>;
+}
+
 /** The key an application signs its assertions with. */
 interface SystemKey {
     /** The private key: PKCS#8 PEM, or a JWK (as an object or its JSON). RSA, for RS256. */
@@ -679,6 +710,17 @@ interface SystemOptions {
     keys?: PactKeys;
     /** The client the keys prove: the system's own, beside the sign-in client. */
     keysClientId?: string;
+    /**
+     * CAUTHY_KEY's Ed25519 key (key/cauthy-key.md §6) and the client it proves:
+     * every token is asked with an EdDSA assertion. Takes the place of `key`,
+     * `keys` and the secret.
+     */
+    signer?: {
+        clientId: string;
+        signer: Promise<Signer>;
+    };
+    /** The system `check` asks about when it is known only later (CAUTHY_KEY: from Cauthy's answer). */
+    currentSystem?: () => string;
     fetch?: typeof fetch;
     /** How long a call to Cauthy may take before it fails with `503 unavailable`, in milliseconds. Default: 2000. */
     timeoutMs?: number;
@@ -832,13 +874,20 @@ interface TokenIdentity {
     system?: string;
     /** Set when the token is a guest's (only with `allowAnonymous`). */
     anonymous?: true;
+    /** The client a person's token was issued through (`azp`); absent when none was named. */
+    authorizedParty?: string;
+    /**
+     * The token's `client_id`: on a client's own token (only with
+     * `allowClientTokens`), the client's public id; on an AI agent's, the agent's.
+     */
+    clientId?: string;
     /** UTC, ISO 8601. */
     expiresAt: string;
     /** The token as it arrived, to pass on. */
     token: string;
 }
 /** Why a token was refused: the closed list of verification/rules.md, and `no_token` when none was given. */
-type TokenRefusal = 'no_token' | 'too_large' | 'malformed' | 'alg_not_allowed' | 'unsupported_header' | 'missing_kid' | 'unknown_kid' | 'weak_key' | 'bad_signature' | 'missing_claim' | 'invalid_claim' | 'wrong_issuer' | 'wrong_audience' | 'expired' | 'not_yet_valid' | 'issued_in_future' | 'wrong_tenant' | 'system_token' | 'anonymous_token';
+type TokenRefusal = 'no_token' | 'too_large' | 'malformed' | 'alg_not_allowed' | 'unsupported_header' | 'missing_kid' | 'unknown_kid' | 'weak_key' | 'bad_signature' | 'missing_claim' | 'invalid_claim' | 'wrong_issuer' | 'wrong_audience' | 'expired' | 'not_yet_valid' | 'issued_in_future' | 'wrong_tenant' | 'system_token' | 'client_token' | 'anonymous_token' | 'wrong_client';
 /**
  * Cauthy's keys could not be fetched (or are not a key set): the token may be
  * good, and the application cannot tell. Answer 503, not 401. It is not a
@@ -880,6 +929,20 @@ interface VerifyTokenOptions {
     allowSystem?: boolean;
     /** Accept a guest's token (`anon: true`). Default: false (rule R14). */
     allowAnonymous?: boolean;
+    /**
+     * Accept a client's own token (a `token_use` claim, from a
+     * `client_credentials` grant) too: for a backend that serves machines as
+     * well as people. Default: false, so a machine never passes as a person
+     * (rule R13). The identity then carries `clientId`.
+     */
+    allowClientTokens?: boolean;
+    /**
+     * The client this backend signs people in through. When set, a person's
+     * token issued through another client (an `azp` naming another) is refused
+     * with `wrong_client` (rule R15); a token with no `azp` passes. In contract
+     * mode it is the link's sign-in client. Default: none, and `azp` is not checked.
+     */
+    clientId?: string;
 }
 /**
  * Cauthy's published keys (K1 to K5 of verification/rules.md): fetched with a
@@ -904,6 +967,19 @@ declare function createTokenVerifier(options?: VerifyTokenOptions): (from: strin
  * which checks them once, at startup).
  */
 declare function verifyToken(from: string | Request | Headers, options?: VerifyTokenOptions): Promise<TokenIdentity>;
+/**
+ * A verifier made from the environment. With `CAUTHY_KEY` the issuer, the
+ * audience and the workspace are Cauthy's answer to `GET /v1/connect/self`
+ * (asked with the key's assertion, once); nothing else is read, and any of
+ * `issuer`, `audience`, `tenantId` given beside it is refused. Without it,
+ * `CAUTHY_ISSUER`, `CAUTHY_AUDIENCE` and `CAUTHY_TENANT_ID`, deprecated.
+ *
+ *   const verify = await createVerifierFromEnv()
+ *   const who = await verify(request)
+ */
+declare function createVerifierFromEnv(options?: Omit<VerifyTokenOptions, 'issuers'> & {
+    key?: string;
+}): Promise<(from: string | Request | Headers) => Promise<TokenIdentity>>;
 
 /**
  * Where the probes go: the running application's origin
@@ -922,6 +998,13 @@ interface Resolved {
 interface Cauthy {
     /** Serves the routes under `basePath`: login, callback, session, refresh, logout, account. */
     handler(request: Request): Promise<Response>;
+    /**
+     * Who the application is. On CAUTHY_KEY, Cauthy's answer to
+     * `GET /v1/connect/self`, waited for: it rejects with `CauthyApiError`
+     * `503 misconfigured` when Cauthy refuses the key. Otherwise what is
+     * configured, at once (`key: null`). Await it at startup to fail early.
+     */
+    ready(): Promise<Identity>;
     /**
      * Checks that this handler is what answers under `basePath` in the running
      * application, and throws `CauthyConfigError` naming the route when another
@@ -990,6 +1073,8 @@ interface Cauthy {
      * an API of this application: `verifyToken` with this instance's issuer, its
      * workspace (by contract, the link's `tenant_id`; otherwise `tenantId` or
      * `CAUTHY_TENANT_ID`) and its audience (`audience` or `CAUTHY_AUDIENCE`).
+     * By contract it also refuses a person's token issued through another
+     * client than the link's (`wrong_client`).
      */
     verifyToken(from: string | Request | Headers, options?: Partial<VerifyTokenOptions>): Promise<TokenIdentity>;
     /** The same, built once: throws `CauthyConfigError` now if the audience or the workspace is missing. */
@@ -1032,4 +1117,4 @@ interface CauthyPact {
 }
 declare function createCauthy(given?: CauthyOptions): Cauthy;
 
-export { createTokenVerifier as $, type AttributeType as A, type PushPolicyOptions as B, type Cauthy as C, type Resolved as D, type ResolvedContract as E, type RoleOf as F, STANDARD_VARIABLES as G, type SessionOrganization as H, type SessionStatus as I, type JsonValue as J, type SessionUser as K, type SystemKey as L, type MountTarget as M, type NewMember as N, type Organization as O, type PactItem as P, type SystemOptions as Q, type ReplayStore as R, type Session as S, type SystemPolicy as T, type TokenIdentity as U, type TokenRefusal as V, type VerifyTokenOptions as W, type VerifyWebhookOptions as X, can as Y, createCauthy as Z, createSystem as _, type CatalogResource as a, definePolicy as a0, failClosed as a1, memoryReplayStore as a2, policySource as a3, pullCatalog as a4, pullPolicy as a5, pushCatalog as a6, pushPolicy as a7, readContract as a8, remoteKeys as a9, verifyToken as aa, verifyWebhook as ab, CauthyApiError as b, CauthyConfigError as c, type CauthyEvent as d, type CauthyOptions as e, type CauthyPact as f, type CauthySystem as g, CauthyTokenError as h, CauthyUnavailableError as i, CauthyWebhookError as j, type CheckOf as k, type CheckQuestion as l, type CheckResult as m, type CheckRule as n, type ConditionalPermission as o, type ContractOptions as p, type OrganizationMember as q, type OrganizationRef as r, type PactStatus as s, type PermissionOf as t, type Permitted as u, type Policy as v, type PolicyDefinition as w, type PolicyPermission as x, type PolicyRole as y, type PublicSession as z };
+export { createCauthy as $, type AttributeType as A, type PolicyRole as B, type Cauthy as C, type PublicSession as D, type PushPolicyOptions as E, type Resolved as F, type ResolvedContract as G, type RoleOf as H, STANDARD_VARIABLES as I, type JsonValue as J, type SessionOrganization as K, type SessionStatus as L, type MountTarget as M, type NewMember as N, type Organization as O, type PactItem as P, type SessionUser as Q, type ReplayStore as R, type Session as S, type SystemKey as T, type SystemOptions as U, type SystemPolicy as V, type TokenIdentity as W, type TokenRefusal as X, type VerifyTokenOptions as Y, type VerifyWebhookOptions as Z, can as _, type CatalogResource as a, createSystem as a0, createTokenVerifier as a1, createVerifierFromEnv as a2, definePolicy as a3, failClosed as a4, memoryReplayStore as a5, policySource as a6, pullCatalog as a7, pullPolicy as a8, pushCatalog as a9, pushPolicy as aa, readContract as ab, remoteKeys as ac, verifyToken as ad, verifyWebhook as ae, CauthyApiError as b, CauthyConfigError as c, type CauthyEvent as d, CauthyKeyError as e, type CauthyKeyReason as f, type CauthyOptions as g, type CauthyPact as h, type CauthySystem as i, CauthyTokenError as j, CauthyUnavailableError as k, CauthyWebhookError as l, type CheckOf as m, type CheckQuestion as n, type CheckResult as o, type CheckRule as p, type ConditionalPermission as q, type ContractOptions as r, type OrganizationMember as s, type OrganizationRef as t, type PactStatus as u, type PermissionOf as v, type Permitted as w, type Policy as x, type PolicyDefinition as y, type PolicyPermission as z };

package/dist/express.d.mts

@@ -1,8 +1,9 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { S as Session, C as Cauthy } from './cauthy-ClP5orP4.mjs';
+import { S as Session, C as Cauthy } from './cauthy-CCSSj3Lg.mjs';
 import './keys-D5k0omTb.mjs';
 import 'jose';
 import './theme.mjs';
+import './identity-BTJ8NB_w.mjs';
 
 declare global {
     namespace Express {