@robota-sdk/agent-transport 3.0.0-beta.100

package/src/__tests__/bearer-resource-gate.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createBearerResourceServer,
+  describeProtectedResource,
+} from '../node/bearer-resource-gate.js';
+
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+function request(headers: Record<string, string>, remoteAddress = '127.0.0.1'): IncomingMessage {
+  return { headers, socket: { remoteAddress } } as unknown as IncomingMessage;
+}
+
+function response() {
+  const written: { status?: number; headers?: Record<string, string> } = {};
+  const res = {
+    writeHead(status: number, headers?: Record<string, string>) {
+      written.status = status;
+      if (headers !== undefined) written.headers = headers;
+      return { end: () => undefined };
+    },
+  } as unknown as ServerResponse;
+  return { res, written };
+}
+
+describe('shared bearer resource-server gate', () => {
+  it('places the RFC 9728 metadata before the resource path and points every challenge at it', () => {
+    const resource = describeProtectedResource({
+      resource: 'https://agent.example.invalid/hooks/events/ci',
+      issuer: 'https://auth.example',
+      scopes: ['a', 'b'],
+      label: 'Test',
+    });
+    expect(resource.wellKnownPath).toBe('/.well-known/oauth-protected-resource/hooks/events/ci');
+    const metadata = 'https://agent.example.invalid/.well-known/oauth-protected-resource/hooks/events/ci';
+    expect(resource.challenges).toEqual({
+      missing: `Bearer resource_metadata="${metadata}"`,
+      invalid: `Bearer error="invalid_token", resource_metadata="${metadata}"`,
+      scope: `Bearer error="insufficient_scope", scope="a b", resource_metadata="${metadata}"`,
+    });
+  });
+
+  it('believes X-Forwarded-For only from a trusted proxy, and only its rightmost untrusted hop', () => {
+    const server = createBearerResourceServer({
+      publicUrl: 'https://agent.example.invalid',
+      trustedProxies: ['127.0.0.1', '10.0.0.2'],
+      label: 'Test',
+    });
+    const budgetAfter = (count: number, req: IncomingMessage) => {
+      let last = server.fail(req);
+      for (let index = 1; index < count; index += 1) last = server.fail(req);
+      return last;
+    };
+    // From an untrusted peer the header is ignored: the peer itself is counted and classed.
+    const untrusted = request({ 'x-forwarded-for': '198.51.100.9' }, '203.0.113.5');
+    expect(server.remote(untrusted)).toBe('public');
+    expect(budgetAfter(21, untrusted).throttled).toBe(true);
+    expect(server.fail(request({}, '198.51.100.9')).throttled).toBe(false);
+    // From a trusted proxy: the nearest untrusted hop, skipping further trusted proxies.
+    const viaProxies = request({ 'x-forwarded-for': '6.6.6.6, 198.51.100.20, 10.0.0.2' });
+    expect(budgetAfter(21, viaProxies).throttled).toBe(true);
+    // A forged hop further left does not move the counted address.
+    const forged = request({ 'x-forwarded-for': '1.1.1.1, 198.51.100.20' });
+    expect(server.fail(forged).throttled).toBe(true);
+    // A garbage hop falls back to the proxy itself.
+    expect(server.remote(request({ 'x-forwarded-for': 'not-an-ip' }))).toBe('loopback');
+    // A different client behind the proxy has its own budget.
+    expect(server.fail(request({ 'x-forwarded-for': '198.51.100.21' })).throttled).toBe(false);
+  });
+
+  it('refuses an unsafe configuration, naming the carrier', () => {
+    const base = {
+      resource: 'https://r.example/x',
+      issuer: 'https://i.example',
+      scopes: ['s'],
+      label: 'Carrier',
+    };
+    expect(() => describeProtectedResource({ ...base, resource: 'http://r.example/x' })).toThrow(
+      /^Carrier public URL must use https/,
+    );
+    expect(() => describeProtectedResource({ ...base, issuer: 'http://i.example' })).toThrow(
+      /^Carrier authorization issuer/,
+    );
+    expect(() => describeProtectedResource({ ...base, scopes: ['a b'] })).toThrow(/valid scope/);
+    expect(() =>
+      createBearerResourceServer({
+        publicUrl: 'https://r.example',
+        trustedProxies: ['proxy'],
+        label: 'Carrier',
+      }),
+    ).toThrow(/^Carrier trusted proxy must be a literal IP address/);
+  });
+
+  it('checks Host and Origin against the public URL and counts only the failures it is told of', () => {
+    let clock = 0;
+    const server = createBearerResourceServer({
+      publicUrl: 'https://agent.example.invalid/hooks',
+      label: 'Test',
+      now: () => clock,
+    });
+    const ok = response();
+    expect(server.checkNames(request({ host: 'agent.example.invalid' }), ok.res)).toBe(true);
+    expect(
+      server.checkNames(
+        request({ host: 'agent.example.invalid:443', origin: 'https://agent.example.invalid' }),
+        ok.res,
+      ),
+    ).toBe(true);
+    const bad = response();
+    expect(server.checkNames(request({ host: '127.0.0.1' }), bad.res)).toBe(false);
+    expect(bad.written.status).toBe(403);
+    const peer = request({ host: 'agent.example.invalid' }, '203.0.113.9');
+    let last = server.fail(peer);
+    for (let index = 1; index < 21; index += 1) last = server.fail(peer);
+    expect(last).toMatchObject({ remote: 'public', throttled: true });
+    expect(server.remote(request({}, '10.0.0.4'))).toBe('private');
+    clock = 60_000;
+    expect(server.fail(peer).throttled).toBe(false);
+  });
+});

