@robota-sdk/agent-transport-http 3.0.0-beta.78 → 3.0.0-beta.81

package/src/__tests__/admission-loopback-scenario.test.ts

@@ -0,0 +1,198 @@
+/**
+ * SEC-008 — the user-execution scenario, as CODE.
+ *
+ * The closure of SEC-008 first carried this evidence as prose: a report that a run had happened
+ * once, with the runner not checked in. Review named the irony — SEC-008 is precisely about "the
+ * trust boundary being documentation rather than code", and the evidence for closing it was
+ * documentation rather than code. So the scenario lives here, where anyone can re-run it.
+ *
+ * What makes this different from the sibling route suites, which already cover the same code paths:
+ * it is a REAL HTTP round-trip over a REAL loopback socket, not an in-process `app.fetch()`. The
+ * thing being demonstrated is what an unauthenticated remote request DOES to a served transport, so
+ * the request has to actually travel.
+ *
+ * The observable is the session TRANSCRIPT — what reached `submit` — because "rejected" and "never
+ * executed" are different claims and only the second one is the security property.
+ */
+
+import { createServer, type Server } from 'node:http';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createHttpTransport } from '../http-transport.js';
+
+import type { IInteractiveSession, ITurnHandle } from '@robota-sdk/agent-interface-session';
+
+/**
+ * A CONFORMANT turn handle. Not `{ status: 'started' }` behind a cast: `ITurnHandle` is
+ * `{ turnId, completed }`, and a double that answers a different shape is a partial
+ * re-implementation the compiler was told to stop checking. The route only awaits the terminal
+ * event today, so the difference is invisible — until a call site reads `.completed`, at which
+ * point the double would misrepresent the contract silently. (#1684 review)
+ */
+function stubHandle(turnId: string): ITurnHandle {
+  return {
+    turnId,
+    completed: Promise.resolve({
+      response: '',
+      history: [],
+      toolSummaries: [],
+      contextState: { usedTokens: 0, maxTokens: 0, usedPercentage: 0, remainingPercentage: 100 },
+    }),
+  };
+}
+
+/** A session that RECORDS what actually reached it — the transcript the scenario asserts on. */
+function createRecordingSession(): { session: IInteractiveSession; transcript: string[] } {
+  const transcript: string[] = [];
+  const listeners = new Map<string, Set<(data: unknown) => void>>();
+  const emit = (event: string, data: unknown): void => {
+    for (const handler of listeners.get(event) ?? []) handler(data);
+  };
+  const session = createTestInteractiveSession({
+    isExecuting: () => false,
+    submit: (async (prompt: string) => {
+      transcript.push(prompt);
+      // The route's SSE stream ends on the terminal event; a session that never emits one leaves
+      // the request hanging, so the case would fail on a timeout — a red for the wrong reason.
+      queueMicrotask(() => emit('complete', { success: true, content: 'done' }));
+      return stubHandle('scenario-turn');
+    }) as IInteractiveSession['submit'],
+    on: ((event: string, handler: (data: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)?.add(handler);
+    }) as IInteractiveSession['on'],
+    off: ((event: string, handler: (data: unknown) => void) => {
+      listeners.get(event)?.delete(handler);
+    }) as IInteractiveSession['off'],
+  });
+  return { session, transcript };
+}
+
+const servers: Server[] = [];
+afterEach(async () => {
+  while (servers.length > 0) {
+    const server = servers.pop();
+    await new Promise<void>((resolve) => server?.close(() => resolve()));
+  }
+});
+
+/**
+ * Serve a transport's app on a real loopback port and return its base URL.
+ *
+ * `fetch` is typed as `Response | Promise<Response>` on Hono — it answers synchronously for some
+ * routes — so the parameter accepts both and the call site awaits, rather than narrowing the app to
+ * a shape it does not have.
+ */
+async function serve(app: {
+  fetch: (request: Request) => Response | Promise<Response>;
+}): Promise<string> {
+  const server = createServer((req, res) => {
+    void (async () => {
+      // Everything inside is guarded: an unhandled rejection here would leave `res.end()` uncalled,
+      // so the client-side `fetch` below would hang to the test timeout instead of failing with a
+      // cause. In a file whose whole subject is a gate that refuses LEGIBLY, an illegible hang is
+      // the wrong failure mode to build the harness on. (#1684 review)
+      try {
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) chunks.push(chunk as Buffer);
+        const address = server.address();
+        const port = typeof address === 'object' && address ? address.port : 0;
+        // Node's `IncomingHttpHeaders` values are `string | string[] | undefined`, which is not
+        // `HeadersInit` — casting across that gap works for this fixture's simple headers and
+        // silently mangles an array-valued one (`set-cookie`, a repeated header) the day the
+        // harness is reused. Built explicitly instead, so a repeated header stays repeated.
+        // (#1684 review)
+        const headers = new Headers();
+        for (const [name, value] of Object.entries(req.headers)) {
+          if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+          else if (value !== undefined) headers.set(name, value);
+        }
+        const response = await app.fetch(
+          new Request(`http://127.0.0.1:${port}${req.url ?? '/'}`, {
+            method: req.method,
+            headers,
+            body: req.method === 'GET' || req.method === 'HEAD' ? undefined : Buffer.concat(chunks),
+          }),
+        );
+        res.statusCode = response.status;
+        res.end(await response.text());
+      } catch (error) {
+        // 500 with the cause in the body, so a broken harness reads as a broken harness rather than
+        // as a transport that answered nothing.
+        res.statusCode = 500;
+        res.end(
+          `scenario harness failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    })();
+  });
+  servers.push(server);
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  return `http://127.0.0.1:${port}`;
+}
+
+async function submit(base: string, prompt: string, headers: Record<string, string> = {}) {
+  const res = await fetch(`${base}/submit`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...headers },
+    body: JSON.stringify({ prompt }),
+  });
+  return { status: res.status, body: await res.text() };
+}
+
+describe('SEC-008 scenario — an unauthenticated remote request reaches no session', () => {
+  it('rejects POST /submit with no credential, and the prompt is NEVER executed', async () => {
+    // `admission` omitted is the shipped default and means SECURE: a credential is minted.
+    const transport = createHttpTransport();
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+
+    const res = await submit(base, 'hello from an unauthenticated caller');
+
+    expect(res.status, `expected a rejection, got ${res.status} ${res.body}`).toBe(401);
+    // The security property is not "answered 401" — it is that nothing ran.
+    expect(transcript, 'the unauthenticated prompt reached the session').toEqual([]);
+  });
+
+  it('accepts the same request with the minted credential, and only that prompt runs', async () => {
+    const transport = createHttpTransport();
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+    const token = transport.getAdmissionToken();
+
+    expect(token, 'omitting admission must MINT a credential, not run open').toBeTruthy();
+
+    const rejected = await submit(base, 'unauthenticated');
+    const accepted = await submit(base, 'authenticated', { authorization: `Bearer ${token}` });
+
+    expect(rejected.status).toBe(401);
+    expect(accepted.status, `expected success, got ${accepted.status} ${accepted.body}`).toBe(200);
+    expect(transcript).toEqual(['authenticated']);
+  });
+
+  it('CONTRAST: an explicitly OPEN transport executes the same unauthenticated prompt', async () => {
+    // What the absent gate used to do for every caller. Reaching this state now takes asking for it
+    // AND writing down why — `openReason` is required, and `open` with a token is refused outright.
+    const transport = createHttpTransport({
+      admission: { open: true, openReason: 'SEC-008 scenario: the contrast this closure rests on' },
+    });
+    const { session, transcript } = createRecordingSession();
+    transport.attach(session);
+    await transport.start();
+    const base = await serve(transport.getApp());
+
+    const res = await submit(base, 'unauthenticated against an open transport');
+
+    expect(transport.getAdmissionToken(), 'an open transport holds no credential').toBeNull();
+    expect(res.status).toBe(200);
+    expect(transcript).toEqual(['unauthenticated against an open transport']);
+  });
+});

package/src/__tests__/http-base-path.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+import { createHttpTransport } from '../http-transport.js';
+
+import type { IHttpTransportSession } from '../http-session.js';
+
+/**
+ * Issue #2480 (TRANS-002): `basePath` was declared and advertised but never read, so routes always
+ * mounted at root. It is honored now.
+ */
+describe('createHttpTransport basePath', () => {
+  it('mounts every route under basePath when one is given', async () => {
+    const transport = createHttpTransport({
+      basePath: '/api',
+      admission: { open: true, openReason: 'basePath test' },
+    });
+    transport.attach({} as IHttpTransportSession);
+    await transport.start();
+    const paths = transport.getApp().routes.map((route) => route.path);
+    expect(paths.length).toBeGreaterThan(0);
+    expect(paths.every((path) => path.startsWith('/api'))).toBe(true);
+  });
+
+  it('mounts at root when basePath is absent', async () => {
+    const transport = createHttpTransport({
+      admission: { open: true, openReason: 'basePath test' },
+    });
+    transport.attach({} as IHttpTransportSession);
+    await transport.start();
+    const paths = transport.getApp().routes.map((route) => route.path);
+    expect(paths.some((path) => path.startsWith('/api'))).toBe(false);
+  });
+});

package/src/__tests__/http-transport.test.ts

@@ -1,26 +1,57 @@
-import { describe, it, expect, vi } from 'vitest';
+import { runTransportLifecycleConformance } from '@robota-sdk/agent-interface-transport/testing';
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import { describe, it, expect, expectTypeOf } from 'vitest';
 import { createHttpTransport } from '../http-transport.js';
-import type { IInteractiveSession } from '@robota-sdk/agent-interface-transport';
+import type { IHttpTransportSession } from '../http-session.js';
+import type { IHttpTransport } from '../http-transport.js';
+import type { ITransportAdapter } from '@robota-sdk/agent-interface-transport';
 
-function createMockSession(): IInteractiveSession {
+function createMockSession(): IHttpTransportSession {
+  const full = createTestInteractiveSession();
+  const {
+    submit,
+    on,
+    off,
+    abort,
+    cancelQueue,
+    getSession,
+    executeCommand,
+    listCommands,
+    getMessages,
+    getContextState,
+    isExecuting,
+    getPendingPrompt,
+    getPendingCount,
+  } = full;
   return {
-    submit: vi.fn(),
-    abort: vi.fn(),
-    cancelQueue: vi.fn(),
-    getMessages: vi.fn().mockReturnValue([]),
-    getContextState: vi
-      .fn()
-      .mockReturnValue({ usedPercentage: 0, usedTokens: 0, maxTokens: 200000 }),
-    isExecuting: vi.fn().mockReturnValue(false),
-    getPendingPrompt: vi.fn().mockReturnValue(null),
-    executeCommand: vi.fn().mockResolvedValue({ message: 'ok', success: true }),
-    listCommands: vi.fn().mockReturnValue([]),
-    on: vi.fn(),
-    off: vi.fn(),
-  } as unknown as IInteractiveSession;
+    submit,
+    on,
+    off,
+    abort,
+    cancelQueue,
+    getSession,
+    executeCommand,
+    listCommands,
+    getMessages,
+    getContextState,
+    isExecuting,
+    getPendingPrompt,
+    getPendingCount,
+  };
 }
 
 describe('createHttpTransport', () => {
+  it('requires exactly the HTTP session port without a broad attach overload', () => {
+    const transport = createHttpTransport();
+    expectTypeOf(transport).toMatchTypeOf<ITransportAdapter<IHttpTransportSession>>();
+    expectTypeOf<IHttpTransport['attach']>().toEqualTypeOf<
+      (session: IHttpTransportSession) => void
+    >();
+    expectTypeOf<IHttpTransportSession>().not.toHaveProperty('listRuntimeTools');
+    expect(Object.keys(createMockSession())).toHaveLength(13);
+  });
+
   it('returns an adapter with name "http"', () => {
     const transport = createHttpTransport();
     expect(transport.name).toBe('http');
@@ -28,7 +59,10 @@ describe('createHttpTransport', () => {
 
   it('throws if start() is called without attach()', async () => {
     const transport = createHttpTransport();
-    await expect(transport.start()).rejects.toThrow('No session attached');
+    await expect(transport.start()).rejects.toMatchObject({
+      name: 'TransportLifecycleError',
+      code: 'not-attached',
+    });
   });
 
   it('throws if getApp() is called before start()', () => {
@@ -38,7 +72,7 @@ describe('createHttpTransport', () => {
 
   it('creates a Hono app after attach + start', async () => {
     const transport = createHttpTransport();
-    transport.attach(createMockSession() as never);
+    transport.attach(createMockSession());
     await transport.start();
     const app = transport.getApp();
     expect(app).toBeDefined();
@@ -47,9 +81,80 @@ describe('createHttpTransport', () => {
 
   it('nullifies app after stop()', async () => {
     const transport = createHttpTransport();
-    transport.attach(createMockSession() as never);
+    transport.attach(createMockSession());
     await transport.start();
     await transport.stop();
     expect(() => transport.getApp()).toThrow('Transport not started');
   });
+
+  it('invokes the shared lifecycle conformance suite', async () => {
+    await runTransportLifecycleConformance({
+      subjectId: '@robota-sdk/agent-transport-http#createHttpTransport',
+      kind: 'service',
+      createAdapter: () =>
+        createHttpTransport({
+          admission: { open: true, openReason: 'ARCH-011 lifecycle conformance' },
+        }),
+      createSession: createMockSession,
+      assertReady: (transport) => {
+        if (typeof transport.getApp().fetch !== 'function') throw new Error('HTTP app not ready');
+      },
+      assertStopped: (transport) => {
+        try {
+          transport.getApp();
+          throw new Error('HTTP app still ready');
+        } catch (error) {
+          if (!(error instanceof Error) || error.message === 'HTTP app still ready') throw error;
+        }
+      },
+    });
+  });
+});
+
+describe('SEC-008: the decision is resolved once', () => {
+  it('requires the credential it minted, not a second one', async () => {
+    // The transport resolved admission at construction and then rebuilt a CONFIG for the routes to
+    // resolve again. Two resolutions of one decision: harmless while a token was given, and a fresh
+    // mint on the second pass if the first had opened without a reason — so the credential the host
+    // was handed by `getAdmissionToken()` would not be the one the routes required.
+    const transport = createHttpTransport();
+    transport.attach(createMockSession());
+    await transport.start();
+    const token = transport.getAdmissionToken();
+
+    expect(token).not.toBeNull();
+    const refused = await transport.getApp().request('/executing');
+    const admitted = await transport
+      .getApp()
+      .request('/executing', { headers: { authorization: `Bearer ${token}` } });
+
+    expect(refused.status).toBe(401);
+    expect(admitted.status, 'the token the host was handed does not open the door').toBe(200);
+  });
+
+  it('MINTS for `token: ""`, and the host is handed what it must present', async () => {
+    // `{ token: '' }` is documented as "mint a fresh one". This pins the outcome end to end.
+    //
+    // It does NOT red-prove the discriminator defect, and saying so is the point of this comment:
+    // `createHttpTransport` resolves at construction, so the routes it builds receive an
+    // already-resolved admission and the discriminator handled that case correctly. The defect was
+    // only reachable through `createAgentRoutes` DIRECTLY — measured, this case passes either way.
+    //
+    // Through that direct path the defect has no black-box symptom either: "requires the empty
+    // string" and "requires a token you were not given" are both 401 forever, because
+    // `bearerCredential` requires at least one character after `Bearer ` and so a presented
+    // credential is never the empty string. It is a LOCKOUT, not a bypass. That is exactly why the
+    // fix deletes the discriminator instead of testing around it, and why the case that IS red on
+    // it lives at the seam (`agent-transport/src/__tests__/admission.test.ts`).
+    const transport = createHttpTransport({ admission: { token: '' } });
+    transport.attach(createMockSession());
+    await transport.start();
+    const token = transport.getAdmissionToken();
+
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+    const admitted = await transport
+      .getApp()
+      .request('/executing', { headers: { authorization: `Bearer ${token}` } });
+    expect(admitted.status, 'the token the host was handed does not open the door').toBe(200);
+  });
 });

package/src/__tests__/routes-streamsse-throw.test.ts

@@ -0,0 +1,49 @@
+/**
+ * The catch around `streamSSE` itself — reached by making the boundary throw.
+ *
+ * The branch guards the claim when Hono throws BEFORE ever running the relay callback, and for two
+ * rounds it shipped as honestly-labelled unverified code: a throw from inside the callback lands in
+ * the inner `finally` (measured — a case built that way was green with this catch removed), and the
+ * real `streamSSE` has no synchronous throw path today. Review asked for the third option: a
+ * synthetic stub AT the module boundary. Mocking `hono/streaming` tests OUR handler's ordering —
+ * hold, then release on the boundary's throw — without asserting anything about Hono's internals,
+ * which is exactly what the branch is written against.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+vi.mock('hono/streaming', () => ({
+  streamSSE: () => {
+    throw new Error('the boundary threw before the callback ran');
+  },
+}));
+
+const { createAgentRoutes } = await import('../routes.js');
+
+describe('a streamSSE that throws synchronously', () => {
+  it('does not leave the session claimed forever', async () => {
+    const session = createTestInteractiveSession();
+    const app = createAgentRoutes({
+      sessionFactory: () => session,
+      // SEC-008: admission is not under test here, and the reason it is open says so.
+      admission: { open: true, openReason: 'SEC-008: this case is about routing, not admission' },
+    });
+    const post = () =>
+      app.request('/submit', {
+        method: 'POST',
+        body: JSON.stringify({ prompt: 'x' }),
+        headers: { 'content-type': 'application/json' },
+      });
+
+    const first = await post();
+    const second = await post();
+
+    // Both requests fail on the thrown boundary — a 500, not this route's business. What IS this
+    // route's business: the second must not be 409. A leaked claim turns every later request into
+    // "session busy" forever, and that difference is the whole reason the catch exists.
+    expect(first.status).toBe(500);
+    expect(second.status, 'the first request took the claim with it').not.toBe(409);
+  });
+});