feat(rpc): transport, server, client, http, mounting, docs (Tasks 5-11)

Brings the uncommitted body of work under version control so it cannot be
lost. Gates are green: 152 tests pass across rpc/router/dev-server,
typecheck, lint, format and check:public-api all clean.

NOT YET REVIEWED. None of Tasks 5-11 has had an independent task review, and
Task 4's second fix round was never re-reviewed either.

Known gaps against the plan, recorded here rather than discovered later:
- packages/rpc/test/{transport,server,client}.test.ts are ABSENT. The plan
  required a test file for each. server.ts holds the fail-closed identity and
  permission checks and currently has no direct coverage at all.
- rpc-endpoint.test.ts has 3 tests where the plan specified 9. Missing:
  unknown service, non-POST, malformed body, non-rpc passthrough, and the
  isInternalCaller sweep. This is the task where a reachable
  /__wrnexus/rpc/* makes every permission check in the workspace bypassable.
- http.test.ts has 3 of 7; integration.test.ts 2 of 3;
  services-discovery.test.ts 1 of 4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/dev-server/package.json

@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@wrnexus/authz": "workspace:*",
+    "@wrnexus/rpc": "workspace:*",
     "@wrnexus/core": "workspace:*",
     "@wrnexus/dev-toolbar": "workspace:*",
     "@wrnexus/router": "workspace:*",

packages/dev-server/src/gateway.ts

@@ -15,6 +15,9 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { RESTART_EXIT_CODE } from "./restart.ts";
 
+const RPC_PATH_PREFIX = "/__wrnexus/rpc";
+const RPC_INTERNAL_HEADER = "x-wrnexus-internal";
+
 export type GatewayForwardAuth = (
   | {
       url: string;
@@ -432,6 +435,13 @@ export function gatewayProxyHeaders(
   return headers;
 }
 
+/** Remove headers that only a direct workspace-to-app request may supply. */
+export function stripUntrustedInternalHeaders(headers: Headers): Headers {
+  const sanitized = new Headers(headers);
+  sanitized.delete(RPC_INTERNAL_HEADER);
+  return sanitized;
+}
+
 /** Boot every app as a child process, then route by Host on one gateway port. */
 export async function startGateway(opts: GatewayOptions): Promise<RunningGateway> {
   const port = opts.port ?? 3000;
@@ -615,6 +625,10 @@ export async function startGateway(opts: GatewayOptions): Promise<RunningGateway
           });
         }
 