package/src/__tests__/channel-frames.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  CHANNEL_FRAME_MAGIC,
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+} from '../channel-frames.js';
+import koreanText from './__fixtures__/korean-text.json';
+
+import type { IBinaryFrame, IChannelEventFrame } from '@robota-sdk/agent-interface-transport';
+
+/**
+ * TRANS-001 — payload-agnostic frame codec.
+ *
+ * The codec is the ONLY thing that knows the carrier envelope; it never interprets the opaque body.
+ * These tests pin round-trip integrity, ordering metadata (`seq`), and explicit malformed-input
+ * results (a result union, never a swallowed default).
+ */
+
+function bytes(...values: number[]): Uint8Array {
+  return Uint8Array.from(values);
+}
+
+describe('channel frame codec (TRANS-001)', () => {
+  it('round-trips an opaque binary payload byte-identically', () => {
+    // Deliberately includes bytes that are invalid UTF-8 and JSON-hostile — the carrier must not care.
+    const payload = bytes(0x00, 0xff, 0xfe, 0x7b, 0x22, 0x80, 0x0a, 0xc3, 0x28);
+    const encoded = encodeBinaryFrame({ kind: 'binary', channel: 'audio', seq: 7, payload });
+
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.kind).toBe('binary');
+    const frame = decoded.frame as IBinaryFrame;
+    expect(frame.channel).toBe('audio');
+    expect(frame.seq).toBe(7);
+    expect(Array.from(frame.payload)).toEqual(Array.from(payload));
+  });
+
+  it('round-trips an empty binary payload', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'blob',
+      seq: 0,
+      payload: new Uint8Array(0),
+    });
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect((decoded.frame as IBinaryFrame).payload.byteLength).toBe(0);
+  });
+
+  it('preserves per-channel ordering through seq on a chunked stream', () => {
+    const source = new Uint8Array(1024);
+    for (let i = 0; i < source.length; i += 1) source[i] = (i * 31) % 256;
+
+    const chunkSize = 100;
+    const wire: Uint8Array[] = [];
+    for (let offset = 0, seq = 0; offset < source.length; offset += chunkSize, seq += 1) {
+      wire.push(
+        encodeBinaryFrame({
+          kind: 'binary',
+          channel: 'file',
+          seq,
+          payload: source.subarray(offset, Math.min(offset + chunkSize, source.length)),
+        }),
+      );
+    }
+
+    // Deliver out of order; the receiver reassembles by `seq`, not by arrival order.
+    const shuffled = [...wire].reverse();
+    const received: IBinaryFrame[] = [];
+    for (const w of shuffled) {
+      const d = decodeChannelFrame(w);
+      expect(d.ok).toBe(true);
+      if (d.ok && d.frame.kind === 'binary') received.push(d.frame);
+    }
+
+    received.sort((a, b) => a.seq - b.seq);
+    const reassembled = new Uint8Array(source.length);
+    let cursor = 0;
+    for (const frame of received) {
+      reassembled.set(frame.payload, cursor);
+      cursor += frame.payload.byteLength;
+    }
+    expect(cursor).toBe(source.length);
+    expect(Array.from(reassembled)).toEqual(Array.from(source));
+  });
+
+  it('round-trips a consumer-declared structured event frame', () => {
+    const encoded = encodeChannelEventFrame({
+      kind: 'event',
+      channel: 'captions',
+      seq: 3,
+      event: 'caption',
+      payload: { text: 'hello', final: true },
+    });
+
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.kind).toBe('event');
+    const frame = decoded.frame as IChannelEventFrame;
+    expect(frame.channel).toBe('captions');
+    expect(frame.seq).toBe(3);
+    expect(frame.event).toBe('caption');
+    expect(frame.payload).toEqual({ text: 'hello', final: true });
+  });
+
+  it('supports multi-byte UTF-8 channel names', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: koreanText.voiceChannelName,
+      seq: 1,
+      payload: bytes(1, 2, 3),
+    });
+    const decoded = decodeChannelFrame(encoded);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.frame.channel).toBe(koreanText.voiceChannelName);
+  });
+
+  it('rejects a channel name that does not fit the 255-byte header field', () => {
+    expect(() =>
+      encodeBinaryFrame({
+        kind: 'binary',
+        channel: 'x'.repeat(256),
+        seq: 0,
+        payload: new Uint8Array(0),
+      }),
+    ).toThrow(/channel name/i);
+  });
+
+  it('rejects an empty channel name', () => {
+    expect(() =>
+      encodeBinaryFrame({ kind: 'binary', channel: '', seq: 0, payload: new Uint8Array(0) }),
+    ).toThrow(/channel name/i);
+  });
+
+  it('rejects a seq outside the uint32 range', () => {
+    expect(() =>
+      encodeBinaryFrame({
+        kind: 'binary',
+        channel: 'c',
+        seq: 2 ** 32,
+        payload: new Uint8Array(0),
+      }),
+    ).toThrow(/seq/i);
+  });
+
+  it('reports a non-channel frame as a typed error result rather than throwing', () => {
+    const decoded = decodeChannelFrame(bytes(0x01, 0x02, 0x03, 0x04, 0x05));
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/magic|channel frame/i);
+  });
+
+  it('reports a truncated frame as a typed error result', () => {
+    const full = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'audio',
+      seq: 1,
+      payload: bytes(9, 9, 9),
+    });
+    const decoded = decodeChannelFrame(full.subarray(0, 6));
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/truncated/i);
+  });
+
+  it('reports an unknown frame kind as a typed error result', () => {
+    const full = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'audio',
+      seq: 1,
+      payload: bytes(9),
+    });
+    const tampered = Uint8Array.from(full);
+    tampered[4] = 0x7f; // unknown kind byte
+    const decoded = decodeChannelFrame(tampered);
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/kind/i);
+  });
+
+  it('reports a malformed event body as a typed error result', () => {
+    const good = encodeChannelEventFrame({
+      kind: 'event',
+      channel: 'c',
+      seq: 0,
+      event: 'e',
+      payload: null,
+    });
+    const tampered = Uint8Array.from(good);
+    // Corrupt the JSON body (everything after the 10 + channelNameLength header bytes).
+    tampered[tampered.length - 1] = 0x7b; // '{'
+    const decoded = decodeChannelFrame(tampered);
+    expect(decoded.ok).toBe(false);
+    if (decoded.ok) return;
+    expect(decoded.error).toMatch(/body|json/i);
+  });
+
+  it('stamps the shared magic so a carrier can route frames without parsing them', () => {
+    const encoded = encodeBinaryFrame({
+      kind: 'binary',
+      channel: 'c',
+      seq: 0,
+      payload: new Uint8Array(0),
+    });
+    expect(Array.from(encoded.subarray(0, CHANNEL_FRAME_MAGIC.length))).toEqual(
+      Array.from(CHANNEL_FRAME_MAGIC),
+    );
+  });
+});

