@pawmaskrelease/psecure 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog: `@pawmaskrelease/psecure`
+
+## 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,254 @@ 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, 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
 
-// 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!,
+```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 (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`. (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=1789b4905f27eec1dc7c7be9cbd964b8e06e194e710d2ed7cf3606b00c234077 fnv1a=117da010 */

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=2f38a9597f9db18b05602cfca1bafa465b1ac361b00890553793033f004b80d6 fnv1a=117da010 */

package/dist/adapters/mobile-bridge.js

@@ -51,4 +51,4 @@ const _0xe2bdfd=this.evaluateMobileSignals(_0x3bcc02);if(_0x567126===PSecureNati
 if(_0x567126===PSecureNativeCommand.CMD_COLLECT_NATIVE_RASP){const _0x430798=new Uint8Array(8);const _0xa0e68a=new DataView(_0x430798.buffer);_0xa0e68a.setUint32(0,_0xe2bdfd>>>0,true);_0xa0e68a.setUint32(4,psecPolyHash32(_0x954c5b,_0xe2bdfd)>>>0,true);return{[_0x1aa615_S(11)]:0,[_0x1aa615_S(12)]:_0x1aa615_S(2),[_0x1aa615_S(13)]:_0xe2bdfd,[_0x1aa615_S(14)]:bytesToHex(_0x430798),};}
 const _0x4eace7=new Uint8Array(this.#_0xa727e7);if(_0xe2bdfd!==0){_0x4eace7[0]=(_0x4eace7[0]^(_0xe2bdfd&(0x5a3ee1a5^0x5a3ee15a)))&(0x2f6ed5a5^0x2f6ed55a);_0x4eace7[1]=(_0x4eace7[1]^((_0xe2bdfd>>>8)&(0x1f803ca5^0x1f803c5a)))&(0x64879ea5^0x64879e5a);_0x4eace7[2]=(_0x4eace7[2]^((_0xe2bdfd>>>(0x9e7964a^0x9e7965a))&(0x3fe139a5^0x3fe1395a)))&(0x166786a5^0x1667865a);_0x4eace7[3]=(_0x4eace7[3]^((_0xe2bdfd>>>(0x7bf8ef42^0x7bf8ef5a))&(0x12a035a5^0x12a0355a)))&(0x6c1325a5^0x6c13255a);_0x4eace7[(0x52913045^0x5291305a)]=(_0x4eace7[(0x1f31f645^0x1f31f65a)]^(0x5b85a3ff^0x5b85a35a))&(0x67acf4a5^0x67acf45a);}
 const _0x088074=psecRandomBytes((0x686bac56^0x686bac5a));const _0xfb6e20=new DataView(_0x088074.buffer,_0x088074.byteOffset,_0x088074.byteLength);_0xfb6e20.setUint32(0,(_0xfb6e20.getUint32(0,true)^(_0x567126>>>0))>>>0,true);_0xfb6e20.setUint32(4,(_0xfb6e20.getUint32(4,true)^(_0x954c5b.length>>>0))>>>0,true);const _0x3271f6=psecChaChaCfbSeal(_0x954c5b,_0x4eace7,_0x088074);_0x4eace7.fill(0);const _0x733c76=new Uint8Array(_0x088074.length+_0x3271f6.ciphertext.length+_0x3271f6.tag.length);_0x733c76.set(_0x088074,0);_0x733c76.set(_0x3271f6.ciphertext,_0x088074.length);_0x733c76.set(_0x3271f6.tag,_0x088074.length+_0x3271f6.ciphertext.length);return{[_0x1aa615_S(11)]:0,[_0x1aa615_S(12)]:_0x1aa615_S(2),[_0x1aa615_S(13)]:_0xe2bdfd,[_0x1aa615_S(14)]:bytesToHex(_0x733c76),[_0x1aa615_S(15)]:bytesToHex(_0x088074),};}}
-/* @psec-self-seal sha256=fc388c45ba5c4c0d3e79b215edba8fd46370559e423cfd4c2e0969b27ac41a49 fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=43061b8174042b3ad21ad653d5c37bac4f32dd0c8143c2eb668e220a6e6299cc fnv1a=117da010 */

package/dist/adapters/react-native.js

@@ -43,4 +43,4 @@ pingNativeCore(){this.#_0xafdc03();return this.#_0xae6fa2.dispatch(PSecureNative
 sealMobileRequest(_0x167378){this.#_0xafdc03();return this.#_0xae6fa2.sealMobileRequest(this.#_0x7902b1,_0x167378,this.#_0xa9f01f);}
 async sealRequestAsync(_0x167378){this.#_0xafdc03();return this.#_0xae6fa2.sealMobileRequestAsync(this.#_0x7902b1,_0x167378,this.#_0xa9f01f);}
 async sealMobileRequestAsync(_0x167378){return this.sealRequestAsync(_0x167378);}}
-/* @psec-self-seal sha256=312ac98508db64906d49f12772b58dc257d0afc7390b7e042185e86ae448e4e3 fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=30fd0e998f80cc8e85dab875d3bc52dd90d456c40ea02e64d202e1f78afc0998 fnv1a=117da010 */

package/dist/adapters/web-shield.js

@@ -50,4 +50,4 @@ return{[_0x63aba3_S(17)]:_0x219643.length===0,[_0x63aba3_S(18)]:_0x219643,[_0x63
 createProtectedFetchInterceptor(_0x81dde3,_0x58a799){return(_0xe81982,_0xf1ec43)=>{if(_0x81dde3.requiresAsyncSealing){throw new Error(_0x63aba3_S(4));}
 const _0xb962a1=globalThis.location;const _0x22312b=typeof _0xb962a1?.href===_0x63aba3_S(5)&&/^https?:/i.test(_0xb962a1.href)?_0xb962a1.href:undefined;const _0xd56d2b=typeof _0xe81982===_0x63aba3_S(5)?new URL(_0xe81982,_0x22312b):new URL(_0xe81982.href);const origin=canonicalizeOrigin(_0xd56d2b);if(!_0x81dde3.isSealOriginAllowed(origin)){throw new Error(`PSecureWebShield: refusing to seal for non-allowlisted origin ${origin} (configure sealOrigins)`);}
 const _0xbb457f=_0x58a799();const _0xb4f832=this.verifyDomSimHashDrift(_0xbb457f.domTokens);const _0x795be8=this.auditScriptTagsForSkimming(_0xbb457f.scripts);const _0x91cb3a=_0xb4f832.raspBit|_0x795be8.raspBit;return _0x81dde3.sealRequest({[_0x63aba3_S(19)]:_0xf1ec43?.method??_0x63aba3_S(6),[_0x63aba3_S(20)]:origin,[_0x63aba3_S(21)]:buildPathAndQuery(_0xd56d2b),[_0x63aba3_S(22)]:(_0xf1ec43?.body??''),[_0x63aba3_S(23)]:_0x91cb3a!==0?_0x91cb3a:undefined,});};}}
-/* @psec-self-seal sha256=7755ba6eaa2e9c155a63dd6a4c443252275e0d5af2c24bb9dbfb9c027c0d2f37 fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=47abfa9f579d6822bcc6cf9bcc6e48c3815e142c57dc4c3d9a11e2c259d8abab fnv1a=117da010 */

package/dist/adapters/web-vault.js

@@ -127,4 +127,4 @@ _0x69cf3d.poisonMask)>>>
 return;}
 if(!handlerObj||typeof handlerObj!==_0x1b7e94_S((0x42513f4b^0x42513f5a))){return;}
 const _0x0fb898=handlerObj;if(typeof _0x0fb898.PS762===_0x1b7e94_S((0x2d3c9c78^0x2d3c9c5a))){handshakeCompleted=true;const _0xa458a0=_0x0fb898.PS762;_0x0fb898.PS762=()=>{};_0xa458a0(Object.freeze(_0x802124),_0xc00404,_0xf1626f);}},});return{[_0x1b7e94_S(119)]:_0xb6fbb2};}
