Connect a direct backend

Outcome#

The preview gateway reaches one public HTTPS backend only through a verified, environment-specific direct binding.

Prerequisites#

• A preview environment and reachable HTTPS origin.
• Backend code that verifies FartherShore-signed requests.
• A safe secret store for the one-time runtime token.

Create the preview runtime target#

farthershore backend create acme \
  --name "Preview API" \
  --slug core \
  --env preview \
  --transport direct \
  --origin-url https://preview-api.example.com \
  --default \
  --idempotency-key preview-core \
  --format json

The first backend in an environment becomes its default unless you choose another. Reusing the same slug in the same environment updates that runtime row.

Declare the matching contract#

import * as fs from "@farthershore/business";

const requests = fs.requests();

const core = fs.backend("core", {
  transport: { mode: "direct" },
  verification: { required: true },
  meters: [requests],
  default: true,
});

const health = fs.route("/health", {
  get: { backend: core, costs: [requests.fixed(1)] },
});

fs.plan("free", {
  kind: fs.plan.kind.free,
  grants: [health],
  limits: [requests.perMinute(60)],
});
export default fs.business();

verification.required defaults to true when omitted. The concrete origin URL must not appear in fs.backend(); it belongs to the environment binding.

farthershore build --format json
git push -u origin HEAD:env/preview
farthershore backend tokens create acme \
  --backend <backendId> \
  --env preview \
  --idempotency-key <persisted-token-create-attempt> \
  --format json

Store the returned secret once as FS_RUNTIME_TOKEN, restart the backend, and verify backend list reports a healthy status. Send one request through the preview runtime and one unsigned request directly to the origin; only the gateway-signed request should pass application verification.

If the token is exposed, rotate it and immediately deploy the new value. Token rotation revokes the old token rather than providing a dual-validity window.

See Backend request verification and Runtime tokens.

Verify#

Require a ready backend row and a successful gateway request. Send one unsigned request directly to the origin and require rejection.

Recovery#

If the origin changes, bind the exact environment again and read it back. If a runtime token is exposed, rotate it and deploy the replacement immediately; the old token stops working without a dual-validity window.

Agent prompt#

Create and declare one signed direct backend in preview, keep the concrete
origin out of the Business program, store the runtime token safely, and prove a
gateway-signed request succeeds while an unsigned origin request fails.