@pawmaskrelease/psecure 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog: `@pawmaskrelease/psecure`
+
+## 1.1.1
+
+Fixes from a first production integration of 1.1.0. Backward compatible with 1.1.0.
+
+### Fixed
+
+- **Every real browser was reported as tampered (critical, all web clients ≤ 1.1.0).** The `env_stub_dom_traps`
+  RASP probe treated a configurable `document.all[0]` descriptor as a polyfill, but WebIDL makes it configurable in
+  every genuine browser (verified on Edge/Chrome 157). Each sealed request carried a RASP bit, the authority counted a
+  strike, and the third request banned the account and device for 24 h. The check is removed. The authority (1.1.1)
+  also no longer counts strikes for apps in Monitor, so a false positive can never ban users there.
+- **`clientIp` option (Fastify, Express)** to pass the end-user IP when `request.ip` is a proxy hop (e.g. Cloudflare
+  Tunnel → Traefik). Use a resolver that only trusts headers your edge sets.
+- **Fastify typing.** `app.register(psecureFastify, { onDecision, blockedResponse })` left the callback parameters
+  implicitly `any` under `strict` (the plugin's optional options parameter made Fastify infer `Record<string, any>`).
+  `psecureFastify` is now typed `PSecureFastifyPlugin` with a required options parameter; Fastify always passes one,
+  and `app.register(psecureFastify)` without options still works.
+- **`createPSecureFetch().ready()` / `status()`** reported `ready` after a background lease refresh failed
+  (`lease acquisition failed`), and `ready()` called right after a request resolved before the queued refresh began.
+  A failed acquisition now sets `failed` (the previous client keeps sealing until its lease expires), `ready()` waits
+  for a queued refresh, and the next successful lease returns to `ready` and clears `lastError()`.
+- README: the backend verification section said the console Monitor/Block switch does not change verdicts. It now
+  describes 1.1: the adapters follow it in `auto`, verifier callers read `verdict.appMode`, pre-1.1 middlewares ignore
+  it.
+
+### Added
+
+- `@pawmaskrelease/psecure/fastify/augment` (types only): types `request.psecure` (`PSecureDecision | null`) and route
+  config `{ psecure?: boolean; psecureAppKey?: string }`. Also exported: `PSecureFastifyRequestDecoration`,
+  `PSecureFastifyRouteConfig`, `PSecureFastifyPlugin`. `request.psecure` is now decorated in every mode (`null` in
+  `off`).
+- `createPSecureAuditThrottle` and its types (`PSecureGuardAuditEvent`, `PSecureAuditSink`,
+  `PSecureAuditThrottleOptions`, `PSecureAuditThrottle`) from `/fastify`, `/express` and `/edge`, not only `/server`.
+  `flush()` and `close()` now return a promise that settles once the sink finished (a failing sink never rejects);
+  `close()` flushes, is idempotent and ignores later decisions.
+- `modeFallback` / `PSECURE_MODE_FALLBACK` (`monitor` | `enforce`, default `monitor`): the mode `auto` applies while
+  the console mode is unknown (restart during an authority outage, cached mode expired). A verdict carrying the
+  console mode always wins.
+- Docs: app pinning and `appMode` trust, testing with a stubbed authority, `blockedResponse` status for reissued
+  leases, per-route opt-in (`protect: []` + route config), audit events, dynamic import of `/fetch`, web setup
+  (`setAccount`, `enabled`, lazy loading, CSP `connect-src`), the cold-start caveat of `auto`.
+- `SERVER_KEY_IS_APP_KEY` (an app key `psec_app_…` in `PSECURE_SERVER_KEY`) now names both key kinds in its message.
+
+### Same release, outside the npm package
+
+- Console: new applications no longer get made-up figures (SDK version, p95 latency, device count); stored
+  placeholders are cleared on load and the Console shows "No data yet". "Apps in use" is counted from the
+  organization's applications (console, admin, app-limit check) instead of a stored counter that drifted.
+- Docs: a "Go to production" checklist (secrets on hosting, real client IP behind proxies, browser checks, Monitor to
+  Block), troubleshooting for denials right after a deploy and a leaked server key runbook.
+
+## 1.1.0
+
+Integrations in under an hour: framework adapters, a sealing `fetch`, actionable errors and a `doctor` CLI.
+Backward compatible with 1.0.0: nothing was removed or changed in meaning, and every 1.0.0 import keeps working.
+
+### Added
+
+- **Server adapters** on one guard core (`createPSecureGuard`), configured from `PSECURE_*` environment variables:
+  - `@pawmaskrelease/psecure/fastify`: `psecureFastify` plugin. It captures the raw body itself, sets `request.psecure`,
+    and supports route config `{ psecure: true | false }`.
+  - `@pawmaskrelease/psecure/express`: `psecure()` middleware and `psecureRawBody` (for `express.json({ verify })`);
+    sets `req.psecure`.
+  - `@pawmaskrelease/psecure/edge`: `withPSecure(handler)` and `createPSecureEdge()` for Next.js, Hono, Cloudflare
+    Workers, Bun and Deno.
+  - `PSECURE_REQUEST_HEADERS` / `PSECURE_EXPOSED_HEADERS` for CORS, `getPSecureDecision(request)`, `onDecision` hook,
+    `createPSecureAuditThrottle`, pino-compatible logging that never contains the key, envelope, lease or body.
+  - Decision table: Monitor never blocks. Block refuses denied and malformed requests everywhere, and fails closed
+    (missing envelope, authority down) only on `protect` routes (default: all guarded routes). A lease reissue is
+    answered `401` + `x-psecure-reissued-lease`; any other refusal is `403 { error: 'PSECURE_REJECTED' }`.
+- **The console Monitor/Block switch drives enforcement.** The default mode `auto` follows the app's mode, which the
+  authority (>= 1.1) reports on every verdict as `appMode`. The last mode seen is cached for 10 minutes when a request
+  carries no verdict; a cold start behaves as Monitor. `PSECURE_MODE=monitor | enforce | off` overrides the switch.
+  `PSecureVerificationVerdict.appMode` is typed.
+- **App pinning** (`appKey` / `PSECURE_APP_KEY`, recommended): the guard sends it as `expectedAppKey`. The
+  authority then denies a lease of any other application, same organization included, with the new reason
+  `app_mismatch`, and the guard only takes a console mode reported for that app (`verdict.appKey`). This closes the
+  downgrade where a lease of a Monitor app is replayed against a Block app's backend. In `auto` without it, the guard
+  logs a one-time `APP_KEY_NOT_PINNED` warning, and `doctor` warns.
+  `PSecureRequestVerificationContext.expectedAppKey`, `PSecureHttpVerifyInput.expectedAppKey`, `verdict.appKey` and
+  the `app_mismatch` reason are typed and pass through `PSecureRemoteAuthorityClient`.
+- **`createPSecureFetch`** (`@pawmaskrelease/psecure/fetch`, also from the root): a drop-in sealing `fetch`. It falls
+  back gracefully to plain `fetch`, filters origins, never sends a POST twice, provides `setAccount()`, refreshes the
+  lease in the background, defaults to `telemetry: 'minimal'` and lazy-loads the client core.
+- **`PSecureConfigError`** with a stable `code`, an English `hint` and a `docsUrl`, for common misconfigurations
+  (public key missing, invalid or mismatched; keys swapped; non-https authority; CSP or unreachable authority; origins;
+  clock skew; raw body; server key missing or rejected).
+- **`npx @pawmaskrelease/psecure doctor`**: checks that the authority is reachable, the pinned key, the clock, CORS,
+  a test lease with the app key and the server key (from `PSECURE_SERVER_KEY` only, never printed). Optionally checks
+  your API's CORS.
+- `PSECURE_SDK_VERSION`.
+
+### Changed
+
+- The `PSecureClient.connect` lease failure error now carries `status` and the authority's SDK `code`
+  (`INVALID_APP_KEY`, `CROSS_TENANT_APP_KEY`, …), and names the code in its message.
+- The `@pawmaskrelease/psecure/server` barrel also exports the guard and the Express and Edge adapters (the Fastify
+  plugin uses `node:stream` and has its own subpath, so `/server` stays edge-safe).

package/README.md

@@ -15,13 +15,97 @@ before it reaches your business logic.
 > shipped in the public npm client package. `@pawmaskrelease/psecure/server` is backend-only, is
 > not exported from the root barrel, and must never be bundled into browser code.
 
-- Full docs: **https://pawmask.com/docs/psecure**
+- Full docs: **https://psecure.pawmask.com/docs**
 - Proprietary software — use requires a valid Paw Mask PSecure subscription or sandbox
   agreement. See [LICENSE](./LICENSE).
 
 > 🇻🇳 **Lưu ý:** Đây là SDK phía client. Việc xác minh (Verify) chạy trên dịch vụ
 > được Paw Mask lưu trữ tại `https://psecure-api.pawmask.com`; bạn cần giấy phép PSecure còn
-> hiệu lực để sử dụng. Xem tài liệu tại https://pawmask.com/docs/psecure.
+> hiệu lực để sử dụng. Xem tài liệu tại https://psecure.pawmask.com/vi/docs.
+
+## Quick start in 5 minutes
+
+You need three values from the PSecure console (the app's **SDK** tab has a *Copy configuration* panel that
+prefills every snippet below):
+
+| Value | Where | Secret? |
+| --- | --- | --- |
+| App key `psec_app_…` | Applications → your app | no (ships in the client) |
+| Authority public key (64 hex) | Keys → Lease signing keypair | no (ships in the client) |
+| API token `psec_pat_…` | Keys → API tokens → Issue (shown **once**) | **yes**: backend env only |
+
+**1. Install** (Node.js >= 20.16 or a modern browser; zero runtime dependencies)
+
+```bash
+npm install @pawmaskrelease/psecure
+```
+
+**2. Client**: seal the requests your app sends to your API.
+
+```ts
+import { createPSecureFetch } from '@pawmaskrelease/psecure/fetch';
+
+export const psecure = createPSecureFetch({
+  appKey: 'psec_app_…',
+  serverPublicKey: '<64-hex authority public key>',
+  apiOrigins: ['https://api.example.com'],
+});
+
+await psecure.fetch('https://api.example.com/api/orders', { method: 'POST', body }); // instead of fetch()
+psecure.setAccount(user?.id ?? null); // on sign-in / sign-out
+```
+
+If PSecure is down or misconfigured, `psecure.fetch` sends the request unsealed: your app keeps working and your
+backend decides.
+
+**3. Server**: verify every request. Put the secrets in the backend environment:
+
+```bash
+PSECURE_SERVER_KEY=psec_pat_…            # the API token (secret)
+PSECURE_ORIGINS=https://api.example.com  # the origin your browsers call this API on
+PSECURE_APP_KEY=psec_app_…               # this backend's app (recommended: refuses leases of your other apps)
+```
+
+Fastify:
+
+```ts
+import { psecureFastify } from '@pawmaskrelease/psecure/fastify';
+await app.register(psecureFastify);
+```
+
+Express:
+
+```ts
+import { psecure, psecureRawBody } from '@pawmaskrelease/psecure/express';
+app.use(express.json({ verify: psecureRawBody })); // keep the exact body bytes
+app.use('/api', psecure());
+```
+
+Next.js (route handler; also Hono, Workers, Bun, Deno):
+
+```ts
+import { withPSecure } from '@pawmaskrelease/psecure/edge';
+export const POST = withPSecure(async (request) => Response.json({ ok: true }));
+```
+
+If your API is on another origin than your web app, allow the PSecure headers in CORS: request headers
+`PSECURE_REQUEST_HEADERS` and exposed headers `PSECURE_EXPOSED_HEADERS` (both exported by every adapter).
+
+**4. Monitor, then Block.** New apps start in **Monitor**: every request is verified and logged
+(`psecure verify` lines, `request.psecure`), nothing is blocked. When the logs look clean, switch the app to
+**Block** in the console: the adapters follow the switch on the next request, no redeploy. (`PSECURE_MODE=monitor |
+enforce | off` overrides the console switch for incidents and tests.)
+
+**5. Check the setup.**
+
+```bash
+PSECURE_SERVER_KEY=psec_pat_… npx @pawmaskrelease/psecure doctor \
+  --app-key psec_app_… --public-key <64 hex> --origin https://app.example.com
+```
+
+`doctor` prints ✓ / ✗ with a fix for: authority reachable, pinned key, clock, CORS, a test lease with your app key,
+your server key (never printed) and the app pinning (`PSECURE_APP_KEY`). Every misconfiguration the SDK detects at runtime is a `PSecureConfigError` with
+a stable `code` and a `hint` (see [Errors](#errors)). Full docs: https://psecure.pawmask.com/docs
 
 ## Install
 
@@ -40,7 +124,7 @@ Requirements: Node.js >= 20.16.0 or a modern browser (ES2023). Zero runtime depe
 3. Your **backend** forwards the envelope to the PSecure **Verify API** with request
    context; Verify returns allow / deny (and policy signals) which your backend enforces.
 
-## Quick start (web / browser)
+## `PSecureClient` in detail (web / browser)
 
 ### 1. One-call connect (`PSecureClient.connect`)
 
@@ -58,7 +142,7 @@ const client = await PSecureClient.connect({
   authorityUrl: 'https://psecure-api.pawmask.com',
   serverPublicKey: PSECURE_SERVER_PUBLIC_KEY, // REQUIRED (hex, PEM, KeyObject, or an array during key rotation)
   sealOrigins: ['https://api.example.com'],   // origins protectFetch may seal for (default: authority origin)
-  appKey: 'pk_live_xxx',
+  appKey: 'psec_app_…',                        // app key from the console (not a secret)
   accountId,
   // telemetry: 'minimal', onBeforeCollect: (ctx) => userHasConsented,  // see "Privacy & consent"
 });
@@ -202,69 +286,357 @@ What the SDK does:
 
 ### 3. Verify on your backend
 
-Use `PSecureRemoteAuthorityClient` and the built-in Express/Edge middlewares from `@pawmaskrelease/psecure/server`, or forward the sealed request headers directly to `POST /v1/request/verify`. (The Split-Key Verification Engine is intentionally excluded from the public npm tarball to prevent offline white-box oracle attacks.)
+> Most backends should use the 1.1 [server adapters](#server-adapters-11) (Fastify, Express, Next.js/Edge). This
+> section documents the lower-level verifier they are built on.
+
+`@pawmaskrelease/psecure/server` forwards the sealed request to the hosted authority and returns its verdict.
+Your server key (tenant API key from the PSecure console) is a **secret**: keep it in the server environment only.
+The Split-Key Verification Engine itself is intentionally not in the public npm package (it would be an offline
+white-box oracle).
 
 ```ts
 import {
   PSecureRemoteAuthorityClient,
-  createPSecureRemoteExpressMiddleware,
+  createPSecureExpressMiddleware,
   createPSecureRemoteFetchEdgeMiddleware,
 } from '@pawmaskrelease/psecure/server';
 
-// Option A — Remote Authority Client (Node.js / Fastify / NestJS / custom handlers):
-const remoteAuthority = new PSecureRemoteAuthorityClient({
-  authorityBaseUrl: 'https://psecure-api.pawmask.com',
-  authorityApiKey: process.env.PSECURE_SERVER_KEY!,
+const authority = new PSecureRemoteAuthorityClient({
+  baseUrl: 'https://psecure-api.pawmask.com',
+  apiKey: process.env.PSECURE_SERVER_KEY!, // SECRET
+  timeoutMs: 1500,                          // default 3000
+});
+```
+
+**Any Node framework (Fastify, NestJS, custom handlers)** — call the verifier with the request exactly as
+received. `body` must be the raw bytes or string the client sent (not re-serialized JSON):
+
+```ts
+const verdict = await authority.verifyHttpRequestAsync({
+  method: req.method,
+  origin: ['https://api.example.com'],   // origins the envelope may be bound to
+  path: req.url,                         // path + '?' + raw query, as received
+  body: req.rawBody,                     // Buffer / Uint8Array / string
+  headers: req.headers,                  // x-psecure-* headers are read from here
+  clientIp: req.ip,
+  userAgent: req.headers['user-agent'],
 });
 
-// Option B — Express / Connect verification middleware:
+if (!verdict.allowed) {
+  // verdict.action: 'REISSUE_LEASE' | 'STEP_UP_CHALLENGE' | 'BAN_ACCOUNT_AND_HWID' | 'STATE_STORE_UNAVAILABLE';
+  // verdict.reason is a generic code.
+  // Never return verdict.detail to the client: it is a server-side diagnostic.
+  return reply.code(403).send({ error: 'request_rejected', reason: verdict.reason });
+}
+// verdict.shadowWouldHaveAction is set when the app runs in Monitor (shadow) mode.
+```
+
+**Express / Connect:**
+
+```ts
 app.use(
   '/api',
-  createPSecureRemoteExpressMiddleware({
-    authorityBaseUrl: 'https://psecure-api.pawmask.com',
-    authorityApiKey: process.env.PSECURE_SERVER_KEY!,
+  createPSecureExpressMiddleware(authority, {
     origins: ['https://api.example.com'],
+    excludePaths: ['/api/health'],
   }),
 );
+```
+
+**Fetch / Edge runtimes (Cloudflare Workers, Next.js middleware, Deno, Bun):**
+
+```ts
+const handler = createPSecureRemoteFetchEdgeMiddleware(
+  authority,
+  (request, verdict) => fetch(request), // downstream; called only for allowed requests
+  { origins: ['https://api.example.com'] },
+);
+export default { fetch: handler };
+```
+
+Roll out in two phases: **Monitor** first (verify every request and record the verdicts, let denied requests
+through), **Block** once the reports look clean. The console Monitor/Block switch of the app drives this:
+
+- **1.1 adapters** (`psecureFastify`, `psecure()`, `withPSecure`, `createPSecureGuard`) in the default mode `auto`
+  follow the switch on the next request, no redeploy (see [Monitor / Block](#monitor--block-mode-auto)).
+- **This lower-level verifier** returns the verdict only; the decision to refuse is your code. The authority (>= 1.1)
+  reports the switch on every verdict as `verdict.appMode` (`'monitor' | 'block'`, with `verdict.appKey`): branch on
+  it, e.g. refuse when `!verdict.allowed && verdict.appMode === 'block'`.
+- **Pre-1.1 middlewares** (`createPSecureExpressMiddleware`, `createPSecureRemoteFetchEdgeMiddleware`) ignore
+  `appMode`: they refuse every denied request whatever the switch says. Upgrade to the 1.1 adapters to follow it.
+
+The verdict itself (`allowed`, `action`, `reason`) does not depend on the switch. `verdict.shadowWouldHaveAction` is
+set only when the authority deployment itself runs in shadow mode. See
+https://psecure.pawmask.com/docs/backend/rollout.
+
+The HTTP contract of the authority (including `POST /v1/request/verify`) is published as OpenAPI 3.1 in
+`server/api/openapi.json` of the repository.
 
-// Option C — Fetch / Edge runtime verification middleware (Cloudflare Workers, Next.js, Hono):
-const psecVerify = createPSecureRemoteFetchEdgeMiddleware({
-  authorityVerifyUrl: 'https://psecure-api.pawmask.com/v1/request/verify',
-  authorityApiKey: process.env.PSECURE_SERVER_KEY!,
+## Server adapters (1.1)
+
+The Fastify plugin, the Express middleware and the Fetch/Edge wrapper share one guard (`createPSecureGuard`, also
+exported for custom integrations). Types are structural: the SDK does not depend on any framework.
+
+### Options
+
+Every option falls back to an environment variable, so `psecureFastify` / `psecure()` / `withPSecure` work with no
+arguments.
+
+| Option | Env | Default | |
+| --- | --- | --- | --- |
+| `serverKey` | `PSECURE_SERVER_KEY` | (required unless `mode: 'off'`) | API token `psec_pat_…`. Never logged. |
+| `origins` | `PSECURE_ORIGINS` (comma separated) | (required) | Public origin(s) your browsers call this API on. The client seals for them. |
+| `mode` | `PSECURE_MODE` | `'auto'` | `auto` follows the console switch; `monitor` / `enforce` / `off` override it. |
+| `authorityUrl` | `PSECURE_AUTHORITY_URL` | `https://psecure-api.pawmask.com` | https only (http for loopback). |
+| `timeoutMs` | `PSECURE_TIMEOUT_MS` | `1500` | Authority call timeout. |
+| `modeFallback` | `PSECURE_MODE_FALLBACK` | `'monitor'` | Mode `auto` applies while the console mode is unknown (cold start, cached mode expired). `'enforce'` for apps in Block: see [Monitor / Block](#monitor--block-mode-auto). |
+| `appKey` | `PSECURE_APP_KEY` | none | **Recommended.** The app this backend serves: sent as `expectedAppKey`, so the authority refuses leases of any other app (`app_mismatch`) and the console mode is only taken for this app. Also scopes the mode cache. Per request: `appKey` on the request (Fastify route config `psecureAppKey`). |
+| `protect` | | `'all'` | Routes that fail closed (see below). Default: **every** guarded route; for per-route opt-in pass `protect: []` and mark routes (Fastify route config `{ psecure: true }`, or matchers). Matchers: `'/pay'`, `'/api/*'`, `'/orders/:id'`, `'POST /pay'`, `RegExp`, `(info) => boolean`. |
+| `skip` | | `[]` | Routes never checked (health checks, webhooks). `OPTIONS` is always skipped. |
+| `onDecision` | | | `(decision, { method, path, route, ip }) => void` for metrics / audit. `createPSecureAuditThrottle({ sink })` turns it into deduplicated audit events (see [Audit events](#audit-events)). |
+| `logger` | | console | pino-compatible `{ info, warn, debug? }` (Fastify uses `app.log`); `false` disables. |
+| `blockedResponse` | | `403 { error: 'PSECURE_REJECTED' }` | `(decision) => ({ status?, body })`: your API's error shape for refused requests. Without `status` the SDK's status is kept: **401** for a reissued lease (the client needs it to adopt the lease and retry), else 403. Keep `error: 'PSECURE_REJECTED'` in the body if you use `createPSecureFetch`: it refreshes the lease on that answer. |
+
+Fastify extras: route config `{ psecure: true }` protects a route, `{ psecure: false }` skips it, `{ psecureAppKey }`
+pins the route to another app. Express extras:
+`maxBodyBytes` (default 1 MiB). Edge extras: `maxBodyBytes`, `clientIp(request)`; `options` may be a function of the
+handler's extra arguments (Cloudflare Workers `env`).
+
+**Per-route opt-in.** By default every guarded route is fail-closed in Block. To protect only some routes:
+
+```ts
+await app.register(psecureFastify, { protect: [] });             // nothing fails closed by default…
+app.post('/v1/pay', { config: { psecure: true } }, handler);     // …except the routes you mark
+app.post('/v1/webhook', { config: { psecure: false } }, handler); // never checked
+// Express / Edge: psecure({ protect: ['POST /v1/pay', '/v1/orders/*'] })
+```
+
+Denied and malformed envelopes are still refused on every guarded route in Block; `protect` only decides where a
+**missing** envelope or an unreachable authority is refused.
+
+**Fastify with TypeScript.** `app.register(psecureFastify, { onDecision, blockedResponse })` types the callbacks
+(1.1.1; in 1.1.0 they were implicitly `any` under `strict`). Add the augmentation once to type `request.psecure`
+(`PSecureDecision | null`) and the route config:
+
+```ts
+import '@pawmaskrelease/psecure/fastify/augment'; // types only (needs fastify 4 or 5 in your project)
+// or, equivalently:
+// declare module 'fastify' {
+//   interface FastifyRequest extends PSecureFastifyRequestDecoration {}
+//   interface FastifyContextConfig extends PSecureFastifyRouteConfig {}
+// }
+```
+
+### Decision table
+
+| Outcome | Monitor | Block (enforce), `protect` route | Block, other route |
+| --- | --- | --- | --- |
+| verified | served | served | served |
+| denied (tampered, replayed, forged, banned, lease of another app) or malformed envelope | served, logged | **403** | **403** |
+| lease must be renewed, with a reissued lease | served + `x-psecure-reissued-lease` | **401** + `x-psecure-reissued-lease` | **401** + header |
+| no envelope | served | **403** | served |
+| authority down / timeout / key rejected | served | **403** (fail-closed) | served |
+
+`createPSecureFetch` adopts a reissued lease on the 401 and retries once. Each decision is available as
+`request.psecure` (Fastify), `req.psecure` / `res.locals.psecure` (Express), or `getPSecureDecision(request)` (all
+adapters, typed): `{ verified, result, action, reason, effectiveMode, modeSource, blocked, wouldBlock,
+envelopeAccountId, ... }`. `envelopeAccountId` is what the client claims: compare it with your session user before
+trusting it.
+
+### Monitor / Block (`mode: 'auto'`)
+
+The authority reports the app's console mode on every verdict (`appMode`). In `auto` the guard blocks only while the
+app is in **Block**. When a request carries no verdict (no envelope, authority unreachable), the guard uses the last
+mode it saw for the app, for up to 10 minutes; with nothing known yet (cold start) it behaves as Monitor. Trade-off:
+right after a restart during an authority outage, unsealed requests are served until the first verdict arrives (a
+cold start is Monitor), and the same happens when the cached mode expired during a long outage. Where that matters
+more than availability:
+
+- `PSECURE_MODE=enforce` pins Block whatever the console says (the switch is then ignored), or
+- `PSECURE_MODE_FALLBACK=enforce` (`modeFallback: 'enforce'`) keeps following the switch but applies Block while the
+  console mode is unknown. A verdict that carries the console mode always wins. Default `monitor`.
+
+Set `PSECURE_APP_KEY`. Without it, the guard follows the mode of whichever app a lease belongs to, so a lease of one
+of your Monitor apps replayed against a Block app's backend would only be logged; the guard warns once at startup
+(`APP_KEY_NOT_PINNED`). With it, that lease is denied (`reason: 'app_mismatch'`) and refused in Block, and the guard
+trusts a verdict's `appMode` only when the verdict's `appKey` equals the pinned key; any other verdict is treated as
+carrying no mode (cache, then `modeFallback`). Each decision says which mode applied (`effectiveMode`) and why
+(`modeSource`: `console`, `cache`, `default` or `config`).
+
+### Audit events
+
+```ts
+import { createPSecureAuditThrottle } from '@pawmaskrelease/psecure/fastify'; // also /express, /edge, /server
+const audit = createPSecureAuditThrottle({ sink: (event) => auditLog.write(event) });
+await app.register(psecureFastify, { onDecision: audit.onDecision });
+app.addHook('onClose', () => audit.close());
+```
+
+The sink (`PSecureAuditSink`, `(event) => void | Promise<void>`) receives a `PSecureGuardAuditEvent`; it is never
+awaited by the request path and its errors are swallowed. Events never contain the key, envelope, lease or body:
+
+- `{ type: 'psecure.reject', result, action, reason, route, method, ip? }`: a refused request, emitted at once.
+  Identical refusals (result, reason, route, ip) are emitted once per `rejectCooldownMs` (default 60 s).
+- `{ type: 'psecure.monitor_summary', windowStart, windowEnd, wouldBlock, distinctIps, distinctIpsCapped, buckets }`:
+  what Monitor would have refused in a window (`summaryWindowMs`, default 10 min); `buckets` is
+  `[{ result, reason, route, count }]`, top 50 by count.
+
+`flush()` emits the pending summary now (nothing if the window is empty) and starts a new window; refusals are never
+buffered. `close()` stops the timer and **flushes**, then ignores later decisions; it is idempotent. Both return a
+promise that settles when the sink finished (`await audit.close()` before exiting).
+
+### Testing with a stubbed authority
+
+Point `authorityUrl` at a local stub (http is accepted on loopback) or pass `fetch`. The guard calls
+`POST {authorityUrl}/psecure.authority.v1.PSecureAuthorityService/VerifySealedRequest` and needs only:
+
+```json
+{ "allowed": true, "action": "ALLOW", "reason": "ok" }
+```
+
+A denial is `{ "allowed": false, "action": "STEP_UP_CHALLENGE", "reason": "verification_failed" }`; a reissue is
+`{ "allowed": false, "action": "REISSUE_LEASE", "reason": "reissue_required", "reissuedLease": { "compactToken": "…" } }`.
+To exercise `auto`, add `"appMode": "block"` (or `"monitor"`) and, when the guard is pinned,
+`"appKey": "<the pinned PSECURE_APP_KEY>"`: without a matching `appKey` the mode is ignored. Requests still need a
+well-formed `x-psecure-envelope` (from a real client, or `sealWirePayloadB64Url` from
+`@pawmaskrelease/psecure/protocol`); without one the guard does not call the authority (`result: 'missing'`). For
+tests that need no verification at all, `PSECURE_MODE=off`.
+
+### Raw body
+
+PSecure hashes the exact bytes the client sealed, so the adapters need the raw body:
+
+- **Fastify** captures it itself (a `preParsing` tap: works with every content-type parser, never parses twice). An
+  existing `request.rawBody` is used as is.
+- **Express**: `express.json({ verify: psecureRawBody })` (same for `express.text` / `raw` / `urlencoded`), or mount
+  `psecure()` before the body parser: it then reads and parses the body once and the parser skips it. A body consumed
+  without its bytes is reported as `raw_body_unavailable` (and refused in Block).
+- **Edge**: read from a clone; your handler gets an unread `request`.
+
+### CORS
+
+```ts
+import { PSECURE_REQUEST_HEADERS, PSECURE_EXPOSED_HEADERS } from '@pawmaskrelease/psecure/fastify';
+await app.register(cors, {
+  origin: ['https://app.example.com'],
+  allowedHeaders: ['content-type', 'authorization', ...PSECURE_REQUEST_HEADERS],
+  exposedHeaders: [...PSECURE_EXPOSED_HEADERS],
 });
+```
 
-// Option D — Direct HTTP call to POST /v1/request/verify:
-const verify = await fetch('https://psecure-api.pawmask.com/v1/request/verify', {
-  method: 'POST',
-  headers: {
-    'content-type': 'application/json',
-    'x-psecure-api-key': process.env.PSECURE_SERVER_KEY!,
-  },
-  body: JSON.stringify({
-    method: req.method,
-    origin: 'https://api.example.com',
-    allowedOrigins: ['https://api.example.com'],
-    path: req.originalUrl ?? req.url,
-    bodyUtf8: rawRequestBody,
-    headers: {
-      'x-psecure-version': req.headers['x-psecure-version'],
-      'x-psecure-envelope': req.headers['x-psecure-envelope'],
-      'x-psecure-aead-tag': req.headers['x-psecure-aead-tag'],
-    },
-    clientIp: req.ip,
-    userAgent: req.headers['user-agent'],
-  }),
+### Recipes
+
+**NestJS** (no Nest dependency): on Express, `const app = await NestFactory.create(AppModule, { rawBody: true });
+app.use(psecure());` (Nest's `rawBody: true` fills `req.rawBody`). On Fastify, `NestFactory.create(AppModule, new
+FastifyAdapter())` then `await app.register(psecureFastify)`. A Nest project compiled to CommonJS needs Node.js
+>= 20.19 or >= 22.12 (`require()` of an ES module).
+
+**Hono**:
+
+```ts
+import { createPSecureEdge } from '@pawmaskrelease/psecure/edge';
+const ps = createPSecureEdge();
+app.use('/api/*', async (c, next) => {
+  const { decision, response } = await ps.check(c.req.raw);
+  if (response) return response;
+  await next();
+  c.res = ps.finish(c.res, decision);
 });
-const result = await verify.json(); // { allowed, action, reason, ... }
 ```
 
+**Cloudflare Workers**: `export default { fetch: withPSecure(handler, (env) => ({ serverKey: env.PSECURE_SERVER_KEY,
+origins: env.PSECURE_ORIGINS, clientIp: (r) => r.headers.get('cf-connecting-ip') ?? undefined })) };`
+
+## Client helper: `createPSecureFetch` (1.1)
+
+`@pawmaskrelease/psecure/fetch` wraps `PSecureClient` for apps that just want a sealing `fetch`:
+
+| Option | Default | |
+| --- | --- | --- |
+| `appKey`, `serverPublicKey`, `apiOrigins` | (required) | Public values; `serverPublicKey` may be an array during a key rotation. Only `apiOrigins` are sealed. |
+| `authorityUrl` | `https://psecure-api.pawmask.com` | |
+| `enabled` | `true` | Rollout switch: `false` = plain fetch, SDK never loaded. |
+| `accountId` | `null` | Or later `setAccount(id \| null)`. |
+| `telemetry`, `onBeforeCollect` | `'minimal'` | See [Privacy & consent](#privacy--consent). |
+| `waitForConnectMs` | `2000` | How long the first requests wait for the lease before going out unsealed. |
+| `onError`, `strict` | | Called once per problem; `strict: true` throws configuration errors instead. |
+
+Returns `{ fetch, setAccount, status, lastError, ready, start, dispose }`. `status()` is `disabled`,
+`misconfigured`, `idle`, `connecting`, `ready` or `failed`. Behaviour:
+
+- Graceful fallback: requests go out unsealed while PSecure is disabled, misconfigured, connecting or failing
+  (retried with backoff from 30 s to 5 min). A request that already left and failed on the network is rethrown,
+  never re-sent unsealed (no duplicated POST).
+- The lease is refreshed in the background when it expires or the API answers `PSECURE_REJECTED`.
+- The SDK core is loaded lazily on the first sealed request (a dynamic import your bundler puts in its own chunk).
+  The eager part of `@pawmaskrelease/psecure/fetch` is about 16 KiB gzip; the lazy core about 112 KiB gzip (measured
+  on 1.1.0, before your bundler's minification).
+- `ready()` resolves with the outcome of the connect or lease refresh in flight: `ready`, or `failed` when the latest
+  lease acquisition failed (including a failed background refresh, 1.1.1); the next successful lease returns to
+  `ready`.
+- Browser CSP: add the authority origin to `connect-src` (e.g. `connect-src 'self' https://api.example.com
+  https://psecure-api.pawmask.com`). A blocked request is reported as `CSP_BLOCKED`.
+
+**Web apps.** Call `setAccount(user.id)` after sign-in and `setAccount(null)` after sign-out: the lease is bound to the
+account and re-acquired (calling it before the first request only records the account). Use `enabled` as the rollout
+switch (`enabled: false` = plain `fetch`, the core is never loaded). The core is loaded on the first sealed request or
+`start()`; call `start()` early (e.g. after the first render) to hide the lease latency.
+
+To keep even the eager ~16 KiB out of a build where PSecure is disabled, import the helper dynamically behind your
+flag; your bundler then splits it out and never loads it:
+
+```ts
+let apiFetch: typeof fetch = fetch;
+if (import.meta.env.VITE_PSECURE_ENABLED === 'true') {
+  const { createPSecureFetch } = await import('@pawmaskrelease/psecure/fetch');
+  apiFetch = createPSecureFetch({ appKey, serverPublicKey, apiOrigins: ['https://api.example.com'] }).fetch;
+}
+```
+
+## Errors
+
+`PSecureConfigError` (`code`, `hint`, `docsUrl`) is thrown at startup by the server adapters and reported by
+`createPSecureFetch` (`lastError()`, `onError`). Runtime problems the guard can only see per request are logged once
+as `psecure config:` lines with the same codes.
+
+| Code | Typical cause |
+| --- | --- |
+| `SERVER_KEY_MISSING` | `PSECURE_SERVER_KEY` not set (set `PSECURE_MODE=off` to run without PSecure) |
+| `SERVER_KEY_IS_APP_KEY`, `SERVER_KEY_IN_CLIENT` | app key and API token swapped |
+| `SERVER_KEY_REJECTED` | token revoked/expired, or of another organization (authority answered 401/403) |
+| `PUBLIC_KEY_MISSING`, `PUBLIC_KEY_INVALID`, `PUBLIC_KEY_MISMATCH` | pinned key absent, malformed, or not the authority's key |
+| `APP_KEY_MISSING`, `APP_KEY_INVALID`, `ORG_INACTIVE` | app key absent, unknown to the authority or not of your organization (also `PSECURE_APP_KEY`), organization suspended |
+| `ORIGINS_MISSING`, `ORIGIN_INVALID`, `ORIGIN_MISMATCH` | `PSECURE_ORIGINS` / `apiOrigins` absent, malformed, or not the same on both sides |
+| `AUTHORITY_INSECURE`, `AUTHORITY_INVALID`, `AUTHORITY_UNREACHABLE`, `CSP_BLOCKED` | http authority, bad URL, network/DNS, CSP `connect-src` |
+| `CLOCK_SKEW` | the device or server clock is off |
+| `RAW_BODY_MISSING` | the body parser dropped the raw bytes |
+| `MODE_INVALID` | `PSECURE_MODE` is not `auto`, `monitor`, `enforce` or `off` (or `PSECURE_MODE_FALLBACK` not `monitor` / `enforce`) |
+
+## `doctor` CLI
+
+```bash
+npx @pawmaskrelease/psecure doctor [--authority <url>] [--app-key psec_app_…] [--public-key <hex>]
+                                   [--origin https://app.example.com] [--api https://api.example.com/health] [--json]
+```
+
+Flags fall back to `PSECURE_AUTHORITY_URL`, `PSECURE_APP_KEY`, `PSECURE_PUBLIC_KEY` and `PSECURE_WEB_ORIGIN` (the
+origin your web app runs on; not `PSECURE_ORIGINS`, which is your API's). The server key is read from `PSECURE_SERVER_KEY` only (a `--server-key` flag is refused so it does
+not land in shell history) and is never printed: `doctor` proves it by sending a deliberately unsealed verify request,
+which the authority must answer with a denial. With `PSECURE_APP_KEY` set, the same call proves that key is an app of
+the token's organization; unset, `doctor` warns. Exit code 1 when a check fails.
+
 ## Entry points
 
 | Import | What it provides |
 | --- | --- |
 | `@pawmaskrelease/psecure` | Client SDK barrel (protocol, crypto, vm, rasp, client, adapters); no server code |
+| `@pawmaskrelease/psecure/fetch` | `createPSecureFetch` (sealing `fetch` with fallback; lazy-loads the client core) |
+| `@pawmaskrelease/psecure/fastify` | **Backend.** `psecureFastify` plugin, `PSECURE_REQUEST_HEADERS`, `PSECURE_EXPOSED_HEADERS`, `createPSecureAuditThrottle` |
+| `@pawmaskrelease/psecure/fastify/augment` | Types only: `request.psecure` and route config `{ psecure, psecureAppKey }` on Fastify's types |
+| `@pawmaskrelease/psecure/express` | **Backend.** `psecure()` middleware, `psecureRawBody`, `createPSecureAuditThrottle` |
+| `@pawmaskrelease/psecure/edge` | **Backend / Edge.** `withPSecure`, `createPSecureEdge` (Next.js, Hono, Workers, Bun, Deno) |
 | `@pawmaskrelease/psecure/client` | `PSecureClient` (`connect` / `sealRequest` / `sealRequestAsync` / `protectFetch` / `dispose`) |
-| `@pawmaskrelease/psecure/server` | **Backend / Edge only.** Remote Authority client & verification middlewares: `PSecureRemoteAuthorityClient`, `createExpressMiddleware`, `createPSecureExpressMiddleware`, `createPSecureRemoteExpressMiddleware`, `createPSecureFetchEdgeMiddleware`, `createPSecureRemoteFetchEdgeMiddleware`. (The Split-Key Verification Engine is never shipped in the public npm package to prevent offline white-box oracle attacks; never import `@pawmaskrelease/psecure/server` from browser code.) |
+| `@pawmaskrelease/psecure/server` | **Backend / Edge only.** Remote Authority client & verification middlewares: `PSecureRemoteAuthorityClient`, `createExpressMiddleware`, `createPSecureExpressMiddleware`, `createPSecureRemoteExpressMiddleware`, `createPSecureFetchEdgeMiddleware`, `createPSecureRemoteFetchEdgeMiddleware`, plus the 1.1 guard (`createPSecureGuard`) and the Express / Edge adapters. (The Split-Key Verification Engine is never shipped in the public npm package to prevent offline white-box oracle attacks; never import `@pawmaskrelease/psecure/server` from browser code.) |
 | `@pawmaskrelease/psecure/protocol` | Wire format, codecs, lease verification, constants, types |
 | `@pawmaskrelease/psecure/crypto` | Crypto primitives & ciphers |
 | `@pawmaskrelease/psecure/vm` | `PSecureVm` bytecode VM + polymorphic bundler |

package/bin/psecure.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// `npx @pawmaskrelease/psecure doctor` — see `psecure --help`.
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 20) {
+  console.error(`@pawmaskrelease/psecure needs Node.js >= 20 (this is ${process.versions.node}).`);
+  process.exit(1);
+}
+const { runPSecureCli } = await import('../dist/cli/doctor.js');
+process.exitCode = await runPSecureCli(process.argv.slice(2), {
+  stdout: (t) => console.log(t),
+  stderr: (t) => console.error(t),
+  env: process.env,
+});

package/dist/adapters/desktop.js

@@ -55,4 +55,4 @@ dispose(){if(this.#_0x1dd12b)
 return;this.#_0x1dd12b=true;this.#_0x557f55.fill(0);this.#_0xd63721.clear();this.#_0x32df7f.dispose();}}
 export async function sealDesktopRequestAsync(_0x53637e,_0x02eef0){if(_0x53637e instanceof PSecureDesktopBridge){return _0x53637e.sealDesktopRequestAsync(_0x02eef0);}
 return _0x53637e.sealRequestAsync({[_0xc9bd50_S(26)]:_0x02eef0.method,[_0xc9bd50_S(27)]:_0x02eef0.path,[_0xc9bd50_S(28)]:_0x02eef0.origin,[_0xc9bd50_S(29)]:_0x02eef0.body,[_0xc9bd50_S(30)]:_0x02eef0.nowMs,});}
-/* @psec-self-seal sha256=35a116d1c1fa149f9415efa4bfc47009b148d54598a8a176b4788e4dfe120b4c fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=2a8c0aa9c667aa603e5f3b3a4cf29077637dc0fb7a64c87c5edf46e6766b9daf fnv1a=dd197b03 */

package/dist/adapters/index.js

@@ -3,4 +3,4 @@ export * from "./mobile-bridge.js";
 export * from "./react-native.js";
 export * from "./desktop.js";
 
-/* @psec-self-seal sha256=4b2feeebab795ca3fac3416571b8bac2dd48cffb8dca888eb3bf004295929f32 fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=6711c3a559952f6bcf55039df4e99df9f78f11aa2db94ff9d53f19950930e50c fnv1a=dd197b03 */