@farthershore/backend 0.19.0 → 0.21.0

package/dist/types/core/verifyRequest.d.ts

@@ -1,4 +1,4 @@
-import type { ReportUsageResult, RequestScopedReportUsageInput } from "./post-stream-usage.js";
+import { type ReportFn } from "./report.js";
 import { type ConsumerPrincipal, type FartherShoreSignedContext } from "./verifyContext.js";
 import type { JwksClient } from "./jwks.js";
 import type { NonceStore } from "./nonceCache.js";
@@ -60,9 +60,27 @@ export type FartherShoreRequestContext = {
     signedContext?: FartherShoreSignedContext;
     /** Managed-RBAC role keys the acting subject holds (display/audit only). */
     roles?: string[];
-    /** Request-bound post-stream reporter, attached by the runtime facade. */
-    reportUsage?: (input: RequestScopedReportUsageInput) => Promise<ReportUsageResult>;
+    /**
+     * THE reporting verb. `report({ meter, values, dims?, quote? })` reports
+     * MEASUREMENTS against the served identity this context already carries —
+     * there is no subscription/release argument to forget. The SDK picks the
+     * transport (signed in-band headers before the response is sent, the attested
+     * post-stream channel after it, or from a background job), so the builder
+     * never chooses one.
+     *
+     * Attached by the runtime facade. A context produced by the BARE
+     * `verifyRequest()` primitive has no metering channel, so its `report()`
+     * throws an error naming the fix rather than dropping the measurement.
+     */
+    report: ReportFn;
 };