+        if (url.pathname === RPC_PATH_PREFIX || url.pathname.startsWith(`${RPC_PATH_PREFIX}/`)) {
+          return new Response("Not found", { status: 404 });
+        }
+
         // Edge rate limit (global, by client IP).
         if (rateLimit && !rateLimit(ip, now())) {
           return new Response("Too Many Requests", {
@@ -665,7 +679,9 @@ export async function startGateway(opts: GatewayOptions): Promise<RunningGateway
         }
 
         // HTTP → reverse-proxy to the app, preserving method/headers/body.
-        const headers = gatewayProxyHeaders(req, url, ip, forwardedHeaders);
+        const headers = stripUntrustedInternalHeaders(
+          gatewayProxyHeaders(req, url, ip, forwardedHeaders),
+        );
         const body =
           req.method === "GET" || req.method === "HEAD" ? undefined : await req.arrayBuffer();
         let res: Response;

packages/dev-server/src/prod.ts

@@ -288,6 +288,7 @@ function buildProdRouter(manifest: ProdManifest): {
     stores: [],
     schemas: [], // descriptors are pre-baked into schemasJs; not needed at runtime
     authz: [], // authz declarations are not needed at runtime in production
+    services: [], // RPC service modules are not yet emitted in production manifests
     matchPage: optimizedMatcher(pages),
     matchApi: optimizedMatcher(api),
     matchRealtime: optimizedMatcher(realtime),

packages/dev-server/src/rpc-dispatch.ts

@@ -0,0 +1,44 @@
+import { RPC_IDENTITY_HEADER, RPC_PATH_PREFIX, type ServiceImplementation } from "@wrnexus/rpc";
+
+export const RPC_INTERNAL_HEADER = "x-wrnexus-internal";
+const EDGE_HEADERS = ["x-forwarded-for", "x-forwarded-host", "x-forwarded-proto", "forwarded"];
+
+export function isRpcPath(pathname: string): boolean {
+  return pathname === RPC_PATH_PREFIX || pathname.startsWith(`${RPC_PATH_PREFIX}/`);
+}
+
+export function isInternalCaller(req: Request): boolean {
+  return (
+    req.headers.get(RPC_INTERNAL_HEADER) === "1" &&
+    !EDGE_HEADERS.some((name) => req.headers.has(name))
+  );
+}
+
+function json(body: unknown, status = 200): Response {
+  return Response.json(body, { status, headers: { "cache-control": "private, no-store" } });
+}
+
+export async function handleRpcRequest(
+  req: Request,
+  url: URL,
+  services: Map<string, ServiceImplementation>,
+): Promise<Response | null> {
+  if (!isRpcPath(url.pathname)) return null;
+  if (!isInternalCaller(req)) return new Response("Not found", { status: 404 });
+  if (req.method !== "POST") return new Response("Method not allowed", { status: 405 });
+  const segments = url.pathname.split("/");
+  const service = segments[3] ? services.get(segments[3]) : undefined;
+  const procedure = segments[4];
+  if (!service || !procedure || segments.length !== 5) {
+    return json({ ok: false, code: "RPC_UNKNOWN", message: "Unknown procedure", retryable: false });
+  }
+  let payload: unknown;
+  try {
+    payload = await req.json();
+  } catch {
+    return json({ ok: false, code: "RPC_INVALID", message: "Invalid input", retryable: false });
+  }
+  return json(
+    await service.invoke(procedure, payload, req.headers.get(RPC_IDENTITY_HEADER) ?? undefined),
+  );
+}

packages/dev-server/src/runtime.ts

@@ -89,6 +89,8 @@ import {
   type ResolvedI18n,
 } from "@wrnexus/i18n";
 import { runMiddleware } from "./pipeline.ts";
+import { handleRpcRequest } from "./rpc-dispatch.ts";
+import type { ServiceImplementation } from "@wrnexus/rpc";
 import type { HmrHub } from "./hmr.ts";
 import type {
   DevToolbarConfig,
@@ -882,6 +884,20 @@ export function createHandlers(deps: RuntimeDeps): Handlers {
     ...(await getMiddleware()),
   ];
   const maxBodyBytes = deps.maxBodyBytes ?? 10 * 1024 * 1024; // 10 MB default
+  let servicesPromise: Promise<Map<string, ServiceImplementation>> | undefined;
+  const loadServices = () =>
+    (servicesPromise ??= (async () => {
+      const services = new Map<string, ServiceImplementation>();
+      for (const entry of router.services) {
+        const imported = await loadModule(entry.file);
+        const implementation = imported.default as ServiceImplementation | undefined;
+        if (!implementation || typeof implementation.invoke !== "function") {
+          throw new Error(`RPC service ${entry.file} must default-export implement(...)`);
+        }
+        services.set(entry.name, implementation);
+      }
+      return services;
+    })());
 
   // Server-side realtime room manager (shared by every `defineRoom` connection).
   const realtime = createRealtimeRegistry();
@@ -948,6 +964,9 @@ export function createHandlers(deps: RuntimeDeps): Handlers {
     const secure = (res: Response): Response =>
       withSecurityHeaders(req, res, mode, runtimeSecurity, nonce);
 
+    const rpcResponse = await handleRpcRequest(req, url, await loadServices());
+    if (rpcResponse) return secure(rpcResponse);
+
     const preflight = createCorsPreflightResponse(req, deps.security);
     if (preflight) return secure(preflight);
 

packages/dev-server/test/gateway.test.ts

@@ -4,6 +4,7 @@ import {
   forwardAuthFailure,
   forwardAuthHeaders,
   gatewayProxyHeaders,
+  stripUntrustedInternalHeaders,
   gatewayRestartDelay,
   internalError,
   stripInternalError,
@@ -34,6 +35,16 @@ test("gateway disables compression for its internal proxy hop", () => {
   expect(headers.get("x-forwarded-for")).toBe("127.0.0.1");
 });
 
+test("gateway proxy headers do not preserve the RPC internal marker", () => {
+  const request = new Request("http://localhost:3000/path", {
+    headers: { "x-wrnexus-internal": "1" },
+  });
+  const headers = stripUntrustedInternalHeaders(
+    gatewayProxyHeaders(request, new URL(request.url), "127.0.0.1", true),
+  );
+  expect(headers.has("x-wrnexus-internal")).toBe(false);
+});
+
 test("forward auth preserves intentional verifier redirects", () => {
   const redirected = forwardAuthFailure(
     new Response(null, { status: 302, headers: { location: "/login?returnTo=%2Fadmin" } }),

packages/dev-server/test/observability-runtime.test.ts

@@ -14,6 +14,7 @@ function runtime(health: HealthRegistry, trustProxy = false) {
     stores: [],
     schemas: [],
     authz: [],
+    services: [],
     matchPage: () => null,
     matchApi: () => null,
     matchRealtime: () => null,

packages/dev-server/test/rpc-endpoint.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+import { defineService, implement, procedure } from "@wrnexus/rpc";
+import { v } from "@wrnexus/validation";
+import { handleRpcRequest, isInternalCaller, isRpcPath } from "../src/rpc-dispatch.ts";
+
+const demo = defineService({
+  name: "demo",
+  procedures: {
+    add: procedure
+      .input(v.object({ a: v.number() }))
+      .output<{ a: number }>()
+      .build(),
+  },
+});
+const services = new Map([
+  ["demo", implement(demo, { add: async ({ a }) => ({ a }) }, { selfApp: "demo-app" })],
+]);
+
+function request(path: string, headers: Record<string, string> = {}) {
+  return new Request(`http://demo.test${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify({ a: 2 }),
+  });
+}
+
+describe("RPC endpoint", () => {
+  test("only matches its reserved prefix", () => {
+    expect(isRpcPath("/__wrnexus/rpc/demo/add")).toBe(true);
+    expect(isRpcPath("/__wrnexus/rpcx/demo/add")).toBe(false);
+  });
+
+  test("dispatches a private request", async () => {
+    const req = request("/__wrnexus/rpc/demo/add", { "x-wrnexus-internal": "1" });
+    expect(await (await handleRpcRequest(req, new URL(req.url), services))!.json()).toEqual({
+      ok: true,
+      value: { a: 2 },
+    });
+  });
+
+  test("rejects public or forwarded requests", async () => {
+    const external = request("/__wrnexus/rpc/demo/add");
+    expect((await handleRpcRequest(external, new URL(external.url), services))!.status).toBe(404);
+    const forwarded = request("/__wrnexus/rpc/demo/add", {
+      "x-wrnexus-internal": "1",
+      "x-forwarded-for": "203.0.113.1",
+    });
+    expect(isInternalCaller(forwarded)).toBe(false);
+    expect((await handleRpcRequest(forwarded, new URL(forwarded.url), services))!.status).toBe(404);
+  });
+});

packages/router/src/index.ts

@@ -61,6 +61,8 @@ export interface Router {
   schemas: ComponentRef[];
   /** Authorization declarations (`app/authz/<name>.ts`) merged into the catalog. */
   authz: ComponentRef[];
+  /** Service implementations (`app/services/<name>.ts`) mounted for inter-app calls. */
+  services: ComponentRef[];
   matchPage(pathname: string): RouteMatch | null;
   matchApi(pathname: string): RouteMatch | null;
   matchRealtime(pathname: string): RouteMatch | null;
@@ -302,6 +304,17 @@ export function buildRouter(appDir: string, opts: RouterOptions = {}): Router {
     authz.push({ name, file: f.file });
   }
 
+  const services: ComponentRef[] = [];
+  for (const f of scanDir(join(appDir, "services"), [".js"])) {
+    if (!/\.(ts|js)$/.test(f.file) || /[.]gen[.](ts|js)$/.test(f.file)) continue;
+    const name = basename(f.file).replace(/\.(ts|js)$/, "");
+    if (!isSafeIslandName(name)) {
+      console.warn(`[wrnexus] skipping service with unsafe name: ${name}`);
+      continue;
+    }
+    services.push({ name, file: f.file });
+  }
+
   return {
     pages,
     api,
@@ -312,6 +325,7 @@ export function buildRouter(appDir: string, opts: RouterOptions = {}): Router {
     stores,
     schemas,
     authz,
+    services,
     matchPage: (p) => matchRoute(pages, p),
     matchApi: (p) => matchRoute(api, p),
     matchRealtime: (p) => matchRoute(realtime, p),

packages/router/test/services-discovery.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildRouter } from "../src/index.ts";
+
+const root = join(import.meta.dir, ".tmp-services");
+mkdirSync(root, { recursive: true });
+
+describe("service discovery", () => {
+  test("discovers source services and skips generated files", () => {
+    const base = mkdtempSync(join(root, "app-"));
+    const services = join(base, "app", "services");
+    mkdirSync(services, { recursive: true });
+    mkdirSync(join(base, "app", "pages"), { recursive: true });
+    writeFileSync(join(services, "billing.ts"), "export default {};");
+    writeFileSync(join(services, "types.gen.ts"), "export type T = string;");
+    expect(buildRouter(join(base, "app")).services.map((service) => service.name)).toEqual([
+      "billing",
+    ]);
+  });
+});

packages/rpc/README.md

@@ -0,0 +1,44 @@
+# `@wrnexus/rpc`
+
+Define a service contract in a shared workspace package, then import that same contract from the caller and callee.
+
+```ts
+import {
+  defineService,
+  implement,
+  inProcessTransport,
+  procedure,
+  serviceClient,
+} from "@wrnexus/rpc";
+import { v } from "@wrnexus/validation";
+
+const greeter = defineService({
+  name: "greeter",
+  procedures: {
+    greet: procedure
+      .input(v.object({ name: v.string() }))
+      .output<{ message: string }>()
+      .build(),
+  },
+});
+
+const service = implement(
+  greeter,
+  { greet: async ({ name }) => ({ message: `Hello, ${name}` }) },
+  { selfApp: "greeter" },
+);
+
+const client = serviceClient(greeter, {
+  app: "greeter",
+  transport: inProcessTransport({
+    "greeter/greet": (input, identity) => service.invoke("greet", input, identity),
+  }),
+});
+await client.greet({ name: "Ada" });
+```
+
+Service files default-export `implement(...)` from `app/services`. The development server mounts them under the private `/__wrnexus/rpc` prefix.
+
+Pass `{ as: ctx }` to `serviceClient` to propagate the subject. The signed token contains only subject and tenant identifiers; permissions are always checked by the callee. Set `WRNEXUS_RPC_SECRET` in every app, use at least 32 characters, and never reuse the session secret.
+
+Calls time out by default. Retrying is intentionally deferred; when introduced, only procedures marked `.idempotent()` may be retried.

packages/rpc/package.json

@@ -22,6 +22,7 @@
     "@wrnexus/authz": "workspace:*",
     "@wrnexus/core": "workspace:*",
     "@wrnexus/jwt": "workspace:*",
+    "@wrnexus/helpers": "workspace:*",
     "@wrnexus/validation": "workspace:*"
   },
   "devDependencies": {

packages/rpc/src/client.ts

@@ -0,0 +1,57 @@
+import type { Context } from "@wrnexus/core";
+import { RPC_ERROR_CODES, ServiceError } from "./errors.ts";
+import { exportSubjectContext } from "./identity.ts";
+import type { Transport } from "./transport.ts";
+import type {
+  AnyProcedures,
+  InferProcedureInput,
+  InferProcedureOutput,
+  ServiceContract,
+} from "./types.ts";
+
+export interface ServiceClientOptions {
+  app?: string;
+  transport: Transport;
+  as?: Context;
+  timeoutMs?: number;
+}
+
+export type ServiceClient<Procedures extends AnyProcedures> = {
+  [K in keyof Procedures]: (
+    input: InferProcedureInput<Procedures[K]>,
+  ) => Promise<InferProcedureOutput<Procedures[K]>>;
+};
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export function serviceClient<Procedures extends AnyProcedures>(
+  contract: ServiceContract<Procedures>,
+  options: ServiceClientOptions,
+): ServiceClient<Procedures> {
+  const app = options.app ?? contract.name;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Proxy({} as ServiceClient<Procedures>, {
+    get(_target, property) {
+      if (typeof property !== "string") return undefined;
+      return async (input: unknown) => {
+        if (!Object.hasOwn(contract.procedures, property)) {
+          throw new ServiceError(RPC_ERROR_CODES.unknown, "Unknown procedure");
+        }
+        const identity = options.as ? await exportSubjectContext(options.as, app) : undefined;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+          const result = await options.transport.call(
+            { app, service: contract.name, procedure: property },
+            input,
+            { signal: controller.signal, ...(identity ? { identity } : {}) },
+          );
+          if (result.ok) return result.value;
+          throw new ServiceError(result.code, result.message);
+        } finally {
+          clearTimeout(timer);
+        }
+      };
+    },
+  });
+}

packages/rpc/src/http.ts

@@ -0,0 +1,73 @@
+import { appOrigin } from "@wrnexus/helpers";
+import { RPC_ERROR_CODES, failure, isRetryableStatus } from "./errors.ts";
+import { RPC_IDENTITY_HEADER } from "./identity.ts";
+import type { CallOptions, RpcTarget, Transport } from "./transport.ts";
+import type { ServiceResult } from "./types.ts";
+
+export const RPC_PATH_PREFIX = "/__wrnexus/rpc";
+export const RPC_INTERNAL_HEADER = "x-wrnexus-internal";
+
+export function rpcPath(service: string, procedure: string): string {
+  return `${RPC_PATH_PREFIX}/${service}/${procedure}`;
+}
+
+export interface HttpTransportOptions {
+  resolveOrigin?: (app: string) => string;
+  fetch?: typeof fetch;
+}
+
+function isServiceResult(value: unknown): value is ServiceResult {
+  if (!value || typeof value !== "object" || !("ok" in value)) return false;
+  const result = value as Record<string, unknown>;
+  return (
+    result.ok === true ||
+    (result.ok === false &&
+      typeof result.code === "string" &&
+      typeof result.message === "string" &&
+      typeof result.retryable === "boolean")
+  );
+}
+
+export function httpTransport(options: HttpTransportOptions = {}): Transport {
+  const resolveOrigin = options.resolveOrigin ?? appOrigin;
+  const doFetch = options.fetch ?? fetch;
+  return {
+    async call(target: RpcTarget, payload: unknown, callOptions: CallOptions) {
+      let response: Response;
+      try {
+        const headers: Record<string, string> = {
+          "content-type": "application/json",
+          [RPC_INTERNAL_HEADER]: "1",
+        };
+        if (callOptions.identity) headers[RPC_IDENTITY_HEADER] = callOptions.identity;
+        response = await doFetch(
+          `${resolveOrigin(target.app)}${rpcPath(target.service, target.procedure)}`,
+          {
+            method: "POST",
+            headers,
+            body: JSON.stringify(payload ?? {}),
+            signal: callOptions.signal,
+          },
+        );
+      } catch {
+        return failure(RPC_ERROR_CODES.transport, "Service unreachable");
+      }
+      if (!response.ok) {
+        return {
+          ok: false,
+          code: RPC_ERROR_CODES.transport,
+          message: `Service returned ${response.status}`,
+          retryable: isRetryableStatus(response.status),
+        };
+      }
+      try {
+        const result: unknown = await response.json();
+        return isServiceResult(result)
+          ? result
+          : failure(RPC_ERROR_CODES.malformed, "Malformed service response");
+      } catch {
+        return failure(RPC_ERROR_CODES.malformed, "Malformed service response");
+      }
+    },
+  };
+}

packages/rpc/src/index.ts

@@ -30,3 +30,17 @@ export {
   rpcSecret,
 } from "./identity.ts";
 export type { ExportOptions, ImportOptions, SubjectContext } from "./identity.ts";
+
+export { inProcessTransport } from "./transport.ts";
+export type { CallOptions, InProcessHandler, RpcTarget, Transport } from "./transport.ts";
+export { implement } from "./server.ts";
+export type {
+  HandlerContext,
+  ImplementOptions,
+  ServiceHandlers,
+  ServiceImplementation,
+} from "./server.ts";
+export { serviceClient } from "./client.ts";
+export type { ServiceClient, ServiceClientOptions } from "./client.ts";
+export { RPC_INTERNAL_HEADER, RPC_PATH_PREFIX, httpTransport, rpcPath } from "./http.ts";
+export type { HttpTransportOptions } from "./http.ts";

packages/rpc/src/server.ts

@@ -0,0 +1,81 @@
+import { RPC_ERROR_CODES, failure, success } from "./errors.ts";
+import { importSubjectContext, type SubjectContext } from "./identity.ts";
+import type {
+  AnyProcedures,
+  InferProcedureInput,
+  InferProcedureOutput,
+  ServiceContract,
+  ServiceResult,
+} from "./types.ts";
+
+export interface HandlerContext {
+  subject?: SubjectContext;
+}
+
+export type ServiceHandlers<Procedures extends AnyProcedures> = {
+  [K in keyof Procedures]: (
+    input: InferProcedureInput<Procedures[K]>,
+    ctx: HandlerContext,
+  ) => Promise<InferProcedureOutput<Procedures[K]>> | InferProcedureOutput<Procedures[K]>;
+};
+
+export interface ImplementOptions {
+  selfApp: string;
+  checkPermission?: (permission: string, subject?: SubjectContext) => Promise<boolean> | boolean;
+}
+
+export interface ServiceImplementation<Procedures extends AnyProcedures = AnyProcedures> {
+  contract: ServiceContract<Procedures>;
+  invoke(procedure: string, payload: unknown, identity?: string): Promise<ServiceResult>;
+}
+
+export function implement<Procedures extends AnyProcedures>(
+  contract: ServiceContract<Procedures>,
+  handlers: ServiceHandlers<Procedures>,
+  options: ImplementOptions,
+): ServiceImplementation<Procedures> {
+  return {
+    contract,
+    async invoke(procedureName, payload, identity) {
+      const definition = contract.procedures[procedureName as keyof Procedures];
+      const handler = handlers[procedureName as keyof Procedures];
+      if (!definition || !handler) return failure(RPC_ERROR_CODES.unknown, "Unknown procedure");
+
+      let subject: SubjectContext | undefined;
+      if (identity !== undefined) {
+        try {
+          subject = await importSubjectContext(identity, options.selfApp);
+        } catch {
+          return failure(RPC_ERROR_CODES.identity, "Invalid identity");
+        }
+      }
+
+      if (definition.permission) {
+        if (!options.checkPermission) return failure(RPC_ERROR_CODES.denied, "Forbidden");
+        try {
+          if (!(await options.checkPermission(definition.permission, subject))) {
+            return failure(RPC_ERROR_CODES.denied, "Forbidden");
+          }
+        } catch {
+          return failure(RPC_ERROR_CODES.denied, "Forbidden");
+        }
+      }
+
+      let input: unknown = payload;
+      if (definition.input) {
+        const parsed = definition.input.parse(payload as Record<string, unknown>);
+        if (!parsed.ok) return failure(RPC_ERROR_CODES.invalid, "Invalid input");
+        input = parsed.value;
+      }
+
+      try {
+        const value = await (handler as (value: unknown, ctx: HandlerContext) => unknown)(input, {
+          subject,
+        });
+        return success(value);
+      } catch {
+        return failure(RPC_ERROR_CODES.handler, "Internal error");
+      }
+    },
+  };
+}

packages/rpc/src/transport.ts

@@ -0,0 +1,38 @@
+import { RPC_ERROR_CODES, failure } from "./errors.ts";
+import type { ServiceResult } from "./types.ts";
+
+export interface RpcTarget {
+  app: string;
+  service: string;
+  procedure: string;
+}
+
+export interface CallOptions {
+  signal?: AbortSignal;
+  identity?: string;
+}
+
+export interface Transport {
+  call(target: RpcTarget, payload: unknown, options: CallOptions): Promise<ServiceResult>;
+}
+
+export type InProcessHandler = (
+  payload: unknown,
+  identity?: string,
+) => Promise<ServiceResult> | ServiceResult;
+
+/** Direct transport for tests and local integration harnesses. */
+export function inProcessTransport(handlers: Record<string, InProcessHandler>): Transport {
+  return {
+    async call(target, payload, options) {
+      if (options.signal?.aborted) return failure(RPC_ERROR_CODES.transport, "Call aborted");
+      const handler = handlers[`${target.service}/${target.procedure}`];
+      if (!handler) return failure(RPC_ERROR_CODES.unknown, "Unknown procedure");
+      try {
+        return await handler(payload, options.identity);
+      } catch {
+        return failure(RPC_ERROR_CODES.handler, "Internal error");
+      }
+    },
+  };
+}

packages/rpc/test/http.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { RPC_ERROR_CODES } from "../src/errors.ts";
+import { RPC_IDENTITY_HEADER } from "../src/identity.ts";
+import { httpTransport, rpcPath } from "../src/http.ts";
+
+const target = { app: "billing", service: "billing", procedure: "createInvoice" };
+
+function transportWith(handler: (request: Request) => Response | Promise<Response>) {
+  return httpTransport({
+    resolveOrigin: () => "http://billing.test",
+    fetch: (async (input: RequestInfo | URL, init?: RequestInit) =>
+      handler(new Request(input, init))) as typeof fetch,
+  });
+}
+
+describe("httpTransport", () => {
+  test("posts to the private endpoint with identity", async () => {
+    const transport = transportWith(async (request) => {
+      expect(request.url).toBe("http://billing.test/__wrnexus/rpc/billing/createInvoice");
+      expect(request.headers.get(RPC_IDENTITY_HEADER)).toBe("token");
+      expect(request.headers.get("x-wrnexus-internal")).toBe("1");
+      expect(await request.json()).toEqual({ amountCents: 5 });
+      return Response.json({ ok: true, value: { invoiceId: "inv_1" } });
+    });
+    expect(await transport.call(target, { amountCents: 5 }, { identity: "token" })).toEqual({
+      ok: true,
+      value: { invoiceId: "inv_1" },
+    });
+  });
+
+  test("classifies unavailable and malformed responses safely", async () => {
+    const unavailable = transportWith(() => new Response("busy", { status: 503 }));
+    const failed = await unavailable.call(target, {}, {});
+    expect(failed).toMatchObject({ code: RPC_ERROR_CODES.transport, retryable: true });
+    const malformed = transportWith(() => Response.json({ hello: "world" }));
+    expect(await malformed.call(target, {}, {})).toMatchObject({
+      code: RPC_ERROR_CODES.malformed,
+      retryable: false,
+    });
+  });
+
+  test("uses the stable reserved path", () => {
+    expect(rpcPath("billing", "createInvoice")).toBe("/__wrnexus/rpc/billing/createInvoice");
+  });
+});

packages/rpc/test/integration.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { Context } from "@wrnexus/core";
+import { v } from "@wrnexus/validation";
+import { serviceClient } from "../src/client.ts";
+import { defineService, procedure } from "../src/contract.ts";
+import { RPC_ERROR_CODES } from "../src/errors.ts";
+import { implement } from "../src/server.ts";
+import { inProcessTransport } from "../src/transport.ts";
+
+const originalRpcSecret = process.env.WRNEXUS_RPC_SECRET;
+const originalAppName = process.env.WRNEXUS_APP_NAME;
+afterEach(() => {
+  if (originalRpcSecret === undefined) delete process.env.WRNEXUS_RPC_SECRET;
+  else process.env.WRNEXUS_RPC_SECRET = originalRpcSecret;
+  if (originalAppName === undefined) delete process.env.WRNEXUS_APP_NAME;
+  else process.env.WRNEXUS_APP_NAME = originalAppName;
+});
+
+const billing = defineService({
+  name: "billing",
+  procedures: {
+    createInvoice: procedure
+      .input(v.object({ amountCents: v.number() }))
+      .output<{ invoiceId: string; forSubject: string }>()
+      .permission("invoice:create")
+      .build(),
+  },
+});
+
+function wire(allowed: boolean) {
+  const service = implement(
+    billing,
+    {
+      createInvoice: async ({ amountCents }, ctx) => ({
+        invoiceId: `inv_${amountCents}`,
+        forSubject: ctx.subject?.subjectId ?? "anon",
+      }),
+    },
+    { selfApp: "billing", checkPermission: async () => allowed },
+  );
+  return inProcessTransport({
+    "billing/createInvoice": (payload, identity) =>
+      service.invoke("createInvoice", payload, identity),
+  });
+}
+
+describe("RPC integration", () => {
+  test("propagates identity and validates the callee permission", async () => {
+    process.env.WRNEXUS_RPC_SECRET = "test-rpc-secret-at-least-32-chars-long";
+    process.env.WRNEXUS_APP_NAME = "web";
+    const client = serviceClient(billing, {
+      app: "billing",
+      as: { user: { id: "u1" }, tenant: { id: "acme" }, locals: {} } as unknown as Context,
+      transport: wire(true),
+    });
+    expect(await client.createInvoice({ amountCents: 250 })).toEqual({
+      invoiceId: "inv_250",
+      forSubject: "u1",
+    });
+  });
+
+  test("denies when the callee permission check refuses", async () => {
+    process.env.WRNEXUS_RPC_SECRET = "test-rpc-secret-at-least-32-chars-long";
+    process.env.WRNEXUS_APP_NAME = "web";
+    const client = serviceClient(billing, {
+      app: "billing",
+      as: { user: { id: "u1" }, locals: {} } as unknown as Context,
+      transport: wire(false),
+    });
+    await expect(client.createInvoice({ amountCents: 1 })).rejects.toMatchObject({
+      code: RPC_ERROR_CODES.denied,
+    });
+  });
+});