sailfork / t3code-github / infra/ relay/ src/ hooks/ HookForwarder.test.ts

import * as NodeHttpPlatform from "@effect/platform-node/NodeHttpPlatform";
import * as NodeServices from "@effect/platform-node/NodeServices";
// @effect-diagnostics-next-line nodeBuiltinImport:off -- Effect's Crypto has no generateKeyPairSync.
import * as NodeCrypto from "node:crypto";
import * as EffectNodeCrypto from "@effect/platform-node/NodeCrypto";
import { describe, expect, it } from "@effect/vitest";
import { RelayApi, RelayHookDeliveryProofPayload } from "@t3tools/contracts/relay";
import * as Deferred from "effect/Deferred";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Redacted from "effect/Redacted";
import * as Tracer from "effect/Tracer";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientError from "effect/http/HttpClientError";
import type * as HttpClientRequest from "effect/http/HttpClientRequest";
import * as HttpClientResponse from "effect/http/HttpClientResponse";
import * as Etag from "effect/http/Etag";
import * as HttpEffect from "effect/http/HttpEffect";
import * as HttpRouter from "effect/http/HttpRouter";
import * as HttpApi from "effect/http-api/HttpApi";
import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";

import * as CloudMintSigner from "../auth/CloudMintSigner.ts";
import * as RelayConfiguration from "../Config.ts";
import * as EnvironmentLinks from "../environments/EnvironmentLinks.ts";
import * as ManagedEndpointAllocations from "../environments/ManagedEndpointAllocations.ts";
import { RELAY_HTTP_ROUTER_CONFIG, traceRelayHttpRequestWith } from "../http/Api.ts";
import * as RelayHttpApi from "../http/Api.ts";
import * as HookForwarder from "./HookForwarder.ts";
import { RELAY_HOOK_DELIVERY_TYP, verifyRelayJwt } from "@t3tools/shared/relayJwt";
import * as HeldHooks from "./HeldHooks.ts";
import * as HookInbox from "./HookInbox.ts";
import type { HeldHook } from "./HookInboxStore.ts";

const mintKeys = NodeCrypto.generateKeyPairSync("ed25519", {
  privateKeyEncoding: { format: "pem", type: "pkcs8" },
  publicKeyEncoding: { format: "pem", type: "spki" },
});

const settings: RelayConfiguration.RelayConfiguration["Service"] = {
  relayIssuer: "https://relay.example.test",
  apns: null,
  clerkSecretKey: Redacted.make("clerk-secret-key"),
  clerkPublishableKey: "pk_test_test",
  clerkJwtAudience: "t3-code-relay",
  apnsDeliveryJobSigningSecret: Redacted.make("apns-delivery-secret"),
  cloudMintPrivateKey: Redacted.make(mintKeys.privateKey),
  cloudMintPublicKey: mintKeys.publicKey,
  managedEndpointBaseDomain: "example.test",
  managedEndpointNamespace: "dev",
};

const environmentId = "env-hook";
const endpointKey = "0123456789abcdef";
const readyAllocation: ManagedEndpointAllocations.ManagedEndpointAllocation = {
  userId: "user_1",
  environmentId,
  hostname: "env.example.test",
  tunnelId: "tunnel-id",
  tunnelName: `t3coderelay-managedendpoint-dev-${endpointKey}`,
  dnsRecordId: "dns-record-id",
  readyAt: "2026-05-25T00:00:00.000Z",
  tunnelReleasedAt: null,
  origin: { localHttpHost: "127.0.0.1", localHttpPort: 3773 },
  updatedAt: "2026-05-25T00:00:00.000Z",
  generation: 1,
};

const managedLink = {
  userId: "user_1",
  environmentId: environmentId as never,
  label: "Hook env",
  endpoint: {
    httpBaseUrl: "https://env.example.test/",
    wsBaseUrl: "wss://env.example.test/ws",
    providerKind: "cloudflare_tunnel" as const,
  },
  environmentPublicKey: "public-key",
  linkedAt: "2026-05-25T00:00:00.000Z",
  holdWebhooksWhileOffline: false,
};