package/src/__tests__/driver-attribution-capability.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createOutboundDelivery } from '../outbound-delivery.js';
+import { subscribeSessionEvents } from '../session-events.js';
+
+import { createTestInteractiveSession } from '@robota-sdk/agent-interface-session/testing';
+
+import type { IInteractiveSession, TDriverId } from '@robota-sdk/agent-interface-session';
+
+/**
+ * ARCH-012 — the sharp edge of an optional contract member.
+ *
+ * `IInteractiveSession` declared `getActiveDriverId?()`, and the one consumer read it as
+ * `session.getActiveDriverId?.() ?? undefined`. Two entirely different situations arrived as the same
+ * `undefined`:
+ *
+ * - the host DOES attribute turns and no driver is active right now, and
+ * - the host does not implement attribution at all.
+ *
+ * The second silently loses every co-drive attribution, with no error, no log, and nothing a reader
+ * or a test could use to tell it from the first. The shipped `InteractiveSession` happens to
+ * implement all three optional members, so the defect was latent for it and live for the 51 casts
+ * that stand in for other implementations.
+ *
+ * The fix is not a better fallback. It is removing the optionality: a host either provides the
+ * capability or does not claim the contract. These cases pin that the member is REQUIRED, which is
+ * what makes "no active driver" the only thing `null` can mean.
+ */
+function hostWithAttribution(driverId: TDriverId | null): IInteractiveSession {
+  // The conformant double, not another hand-rolled partial — the cast ratchet objected to the first
+  // draft of this very file, which is the behaviour it exists for.
+  return createTestInteractiveSession({
+    getActiveDriverId: () => driverId,
+    on: vi.fn(),
+    off: vi.fn(),
+  });
+}
+
+describe('driver attribution is a declared capability, not an optional call (ARCH-012)', () => {
+  it('TYPE-LEVEL: a host that omits the attribution members does not satisfy the contract', () => {
+    // Judged by `pnpm typecheck`, not by this assertion — `@ts-expect-error` fails the BUILD when the
+    // error it expects does not occur.
+    //
+    // `Omit` rather than a hand-written object literal, deliberately. A literal missing the three
+    // members is also missing the forty required ones, so `@ts-expect-error` would be satisfied by
+    // the wrong error and the case would pass whether or not the optionality was ever removed. That
+    // is precisely the accidental-green shape; the first draft of this test had it. This type carries
+    // every other member and differs ONLY in the three.
+    type OmitsAttribution = Omit<
+      IInteractiveSession,
+      'getActiveDriverId' | 'getPendingCount' | 'isInitialized'
+    >;
+    const host = {} as OmitsAttribution;
+    // @ts-expect-error ARCH-012: the three are REQUIRED. If this ever compiles again the optionality
+    // is back, and `undefined` means both "no active driver" and "cannot answer" once more.
+    const asSession: IInteractiveSession = host;
+    expect(asSession).toBeDefined();
+  });
+
+  it('stamps the active driver onto a turn-authored event', () => {
+    const send = vi.fn();
+    const session = hostWithAttribution('driver-7');
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const handler = vi.mocked(session.on).mock.calls.find(([name]) => name === 'user_message')?.[1];
+    (handler as (content: string) => void)('hello');
+
+    expect(send).toHaveBeenCalledWith(expect.objectContaining({ driverId: 'driver-7' }));
+  });
+
+  it('omits the driver when the host attributes turns and none is active', () => {
+    // `null` now means exactly one thing: nobody is driving. It used to be indistinguishable from
+    // "this host cannot answer the question".
+    const send = vi.fn();
+    const session = hostWithAttribution(null);
+    subscribeSessionEvents(session, createOutboundDelivery(send, vi.fn()));
+
+    const handler = vi.mocked(session.on).mock.calls.find(([name]) => name === 'user_message')?.[1];
+    (handler as (content: string) => void)('hello');
+
+    expect(send).toHaveBeenCalledWith(expect.not.objectContaining({ driverId: expect.anything() }));
+  });
+});