@absol-labs/agent 0.4.0 → 0.5.0

package/src/frameworks/langchain.ts

@@ -230,7 +230,7 @@ export function createLangChainVerifiedStreamTools(
     new DynamicStructuredToolCtor({
       name: "check_stream_status",
       description:
-        "Read the current stream status and whether the agent should stop work.",
+        "Read the current stream status and whether the agent should stop work. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
       schema: streamStatusToolSchema as any,
       func: async ({ streamId }: z.infer<typeof streamStatusToolSchema>) => {
         const result = await options.agentClient.getStreamStatus(
@@ -244,7 +244,7 @@ export function createLangChainVerifiedStreamTools(
     new DynamicStructuredToolCtor({
       name: "reclaim_unspent",
       description:
-        "Close and/or reclaim an existing stream under the same signed mandate controls.",
+        "Close and/or reclaim an existing stream under the same signed mandate controls. V2 reclaim follows checkpoint finalization or escape-window rules.",
       schema: reclaimToolSchema as any,
       func: async (input: z.infer<typeof reclaimToolSchema>) => {
         const signedMandate = parseSignedMandateInput(input.signedMandate);

package/src/gateway/caller-auth-gateway.ts

@@ -0,0 +1,328 @@
+import { MetrikClient } from "@absol-labs/sdk";
+import { isAddress, isHex, type Address, type Hex } from "viem";
+
+import {
+  CAPABILITY_HEADER_NAME,
+  decodeCapabilityHeader,
+  hashInvocationPath,
+  InvalidCapabilityHeaderError,
+  recoverInvocationCapabilitySigner,
+  type InvocationCapabilityDomainInput,
+  type SignedInvocationCapability,
+} from "../capability/invocation-capability.js";
+
+/**
+ * Seller-side caller-auth gateway (metrik-agent#63, impl of #62 part 1/2).
+ *
+ * Authorizes an incoming service request ONLY when it carries a valid
+ * `InvocationCapability` (see `../capability/invocation-capability.ts`) whose
+ * signer is the buyer of an active, funded, non-expired `StreamEscrowV2`
+ * stream matching this gateway's configured `serviceRef` - and the capability
+ * itself is unexpired, unreplayed, and bound to the exact method+path being
+ * called. Revocation is automatic: once a stream is closed/expired/reclaimed,
+ * the on-chain read step below fails closed and access stops with no extra
+ * bookkeeping.
+ */
+
+/** Machine-readable, closed set of rejection reasons - every failure mode is distinct. */
+export type CallerAuthDenialReason =
+  | "missing-capability-header"
+  | "malformed-capability-header"
+  | "capability-expired"
+  | "invalid-signature"
+  | "method-mismatch"
+  | "path-mismatch"
+  | "service-ref-mismatch"
+  | "nonce-replayed"
+  | "stream-not-found"
+  | "buyer-mismatch"
+  | "stream-not-active"
+  | "stream-expired"
+  | "stream-not-funded";
+
+export interface CallerAuthDecision {
+  readonly authorized: boolean;
+  readonly reason?: CallerAuthDenialReason;
+  /** Set only when `authorized === false`. */
+  readonly httpStatus?: 402 | 403;
+  /** Set only when `authorized === true`. */
+  readonly stream?: GatewayStreamView;
+  /** The decoded (but not necessarily valid) capability, when one was present. */
+  readonly capability?: SignedInvocationCapability;
+}
+
+/** The minimal on-chain stream fields the gateway needs to authorize a call. */
+export interface GatewayStreamView {
+  readonly buyer: Address;
+  readonly serviceRef: Hex;
+  readonly deposit: bigint;
+  readonly claimedCumulative: bigint;
+  readonly expiresAt: number;
+  readonly status: "active" | "closed";
+}
+
+/** Pluggable on-chain stream reader, so the gateway is testable without a live RPC. */
+export interface StreamReader {
+  getStream(streamId: Hex): Promise<GatewayStreamView>;
+}
+
+export class UnknownStreamGatewayError extends Error {
+  constructor(message: string, options?: { readonly cause?: unknown }) {
+    super(message, options);
+    this.name = "UnknownStreamGatewayError";
+  }
+}
+
+/** Default `StreamReader`: real, read-only `MetrikClient.getStreamV2` (no wallet, no writes). */
+export function createSdkStreamReader(options: {
+  readonly escrowAddress: Address;
+  readonly rpcUrl: string;
+}): StreamReader {
+  const metrik = MetrikClient.baseSepolia({
+    escrow: options.escrowAddress,
+    rpcUrl: options.rpcUrl,
+  });
+  return {
+    async getStream(streamId) {
+      try {
+        const stream = await metrik.getStreamV2(streamId);
+        return {
+          buyer: stream.buyer,
+          serviceRef: stream.serviceRef,
+          deposit: stream.deposit,
+          claimedCumulative: stream.claimedCumulative,
+          expiresAt: stream.expiresAt,
+          status: stream.status,
+        };
+      } catch (cause) {
+        throw new UnknownStreamGatewayError(
+          `failed to read stream ${streamId}: ${cause instanceof Error ? cause.message : String(cause)}`,
+          { cause },
+        );
+      }
+    },
+  };
+}
+
+/** Single-use nonce replay protection. */
+export interface NonceReplayCache {
+  /** Returns `true` (and records the nonce) IFF it has not been consumed before. Fails closed on a repeat. */
+  consume(nonce: Hex, expiresAtSeconds: number): boolean;
+}
+
+/**
+ * In-memory replay cache. Sufficient for a single-instance reference gateway;
+ * a multi-instance deployment should back this with a shared store (Redis,
+ * etc.) via the same `NonceReplayCache` interface.
+ */
+export class InMemoryNonceReplayCache implements NonceReplayCache {
+  private readonly seen = new Map<string, number>();
+
+  consume(nonce: Hex, expiresAtSeconds: number): boolean {
+    this.sweep();
+    const key = nonce.toLowerCase();
+    if (this.seen.has(key)) {
+      return false;
+    }
+    this.seen.set(key, expiresAtSeconds);
+    return true;
+  }
+
+  private sweep(): void {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    for (const [key, expiresAtSeconds] of this.seen) {
+      if (expiresAtSeconds < nowSeconds) {
+        this.seen.delete(key);
+      }
+    }
+  }
+}
+
+export interface CallerAuthGatewayConfig {
+  /** The `StreamEscrowV2` this gateway's streams settle on. */
+  readonly escrowAddress: Address;
+  /** RPC used for the default `StreamReader` (ignored if `streamReader` is supplied). */
+  readonly rpcUrl?: string;
+  /** The service this gateway fronts. Every request's stream AND capability must match it. */
+  readonly serviceRef: Hex;
+  /** Chain id for EIP-712 domain separation. Default `84532` (Base Sepolia). */
+  readonly chainId?: number;
+  /** Capability header name. Default {@link CAPABILITY_HEADER_NAME}. */
+  readonly headerName?: string;
+  /** Override the on-chain reader (tests inject a fake; default is the real SDK reader). */
+  readonly streamReader?: StreamReader;
+  /** Override the replay cache (tests inject a fake; default is in-memory). */
+  readonly nonceCache?: NonceReplayCache;
+  /** Injectable clock (unix seconds), for tests. */
+  readonly now?: () => number;
+}
+
+export interface CallerAuthRequestInput {
+  /** Lower-cased-lookup-safe header map (e.g. Node's `IncomingMessage.headers`). */
+  readonly headers: Readonly<Record<string, string | undefined>>;
+  readonly method: string;
+  /** The request path (query/fragment are ignored - only the path is bound). */
+  readonly path: string;
+}
+
+/**
+ * Authorizes requests against stream-bound `InvocationCapability` headers.
+ * Framework-agnostic: `authorize()` takes a plain `{headers, method, path}`
+ * triple so it can front any HTTP server (Node `http`, Express, Fastify, ...).
+ * See `./http-server.ts` for a ready-to-run reverse-proxy reference server.
+ */
+export class CallerAuthGateway {
+  private readonly streamReader: StreamReader;
+  private readonly nonceCache: NonceReplayCache;
+  private readonly headerName: string;
+  private readonly domain: InvocationCapabilityDomainInput;
+  private readonly serviceRef: Hex;
+  private readonly now: () => number;
+
+  constructor(config: CallerAuthGatewayConfig) {
+    if (!isAddress(config.escrowAddress)) {
+      throw new Error("escrowAddress must be an EVM address");
+    }
+    if (
+      !isHex(config.serviceRef, { strict: true }) ||
+      config.serviceRef.length !== 66
+    ) {
+      throw new Error("serviceRef must be a 32-byte hex value");
+    }
+    if (config.streamReader === undefined && config.rpcUrl === undefined) {
+      throw new Error(
+        "rpcUrl is required unless an explicit streamReader is supplied",
+      );
+    }
+
+    this.serviceRef = config.serviceRef;
+    this.headerName = (
+      config.headerName ?? CAPABILITY_HEADER_NAME
+    ).toLowerCase();
+    this.streamReader =
+      config.streamReader ??
+      createSdkStreamReader({
+        escrowAddress: config.escrowAddress,
+        rpcUrl: config.rpcUrl as string,
+      });
+    this.nonceCache = config.nonceCache ?? new InMemoryNonceReplayCache();
+    this.domain = {
+      chainId: config.chainId ?? 84532,
+      verifyingContract: config.escrowAddress,
+    };
+    this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+  }
+
+  async authorize(
+    request: CallerAuthRequestInput,
+  ): Promise<CallerAuthDecision> {
+    const headerValue = lookupHeader(request.headers, this.headerName);
+    if (headerValue === undefined || headerValue.length === 0) {
+      return deny("missing-capability-header", 403);
+    }
+
+    let capability: SignedInvocationCapability;
+    try {
+      capability = decodeCapabilityHeader(headerValue);
+    } catch (error) {
+      if (error instanceof InvalidCapabilityHeaderError) {
+        return deny("malformed-capability-header", 403);
+      }
+      throw error;
+    }
+
+    const nowSeconds = this.now();
+
+    if (nowSeconds >= capability.expiry) {
+      return deny("capability-expired", 403, capability);
+    }
+
+    let signer: Address;
+    try {
+      signer = await recoverInvocationCapabilitySigner(
+        capability,
+        this.domain,
+        capability.signature as Hex,
+      );
+    } catch {
+      return deny("invalid-signature", 403, capability);
+    }
+    if (signer.toLowerCase() !== capability.buyer.toLowerCase()) {
+      return deny("invalid-signature", 403, capability);
+    }
+
+    if (capability.method.toUpperCase() !== request.method.toUpperCase()) {
+      return deny("method-mismatch", 403, capability);
+    }
+
+    const expectedPathHash = hashInvocationPath(request.path);
+    if (expectedPathHash.toLowerCase() !== capability.pathHash.toLowerCase()) {
+      return deny("path-mismatch", 403, capability);
+    }
+
+    if (capability.serviceRef.toLowerCase() !== this.serviceRef.toLowerCase()) {
+      return deny("service-ref-mismatch", 403, capability);
+    }
+
+    // Consume the nonce BEFORE the on-chain read: the replay check is the
+    // cheapest gate and must fail closed even if the RPC is slow/unavailable.
+    if (!this.nonceCache.consume(capability.nonce as Hex, capability.expiry)) {
+      return deny("nonce-replayed", 403, capability);
+    }
+
+    let stream: GatewayStreamView;
+    try {
+      stream = await this.streamReader.getStream(capability.streamId as Hex);
+    } catch {
+      return deny("stream-not-found", 403, capability);
+    }
+
+    if (stream.buyer.toLowerCase() !== capability.buyer.toLowerCase()) {
+      return deny("buyer-mismatch", 403, capability);
+    }
+    if (stream.serviceRef.toLowerCase() !== this.serviceRef.toLowerCase()) {
+      return deny("service-ref-mismatch", 403, capability);
+    }
+    if (stream.status !== "active") {
+      return deny("stream-not-active", 403, capability);
+    }
+    if (nowSeconds >= stream.expiresAt) {
+      return deny("stream-expired", 403, capability);
+    }
+    if (stream.deposit <= stream.claimedCumulative) {
+      return deny("stream-not-funded", 402, capability);
+    }
+
+    return { authorized: true, stream, capability };
+  }
+}
+
+function deny(
+  reason: CallerAuthDenialReason,
+  httpStatus: 402 | 403,
+  capability?: SignedInvocationCapability,
+): CallerAuthDecision {
+  return {
+    authorized: false,
+    reason,
+    httpStatus,
+    ...(capability === undefined ? {} : { capability }),
+  };
+}
+
+function lookupHeader(
+  headers: Readonly<Record<string, string | undefined>>,
+  name: string,
+): string | undefined {
+  // Header maps may or may not already be lower-cased by the caller's framework;
+  // normalize defensively so a differently-cased key still resolves.
+  if (headers[name] !== undefined) {
+    return headers[name];
+  }
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === name) {
+      return value;
+    }
+  }
+  return undefined;
+}

package/src/gateway/http-server.ts

@@ -0,0 +1,325 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { isAddress, isHex, type Address, type Hex } from "viem";
+
+import {
+  CallerAuthGateway,
+  type CallerAuthDenialReason,
+} from "./caller-auth-gateway.js";
+
+/**
+ * Reference standalone reverse-proxy gateway server (metrik-agent#63).
+ *
+ * A seller runs this in front of their real HTTP service. Every request must
+ * carry a valid `InvocationCapability` header (see
+ * `../capability/invocation-capability.ts`); on pass, the request is proxied
+ * to `upstreamUrl` verbatim and its response is returned unmodified. On fail,
+ * a `402`/`403` with a machine-readable JSON reason is returned and the
+ * upstream is never touched.
+ */
+
+/** Maximum buffered request body size (bytes) - bounds memory per request. */
+const MAX_BODY_BYTES = 16 * 1024 * 1024;
+
+/** Hop-by-hop headers that must never be forwarded verbatim to the upstream. */
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+  "content-length",
+]);
+
+export interface CallerAuthGatewayServerConfig {
+  readonly gateway: CallerAuthGateway;
+  /** Base URL of the real service this gateway fronts (e.g. `https://svc.example.com`). */
+  readonly upstreamUrl: string;
+  /** Extra request-timeout for the upstream fetch, in ms. Default 30000. */
+  readonly upstreamTimeoutMs?: number;
+}
+
+export interface CallerAuthGatewayServer {
+  readonly httpServer: Server;
+  listen(port: number, host?: string): Promise<{ port: number; host: string }>;
+  close(): Promise<void>;
+}
+
+export function createCallerAuthGatewayServer(
+  config: CallerAuthGatewayServerConfig,
+): CallerAuthGatewayServer {
+  const upstreamBase = new URL(config.upstreamUrl);
+  const upstreamTimeoutMs = config.upstreamTimeoutMs ?? 30_000;
+
+  const httpServer = createServer((req, res) => {
+    handleRequest(
+      req,
+      res,
+      config.gateway,
+      upstreamBase,
+      upstreamTimeoutMs,
+    ).catch((error) => {
+      logError("unhandled request error", error);
+      if (!res.headersSent) {
+        writeJsonError(res, 500, "internal-error");
+      } else {
+        res.end();
+      }
+    });
+  });
+
+  return {
+    httpServer,
+    listen: (port, host = "0.0.0.0") =>
+      new Promise((resolve, reject) => {
+        const onError = (error: Error) => reject(error);
+        httpServer.once("error", onError);
+        httpServer.listen(port, host, () => {
+          httpServer.removeListener("error", onError);
+          const address = httpServer.address() as AddressInfo;
+          resolve({ port: address.port, host });
+        });
+      }),
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        httpServer.close((error) => (error ? reject(error) : resolve()));
+      }),
+  };
+}
+
+async function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  gateway: CallerAuthGateway,
+  upstreamBase: URL,
+  upstreamTimeoutMs: number,
+): Promise<void> {
+  const requestUrl = new URL(req.url ?? "/", "http://localhost");
+  const method = req.method ?? "GET";
+  const headers = normalizeIncomingHeaders(req.headers);
+
+  const decision = await gateway.authorize({
+    headers,
+    method,
+    path: requestUrl.pathname,
+  });
+
+  if (!decision.authorized) {
+    writeJsonError(
+      res,
+      decision.httpStatus ?? 403,
+      decision.reason ?? "unauthorized",
+    );
+    return;
+  }
+
+  let body: Buffer | undefined;
+  if (method !== "GET" && method !== "HEAD") {
+    body = await readBody(req);
+  }
+
+  const upstreamHeaders = new Headers();
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined || HOP_BY_HOP_HEADERS.has(key)) {
+      continue;
+    }
+    upstreamHeaders.set(key, value);
+  }
+
+  const upstreamUrl = new URL(
+    requestUrl.pathname + requestUrl.search,
+    upstreamBase,
+  );
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), upstreamTimeoutMs);
+  try {
+    const upstreamResponse = await fetch(upstreamUrl, {
+      method,
+      headers: upstreamHeaders,
+      ...(body === undefined ? {} : { body }),
+      signal: controller.signal,
+    });
+
+    res.writeHead(
+      upstreamResponse.status,
+      headersToObject(upstreamResponse.headers),
+    );
+    const buffer = Buffer.from(await upstreamResponse.arrayBuffer());
+    res.end(buffer);
+  } catch (error) {
+    logError("upstream request failed", error);
+    writeJsonError(res, 502, "upstream-unavailable");
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function normalizeIncomingHeaders(
+  headers: IncomingMessage["headers"],
+): Record<string, string | undefined> {
+  const normalized: Record<string, string | undefined> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    normalized[key.toLowerCase()] = Array.isArray(value) ? value[0] : value;
+  }
+  return normalized;
+}
+
+function headersToObject(headers: Headers): Record<string, string> {
+  const result: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    if (HOP_BY_HOP_HEADERS.has(key.toLowerCase())) return;
+    result[key] = value;
+  });
+  return result;
+}
+
+class BodyTooLargeError extends Error {}
+
+async function readBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer;
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) {
+      throw new BodyTooLargeError("request body too large");
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+function writeJsonError(
+  res: ServerResponse,
+  status: number,
+  reason:
+    | CallerAuthDenialReason
+    | "unauthorized"
+    | "internal-error"
+    | "upstream-unavailable",
+): void {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  res
+    .writeHead(status, { "Content-Type": "application/json" })
+    .end(JSON.stringify({ authorized: false, reason }));
+}
+
+function logError(context: string, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[metrik-caller-auth-gateway] ${context}: ${message}`);
+}
+
+// ── Environment configuration ────────────────────────────────────────────────
+
+export interface CallerAuthGatewayEnvConfig {
+  readonly host: string;
+  readonly port: number;
+  readonly escrowAddress: Address;
+  readonly rpcUrl: string;
+  readonly serviceRef: Hex;
+  readonly chainId: number;
+  readonly upstreamUrl: string;
+  readonly headerName?: string;
+}
+
+/**
+ * Parses the gateway's env contract:
+ * - `METRIK_GATEWAY_ESCROW_ADDRESS` (required) - the `StreamEscrowV2` this
+ *   gateway checks streams against.
+ * - `METRIK_GATEWAY_RPC_URL` (required) - RPC used for the read-only stream check.
+ * - `METRIK_GATEWAY_SERVICE_REF` (required) - bytes32 `serviceRef` this gateway fronts.
+ * - `METRIK_GATEWAY_UPSTREAM_URL` (required) - the real service to proxy to on pass.
+ * - `METRIK_GATEWAY_CHAIN_ID` (optional) - default `84532` (Base Sepolia).
+ * - `METRIK_GATEWAY_HEADER_NAME` (optional) - default `x-metrik-capability`.
+ * - `PORT` / `METRIK_GATEWAY_PORT` (optional) - default `8787`.
+ * - `METRIK_GATEWAY_HOST` (optional) - default `0.0.0.0`.
+ *
+ * Fail-closed: throws if any required var is missing or malformed.
+ */
+export function parseCallerAuthGatewayEnvConfig(
+  env: NodeJS.ProcessEnv = process.env,
+): CallerAuthGatewayEnvConfig {
+  const escrowAddress = requireEnv(env, "METRIK_GATEWAY_ESCROW_ADDRESS");
+  if (!isAddress(escrowAddress)) {
+    throw new Error("METRIK_GATEWAY_ESCROW_ADDRESS must be an EVM address");
+  }
+  const rpcUrl = requireEnv(env, "METRIK_GATEWAY_RPC_URL");
+  const serviceRef = requireEnv(env, "METRIK_GATEWAY_SERVICE_REF");
+  if (!isHex(serviceRef, { strict: true }) || serviceRef.length !== 66) {
+    throw new Error("METRIK_GATEWAY_SERVICE_REF must be a 32-byte hex value");
+  }
+  const upstreamUrl = requireEnv(env, "METRIK_GATEWAY_UPSTREAM_URL");
+  // eslint-disable-next-line no-new -- validates the URL is well-formed.
+  new URL(upstreamUrl);
+
+  const chainIdRaw = env.METRIK_GATEWAY_CHAIN_ID ?? "84532";
+  const chainId = Number(chainIdRaw);
+  if (!Number.isInteger(chainId) || chainId <= 0) {
+    throw new Error(`invalid METRIK_GATEWAY_CHAIN_ID: ${chainIdRaw}`);
+  }
+
+  const portRaw = env.METRIK_GATEWAY_PORT ?? env.PORT ?? "8787";
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error(`invalid port: ${portRaw}`);
+  }
+
+  const host = env.METRIK_GATEWAY_HOST ?? "0.0.0.0";
+  const headerName = env.METRIK_GATEWAY_HEADER_NAME;
+
+  return {
+    host,
+    port,
+    escrowAddress,
+    rpcUrl,
+    serviceRef,
+    chainId,
+    upstreamUrl,
+    ...(headerName === undefined ? {} : { headerName }),
+  };
+}
+
+function requireEnv(env: NodeJS.ProcessEnv, name: string): string {
+  const value = env[name];
+  if (value === undefined || value.trim().length === 0) {
+    throw new Error(`${name} is required (fail-closed)`);
+  }
+  return value;
+}
+
+/** Builds and starts the reference gateway server entirely from the environment. */
+export async function startCallerAuthGatewayServerFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<CallerAuthGatewayServer & { readonly boundPort: number }> {
+  const config = parseCallerAuthGatewayEnvConfig(env);
+  const gateway = new CallerAuthGateway({
+    escrowAddress: config.escrowAddress,
+    rpcUrl: config.rpcUrl,
+    serviceRef: config.serviceRef,
+    chainId: config.chainId,
+    ...(config.headerName === undefined
+      ? {}
+      : { headerName: config.headerName }),
+  });
+  const server = createCallerAuthGatewayServer({
+    gateway,
+    upstreamUrl: config.upstreamUrl,
+  });
+  const { port } = await server.listen(config.port, config.host);
+  return Object.assign(server, { boundPort: port });
+}

package/src/gateway/server-entry.ts

@@ -0,0 +1,38 @@
+import { startCallerAuthGatewayServerFromEnv } from "./http-server.js";
+
+/**
+ * Runnable entrypoint for the reference caller-auth gateway (metrik-agent#63).
+ * Reads all configuration from the environment (see
+ * {@link parseCallerAuthGatewayEnvConfig}) and refuses to start if required
+ * config is missing (fail-closed).
+ *
+ * Start with: `pnpm gateway` (or `node dist/gateway/server-entry.js`).
+ */
+async function main(): Promise<void> {
+  const server = await startCallerAuthGatewayServerFromEnv();
+  const host = process.env.METRIK_GATEWAY_HOST ?? "0.0.0.0";
+  console.error(
+    `[metrik-caller-auth-gateway] listening on http://${host}:${server.boundPort}`,
+  );
+
+  const shutdown = (signal: string) => {
+    console.error(
+      `[metrik-caller-auth-gateway] ${signal} received — shutting down`,
+    );
+    server
+      .close()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+main().catch((error) => {
+  console.error(
+    error instanceof Error
+      ? error.message
+      : "failed to start caller-auth gateway server",
+  );
+  process.exit(1);
+});