-/* @psec-self-seal sha256=02d13de6855c11208807183f9fe8f19110060915bf280d183ee5571d9994f6d7 fnv1a=08e6fb10 */
+/* @psec-self-seal sha256=a211895f858b8ee7b9dd4c247af008e5ee41715a10b9ecb22eba33daa6d33a6f fnv1a=117da010 */

package/dist/cli/doctor.d.ts

@@ -0,0 +1,31 @@
+import { type PSecureConfigErrorCode } from '../errors.js';
+export interface PSecureDoctorOptions {
+    authority?: string;
+    appKey?: string;
+    publicKey?: string;
+    origin?: string;
+    api?: string;
+    serverKey?: string;
+    pinnedAppKey?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+export type PSecureDoctorStatus = 'pass' | 'fail' | 'warn' | 'skip';
+export interface PSecureDoctorCheck {
+    id: string;
+    title: string;
+    status: PSecureDoctorStatus;
+    detail: string;
+    fix?: string;
+    code?: PSecureConfigErrorCode;
+}
+export declare function runPSecureDoctor(opts: PSecureDoctorOptions): Promise<PSecureDoctorCheck[]>;
+export declare function formatPSecureDoctorReport(checks: readonly PSecureDoctorCheck[]): string;
+export interface PSecureCliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    env: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+}
+export declare function runPSecureCli(argv: readonly string[], io: PSecureCliIo): Promise<number>;