interface Harness {
  readonly execute?: (
    request: HttpClientRequest.HttpClientRequest,
  ) => Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError>;
  readonly links?: ReadonlyArray<typeof managedLink>;
  readonly allocation?: ManagedEndpointAllocations.ManagedEndpointAllocation | null;
  readonly allow?: (key: string) => boolean;
  readonly allowEndpoint?: (endpointKey: string) => boolean;
  readonly inboxCapacity?: number;
}

function makeHarness(options: Harness = {}) {
  const sent: Array<HttpClientRequest.HttpClientRequest> = [];
  const rateLimitKeys: Array<string> = [];
  const held: Array<HeldHook & { readonly baseUrl: string }> = [];
  const execute =
    options.execute ??
    ((request: HttpClientRequest.HttpClientRequest) =>
      Effect.succeed(
        HttpClientResponse.fromWeb(
          request,
          new Response("ok", { status: 200, headers: { "content-type": "text/plain" } }),
        ),
      ));
  const layerForwarder = HookForwarder.layer.pipe(
    Layer.provideMerge(HeldHooks.layer),
    Layer.provide(CloudMintSigner.layer),
    Layer.provide(
      Layer.mergeAll(
        Layer.succeed(RelayConfiguration.RelayConfiguration, settings),
        Layer.mock(EnvironmentLinks.EnvironmentLinks, {
          findActiveManagedForEnvironment: (input) =>
            Effect.succeed(
              (options.links ?? [managedLink]).filter(
                (link) =>
                  link.environmentId === input.environmentId &&
                  (input.userId === undefined || link.userId === input.userId),
              ),
            ),
        }),
        Layer.mock(ManagedEndpointAllocations.ManagedEndpointAllocations, {
          getByTunnelName: (tunnelName) => {
            const allocation =
              options.allocation === undefined ? readyAllocation : options.allocation;
            return Effect.succeed(allocation?.tunnelName === tunnelName ? allocation : null);
          },
        }),
        Layer.succeed(
          HttpClient.HttpClient,
          HttpClient.make((request) => {
            sent.push(request);
            return execute(request);
          }),
        ),
        Layer.mock(HookInbox.HookInbox, {
          hold: ({ hook, baseUrl }) =>
            Effect.sync(() => {
              if (held.length >= (options.inboxCapacity ?? Infinity)) return false;
              held.push({ ...hook, baseUrl });
              return true;
            }),
        }),
        EffectNodeCrypto.layer,
        Layer.succeed(HookForwarder.HookRateLimiter, {
          allowHook: (key) =>
            Effect.sync(() => {
              rateLimitKeys.push(key);
              return options.allow ? options.allow(key) : true;
            }),
          allowEndpoint: (key) =>
            Effect.sync(() => (options.allowEndpoint ? options.allowEndpoint(key) : true)),
        }),
      ),
    ),
  );
  const httpEffect = HttpRouter.toHttpEffect(
    Layer.mergeAll(
      HttpApiBuilder.layer(HttpApi.make("RelayApi").add(RelayApi.groups.hooks)).pipe(
        Layer.provide(HookForwarder.layerApi.pipe(Layer.provide(layerForwarder))),
        Layer.provide([NodeServices.layer, NodeHttpPlatform.layer, Etag.layerWeak]),
      ),
      RelayHttpApi.layerNotFoundRoute,
      RelayHttpApi.layerCors,
    ),
  ).pipe(Effect.provideService(HttpRouter.RouterConfig, RELAY_HTTP_ROUTER_CONFIG));
  // Use the Workers request path so pre-response handlers apply.
  const send = (request: Request) =>
    Effect.gen(function* () {
      const handler = yield* httpEffect;
      const sent = yield* Deferred.make<HttpServerResponse.HttpServerResponse>();
      yield* HttpEffect.toHandled(handler, (_request, response) =>
        Deferred.succeed(sent, response),
      ).pipe(
        Effect.provideService(
          HttpServerRequest.HttpServerRequest,
          HttpServerRequest.fromWeb(request),
        ),
      );
      return yield* Deferred.await(sent);
    });
  return { sent, rateLimitKeys, held, send, httpEffect };
}