+/**
+ * The verified Farther Shore context — the identity + reporting handle a
+ * handler (or a background job the handler hands it to) works with. Alias of
+ * {@link FartherShoreRequestContext}: a background job is simply given the
+ * already-verified context, so there is no second context type to learn.
+ */
+export type FartherShoreContext = FartherShoreRequestContext;
 export type VerifyRequestDeps = {
     jwks: JwksClient;
     nonceCache: NonceStore;

package/dist/types/generated/runtime-contract.d.ts

@@ -1,127 +1,3 @@
-export declare const RUNTIME_CONTRACT_VERSION: 1;
-export declare const RUNTIME_TOKEN_ENV: "FS_RUNTIME_TOKEN";
-export declare const RUNTIME_TOKEN_CONTRACT: {
-    readonly environmentVariable: "FS_RUNTIME_TOKEN";
-    readonly prefixes: {
-        readonly live: "fsrt_live_";
-        readonly test: "fsrt_test_";
-    };
-    readonly opaque: true;
-    readonly storage: "sha256-hash-only";
-    readonly lastFour: true;
-    readonly capabilities: readonly ["gateway_verification", "metering", "health", "tunnel"];
-};
-export declare const RUNTIME_BOOTSTRAP_CONTRACT: {
-    readonly method: "POST";
-    readonly path: "/v1/runtime/bootstrap";
-    readonly authorization: "Bearer fsrt_...";
-    readonly request: {
-        readonly instanceId: "string?";
-        readonly sdkVersion: "string?";
-        readonly sdkLanguage: "string?";
-    };
-    readonly response: {
-        readonly product: {
-            readonly id: "string";
-            readonly slug: "string";
-        };
-        readonly backend: {
-            readonly id: "string";
-            readonly slug: "string";
-            readonly name: "string";
-        };
-        readonly environment: {
-            readonly id: "string?";
-            readonly kind: "live | test";
-        };
-        readonly capabilities: "string[]";
-        readonly verification: {
-            readonly required: "boolean";
-            readonly jwksUrl: "string";
-            readonly clockSkewSeconds: "number";
-            readonly replayWindowSeconds: "number";
-            readonly headerNames: "object";
-        };
-        readonly metering: {
-            readonly enabled: "boolean";
-            readonly endpoint: "string";
-            readonly credential: "string";
-            readonly allowedMeters: "string[]";
-            readonly allowedRoutes: "string[]";
-            readonly perEventMax: "number";
-        };
-        readonly transport: {
-            readonly mode: "direct | tunnel";
-            readonly runner: "embedded | sidecar | null";
-            readonly originUrl: "string?";
-            readonly originHostname: "string?";
-            readonly localTarget: "string?";
-            readonly cloudflared: "object?";
-        };
-        readonly routes: "object[]";
-        readonly policyVersion: "string";
-        readonly refreshAfterSeconds: "number";
-    };
-};
-export declare const RUNTIME_SIGNING_CONTRACT: {
-    readonly algorithm: "Ed25519";
-    readonly encoding: "base64url";
-    readonly keyMaterial: "service-jwt-jwks";
-    readonly canonicalString: {
-        readonly description: "Byte-exact, language-neutral serialization of the signed claim set. Fields are emitted in the FIXED order below, one per line, each as `name:value`, joined by a single newline (\\n, U+000A). NO trailing newline. The serialization depends on neither JSON key ordering nor any Node.js Buffer/serialization detail — only UTF-8 byte encoding of the field values. Empty/absent values are emitted as the empty string after the colon. Go/Python/Java/Rust reproduce this identically.";
-        readonly fieldSeparator: "\n";
-        readonly keyValueSeparator: ":";
-        readonly trailingNewline: false;
-        readonly fieldEncoding: "utf-8";
-        readonly fields: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version", "context-hash"];
-        readonly fieldRules: {
-            readonly method: "Uppercased HTTP method (e.g. GET, POST).";
-            readonly path: "Request path, percent-encoded as received, no host, no query string. Always begins with '/'.";
-            readonly query: "The request's query string bytes VERBATIM, after the caller has stripped the URL's single leading '?' delimiter. Use the RAW wire query exactly as received — NO sorting, NO filtering, NO re-stripping a leading '?', NO dropping empty pairs, NO re-encoding. The signature binds to the exact query bytes: any reorder, added/removed/relocated pair, or re-encoding changes the bytes and MUST fail verification. Every SDK verifier MUST read the raw wire query (never a re-parsed/re-serialized form, which could reorder or re-encode and would then fail legitimate requests). Any normalization (sorting by name or value, dropping/moving empty pairs, re-stripping '?') is FORBIDDEN — each collapses distinct wire queries under one signature. Empty string when there is no query.";
-            readonly "body-hash": "Lowercase hex SHA-256 of the RAW request body bytes. For an empty body, the SHA-256 of zero bytes (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Streaming-exempt requests use the literal token 'STREAM'.";
-            readonly "request-id": "Opaque unique request id minted by the gateway (also the replay-cache nonce).";
-            readonly timestamp: "Integer Unix epoch seconds (UTC) at signing time, as a base-10 string with no padding.";
-            readonly "business-id": "Business id the request is routed to.";
-            readonly "backend-id": "Backend id the route binds to.";
-            readonly "route-id": "Resolved route id; empty string if the route is unresolved.";
-            readonly "policy-version": "Tenant artifact / policy version the gateway signed under.";
-            readonly "context-hash": "Lowercase hex SHA-256 of the presented X-Fs-Context JWT string (identity-context binding). For a request with no signed context, the SHA-256 of the empty string (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855). Binds the identity context into the request signature so one verification covers both.";
-        };
-    };
-};
-/**
- * Ordered list of fields in the canonical signing string. The order here is
- * load-bearing and identical across all language SDKs.
- */
-export declare const RUNTIME_CANONICAL_FIELDS: readonly ["method", "path", "query", "body-hash", "request-id", "timestamp", "business-id", "backend-id", "route-id", "policy-version", "context-hash"];
-export declare const RUNTIME_BODY_HASH_CONTRACT: {
-    readonly algorithm: "SHA-256";
-    readonly encoding: "hex-lower";
-    readonly source: "raw-request-bytes";
-    readonly emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-    readonly maxBodyBytes: 10485760;
-    readonly streamingExemptToken: "STREAM";
-    readonly streamingExemptContentTypes: readonly ["text/event-stream", "application/octet-stream", "multipart/form-data"];
-    readonly overMaxStatus: 413;
-};
-export declare const RUNTIME_HEADERS: {
-    readonly signature: "x-fs-signature";
-    readonly keyId: "x-fs-key-id";
-    readonly requestId: "x-fs-request-id";
-    readonly timestamp: "x-fs-timestamp";
-    readonly businessId: "x-fs-business-id";
-    readonly backendId: "x-fs-backend-id";
-    readonly routeId: "x-fs-route-id";
-    readonly policyVersion: "x-fs-policy-version";
-    readonly bodyHash: "x-fs-body-hash";
-};
-export declare const RUNTIME_REPLAY_CONTRACT: {
-    readonly windowSeconds: 300;
-    readonly clockSkewSeconds: 5;
-    readonly nonce: "x-fs-request-id";
-    readonly nonceCache: "bounded-lru";
-    readonly policy: "fail-closed";
-};
 export declare const RUNTIME_ERROR_CODES: {
     readonly missingSignature: "missing_signature";
     readonly malformedSignature: "malformed_signature";
@@ -143,40 +19,15 @@ export declare const RUNTIME_ERROR_CODES: {
     readonly surfaceNotAllowed: "surface_not_allowed";
 };
 export type RuntimeErrorCode = (typeof RUNTIME_ERROR_CODES)[keyof typeof RUNTIME_ERROR_CODES];
-export declare const RUNTIME_METERING_CONTRACT: {
-    readonly endpoint: "/v1/metering/events";
-    readonly method: "POST";
-    readonly credential: "reusable-bearer";
-    readonly event: {
-        readonly event_id: "string";
-        readonly business_id: "string";
-        readonly backend_id: "string";
-        readonly route_id: "string?";
-        readonly request_id: "string?";
-        readonly requestId: "string?";
-        readonly subscriptionId: "string";
-        readonly nonce: "string?";
-        readonly meter: "string";
-        readonly qty: "number";
-        readonly timestamp: "string";
-    };
-    readonly postStreamEvent: {
-        readonly requestId: "string";
-        readonly subscriptionId: "string?";
-        readonly nonce: "string";
-        readonly meters: "Record<string, number>";
-        readonly creditUnitsConsumed: "Record<string, number>?";
-        readonly measureContext: "Record<string, unknown>?";
-        readonly signature: "string";
-    };
-    readonly idempotencyKey: "event_id";
-    readonly delivery: "at-least-once";
-    readonly billingOnly: true;
-    readonly realtimeEnforced: false;
-    readonly postStreamBillingOnly: true;
-    readonly postStreamRealtimeEnforced: false;
-    readonly postStreamTrustModel: "HMAC-attested and bound to one served postStreamBilling gateway request. Core writes one billable UsageEvent using the served plan and time. The callback never mutates Durable Object enforcement windows.";
-    readonly trustModel: "upstream-reported values are NOT cryptographically attested; a buggy or compromised upstream can self-report arbitrary values for its OWN product only. Core enforces allowedMeters/allowedRoutes from the authoritative token record at ingest, applies a per-event sanity max (perEventMax), and raises an implausible-volume alert.";
+export declare const RUNTIME_BODY_HASH_CONTRACT: {
+    readonly algorithm: "SHA-256";
+    readonly encoding: "hex-lower";
+    readonly source: "raw-request-bytes";
+    readonly emptyBodyHash: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+    readonly maxBodyBytes: 10485760;
+    readonly streamingExemptToken: "STREAM";
+    readonly streamingExemptContentTypes: readonly ["text/event-stream", "application/octet-stream", "multipart/form-data"];
+    readonly overMaxStatus: 413;
 };
 export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {
     readonly headers: {
@@ -198,14 +49,18 @@ export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {
     readonly payload: {
         readonly method: "string";
         readonly path: "string";
-        readonly rawDimsUnits: "Record<string, number>";
+        readonly rawDimsUnits: "Record<string, number>?";
         readonly measureContext: "Record<string, unknown>?";
         readonly creditUnitsConsumed: "Record<string, number>?";
+        readonly measurementsVersion: "1?";
+        readonly measurements: "Array<{ meter: string; values: Record<string, number>; dims?: Record<string, string> }>?";
+        readonly quote: "{ currency: string; amountNanos: string }?";
     };
     readonly errors: {
         readonly missingToken: "missing_token";
         readonly invalidMeterKey: "invalid_meter_key";
         readonly invalidMeterValue: "invalid_meter_value";
+        readonly invalidQuote: "invalid_quote";
     };
     readonly httpAdapter: {
         readonly input: "Request";
@@ -215,33 +70,3 @@ export declare const RUNTIME_RESPONSE_METERING_CONTRACT: {
         readonly gatewayStripsInternalHeaders: true;
     };
 };
-export declare const RUNTIME_HEALTH_CONTRACT: {
-    readonly endpoint: "/v1/runtime/health";
-    readonly method: "POST";
-    readonly request: {
-        readonly instanceId: "string?";
-        readonly status: "starting | ready | degraded | stopping";
-    };
-    readonly readinessStates: readonly ["UNKNOWN", "WAITING", "READY", "DEGRADED", "OFFLINE"];
-    readonly checks: readonly ["runtime_token_valid", "bootstrapped", "tunnel_running", "signed_request_2xx", "unsigned_request_401", "stale_signature_401", "wrong_route_401", "metering_observed"];
-    readonly report: {
-        readonly runtimeToken: "boolean";
-        readonly bootstrap: "boolean";
-        readonly tunnel: "string?";
-        readonly verification: "boolean";
-        readonly metering: "boolean";
-    };
-};
-export declare const RUNTIME_TRANSPORT_CONTRACT: {
-    readonly modes: {
-        readonly direct: "Gateway fetches the builder's public origin URL; the SDK middleware fail-closed-verifies every request via Ed25519 request signing. Provisions zero Cloudflare objects. Available on all tiers; also the dev path.";
-        readonly tunnel: "Farther Shore provisions a private outbound Cloudflare Tunnel; no inbound port. The Production-secure tier. Consumes Cloudflare tunnel/route slots.";
-    };
-    readonly runners: {
-        readonly embedded: "fs.start() supervises cloudflared as a child process (default DX).";
-        readonly sidecar: "Vanilla cloudflare/cloudflared container beside the app (production / non-Node).";
-    };
-    readonly channelTrust: readonly ["tunnel"];
-    readonly requestTrust: "x-fs-signature";
-    readonly invariant: "Channel trust (tunnel) and request trust (the X-FS-* signature) are distinct layers; both always apply. CF-Access-* headers are transport-layer only and are IGNORED by the SDK.";
-};

package/dist/types/index.d.ts

@@ -1,27 +1,29 @@
 import { FartherShore, type FartherShoreInitOptions } from "./core/runtime.js";
-import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "./adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler } from "./adapters/express.js";
+import { type PermissionCarrier } from "./core/permissions.js";
 export { FartherShore } from "./core/runtime.js";
 export type { FartherShoreInitOptions } from "./core/runtime.js";
 export { FartherShoreError, statusForCode } from "./core/errors.js";
-export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
+export { verifyRequest, type VerifyRequestInput, type VerifyRequestDeps, type FartherShoreContext, type FartherShoreRequestContext, type HeadersLike, } from "./core/verifyRequest.js";
+export { MEASUREMENTS_VERSION } from "./core/report.js";
+export type { ReportInput, ReportResult, ReportTransport, Measurement, MeasurementValues, MeasurementDimensions, QuoteInput, QuoteProposal, } from "./core/report.js";
 export { verifyContext, decodeContextClaims, principalFromContextClaims, } from "./core/verifyContext.js";
 export type { FartherShoreSignedContext, ConsumerPrincipal, } from "./core/verifyContext.js";
 export { requireMember, requireService, credentialKind, isPortalSession, type MemberSubject, type ServiceSubject, type PrincipalCarrier, } from "./core/subject.js";
-export { hasPermission, requirePermission, permissionGrants, permissionSatisfies, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
+export { hasPermission, requirePermission, permissionSatisfies, routePermission, READ_METHODS, FartherShorePermissionError, type PermissionCarrier, } from "./core/permissions.js";
 export { JwksClient, type Jwk, type JwksClientOptions } from "./core/jwks.js";
 export { NonceCache, type NonceCacheOptions, type NonceStore, } from "./core/nonceCache.js";
+export { type ReplayProtectionDiagnostic, type ReplayProtectionMode, } from "./core/replay-protection.js";
 export { BootstrapClient, type BootstrapClientOptions, } from "./core/bootstrap.js";
-export { MeteringClient, type MeteringClientOptions, type MeterOptions, } from "./core/metering.js";
-export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type RequestScopedReportUsageInput, type ReportUsageResult, } from "./core/post-stream-usage.js";
 export { buildHealthReport, reportHealth, type HealthSnapshot, type HealthStatus, type HeartbeatOptions, } from "./core/health.js";
 export { ShutdownManager, type ShutdownHook } from "./core/shutdown.js";
 export { CloudflaredSupervisor, nodeSpawn, REDACTED_TOKEN, type SpawnFn, type SpawnedTunnelProcess, type CloudflaredSupervisorOptions, type TunnelState, type TunnelStatus, } from "./core/tunnel.js";
 export type { FartherShoreTunnelOptions } from "./core/runtime.js";
-export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
+export { createExpressMiddleware, createExpressHandler, type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type ExpressNext, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler, type VerifiedPrincipalContext, } from "./adapters/express.js";
 export { FS_RUNTIME_TOKEN_ENV, RUNTIME_TOKEN_PREFIXES, RUNTIME_TOKEN_OPERATIONS, RUNTIME_HEADER_NAMES, RUNTIME_CLOCK_SKEW_SECONDS, RUNTIME_REPLAY_WINDOW_SECONDS, EMPTY_BODY_SHA256, STREAMING_EXEMPT_BODY_HASH, MAX_BODY_BYTES, type RuntimeErrorCode, type RuntimeTokenOperation, type CanonicalSigningInput, type RuntimeBootstrapResponse, type RuntimeMeteringEvent, type RuntimeHealthReport, type TransportMode, RUNTIME_ERROR_CODE_TO_ERROR_CODE, runtimeErrorToErrorCode, type LimitDescriptor, type RuntimeMappedErrorCode, } from "./runtime-types.js";
 export { RUNTIME_ERROR_CODES } from "./generated/runtime-contract.js";
 export { hashBody, buildCanonicalSigningString, canonicalizeQuery, signCanonicalString, verifyCanonicalSignature, runtimeTokenKind, } from "./runtime-signing.js";
-export { createUsage, withUsage, computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type UsageMap, type UsageReporter, type MeteringOptions, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";
+export { computeMeteringHeaders, MeteringError, METERING_PAYLOAD_HEADER, METERING_SIGNATURE_HEADER, METERING_TOKEN_HEADER, DEFAULT_TOKEN_ENV, type MeteringHeaders, type ComputeMeteringOptions, type ResponseMeteringUsagePayload, } from "./response-metering.js";
 /**
  * The conceptual public entrypoint. `fartherShore.initFromEnv()` mirrors the
  * language-neutral spec. The returned instance is augmented with `middleware()`
@@ -37,7 +39,27 @@ export type FartherShoreInstance = FartherShore & {
      * context is absent, `principal_required` when it is identity-less) before the
      * callback runs. Pairs with the strict `middleware()`.
      */
-    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    handler: {
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+        /**
+         * Options-first overload: `fs.handler({ permission: "widgets:write" }, cb)`
+         * asserts the permission (fail-closed) before the callback runs,
+         * responding `403 permission_denied` otherwise.
+         */
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    };
+    /**
+     * In-handler authorization helpers bound to the instance — the SAME shape as
+     * the dev runtime's `rt.authz` (which additionally traces each decision), so
+     * dev and prod code reads identically. Both key ONLY on `ctx.permissions`
+     * with FAIL-CLOSED carrier semantics: an ABSENT permission set DENIES.
+     */
+    authz: {
+        /** True when the acting user holds `key` (`*` / `<subject>:*` / exact). */
+        hasPermission(ctx: PermissionCarrier, key: string): boolean;
+        /** Assert `key` is held; throws `FartherShorePermissionError` (403). */
+        requirePermission(ctx: PermissionCarrier, key: string): void;
+    };
 };
 export declare const fartherShore: {
     /** Derive everything from FS_RUNTIME_TOKEN via bootstrap. */

package/dist/types/internal/index.d.ts

@@ -0,0 +1,2 @@
+export { createReportFn, rawDimsUnitsOf, type ReportChannels, type ResponseSink, type ReportFn, } from "../core/report.js";
+export { PostStreamUsageClient, type PostStreamUsageClientOptions, type ReportUsageInput, type ReportUsageResult, } from "../core/post-stream-usage.js";

package/dist/types/response-metering.d.ts

@@ -1,18 +1,39 @@
-declare const RESPONSE_METERING_ERROR_CODES: {
+/** The response-metering fault codes carried by {@link MeteringError}. */
+export declare const RESPONSE_METERING_ERROR_CODES: {
     readonly missingToken: "missing_token";
     readonly invalidMeterKey: "invalid_meter_key";
     readonly invalidMeterValue: "invalid_meter_value";
+    readonly invalidQuote: "invalid_quote";
 };
-type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
+export type ResponseMeteringErrorCode = (typeof RESPONSE_METERING_ERROR_CODES)[keyof typeof RESPONSE_METERING_ERROR_CODES];
 /**
  * The signed response-metering payload. `computeMeteringHeaders` accepts one of
  * these directly, so a non-Express / non-Fetch handler (or a Python/Go backend
- * following the wire recipe) can stamp valid headers without `withUsage`.
+ * following the wire recipe) can stamp valid headers with no JS SDK at all.
+ * `ctx.report()` is the JS surface that builds it.
+ *
+ * `measurements` (with its `measurementsVersion`) is the measurement lane the
+ * one reporting verb emits: `{ meter, values, dims }` as declared in the
+ * business release. `rawDimsUnits` remains as the flat projection the gateway's
+ * existing settlement lane reads.
  */
 export type ResponseMeteringUsagePayload = {
     method: string;
     path: string;
-    rawDimsUnits: Record<string, number>;
+    rawDimsUnits?: Record<string, number>;
+    /** Schema version of {@link measurements}; currently `1`. */
+    measurementsVersion?: number;
+    /** Reported measurements — the authoritative rating input. */
+    measurements?: {
+        meter: string;
+        values: Record<string, number>;
+        dims?: Record<string, string>;
+    }[];
+    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
+    quote?: {
+        currency: string;
+        amountNanos: string;
+    };
     measureContext?: Record<string, unknown>;
     creditUnitsConsumed?: Record<string, number>;
     operationKey?: string;
@@ -43,43 +64,10 @@ export declare const METERING_PAYLOAD_HEADER: "x-fs-metering";
 export declare const METERING_SIGNATURE_HEADER: "x-fs-metering-sig";
 export declare const METERING_TOKEN_HEADER: "x-fs-metering-token";
 export declare const DEFAULT_TOKEN_ENV: "FS_RUNTIME_TOKEN";
-export type UsageMap = Record<string, number>;
-export type BillableUsageMap = UsageMap;
-export type MeteringOptions = {
-    token?: string;
-    env?: Record<string, string | undefined>;
-    /**
-     * Gateway request id for dev-mode trace/usage association (never signed).
-     * Thread the VERIFIED `ctx.requestId` here — the strict middleware strips the
-     * inbound `x-fs-request-id` header, so the request object no longer carries it.
-     * Falls back to the request's `x-fs-request-id` header when unset.
-     */
-    requestId?: string;
-    measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: BillableUsageMap;
-    /** Gateway-validated operation identity hint. The SDK signs and transports it
-     *  but never decides billing or policy from it. */
-    operationKey?: string;
-    /** Gateway-validated policy hint. Advisory identity only; the gateway remains
-     *  authoritative for customerBillable/provider-cost decisions. */
-    usagePolicyId?: string;
-};
-export type UsageWrapOptions = {
-    measureContext?: Record<string, unknown>;
-    creditUnitsConsumed?: BillableUsageMap;
-    operationKey?: string;
-    usagePolicyId?: string;
-};
-export type UsageReporter = {
-    report(meter: string, value: number): UsageReporter;
-    wrap(response: Response, options?: UsageWrapOptions): Promise<Response>;
-};
 export declare class MeteringError extends Error {
     readonly code: ResponseMeteringErrorCode;
     constructor(code: ResponseMeteringErrorCode, message: string);
 }
-export declare function createUsage(request: Request, options?: MeteringOptions): UsageReporter;
-export declare function withUsage(request: Request, response: Response, usage: UsageMap, options?: MeteringOptions): Promise<Response>;
 /**
  * Compute the three response-metering headers for a payload as a plain
  * name→value map, attachable to ANY response mechanism (Fetch `Response`,
@@ -87,7 +75,9 @@ export declare function withUsage(request: Request, response: Response, usage: U
  * primitive: it NEVER throws at request time — if no token is resolvable (or
  * signing fails) it skips stamping, reports the reason (`onSkip` / dev hook /
  * a `console.warn`), and returns `{}` so the builder's endpoint is never broken.
- * `withUsage`/`createUsage` are thin sugar over it.
+ *
+ * This is the framework-neutral wire recipe: `ctx.report()` is the JS surface
+ * over it, and a Python/Go backend can stamp identical headers by building the
+ * same payload (see `docs/response-metering-wire.md`).
  */
 export declare function computeMeteringHeaders(payload: ResponseMeteringUsagePayload, options?: ComputeMeteringOptions): Promise<MeteringHeaders>;
-export {};

package/dist/types/runtime-types.d.ts

@@ -37,7 +37,7 @@ export type LimitClass = "quota" | "rate" | "concurrency" | "capacity" | "spend"
  *  `LimitReaction`. */
 export type LimitReaction = "none" | "backoff_retry" | "wait_then_retry" | "queue" | "reduce_then_retry" | "fallback" | "upgrade";
 /** Where a limit was decided. Mirrors contracts `LimitOrigin`. */
-export type LimitOrigin = "platform" | "provider";
+export type LimitOrigin = "platform" | "provider" | "subscriber";
 /**
  * F1 — the `_fs` deny envelope a backend stamps on a usage-limit deny body.
  * Structurally identical to the contracts `FsDenyEnvelope`.
@@ -45,6 +45,7 @@ export type LimitOrigin = "platform" | "provider";
 export interface FsDenyEnvelope {
     limitClass: LimitClass;
     scope?: string;
+    actorScope?: "member" | "service_account";
     metric?: string;
     reset?: number;
     remaining?: number;
@@ -75,6 +76,7 @@ export interface FsDenyEnvelope {
 export declare const DENY_ENVELOPE_FIELDS: {
     limitClass: true;
     scope: true;
+    actorScope: true;
     metric: true;
     reset: true;
     remaining: true;
@@ -286,6 +288,19 @@ export type RuntimePostStreamUsageEvent = {
     meters: Record<string, number>;
     creditUnitsConsumed?: Record<string, number>;
     measureContext?: Record<string, unknown>;
+    /** Schema version of {@link measurements}; currently `1`. */
+    measurementsVersion?: number;
+    /** Measurement lane — `{ meter, values, dims }` as declared in the release. */
+    measurements?: {
+        meter: string;
+        values: Record<string, number>;
+        dims?: Record<string, string>;
+    }[];
+    /** Proposed rate input for a `backendQuoted` pricing rule (core clamps it). */
+    quote?: {
+        currency: string;
+        amountNanos: string;
+    };
     signature: string;
 };
 export type RuntimeHealthReport = {

package/dist/types/testing/devRuntime.d.ts

@@ -1,5 +1,5 @@
 import { FartherShore } from "../core/runtime.js";
-import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type MiddlewareOptions, type VerifiedExpressHandler } from "../adapters/express.js";
+import { type ExpressMiddleware, type ExpressRequestLike, type ExpressResponseLike, type HandlerOptions, type MiddlewareOptions, type VerifiedExpressHandler } from "../adapters/express.js";
 import { type PermissionCarrier } from "../core/permissions.js";
 import { type DevGateway } from "./devGateway.js";
 import { DevUsageSink } from "./usageSink.js";
@@ -14,7 +14,16 @@ export type TracedCarrier = PermissionCarrier & {
 export type FartherShoreDevInstance = FartherShore & {
     middleware(options?: MiddlewareOptions): ExpressMiddleware;
     /** Strict-context handler wrapper (guaranteed non-optional ctx). */
-    handler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    handler: {
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+        /** Options-first overload — declarative `permission` gate. */
+        <Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
+    };
+    /** Traced authz helpers — the SAME shape as the prod facade's `fs.authz`. */
+    authz: {
+        hasPermission(ctx: TracedCarrier, key: string): boolean;
+        requirePermission(ctx: TracedCarrier, key: string): void;
+    };
     /** The dev harness attached to this runtime. */
     dev: DevRuntime;
 };

package/dist/types/testing/index.d.ts

@@ -6,3 +6,4 @@ export { writeDevKeysFile, readDevKeysFile, personaClientFromKeysFile, DEFAULT_K
 export { DevUsageSink, type DevUsageEvent } from "./usageSink.js";
 export { DevTraceSink, redactValue, type DevTrace, type DevMode, type VerificationOutcome, type AuthzDecisionEntry, type MeteringTraceEntry, } from "./traceSink.js";
 export { isProductionEnv, assertNotProduction, DevModeInProductionError, } from "./prodGuard.js";
+export { signWebhookForTesting, type SignWebhookForTestingInput, type SignedTestWebhook, } from "./webhooks.js";

package/dist/types/testing/usageSink.d.ts

@@ -26,7 +26,7 @@ export type DevUsageEvent = {
 /** In-memory, assertable sink for all dev usage. */
 export declare class DevUsageSink {
     readonly events: DevUsageEvent[];
-    /** Record a signed response-metering payload (withUsage / computeMeteringHeaders). */
+    /** Record a signed response-metering payload (report() in-band / computeMeteringHeaders). */
     recordResponse(payload: Record<string, unknown>, requestId?: string): void;
     /** Record a background `fs.meter()` event captured by the dev gateway. */
     recordMeterEvent(event: RuntimeMeteringEvent): void;

package/dist/types/testing/webhooks.d.ts

@@ -0,0 +1,30 @@
+import type { WebhookEnvelope, WebhookEnvelopeType, WebhookEventData } from "../webhooks/types.js";
+export interface SignWebhookForTestingInput<T extends WebhookEnvelopeType> {
+    /** The endpoint secret(s) the receiver is configured with (current first). */
+    secret: string | readonly string[];
+    type: T;
+    data: WebhookEventData[T];
+    /** Defaults to a random delivery id. */
+    id?: string;
+    businessId?: string;
+    environmentId?: string | null;
+    /** Defaults to now (ISO). */
+    createdAt?: string;
+    /** Signing timestamp (unix seconds); defaults to now. */
+    timestamp?: number;
+}
+export interface SignedTestWebhook<T extends WebhookEnvelopeType> {
+    envelope: WebhookEnvelope<T>;
+    /** The exact bytes to POST. */
+    body: string;
+    /** `webhook-id` / `webhook-timestamp` / `webhook-signature` / event / content-type. */
+    headers: Record<string, string>;
+    /** Convenience: a `Request` you can hand straight to `handler.fetch`. */
+    request(url?: string): Request;
+}
+/**
+ * Build + sign one delivery the way the platform does (Standard Webhooks
+ * over `${id}.${timestamp}.${body}`). Pass several secrets to emulate the
+ * 24 h dual-signing rotation window.
+ */
+export declare function signWebhookForTesting<T extends WebhookEnvelopeType>(input: SignWebhookForTestingInput<T>): SignedTestWebhook<T>;