@pawmaskrelease/psecure 0.1.0-beta → 1.1.0

package/README.md

@@ -1,175 +1,560 @@
-# @pawmask/psecure
-
-**Paw Security (PSecure)** is the client SDK for the [Paw Mask](https://pawmask.com)
-anti-tamper / anti-reverse-engineering platform. It seals every outgoing request from
-your web, Node, mobile, or desktop app with a bytecode-VM-protected, device-bound
-cryptographic envelope, and your backend confirms each request against the hosted
-**PSecure Verify API** — stopping replayed, forged, scripted, and tampered traffic
-before it reaches your business logic.
-
-> This package ships the **client SDK only**. Verification runs on the Paw Mask
-> hosted authority (`https://api.pawmask.com`). Self-hosting the split-key authority
-> is a separate Paw Mask enterprise offering.
-
-- Full docs: **https://pawmask.com/docs/psecure**
-- 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://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.
-
-## Install
-
-```bash
-npm install @pawmask/psecure
-```
-
-Requirements: Node.js >= 18.17 or a modern browser (ES2023). Zero runtime dependencies.
-
-## How it works
-
-1. Your app **leases** a short-lived, server-signed ticket from the hosted authority.
-2. The client **seals** each request into an envelope using the lease: a 3-basic-block
-   bytecode VM, device (hardware-anchor) binding, RASP telemetry, and an HMAC-SHA256
-   AEAD tag. The envelope travels in `x-psecure-*` headers.
-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)
-
-### 1. Zero-config auto-connect (`PSecureClient.connect`)
-
-The recommended one-call integration collects 128+ hardware/WebGL/Audio/ALU signals, generates an ephemeral Ed25519 Proof-of-Possession (PoP) keypair, and acquires a Split-Key Lease from `/psec/lease`:
-
-```ts
-import { PSecureClient } from '@pawmask/psecure';
-
-const client = await PSecureClient.connect({
-  authorityUrl: 'https://api.pawmask.com',
-  appKey: 'pk_live_xxx',
-  accountId,
-  installId,
-});
-
-const response = await client.protectFetch('https://api.example.com/api/order', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ sku: 1 }),
-});
-```
-
-### 2. Manual lease & sealing (advanced)
-
-Obtain a lease from the Authority (`POST /psec/lease` or `/v1/lease/issue`) with your application key:
-
-```ts
-const res = await fetch('https://api.pawmask.com/psec/lease', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ appKey: 'pk_live_xxx', accountId, installId }),
-});
-const lease = await res.json(); // { leaseToken, serverPublicKey, ... }
-```
-
-Then initialize `PSecureClient` and seal requests:
-
-```ts
-import { PSecureClient } from '@pawmask/psecure';
-import type { PSecureHardwareAnchors } from '@pawmask/psecure';
-
-const hardwareAnchors: PSecureHardwareAnchors = {
-  cpuAnchor,        // CPU core & architecture anchor
-  gpuAnchor,        // GPU / WebGL renderer & shader precision anchor
-  aluAudioAnchor,   // AudioContext / IEEE-754 ALU anchor
-  displayAnchor,    // screen / color-depth / pixel geometry anchor
-  platformAnchor,   // OS / timezone / locale anchor
-};
-
-const client = new PSecureClient({
-  accountId,
-  installId,
-  serverPublicKey: lease.serverPublicKey,
-  leaseToken: lease.leaseToken,
-  hardwareAnchors,
-});
-
-// Option A — drop-in fetch wrapper (adds the x-psecure-* headers automatically):
-const response = await client.protectFetch('https://api.example.com/api/order', {
-  method: 'POST',
-  body: JSON.stringify({ sku: 1 }),
-});
-
-// Option B — seal manually and attach the headers yourself:
-const { envelope, headers } = client.sealRequest({
-  method: 'POST',
-  path: '/api/order',
-  body: JSON.stringify({ sku: 1 }),
-});
-// headers → { 'x-psecure-version', 'x-psecure-envelope', 'x-psecure-aead-tag' }
-```
-
-When the authority re-issues a lease (`x-psecure-reissued-lease`), call `client.updateLeaseToken(newToken)`.
-
-### 3. Verify on your backend
-
-Use the built-in Express/Edge middleware from `@pawmask/psecure/server` or forward the sealed request headers directly to `POST /v1/request/verify`:
-
-```ts
-import { createPSecureRemoteFetchEdgeMiddleware } from '@pawmask/psecure/server';
-
-// Option A — Remote Edge / Express verification middleware:
-const psecVerify = createPSecureRemoteFetchEdgeMiddleware({
-  authorityVerifyUrl: 'https://api.pawmask.com/v1/request/verify',
-  authorityApiKey: process.env.PSECURE_SERVER_KEY!,
-});
-
-// Option B — Direct HTTP call to POST /v1/request/verify:
-const verify = await fetch('https://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,
-    path: req.path,
-    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'],
-  }),
-});
-const result = await verify.json(); // { allowed, action, reason, ... }
-```
-
-## Entry points
-
-| Import | What it provides |
-| --- | --- |
-| `@pawmask/psecure` | Full client & server SDK barrel |
-| `@pawmask/psecure/client` | `PSecureClient` (`connect` / `sealRequest` / `protectFetch`) |
-| `@pawmask/psecure/server` | `PSecureServerAuthority`, `createPSecureExpressMiddleware`, `createExpressMiddleware`, `createPSecureRemoteFetchEdgeMiddleware` |
-| `@pawmask/psecure/protocol` | Wire format, codecs, lease verification, constants, types |
-| `@pawmask/psecure/crypto` | Crypto primitives & ciphers |
-| `@pawmask/psecure/vm` | `PSecureVm` bytecode VM + polymorphic bundler |
-| `@pawmask/psecure/rasp` | RASP probes, device intelligence, hardware binding |
-| `@pawmask/psecure/web-shield` | `PSecureWebShield` DOM/script integrity (browser) |
-| `@pawmask/psecure/react-native` | React Native bridge adapter |
-| `@pawmask/psecure/desktop` | Desktop bridge adapter |
-| `@pawmask/psecure/mobile-bridge` | Native mobile bridge adapter |
-| `@pawmask/psecure/web-kernel` | Standalone obfuscated web VM kernel (browser) |
-
-## Native (Rust) core
-
-A high-assurance Rust core (`psecure_core`) and packer exist for server-side and native
-deployments. They are **not required** by this JavaScript/TypeScript client SDK and are
-**not** shipped in this npm package. Contact Paw Mask for native/enterprise integration.
-
-## License
-
-Proprietary. Copyright Paw Mask. See [LICENSE](./LICENSE).
+# @pawmaskrelease/psecure
+
+**Paw Security (PSecure)** is the client SDK for the [Paw Mask](https://pawmask.com)
+anti-tamper / anti-reverse-engineering platform. It seals every outgoing request from
+your web, Node, mobile, or desktop app with a bytecode-VM-protected, device-bound
+cryptographic envelope, and your backend confirms each request against the hosted
+**PSecure Verify API** — stopping replayed, forged, scripted, and tampered traffic
+before it reaches your business logic.
+
+> Verification runs on the Paw Mask Authority (`https://psecure-api.pawmask.com` or your
+> deployed `psecure-authority` binary/container). The package also provides Node.js and
+> Edge remote verification clients & middlewares (`@pawmaskrelease/psecure/server`) that forward
+> sealed envelopes to the Authority. To prevent offline white-box verification oracle
+> attacks, the Split-Key Verification Engine (`PSecureServerAuthority`) is **never**
+> 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://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://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
+
+```bash
+npm install @pawmaskrelease/psecure
+```
+
+Requirements: Node.js >= 20.16.0 or a modern browser (ES2023). Zero runtime dependencies.
+
+## How it works
+
+1. Your app **leases** a short-lived, server-signed ticket from the hosted authority.
+2. The client **seals** each request into an envelope using the lease: a 3-basic-block
+   bytecode VM, device (hardware-anchor) binding, RASP telemetry, and an HMAC-SHA256
+   AEAD tag. The envelope travels in `x-psecure-*` headers.
+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.
+
+## `PSecureClient` in detail (web / browser)
+
+### 1. One-call connect (`PSecureClient.connect`)
+
+`connect()` collects device anchors (subject to `telemetry` / consent, see below), creates a
+Proof-of-Possession (PoP) key, acquires a lease from `/psec/lease` on `authorityUrl`, and verifies the
+lease signature against the **pinned** authority key:
+
+```ts
+import { PSecureClient } from '@pawmaskrelease/psecure';
+
+// Ship the authority's Ed25519 public key with your build (env / config); never fetch it at runtime.
+const PSECURE_SERVER_PUBLIC_KEY = '<64-hex Ed25519 public key from the Paw Mask console>';
+
+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: 'psec_app_…',                        // app key from the console (not a secret)
+  accountId,
+  // telemetry: 'minimal', onBeforeCollect: (ctx) => userHasConsented,  // see "Privacy & consent"
+});
+
+const response = await client.protectFetch('https://api.example.com/api/order', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ sku: 1 }),
+});
+
+// On logout:
+client.dispose();
+```
+
+`connect()` rejects:
+- a missing or invalid `serverPublicKey`;
+- a non-https `authorityUrl` (http is allowed only for `localhost`/loopback, or with `allowInsecureHttp: true`
+  in development);
+- a `leaseEndpointPath` that is not a relative path, or that resolves to another origin;
+- a lease that does not verify against the pinned key, is for another account/install/PoP key, or is already
+  expired.
+
+A `serverPublicKeyHex` in the lease response is never used. If it differs from the pinned key, `connect()`
+fails as a likely MITM.
+
+**PoP key.** By default (`popKey: 'auto'`) the PoP key is a **non-extractable WebCrypto Ed25519 `CryptoKey`**
+when the platform supports it, with a fallback to an in-memory software key. Clients holding a WebCrypto key
+seal asynchronously: use `protectFetch()` or `sealRequestAsync()`. The synchronous `sealRequest()` and the
+`PSecureWebShield` vault helpers need `popKey: 'software'`.
+
+### 2. Manual lease & sealing (advanced)
+
+Obtain a lease from the authority on your own channel, then construct the client. The pinned
+`serverPublicKey` comes from your build configuration, not from the lease response.
+
+```ts
+import { PSecureClient } from '@pawmaskrelease/psecure';
+import type { PSecureHardwareAnchors } from '@pawmaskrelease/psecure';
+
+const pop = PSecureClient.generateEphemeralPopKeyPair(); // or: await PSecureClient.generateNonExtractablePopKeyPair()
+// ... request a lease bound to pop.clientPopPubKeyHex from your authority ...
+
+const client = new PSecureClient({
+  accountId,
+  installId,
+  serverPublicKey: PSECURE_SERVER_PUBLIC_KEY, // REQUIRED, pinned
+  leaseToken: lease.compactToken,             // SECRET: never log it or put it in URLs
+  hardwareAnchors,
+  clientPopSeedHex: pop.clientPopSeedHex,     // REQUIRED for PoP-bound leases (or clientPopKey: { privateKey, publicKeyHex })
+  authorityUrl: 'https://psecure-api.pawmask.com', // default seal origin and reissue origin
+  sealOrigins: ['https://api.example.com'],
+});
+
+// Option A: drop-in fetch wrapper (accepts a string, URL or Request)
+const response = await client.protectFetch('https://api.example.com/api/order', {
+  method: 'POST',
+  body: JSON.stringify({ sku: 1 }),
+});
+
+// Option B: seal manually and attach the headers yourself
+const { envelope, headers } = client.sealRequest({
+  method: 'POST',
+  origin: 'https://api.example.com', // bound into the AEAD tag and PoP signature (protocol 0.1.1)
+  path: '/api/order',                // exact path + '?' + raw query, as sent on the wire
+  body: JSON.stringify({ sku: 1 }),
+});
+// headers → { 'x-psecure-version', 'x-psecure-envelope', 'x-psecure-aead-tag' }
+```
+
+**Reissued leases.** On a `401`, `protectFetch` adopts an `x-psecure-reissued-lease` header only when all of
+these hold:
+- the response comes from an origin in `reissueOrigins` (default: the authority origin; add your API origin if
+  your API middleware performs reissue);
+- the lease verifies against the pinned key;
+- it is for the same account, install and PoP key;
+- it is `w2:`-wrapped (authenticated) under the current session key and continues the current lease chain;
+- it is newer than the current lease, has not been used before, and is unexpired.
+
+Anything else is ignored and the original `401` is returned. `client.updateLeaseToken(token, { nowMs? })`
+applies the same checks, except that wrapping is required only for header-delivered reissues.
+
+### Breaking changes (v1.0.0 release / protocol 0.1.1 security baseline)
+
+| Change | Migration |
+| --- | --- |
+| `serverPublicKey` is **required** for `connect()` and `new PSecureClient()`. Auto-discovery from the lease response, `GET /v1/public-key` and `globalThis.__PSEC_TENANT_KERNEL__` was removed, and so was `requirePinnedServerPublicKey` (pinning is always on). | Pass the authority key from build config. An array of keys is accepted for key rotation. |
+| `protectFetch` seals only for `sealOrigins` (default: the origin of `authorityUrl`). Other origins throw. | Add every API origin that must receive sealed requests. |
+| The envelope gains `origin`, and the AEAD/PoP canonical messages changed (protocol 0.1.1). `sealRequest()` needs `input.origin`, or `authorityUrl` / `sealOrigins` on the client. | Upgrade the verifier together with the SDK. |
+| A PoP-bound lease without `clientPopSeedHex` / `clientPopKey` throws. A lease without `publicLeaseToken` throws, so the private token is never sent. | Pass the PoP key the lease was issued for. |
+| Reissued leases are validated (see above). Legacy `w1:` wrapping is rejected. | The authority must emit `w2:` reissues. |
+| `connect()` defaults to a non-extractable WebCrypto PoP key, which makes the sync `sealRequest()` throw. | Use `protectFetch` / `sealRequestAsync`, or pass `popKey: 'software'`. |
+| `createOneTimeSetterBridge` returns a random, non-configurable `handlerKey` that is not deleted after the handshake. `simulatedCallerStack` can only add suspicion. The vault helpers enforce `sealOrigins`. | Pass `handlerKey` to the UI module privately; do not hardcode it. |
+| `PSecureDesktopBridge` IPC packets carry `issuedAtMs`, bound in the AEAD. Packets outside `ipcReplayWindowMs` (default 120 s) are rejected. | Re-seal IPC messages with the new SDK on both ends. |
+| `connect()` requires https for non-loopback authorities and validates `leaseEndpointPath`. | Use https, or `allowInsecureHttp` in development. |
+
+### Privacy & consent
+
+In `telemetry: 'full'` mode (the default), `connect()` reads device characteristics and stores an identifier:
+- it reads CPU cores, platform, language, screen, the WebGL renderer, and canvas and audio hashes;
+- it stores a random install identifier in `localStorage.__psec_install_id`.
+
+In the EU/EEA, this is access to and storage of information on the user's device (ePrivacy Art. 5(3)). It
+typically needs consent, unless you document that it is strictly necessary for a service the user requested.
+Fraud prevention under GDPR Art. 6(1)(f) still needs a legitimate-interest assessment, and usually a DPIA.
+
+The SDK gives you these controls:
+- **`onBeforeCollect(ctx)`** is called **before anything is read or stored**. `ctx` lists the signal groups,
+  whether an identifier will be persisted, and whether device fingerprinting will run. Return:
+  - `false` to abort (nothing is collected and no request is sent);
+  - `true` to proceed;
+  - `'minimal'` or `'full'` to choose the level.
+- **`telemetry: 'minimal'`** collects only coarse hints (CPU core count, platform, language). It hashes every
+  anchor client-side (salted with `anchorSalt` or `appKey`) and uses a per-session install id, so nothing is
+  stored. Device binding is correspondingly weaker.
+- **`hashAnchors: true`** also hashes the anchors in `'full'` mode.
+
+Other behavior:
+- Sealed envelopes, which carry the anchors, are only sent to `sealOrigins`.
+- RASP integrity probes (automation and tamper indicators) run in both modes.
+- Retention of envelope data is governed by your authority / Paw Mask DPA; document it in your privacy notice.
+
+### Security model & limits
+
+What the SDK does:
+- The authority key is pinned, and leases signed by any other key are rejected.
+- Secrets live in ECMAScript `#private` fields.
+- `crypto.getRandomValues`, `crypto.subtle`, `fetch`, `Response#text`, `Headers#get` and `JSON` are captured
+  when the SDK module is first evaluated, so monkey-patching them afterwards has no effect. Load the SDK before
+  third-party scripts.
+
+**Limits:**
+- Same-realm malicious script (XSS, main-world extensions) can still call `protectFetch` as an oracle.
+- Scripts that run before the SDK can interpose on primitives.
+- The lease `compactToken` is a bearer secret that contains the session key. Anyone who captures the
+  `/psec/lease` response body can recover the session key: from HAR files, proxy or APM logs, or a hooked
+  `fetch` that ran first. With a non-extractable PoP key they still cannot produce valid PoP signatures, so
+  PoP-enforcing verifiers reject the clones. A full fix (planned) derives the session key by ECDH/HPKE to a
+  client key instead of shipping it in the token.
+- The `PSecureWebShield` vault and bridge helpers are defence-in-depth against casual tooling. They are not a
+  security boundary.
+
+### 3. Verify on your backend
+
+> 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,
+  createPSecureExpressMiddleware,
+  createPSecureRemoteFetchEdgeMiddleware,
+} from '@pawmaskrelease/psecure/server';
+
+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'],
+});
+
+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',
+  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, but let denied requests
+through — this is a decision of your backend (for example an environment flag around the `if (!verdict.allowed)`
+branch). **Enforce** once the reports look clean. The application mode in the PSecure console (Monitor / Block)
+classifies the app's telemetry; it does not change verdicts. `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.
+
+## 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. |
+| `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). 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. |
+| `logger` | | console | pino-compatible `{ info, warn, debug? }` (Fastify uses `app.log`); `false` disables. |
+| `blockedResponse` | | `403 { error: 'PSECURE_REJECTED' }` | Your API's error shape for refused requests. |
+
+Fastify extras: route config `{ psecure: true }` protects a route, `{ psecure: false }` skips it. 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`).
+
+### 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.
+Pin `mode: 'enforce'` (or `PSECURE_MODE=enforce`) where that matters more than availability.
+
+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. Each decision says which
+mode applied (`effectiveMode`) and why (`modeSource`: `console`, `cache`, `default` or `config`).
+
+### 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],
+});
+```
+
+### 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);
+});
+```
+
+**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 (1.1.0,
+  before your bundler's minification).
+- Browser CSP: add the authority origin to `connect-src`. A blocked request is reported as `CSP_BLOCKED`.
+
+## 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` |
+
+## `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` |
+| `@pawmaskrelease/psecure/express` | **Backend.** `psecure()` middleware, `psecureRawBody` |
+| `@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`, 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 |
+| `@pawmaskrelease/psecure/rasp` | RASP probes, device intelligence, hardware binding |
+| `@pawmaskrelease/psecure/web-shield` | `PSecureWebShield` DOM/script integrity (browser) |
+| `@pawmaskrelease/psecure/react-native` | React Native bridge adapter |
+| `@pawmaskrelease/psecure/desktop` | Desktop bridge adapter |
+| `@pawmaskrelease/psecure/mobile-bridge` | Native mobile bridge adapter |
+| `@pawmaskrelease/psecure/web-kernel` | Standalone obfuscated web VM kernel (browser) |
+
+## Native (Rust) core
+
+A high-assurance Rust native kernel (`psecure_core` — `libpsecure_core.so`, `psecure_core.dll`,
+`libpsecure_core.dylib` / `.a`) and post-build ephemeral binary packer (`psecure_packer`) implement
+full Protocol `0.1.1` parity with the TypeScript SDK and Go Authority — including Native Client
+Ed25519 Proof-of-Possession (`psec-pop-v0.1.1`: `clientPopPubKeyHex` in `psec_lease_req` +
+`clientPopSigHex` in sealed envelopes), Kleptographic seals (`kleptoStreamSeed`, `kleptoMortonSeal`,
+`wasmPulseSeal`), UTF-16 `computeDynamicPolyCanaryHex` parity, and pin-on-init `serverPublicKeyHex`
+locking. They are **not required** by this JavaScript/TypeScript client SDK and are **not** shipped
+in this npm package. Contact Paw Mask for native/enterprise integration.
+
+## License
+
+Proprietary. Copyright Paw Mask. See [LICENSE](./LICENSE).