@farthershore/backend

The runtime SDK for your own backend. When you run a software product on Farther Shore with a bring-your-own-backend, the platform's edge gateway sits in front of your service. This package lets your backend trust the gateway (verify that each request really came from it) and report usage back for metering and billing — from a single token, FS_RUNTIME_TOKEN.

Install one package, set one environment variable, and you get fail-closed gateway-to-upstream request verification, response-bound usage reporting, and graceful lifecycle (health + shutdown). Everything else — your product, backend, and environment ids, the verification keys, and the metering endpoint — is fetched automatically from the token at startup.

Status: 0.14.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.

Install

npm install @farthershore/backend

Requires Node 22+. The Express adapter has an optional express peer dependency (v4 or v5); the core verification primitive is framework-neutral.

Quick start (any Fetch-compatible handler)

import { fartherShore, withUsage } from "@farthershore/backend";

const fs = fartherShore.initFromEnv(); // derives everything from FS_RUNTIME_TOKEN

export async function POST(request: Request) {
  const url = new URL(request.url);
  const body = new Uint8Array(await request.clone().arrayBuffer());

  // Fail-closed: throws a FartherShoreError if the request is not a genuine,
  // unmodified request signed by the gateway.
  await fs.verifyRequest({
    method: request.method,
    path: url.pathname,
    query: url.search,
    headers: request.headers,
    body,
  });

  const result = await runWorkflow(await request.json());

  // Report usage on the way out — no extra network call.
  return withUsage(request, Response.json(result), {
    tokens_used: result.tokensUsed,
  });
}

Quick start (Express)

import { fartherShore } from "@farthershore/backend";

const fs = fartherShore.initFromEnv();

app.use(fs.middleware()); // fail-closed verify -> req.fartherShore

app.post("/v1/runs", async (req, res) => {
  const result = await runWorkflow(req.body);
  res.json(result);
});

app.listen(3000);
process.on("SIGTERM", () => void fs.shutdown());

What initFromEnv() derives

You configure exactly one thing: FS_RUNTIME_TOKEN (mint it for your backend with the Farther Shore CLI or dashboard). Everything else — product / backend / environment ids, the JWKS url used to verify signatures, the metering endpoint and credential, and verification settings — is fetched from the platform at startup and cached in memory. The token is validated eagerly, so a missing or malformed token fails fast.

You can override the core URL via FS_CORE_URL (or pass options to initFromEnv()), but in normal use no other configuration is needed.

Request verification (fail-closed, always)

fs.middleware() (Express) and the framework-neutral fs.verifyRequest({ method, path, query, headers, body }) recompute a canonical signing string from the actual request and verify the gateway's Ed25519 signature against a JWKS-resolved public key. The plaintext X-FS-* headers are untrusted — identity comes only from a signature whose claims match the real request, so a forged or replayed request cannot impersonate the gateway.

Every failure (missing / malformed / bad-signature / stale / clock-skew / wrong-route / body-hash-mismatch / replayed-nonce / unknown-key / keys-unavailable) throws a typed FartherShoreError that maps to HTTP 401 (413 for oversized bodies). There is no fail-open path.

Response-bound usage reporting

Use withUsage() (or the builder-style createUsage()) when you know the usage for a request while you are returning the response. These helpers make no network call — they sign the usage into internal response headers, and the gateway verifies, settles, and strips those headers before your subscriber sees the response.

import { withUsage } from "@farthershore/backend";

export async function POST(request: Request) {
  const result = await runWorkflow(await request.json());
  return withUsage(
    request,
    Response.json(result),
    { tokens_used: result.tokensUsed },
    {
      measureContext: { model: result.model },
      creditUnitsConsumed: { credits: result.creditsUsed },
    },
  );
}

• measureContext is free-form pricing/analytics context persisted with the usage event.
• creditUnitsConsumed is a numeric map for credit-wallet style products; keys and values are validated locally before signing.

The meter keys you report (e.g. tokens_used) must match meters declared in your product. Request-count style limits are enforced by the gateway and need no backend code.

Async / background usage

Use fs.meter(meter, qty, { requestId, routeId }) only for usage that is not tied to a gateway response — background jobs, deferred billing, batch work. It enqueues an idempotent event and POSTs it to the platform's metering endpoint. Delivery is at-least-once; the event idempotency key keeps ingestion safe. Background usage is tallied and billed after the cycle, not enforced in real time.

Post-stream usage reporting

Use fs.reportUsage() when a gateway request streams its response and the billable total is known only after the stream completes. Declare that route with postStreamBilling: true, then report from the request-scoped verified context so the SDK retains the attested subscription subject:

const context = await fs.verifyRequest({ method, path, query, headers, body });

await streamResponse(context);
await context.reportUsage?.({
  meters: { output_tokens: 1280 },
  measureContext: { model: "apsu-1" },
});

The callback is HMAC-attested and requires a subscription subject. Core binds it to the immutable gateway request row and writes one billable UsageEvent with the gateway-known request units merged with reported actual units, the served plan, served route, and served request time. The gateway evidence row is unbilled and omits only response-derived dimensions. This is a billing-only channel: it does not settle or mutate Durable Object enforcement windows, so units that are unknown at admission cannot be hard-enforced. Knowable request dimensions still follow the normal admission path and are billed once on the merged callback.

Gateway evidence is published asynchronously. If the callback arrives first, Core parks the verified payload and the SDK retries only post_stream_request_not_found with bounded backoff, reusing the exact signed payload and nonce. A maintenance pass binds any remaining parked callback once evidence lands and durably alerts if it expires. The SDK method is best-effort and resolves { ok: false, reason } instead of rejecting, so handle or log a failed report according to your service's delivery policy.

Lifecycle

• fs.health() returns the current local health report (token present, bootstrap loaded, verification + metering status).
• 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:

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 | | ------------------------------------ | ---------------------------------------------------- | | fartherShore.initFromEnv() | Create the runtime instance from FS_RUNTIME_TOKEN. | | 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.reportUsage(input) | Attested post-stream usage callback. | | 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

Three 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.
• Post-stream (fs.reportUsage or the request-scoped context.reportUsage) is attested and request-bound for streaming routes declared with postStreamBilling: true. It writes the sole billable row for gateway-known plus reported actual units and never mutates real-time enforcement windows.
• 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
• Provisioning a backend and minting a runtime token is done through the Farther Shore CLI or dashboard.