const hookUrl = (path = "hook-1/secret-token", query = "") =>
  `https://relay.test/v1/hooks/${endpointKey}/${path}${query}`;

const readBody = (response: HttpServerResponse.HttpServerResponse) =>
  Effect.promise(() => HttpServerResponse.toWeb(response).arrayBuffer()).pipe(
    Effect.map((buffer) => new Uint8Array(buffer)),
  );
const readJson = (response: HttpServerResponse.HttpServerResponse) =>
  Effect.promise(() => HttpServerResponse.toWeb(response).json());

const requestBytes = (request: HttpClientRequest.HttpClientRequest) =>
  request.body._tag === "Uint8Array" ? request.body.body : new Uint8Array(0);

describe("HookForwarder", () => {
  it.effect("forwards the exact body bytes, query and filtered headers", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      const body = new Uint8Array([0, 255, 10, 13, 0x7b, 0x22, 0xc3, 0x28]);
      const response = yield* harness.send(
        new Request(hookUrl("hook-1/tok%2Fen", "?a=1&b=two%20words"), {
          method: "POST",
          headers: {
            "content-type": "application/octet-stream",
            authorization: "Bearer sender-secret",
            "x-hub-signature-256": "sha256=abc",
            cookie: "session=1",
            "cf-connecting-ip": "1.2.3.4",
            "x-forwarded-for": "1.2.3.4",
            "x-real-ip": "1.2.3.4",
            "proxy-authorization": "Basic x",
            connection: "keep-alive",
          },
          body,
        }),
      );
      expect(response.status).toBe(200);
      expect(harness.sent).toHaveLength(1);
      const sent = harness.sent[0]!;
      expect(sent.method).toBe("POST");
      expect(sent.url).toBe("https://env.example.test/api/hooks/hook-1/tok%2Fen?a=1&b=two%20words");
      expect(Array.from(requestBytes(sent))).toEqual(Array.from(body));
      expect(sent.headers.authorization).toBe("Bearer sender-secret");
      expect(sent.headers["x-hub-signature-256"]).toBe("sha256=abc");
      expect(sent.headers["content-type"]).toBe("application/octet-stream");
      for (const dropped of [
        "cookie",
        "cf-connecting-ip",
        "x-forwarded-for",
        "x-real-ip",
        "proxy-authorization",
        "connection",
        "host",
      ]) {
        expect(sent.headers[dropped]).toBeUndefined();
      }
      expect(sent.headers["content-length"]).toBe(String(body.length));
      expect(harness.rateLimitKeys).toHaveLength(1);
      expect(harness.rateLimitKeys[0]).toMatch(/^[0-9a-f]{64}$/);
    }),
  );

  it.effect("signs each forward for the environment, replacing any copy a sender sent", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      yield* harness.send(
        new Request(hookUrl("hook-1/tok"), {
          method: "POST",
          headers: { "x-t3-relay-delivery": "forged", "x-t3-relay-delivery-id": "forged" },
          body: "{}",
        }),
      );
      const sent = harness.sent[0]!;
      const payload = yield* verifyRelayJwt(RelayHookDeliveryProofPayload, {
        publicKey: mintKeys.publicKey,
        token: sent.headers["x-t3-relay-delivery"]!,
        typ: RELAY_HOOK_DELIVERY_TYP,
        issuer: settings.relayIssuer,
        audience: `t3-env:${environmentId}`,
      }).pipe(Effect.provide(EffectNodeCrypto.layerSignature));
      expect(payload).toMatchObject({
        environmentId,
        hookId: "hook-1",
        deliveryId: sent.headers["x-t3-relay-delivery-id"],
        receivedAt: sent.headers["x-t3-relay-received-at"],
      });
      expect(sent.headers["x-t3-relay-delivery-id"]).not.toBe("forged");
    }),
  );

  it.effect("passes upstream status, body and content-type through", () =>
    Effect.gen(function* () {
      const harness = makeHarness({
        execute: (request) =>
          Effect.succeed(
            HttpClientResponse.fromWeb(
              request,
              new Response('{"error":"bad_signature"}', {
                status: 401,
                headers: { "content-type": "application/json", "set-cookie": "x=1" },
              }),
            ),
          ),
      });
      const response = yield* harness.send(new Request(hookUrl(), { method: "GET" }));
      expect(response.status).toBe(401);
      expect(response.headers["content-type"]).toBe("application/json");
      expect(response.headers["set-cookie"]).toBeUndefined();
      expect(response.headers["access-control-allow-origin"]).toBeUndefined();
      expect(response.headers["x-content-type-options"]).toBe("nosniff");
      expect(response.headers["content-security-policy"]).toBe("sandbox; default-src 'none'");
      expect(new TextDecoder().decode(yield* readBody(response))).toBe('{"error":"bad_signature"}');
      expect(harness.sent[0]?.method).toBe("GET");
    }),
  );

  it.effect("rejects bodies over 1 MiB by content-length and while reading", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      const declared = yield* harness.send(
        new Request(hookUrl(), {
          method: "POST",
          headers: { "content-length": String(HookForwarder.RELAY_HOOK_MAX_BODY_BYTES + 1) },
          body: "x",
        }),
      );
      expect(declared.status).toBe(413);

      const oversized = new Uint8Array(HookForwarder.RELAY_HOOK_MAX_BODY_BYTES + 1);
      const stream = new ReadableStream<Uint8Array>({
        start(controller) {
          controller.enqueue(oversized.subarray(0, 600_000));
          controller.enqueue(oversized.subarray(600_000));
          controller.close();
        },
      });
      const streamed = yield* harness.send(
        new Request(hookUrl(), { method: "POST", body: stream, duplex: "half" } as RequestInit),
      );
      expect(streamed.status).toBe(413);
      expect(yield* readJson(streamed)).toEqual({ error: "payload_too_large" });
      expect(harness.sent).toHaveLength(0);
    }),
  );

  it.effect("returns 404 for unknown endpoints and unready endpoints", () =>
    Effect.gen(function* () {
      const unknown = makeHarness();
      for (const key of ["fedcba9876543210", environmentId]) {
        const response = yield* unknown.send(
          new Request(`https://relay.test/v1/hooks/${key}/hook-1/token`, { method: "POST" }),
        );
        expect(response.status).toBe(404);
        expect(yield* readJson(response)).toEqual({ error: "hook_not_found" });
      }
      expect(unknown.sent).toHaveLength(0);

      const unready = makeHarness({ allocation: { ...readyAllocation, readyAt: null } });
      const unreadyResponse = yield* unready.send(new Request(hookUrl(), { method: "POST" }));
      expect(unreadyResponse.status).toBe(404);
      expect(unready.sent).toHaveLength(0);
    }),
  );

  it.effect("forwards only to the link that owns the endpoint key", () =>
    Effect.gen(function* () {
      const intruder = {
        ...managedLink,
        userId: "user_attacker",
        environmentPublicKey: "attacker-key",
        endpoint: { ...managedLink.endpoint, httpBaseUrl: "https://attacker.example.test/" },
      };
      const harness = makeHarness({ links: [intruder, managedLink] });
      const response = yield* harness.send(new Request(hookUrl(), { method: "POST", body: "{}" }));
      expect(response.status).toBe(200);
      expect(harness.sent.map((request) => new URL(request.url).host)).toEqual([
        "env.example.test",
      ]);

      const orphaned = makeHarness({ links: [intruder] });
      const orphanedResponse = yield* orphaned.send(
        new Request(hookUrl(), { method: "POST", body: "{}" }),
      );
      expect(orphanedResponse.status).toBe(404);
      expect(orphaned.sent).toHaveLength(0);
    }),
  );

  it.effect("maps tunnel-offline and network failures to 503", () =>
    Effect.gen(function* () {
      const offline = makeHarness({
        execute: (request) =>
          Effect.succeed(HttpClientResponse.fromWeb(request, new Response("", { status: 530 }))),
      });
      const offlineResponse = yield* offline.send(new Request(hookUrl(), { method: "POST" }));
      expect(offlineResponse.status).toBe(503);
      expect(yield* readJson(offlineResponse)).toEqual({ error: "environment_unavailable" });

      const network = makeHarness({
        execute: (request) =>
          Effect.fail(
            new HttpClientError.HttpClientError({
              reason: new HttpClientError.TransportError({ request, cause: new Error("reset") }),
            }),
          ),
      });
      const networkResponse = yield* network.send(new Request(hookUrl(), { method: "POST" }));
      expect(networkResponse.status).toBe(503);
    }),
  );

  it.effect("does not relay an upstream response larger than the cap", () =>
    Effect.gen(function* () {
      const harness = makeHarness({
        execute: (request) =>
          Effect.succeed(
            HttpClientResponse.fromWeb(
              request,
              new Response(new Uint8Array(64 * 1024 + 1), { status: 200 }),
            ),
          ),
      });
      const response = yield* harness.send(new Request(hookUrl(), { method: "POST" }));
      expect(response.status).toBe(503);
      expect(yield* readJson(response)).toEqual({ error: "environment_unavailable" });
    }),
  );

  it.effect("drops headers the sender names in Connection", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      yield* harness.send(
        new Request(hookUrl(), {
          method: "POST",
          body: "{}",
          headers: { connection: "x-hop, keep-alive", "x-hop": "1", "x-keep": "2" },
        }),
      );
      const sent: Readonly<Record<string, string>> = harness.sent[0]?.headers ?? {};
      expect(sent["x-hop"]).toBeUndefined();
      expect(sent["x-keep"]).toBe("2");
    }),
  );

  it.effect("gives requests with a wrong token their own budget", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      yield* harness.send(
        new Request(hookUrl("hook-1/real-token"), { method: "POST", body: "{}" }),
      );
      yield* harness.send(new Request(hookUrl("hook-1/guessed"), { method: "POST", body: "{}" }));
      expect(new Set(harness.rateLimitKeys).size).toBe(2);
    }),
  );

  it.effect("gives two spellings of one token a single budget", () =>
    Effect.gen(function* () {
      const harness = makeHarness();
      yield* harness.send(new Request(hookUrl("hook-1/token"), { method: "POST", body: "{}" }));
      yield* harness.send(new Request(hookUrl("hook-1/%74oken"), { method: "POST", body: "{}" }));
      expect(new Set(harness.rateLimitKeys).size).toBe(1);
    }),
  );

  it.effect("returns 429 when the hook's budget is spent", () =>
    Effect.gen(function* () {
      const harness = makeHarness({ allow: () => false });
      const response = yield* harness.send(new Request(hookUrl(), { method: "POST" }));
      expect(response.status).toBe(429);
      expect(harness.sent).toHaveLength(0);
    }),
  );

  it.effect("never records the token in the server span", () =>
    Effect.gen(function* () {
      const spans: Array<Tracer.NativeSpan> = [];
      const tracer = Tracer.make({
        span: (options) => {
          const span = new Tracer.NativeSpan(options);
          spans.push(span);
          return span;
        },
      });
      const harness = makeHarness();
      const handler = yield* harness.httpEffect;
      const response = yield* traceRelayHttpRequestWith(
        handler,
        Layer.succeed(Tracer.Tracer, tracer),
      ).pipe(
        Effect.provideService(
          HttpServerRequest.HttpServerRequest,
          HttpServerRequest.fromWeb(
            new Request(hookUrl("hook-1/super-secret-token", "?sig=also-secret"), {
              method: "POST",
              headers: { "x-gitlab-token": "header-secret" },
              body: "{}",
            }),
          ),
        ),
      );
      expect(response.status).toBe(200);
      expect(harness.sent[0]?.url).toContain("super-secret-token");
      yield* Effect.yieldNow;
      const serialized = spans
        .flatMap((span) => [span.name, ...Array.from(span.attributes.values(), String)])
        .join("\n");
      expect(serialized).not.toContain("super-secret-token");
      expect(serialized).not.toContain("also-secret");
      expect(serialized).not.toContain("header-secret");
      const server = spans.find((span) => span.kind === "server");
      expect(server?.attributes.get("url.path")).toBe(`/v1/hooks/${endpointKey}/hook-1/redacted`);
    }),
  );

  describe("holding requests while the environment is offline", () => {
    const offline = (request: HttpClientRequest.HttpClientRequest) =>
      Effect.fail(
        new HttpClientError.HttpClientError({
          reason: new HttpClientError.TransportError({ request, cause: new Error("offline") }),
        }),
      );

    it.effect("holds when cloudflared answers that the local server is down", () =>
      Effect.gen(function* () {
        for (const status of [502, 503, 504, 530]) {
          const harness = makeHarness({
            links: [{ ...managedLink, holdWebhooksWhileOffline: true }],
            execute: (request) =>
              Effect.succeed(HttpClientResponse.fromWeb(request, new Response("", { status }))),
          });
          const response = yield* harness.send(
            new Request(hookUrl(), { method: "POST", body: "{}" }),
          );
          expect(response.status).toBe(202);
          expect(harness.held).toHaveLength(1);
        }
      }),
    );

    it.effect("stays a plain proxy when the environment has not opted in", () =>
      Effect.gen(function* () {
        const harness = makeHarness({ execute: offline });
        const response = yield* harness.send(
          new Request(hookUrl(), { method: "POST", body: "{}" }),
        );
        expect(response.status).toBe(503);
        expect(harness.held).toHaveLength(0);
      }),
    );

    it.effect("holds the exact request and answers 202 once opted in", () =>
      Effect.gen(function* () {
        const harness = makeHarness({
          execute: offline,
          links: [{ ...managedLink, holdWebhooksWhileOffline: true }],
        });
        const body = new Uint8Array([0, 255, 10]);
        const response = yield* harness.send(
          new Request(hookUrl("%68ook-1/tok%2Fen", "?a=1"), {
            method: "POST",
            body,
            headers: { "x-t3-relay-delivery-id": "forged", "x-sig": "s" },
          }),
        );
        expect(response.status).toBe(202);
        const [hook] = harness.held;
        expect(hook?.baseUrl).toBe("https://env.example.test/");
        expect(hook?.rawToken).toBe("tok%2Fen");
        expect(hook?.query).toBe("a=1");
        expect([...(hook?.body ?? [])]).toEqual([0, 255, 10]);
        expect(hook?.headers["x-sig"]).toBe("s");
        expect(hook?.hookKey).toBe("hook-1");
        expect(hook?.headers["x-t3-relay-delivery-id"]).toBeUndefined();
        expect(hook?.id).not.toBe("forged");
      }),
    );

    it.effect("answers 503 inbox_full when the environment's inbox is full", () =>
      Effect.gen(function* () {
        const harness = makeHarness({
          execute: offline,
          links: [{ ...managedLink, holdWebhooksWhileOffline: true }],
          inboxCapacity: 0,
        });
        const response = yield* harness.send(
          new Request(hookUrl(), { method: "POST", body: "{}" }),
        );
        expect(response.status).toBe(503);
        expect(yield* readJson(response)).toEqual({ error: "inbox_full" });
      }),
    );
  });
});