@farthershore/backend/express exports
Every public export and declaration from @farthershore/backend/express.
Every public export and declaration from @farthershore/backend/express.
Import from @farthershore/backend/express. This reference is extracted from the published declaration surface for version 0.21.2. Read the collection's guides for workflows, prerequisites and failure handling.
Wrap a route handler so it runs only with a GUARANTEED verified PRINCIPAL. The
strict {@link createExpressMiddleware} already attaches `req.fartherShore`
before any handler runs; this closes the type gap by handing the handler a
{@link VerifiedPrincipalContext} whose `principal` is NON-OPTIONAL (no
optional-chaining to read `ctx.principal`). It enforces that guarantee at
runtime with two fail-closed 401s BEFORE the callback runs:
- `context_unverified` when there is no verified context at all (handler
mounted without the middleware);
- `principal_required` when the context is verified but identity-less (a
valid gateway request that carried no `X-Fs-Context`) — so the callback is
never invoked with an absent `ctx.principal`.
A thrown `FartherShoreError` / `FartherShorePermissionError` — e.g. from
`requireMember(ctx)` — is mapped to its typed status; any other error is
forwarded to `next` for the app's error pipeline.
Returns the wide {@link ExpressMiddleware} so it drops straight into
`app.post(path, fs.handler(...))`: a handler whose `req` is narrowed to a
`{ fartherShore: ... }` request type is a SUBTYPE of Express's `Request` and
would fail Express's `RequestHandler` assignability — moving the verified
context onto its own `ctx` argument (not the `req` type) is what keeps the
non-optional guarantee AND Express compatibility.
Options-first overload: `fs.handler({ permission: "widgets:write" }, cb)`
asserts the verified principal holds `permission` (via the fail-closed
carrier gate — an absent permission set DENIES) BEFORE the callback runs,
responding `403 permission_denied` otherwise. The key is checked with the
unified grammar (`*` / `<subject>:*` / exact); derive route-shaped keys with
`routePermission(subject, method)`.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L129.
export declare function createExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
export declare function createExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike>(options: HandlerOptions, handler: VerifiedExpressHandler<Req, Res>): ExpressMiddleware;
Build the Express middleware. Captures raw body bytes, calls verifyRequest,
and fail-closes on any error.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L105.
export declare function createExpressMiddleware(fs: FartherShore__b6398b2ddfc7, options?: MiddlewareOptions): ExpressMiddleware;
Public export ExpressMiddleware.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L30.
export type ExpressMiddleware = (req: ExpressRequestLike, res: ExpressResponseLike, next: ExpressNext) => void;
Public export ExpressNext.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L29.
export type ExpressNext = (err?: unknown) => void;
Minimal Express-shaped types so we don't hard-depend on
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L5.
export type ExpressRequestLike = {
method: string;
/** Original URL incl. query, e.g. "/v1/x?a=1". */
originalUrl?: string;
url?: string;
path?: string;
headers: Record<string, string | string[] | undefined>;
/** Raw body bytes if captured by an upstream raw parser. */
rawBody?: Buffer | Uint8Array;
body?: unknown;
fartherShore?: FartherShoreRequestContext__fee40dd450e8;
};
Public export ExpressResponseLike.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L17.
export type ExpressResponseLike = {
status(code: number): ExpressResponseLike;
json(body: unknown): unknown;
setHeader(name: string, value: string): void;
/**
* Node's `ServerResponse.headersSent`. This is what makes the reporting verb's
* transport choice AUTOMATIC: while it is false the measurement rides signed
* response headers (no network call); once the response is on the wire
* `ctx.report()` transparently switches to the post-stream channel.
*/
headersSent?: boolean;
};
Options for the `fs.handler(options, cb)` overload.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L91.
export type HandlerOptions = {
/**
* Permission key the verified principal must hold (unified grammar:
* `*` / `<subject>:*` / exact — custom strings work). Checked with the
* FAIL-CLOSED carrier gate (`requirePermission`): an ABSENT permission set
* denies. On failure the wrapper responds `403 { error: "permission_denied" }`
* before the callback runs.
*/
permission?: string;
};
Public export MiddlewareOptions.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L31.
export type MiddlewareOptions = {
/**
* STRICT BY DEFAULT (`true`). Every request is verified FAIL-CLOSED and its
* inbound `x-fs-*` headers are stripped before the handler runs — the verified
* `req.fartherShore` context is the only identity source. The builder need not
* pass this: the gateway signs every request, and a missing/invalid signature
* or context is a `401`.
*
* Set `always: false` to instead DEFER to bootstrap's
* `verification.required` flag — when the backend contract does not require
* verification, the request passes through WITHOUT a context (and without
* stripping). This is an advanced escape hatch for a backend that intentionally
* consumes no identity; the secure default is strict.
*/
always?: boolean;
/**
* Called when verification REJECTS a request, with the diagnostic detail that
* is deliberately withheld from the response body.
*
* The wire response is only `{ error: <code> }` (plus the error's `details`,
* if any) — several distinct causes share one code (`route_mismatch` covers
* both a business mismatch and a backend mismatch; an unserved route id is
* the separate `route_unknown`), and the specifics must not leak to an
* unauthenticated caller. But discarding them entirely leaves the operator
* with no way to tell which cause fired, in their OWN logs, for their OWN
* server. That is what this hook restores.
*
* Defaults to a one-line `console.warn`. Pass a function to route it into a
* structured logger, or `() => {}` to silence it.
*/
onVerificationError?: (detail: {
code: string;
message: string;
status: number;
method: string;
path: string;
}) => void;
};
A route handler that runs only with a GUARANTEED verified PRINCIPAL. The first
argument is the {@link VerifiedPrincipalContext} — read `ctx.principal` and
`ctx.signedContext` (and narrow with `requireMember`/`requireService`)
without any optional-chaining.
See {@link createExpressHandler}.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L89.
export type VerifiedExpressHandler<Req extends ExpressRequestLike = ExpressRequestLike, Res extends ExpressResponseLike = ExpressResponseLike> = (ctx: VerifiedPrincipalContext, req: Req, res: Res, next: ExpressNext) => void | Promise<void>;
A verified request context whose {@link ConsumerPrincipal} is GUARANTEED
present — the shape handed to a {@link VerifiedExpressHandler}. The raw
`FartherShoreRequestContext.principal` is optional (an identity-less gateway
request is legitimate on the `fs.middleware()` path); `fs.handler()` narrows to
this type only AFTER rejecting an absent principal with `401 principal_required`,
so the callback can read `ctx.principal` (and narrow with
`requireMember`/`requireService`) without any optional-chaining.
Declaration source: packages/backend/dist/types/adapters/express.d.ts#L78.
export type VerifiedPrincipalContext = FartherShoreRequestContext__fee40dd450e8 & {
principal: ConsumerPrincipal__16f951b9786d;
signedContext: FartherShoreSignedContext__24c947c09583;
};
These declarations explain types reachable from the public exports above. They are source evidence, not supported package imports. Suffixed names are documentation identifiers that preserve distinct lexical bindings. Standard-library and third-party types (for example Promise, React and Zod) remain external boundaries; their implementation declarations are not expanded here.
Declaration source: packages/backend/dist/types/core/verifyContext.d.ts#L8.
export type ConsumerPrincipal__16f951b9786d = {
org: {
id: string;
};
subject: {
kind: "member";
/** The member's stable internal id (never an IdP subject/email). */
memberId: string;
/** How this request's identity was proven. */
via: "session" | "api_key";
/** The personal `fsk_` key id when `via === "api_key"` (audit). */
keyId?: string;
} | {
kind: "service";
/** The org-owned service account id — the stable service identity. */
serviceAccountId: string;
/** The specific service `fsk_` key id (rotates; audit). */
keyId: string;
};
};
Declaration source: packages/backend/dist/types/core/runtime.d.ts#L84.
export declare class FartherShore__b6398b2ddfc7 {
private readonly bootstrapClient;
private readonly fetchImpl;
private readonly verificationEnabled;
private readonly meteringEnabledOverride;
private readonly runtimeToken;
private readonly coreUrl;
private readonly instanceId?;
private readonly tunnelOptions;
/** OPTIONAL HS256 secret(s) — defense-in-depth over the cv=2 X-Fs-Context. */
private readonly contextSecrets;
private readonly nonceCache;
private readonly replayProtectionDiagnostic;
private readonly shutdownManager;
/** Bounds the on-demand bootstrap refreshes an unknown route id can trigger. */
private readonly routeRefreshLimiter;
private jwks;
private postStreamUsageClient;
private tunnel;
private bootstrapped;
constructor(options?: FartherShoreInitOptions__d009c6effb6b);
/** Ensure bootstrap config is loaded; build the JWKS + metering clients. */
ensureBootstrapped(): Promise<RuntimeBootstrapResponse__aecc7a0d671f>;
/**
* Boot-time route reconciliation (call once, before `listen()`). Reflects the
* app's real route surface, diffs it against the declared lock from bootstrap,
* REPORTS drift to the platform, and CONFIRMS the declared `pending` routes
* this replica serves. Fail-OPEN: never throws / never blocks boot.
*
* The reflection code is dynamically imported so it stays OFF the per-request
* verification hot path (the runtime stays route-unaware there). The report is
* an OUTBOUND backend→core call (same channel as bootstrap/metering), so it
* works for every transport (direct / tunnel).
*
* Returns the reconcile result (or null if reflection is unavailable / boot
* reporting failed). v1 reflects Express; `app` omitted → no-op.
*/
ready(app?: unknown): Promise<ReconcileResult__9286f3220e09 | null>;
/** Outbound report sink for `ready()` — runtime-token-authed POSTs to core. */
private buildReportSink;
/**
* Framework-neutral verification primitive. Fail-closed: throws a typed
* FartherShoreError on any verification failure. Returns the verified context.
*/
verifyRequest(input: VerifyRequestInput__5a17124b6df7, options?: VerifyRequestHostOptions__981e9466821d): Promise<FartherShoreRequestContext__fee40dd450e8>;
/**
* Bind the ONE reporting verb to a verified context. Identity comes from the
* context (`signedContext.subscriptionId` + `requestId`) — never from the
* caller — so a handler cannot forget it, and a background job that is handed
* this context keeps reporting against the SAME served identity.
*/
private buildReportFn;
/** Whether verification is required (bootstrap × opt-out). */
verificationRequired(): Promise<boolean>;
/**
* Start the embedded runner. For a `tunnel` backend whose runner is
* `embedded`, this supervises `cloudflared` as a child process
* (spawned via the injected/default spawner) using the tunnel token from
* bootstrap. For every other transport (`direct`, or the `sidecar` runner)
* it is a no-op — there is no SDK-managed process to run.
*
* Fail-open by default: a tunnel that cannot start does NOT crash the host app
* (request verification stays fail-closed regardless — a different axis).
*/
start(): Promise<void>;
/**
* PRIVATE transport for the post-stream lane of `ctx.report()`. Never rejects
* — a metering hiccup must not break a builder's endpoint. This is machinery,
* not surface: the ONE public reporting verb is `ctx.report()`.
*/
private reportPostStreamUsage;
/**
* How far replay protection actually reaches — `"shared"` (enforced across
* every replica) or `"single-instance"` (this process only). Deployment
* diagnostic: log it at boot, or assert on it in a smoke test, so the mode is
* never a surprise. See {@link FartherShoreInitOptions.nonceStore}.
*/
replayProtection(): ReplayProtectionDiagnostic__a3a9ef1278f1;
/** Current local health report. */
health(): RuntimeHealthReport__0174b488600d;
/** Graceful shutdown: flush metering + send a stopping heartbeat. */
shutdown(): Promise<void>;
/** Register an additional shutdown hook (e.g. the cloudflared supervisor). */
onShutdown(hook: () => Promise<void> | void): void;
}
Declaration source: packages/backend/dist/types/core/runtime.d.ts#L21.
export type FartherShoreInitOptions__d009c6effb6b = {
/** Explicit runtime token. Defaults to process.env.FS_RUNTIME_TOKEN. */
runtimeToken?: string;
/** Core base URL. Defaults to FS_CORE_URL or https://core.farthershore.com. */
coreUrl?: string;
/** Env map (tests). Defaults to process.env. */
env?: Record<string, string | undefined>;
/** Injectable fetch (tests). */
fetchImpl?: typeof fetch;
/** Optional advanced opt-outs (default: everything on). */
verification?: {
enabled?: boolean;
};
metering?: {
enabled?: boolean;
};
/** Embedded-cloudflared runner config (advanced opt-in; default DX is on). */
tunnel?: FartherShoreTunnelOptions__07694d2dbe44;
/** SDK metadata forwarded to bootstrap. */
instanceId?: string;
/**
* OPTIONAL HS256 secret(s) for the gateway's cv=2 `X-Fs-Context` claim — pure
* DEFENSE-IN-DEPTH, NOT required to derive identity. The consumer principal is
* always produced from the `X-Fs-Context` token whose bytes are vouched for by
* the Ed25519 request signature (the token's SHA-256 is bound into the signed
* canonical string). These secrets add a second, independent HS256 proof: when
* configured, a presented token must ALSO pass HS256 or the request is
* rejected. They are the GATEWAY CONTEXT-SIGNING keyring values
* (`CONTEXT_SIGNING_KEYS_JSON`; supply every live key during rotation —
* try-all), NOT the business's `contextTokenSecret` (which signs `fsc_`
* INGRESS tokens verified BY the gateway — setting that here would reject every
* valid gateway request). Defaults to `FS_CONTEXT_SECRETS` (comma-separated)
* from the env. Leaving it unset is the common case.
*/
contextSecrets?: readonly string[];
/**
* OPTIONAL shared replay-prevention store. Not required: the signature's
* ~305s time window is the always-on defense, and the zero-config default is
* an in-memory per-process cache. Inject a shared atomic store (Redis /
* Memcached / Cloudflare KV / Durable Object) implementing {@link NonceStore}
* only if you want one-time-use enforced ACROSS replicas rather than within
* each one. `checkAndRemember` may be async, and should be TTL-bound to the
* signature validity window.
*
* If you do inject one, an outage of that store fails requests CLOSED — it
* never degrades to "not a replay".
*/
nonceStore?: NonceStore__85b099a3f9b9;
};
Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L24.
export type FartherShoreRequestContext__fee40dd450e8 = {
requestId: string;
businessId: string;
backendId: string;
routeId: string;
policyVersion: string;
timestamp: number;
bodyHash: string;
/** Filled by the host bootstrap layer (tenant/customer), not by verify. */
tenantId?: string;
customerId?: string;
meters?: string[];
features?: Record<string, unknown>;
/**
* The verified CONSUMER PRINCIPAL behind this request (consumer-principal
* wave, D3) — derived from the cv=2 `X-Fs-Context` whose bytes are vouched for
* by the Ed25519 request signature (the token hash is bound into the canonical
* signing string). OPTIONAL on this raw `fs.middleware()` path: a valid gateway
* request MAY be identity-less (no `X-Fs-Context` — the gateway signs an
* empty context hash), in which case there is no principal to resolve. This
* field is typed honestly here; the `fs.handler()` path (createExpressHandler)
* is where the GUARANTEED non-optional principal lives — it rejects an
* identity-less request with `401 principal_required` before the callback runs.
* Use {@link requireMember} to narrow to the member arm on member-only routes.
*/
principal?: ConsumerPrincipal__16f951b9786d;
/**
* Managed-RBAC permissions the gateway resolved for the acting subject —
* sourced ONLY from the VERIFIED signed `X-Fs-Context` claim (the unsigned
* `x-fs-permissions` fallback is GONE). `undefined` when the claim was absent
* ⇒ FAR-723 carrier-level DENY; `[]` for an authenticated subject with no
* grants. Read via {@link hasPermission} / {@link requirePermission}.
*/
permissions?: string[];
/** Exact current-G product permissions default-allowed for this request. */
unassignedProductPermissions?: string[];
/** The VERIFIED signed cv=2 context payload. Its permissions/roles populated
* the fields above; its claims derived {@link principal}. */
signedContext?: FartherShoreSignedContext__24c947c09583;
/** Managed-RBAC role keys the acting subject holds (display/audit only). */
roles?: string[];
/**
* 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__89e79b33cabf;
};
Declaration source: packages/backend/dist/types/core/verifyContext.d.ts#L33.
export type FartherShoreSignedContext__24c947c09583 = {
/** Claim-format version. This SDK understands ONLY cv=2 (consumer principal). */
cv: 2;
/** Resource owner: member id (member) or service account id (service). */
sub: string;
/** API key / service credential id, when the call is key-borne. */
client_id?: string;
/** Nested actor (on-behalf-of): personal-key traffic sets `{ sub: keyId }`. */
act?: {
sub: string;
};
/** The org (tenant) id. */
org: string;
businessId: string;
compiledPlanId: string;
subscriptionId: string;
subscriberId: string;
environmentId: string | null;
subjectKey: string;
/** Which subject arm this context resolves to. */
subjectKind: "member" | "service";
/** The org-owned service account id, for service subjects (mirror of `sub`). */
serviceAccountId?: string;
/** The bound role keys (absent when unminted). */
roles?: string[];
/** The unified-authz permission claim (absent when unminted). */
permissions?: string[];
/** Exact current-G product permissions default-allowed for this request. */
unassignedProductPermissions?: string[];
};
Declaration source: packages/backend/dist/types/core/runtime.d.ts#L9.
export type FartherShoreTunnelOptions__07694d2dbe44 = {
/** Opt out of the embedded cloudflared runner (e.g. sidecar mode). */
enabled?: boolean;
/** Injected spawner (tests/non-default hosts). Defaults to node:child_process. */
spawn?: SpawnFn__a4d2414f74db;
/** Explicit cloudflared binary path. */
binaryPath?: string;
/** Crash the host app if the tunnel cannot start. Default: fail-open. */
failClosed?: boolean;
/** Log sink for redacted cloudflared output. */
logger?: (line: string) => void;
};
Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L22.
export type HeadersLike__89315298f855 = Headers | Record<string, string | string[] | undefined>;
Declaration source: packages/backend/dist/types/core/report.d.ts#L5.
export type MeasurementDimensions__e2d8137e24a6 = Record<string, string>;
Declaration source: packages/backend/dist/types/core/report.d.ts#L3.
export type MeasurementValues__ab2d89ace8f2 = Record<string, number>;
Declaration source: packages/backend/dist/types/core/nonceCache.d.ts#L13.
export interface NonceStore__85b099a3f9b9 {
checkAndRemember(id: string): boolean | Promise<boolean>;
}
Declaration source: packages/backend/dist/types/reflect/reconcile.d.ts#L23.
export interface ReconcileResult__9286f3220e09 {
/** Reflected surface matched the declared lock. */
inSync: boolean;
/** A drift report was sent. */
reportedDrift: boolean;
/** Route ids confirmed served (pending → clearable). */
confirmedRouteIds: string[];
/** A report sink call failed (swallowed — boot never blocks on it). */
reportError?: string;
}
Declaration source: packages/backend/dist/types/core/replay-protection.d.ts#L4.
export type ReplayProtectionDiagnostic__a3a9ef1278f1 = {
mode: ReplayProtectionMode__c5da7b084f0a;
/** True when replay is enforced across every replica, not just this process. */
crossReplica: boolean;
};
Declaration source: packages/backend/dist/types/core/replay-protection.d.ts#L3.
export type ReplayProtectionMode__c5da7b084f0a = "shared" | "single-instance";
Declaration source: packages/backend/dist/types/core/report.d.ts#L115.
export type ReportFn__89e79b33cabf = (input: ReportInput__0f8959765e13 | readonly ReportInput__0f8959765e13[]) => Promise<ReportResult__1d967fd166a1>;
Declaration source: packages/backend/dist/types/core/report.d.ts#L28.
export type ReportInput__0f8959765e13 = {
/** Meter key as declared in the business release (plain string at the wire). */
meter: string;
/** Observed values keyed by measure key, e.g. `{ input_tokens: 1200 }`. */
values: MeasurementValues__ab2d89ace8f2;
/** Catalog selectors, e.g. `{ model: "acme-4", cache_status: "hit" }`. */
dims?: MeasurementDimensions__e2d8137e24a6;
/**
* OPTIONAL money proposal for a `backendQuoted` pricing rule: a PER-UNIT
* rate in nanodollars (multiplied by the measured quantity — never a
* total). Opaque at the authoring boundary (a job result carries it through
* untyped); validated against {@link QuoteInput} here and transmitted as a
* {@link QuoteProposal}. Applies to every backend-quoted component of this
* report; ignored by rules that are not backend-quoted.
*/
quote?: unknown;
};
Declaration source: packages/backend/dist/types/core/report.d.ts#L53.
export type ReportResult__1d967fd166a1 = {
ok: true;
transport: ReportTransport__0721adbb43b4;
} | {
ok: false;
transport: ReportTransport__0721adbb43b4;
reason: string;
/** The PLATFORM's error code, when the failure came back in a response
* body (e.g. `post_stream_request_not_found`). Absent for local faults.
* Surfaced so a builder can act on the cause without wrapping fetch. */
code?: string;
/** The platform's own error message, verbatim. */
message?: string;
/** HTTP status of the final delivery attempt, when there was one. */
status?: number;
};
Declaration source: packages/backend/dist/types/core/report.d.ts#L46.
export type ReportTransport__0721adbb43b4 = "in_band" | "post_stream";
Declaration source: packages/backend/dist/types/core/report.d.ts#L78.
export type ResponseSink__b746e2445083 = {
/** True while headers can still be stamped onto the outgoing response. */
canStampHeaders(): boolean;
/** Stamp the signed metering headers onto the outgoing response. */
stampHeaders(headers: Record<string, string>): void;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L126.
declare const RUNTIME_HEADER_NAMES__adc010c1041a: {
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";
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L124.
declare const RUNTIME_TOKEN_OPERATIONS__1b6bc2f07e6d: readonly ["gateway_verification", "metering", "health", "tunnel", "drift_report"];
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L119.
declare const RUNTIME_TOKEN_PREFIXES__449e80fc59d4: {
readonly live: "fsrt_live_";
readonly test: "fsrt_test_";
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L228.
export type RuntimeBootstrapResponse__aecc7a0d671f = {
business: {
id: string;
slug: string;
};
backend: {
id: string;
slug: string;
name: string;
};
/**
* Every backend id this token may serve, across ALL of the business's
* environments — `backend.id` is always a member.
*
* One deployment holds exactly one `FS_RUNTIME_TOKEN`, so an
* environment-scoped token forced a SEPARATE deployment per environment:
* serving a preview env meant repointing (and breaking) production. A
* business-scoped token serves every environment from one deployment, and the
* SDK checks the gateway's signed backend id for MEMBERSHIP of this set
* rather than equality with a single id.
*
* Optional and additive: an older core omits it and the SDK falls back to the
* single-id equality check.
*/
backendIds?: string[];
environment: {
id: string | null;
kind: RuntimeEnvironmentKind__ac9ea026fbe7;
};
operations: RuntimeTokenOperation__29f1e3868c88[];
verification: RuntimeVerificationConfig__5494b13a9008;
metering: RuntimeMeteringConfig__3d27722db6c2;
transport: RuntimeTransportConfig__7254e971c589;
routes: RuntimeRouteDescriptor__48a862559af0[];
/** Reflected route-surface lock (surfaceHash + version). Present once core
* serves it; `fs.ready()` diffs the reflected surface against it. */
lock?: RuntimeLockDescriptor__0d22ecd0bb58;
policyVersion: string;
refreshAfterSeconds: number;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L180.
export type RuntimeEnvironmentKind__ac9ea026fbe7 = RuntimeTokenKind__821c369e851d;
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L306.
export type RuntimeHealthReport__0174b488600d = {
runtimeToken: boolean;
bootstrap: boolean;
tunnel: string | null;
verification: boolean;
metering: boolean;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L224.
export type RuntimeLockDescriptor__0d22ecd0bb58 = {
surfaceHash: string;
lockVersion: number;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L195.
export type RuntimeMeteringConfig__3d27722db6c2 = {
enabled: boolean;
endpoint: string;
credential: string;
allowedMeters: string[];
allowedRoutes: string[];
perEventMax: number;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L214.
export type RuntimeRouteDescriptor__48a862559af0 = {
id: string;
method: string;
path: string;
backendId: string;
/** Declared-but-not-yet-confirmed-served route. `fs.ready()` confirms the ones
* this replica actually serves so core can clear the flag and publish. */
pending?: boolean;
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L123.
export type RuntimeTokenKind__821c369e851d = keyof typeof RUNTIME_TOKEN_PREFIXES__449e80fc59d4;
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L125.
export type RuntimeTokenOperation__29f1e3868c88 = (typeof RUNTIME_TOKEN_OPERATIONS__1b6bc2f07e6d)[number];
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L203.
export type RuntimeTransportConfig__7254e971c589 = {
mode: TransportMode__341e38853a53;
runner: TransportRunner__21383ffda4d0 | null;
originUrl?: string;
originHostname?: string;
localTarget?: string;
cloudflared?: {
tunnelToken: string;
version: string;
};
};
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L188.
export type RuntimeVerificationConfig__5494b13a9008 = {
required: boolean;
jwksUrl: string;
clockSkewSeconds: number;
replayWindowSeconds: number;
headerNames: typeof RUNTIME_HEADER_NAMES__adc010c1041a;
};
Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L11.
export interface SpawnedTunnelProcess__65f87a1c4fc6 {
readonly stdout: StdioStream__d26eea00aaf1 | null;
readonly stderr: StdioStream__d26eea00aaf1 | null;
readonly pid?: number;
/** Register the process-exit handler. */
on(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
/** Signal the child to stop. */
kill(signal?: NodeJS.Signals | number): boolean;
}
Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L25.
export type SpawnFn__a4d2414f74db = (command: string, args: string[], options?: {
env?: NodeJS.ProcessEnv;
}) => SpawnedTunnelProcess__65f87a1c4fc6;
Declaration source: packages/backend/dist/types/core/tunnel.d.ts#L4.
type StdioStream__d26eea00aaf1 = Pick<EventEmitter, "on">;
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L181.
export type TransportMode__341e38853a53 = "direct" | "tunnel";
Declaration source: packages/backend/dist/types/runtime-types.d.ts#L182.
export type TransportRunner__21383ffda4d0 = "embedded" | "sidecar";
Declaration source: packages/backend/dist/types/core/runtime.d.ts#L76.
export type VerifyRequestHostOptions__981e9466821d = {
responseSink?: ResponseSink__b746e2445083;
};
Declaration source: packages/backend/dist/types/core/verifyRequest.d.ts#L6.
export type VerifyRequestInput__5a17124b6df7 = {
method: string;
/** Path only (no host, no query). */
path: string;
/** Raw query string (with or without leading '?'); "" when absent. */
query?: string;
headers: HeadersLike__89315298f855;
/** Raw request bytes captured pre-parser; null/undefined for empty body. */
body?: Uint8Array | null;
/**
* True when the request is body-hash-exempt (streaming). The signed hash must
* then be the STREAM sentinel and the body is not hashed (size cap still
* applies upstream).
*/
streamingExempt?: boolean;
};