@farthershore/backend 0.12.0 → 0.13.0

package/README.md

@@ -12,7 +12,7 @@ graceful lifecycle (health + shutdown). Everything else — your product, backen
 and environment ids, the verification keys, and the metering endpoint — is
 fetched automatically from the token at startup.
 
-> **Status: `0.12.0`.** Pre-1.0: minor releases may include breaking changes, so
+> **Status: `0.13.0`.** Pre-1.0: minor releases may include breaking changes, so
 > pin this package to an exact version (or a patch-only range) and upgrade
 > deliberately.
 
@@ -149,6 +149,58 @@ real time.
 - `fs.shutdown()` flushes any buffered metering and sends a `stopping` heartbeat.
   Call it on `SIGTERM` / `SIGINT` for graceful shutdown.
 
+## Local development & testing — the mode ladder
+
+You do not need the platform to test a backend that runs behind it. Pick the
+lowest tier that answers your question — each is a superset of the one below.
+
+**Tier 0 — off (needs NOTHING from the SDK).** Unit-test your business logic
+directly. The gateway sits in front of you in production; your pure handlers
+don't import Farther Shore to be tested. There is no SDK step at this tier — see
+`templates/1-unit.test.ts`.
+
+**Tier 1 — passthrough.** Run your real app over HTTP with `fs.middleware()`
+mounted but verification OFF, matching the pre-keystone deploy order: the
+middleware passes requests through without attaching a context, so your routes
+run normally. Activate with `FS_DEV_MODE=passthrough`. See
+`templates/2-passthrough-http.test.ts`.
+
+**Tier 2 — simulated.** A real runtime wired to an in-process gateway with
+fail-closed verification ON and SIGNED personas driving requests. Assert the
+fail-closed boundary (a persona without a permission gets 403) and that usage is
+metered. Activate with `FS_DEV_MODE=simulated`, or construct explicitly:
+
+```ts
+import { createDevRuntime, definePersona } from "@farthershore/backend/testing";
+
+const rt = createDevRuntime({
+  mode: "simulated",
+  personas: {
+    creator: definePersona({
+      name: "creator",
+      permissions: ["widgets:create"],
+    }),
+  },
+});
+
+// Sign a request as a persona and drive your app (supertest, fetch, or inject):
+const headers = await rt.asPersona("creator").headers({ path: "/v1/widgets" });
+// rt.usage.byMeter()   → assert reported usage
+// rt.trace.forRequest(id) → why a request verified / was denied
+```
+
+`@farthershore/backend/testing` gives you signed personas (owner / admin /
+member / anonymous, plus your own), an in-process gateway fixture, and
+assertable `usage` + per-request `trace` side channels. It is dev/test tooling
+only — **it throws when `NODE_ENV=production`**, and `FS_DEV_MODE` is never a
+required-at-boot variable. When `FS_DEV_MODE` is set, `initFromEnv()`
+self-constructs the simulator (ephemeral keys, a loud banner, JSONL usage/trace
+logs under `.farthershore/`, and a mode-600 `.farthershore/dev-keys.json` so a
+separate test-runner process can sign against a running service via
+`personaClientFromKeysFile`).
+
+See `templates/3-simulated-authz.test.ts` for the full fail-closed + usage flow.
+
 ## Key exports
 
 | Export                               | Purpose                                              |
@@ -157,13 +209,26 @@ real time.
 | `fs.middleware()`                    | Express fail-closed verify → `req.fartherShore`.     |
 | `fs.verifyRequest({...})`            | Framework-neutral request verification.              |
 | `withUsage()` / `createUsage()`      | Response-bound usage reporting (no network call).    |
+| `computeMeteringHeaders()`           | Metering headers as a plain map — never throws.      |
 | `fs.meter(meter, qty, opts)`         | Async/background usage event.                        |
 | `fs.health()` / `fs.shutdown()`      | Health report and graceful shutdown.                 |
 | `FartherShoreError`, `MeteringError` | Typed errors.                                        |
+| `@farthershore/backend/testing`      | Dev-mode + persona test harness (dev/test only).     |
 
 A subpath export, `@farthershore/backend/express`, exposes the Express adapter
 types directly if you prefer to wire the middleware yourself.
 
+## Metering channels
+
+Two usage channels exist and are **not** interchangeable:
+
+- **Response-bound** (`withUsage` / `createUsage` / `computeMeteringHeaders`) is
+  the attested, request-bound settlement channel: the gateway verifies the HMAC
+  and settles the reported units against the request's lease in the same
+  lifecycle. Wire recipe (any language): [`docs/response-metering-wire.md`](docs/response-metering-wire.md).
+- **Background** (`fs.meter`) is a billing-only, unattested, post-cycle tally for
+  usage not tied to a gateway response. It never settles a lease.
+
 ## Learn more
 
 - Platform documentation: https://docs.farthershore.com