@robota-sdk/agent-transport 3.0.0-beta.79 → 3.0.0-beta.82

package/src/__tests__/admission.test.ts

@@ -0,0 +1,130 @@
+/**
+ * SEC-008 — the admission seam's own cases.
+ *
+ * `resolveAdmission` had none. It was exercised only THROUGH the four transports that call it, and
+ * both defects review found here are ones that indirection hides: a transport passing a well-formed
+ * config never exhibits either.
+ *
+ * The seam's whole claim is "one place to read and one place to change". A seam nobody tests
+ * directly is one place to read and four places to find out you were wrong.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { bearerCredential, resolveAdmission } from '../node/admission.js';
+
+const OPEN_REASON = 'loopback only, the port is bound to 127.0.0.1';
+
+describe('resolveAdmission is secure by default', () => {
+  it('mints when nothing is asked for', () => {
+    const admission = resolveAdmission();
+
+    expect(admission.token).toMatch(/^[0-9a-f]{64}$/);
+    expect(admission.openReason).toBeUndefined();
+  });
+
+  it('keeps an explicit token', () => {
+    expect(resolveAdmission({ token: 'chosen-by-the-host' })).toEqual({
+      token: 'chosen-by-the-host',
+    });
+  });
+
+  it('opens only with a reason', () => {
+    expect(resolveAdmission({ open: true, openReason: OPEN_REASON })).toEqual({
+      token: null,
+      openReason: OPEN_REASON,
+    });
+    expect(() => resolveAdmission({ open: true })).toThrow(/requires `openReason`/);
+    expect(() => resolveAdmission({ open: true, openReason: '   ' })).toThrow(
+      /requires `openReason`/,
+    );
+  });
+
+  it('MINTS for an empty-string token rather than requiring the empty string', () => {
+    // The value behind the discriminator defect. `{ token: '' }` is documented as "mint a fresh
+    // one", and the HTTP route's `'token' in options.admission` read it as ALREADY RESOLVED and
+    // installed the empty string as the required credential — which a peer sending an empty bearer
+    // then matches. The route no longer discriminates; this pins the value it depends on.
+    expect(resolveAdmission({ token: '' }).token).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe('resolveAdmission is idempotent', () => {
+  // Why it must be: the HTTP route accepts either shape, and BOTH interfaces declare a `token`, so
+  // they cannot be told apart structurally. Making the function accept its own output deletes that
+  // question instead of answering it wrongly.
+  it('returns an already-resolved token admission unchanged', () => {
+    const resolved = resolveAdmission({ token: 'chosen-by-the-host' });
+
+    expect(resolveAdmission(resolved)).toEqual(resolved);
+  });
+
+  it('returns an already-resolved OPEN admission unchanged, reason and all', () => {
+    // The case that made the old code wrong in the dangerous direction: re-resolving an open
+    // admission through a config-shaped path either minted a token nobody holds or dropped the
+    // reason and left an unexplained open transport.
+    const resolved = resolveAdmission({ open: true, openReason: OPEN_REASON });
+
+    expect(resolved).toEqual({ token: null, openReason: OPEN_REASON });
+    expect(resolveAdmission(resolved)).toEqual(resolved);
+  });
+
+  it('REFUSES an open admission that arrives without its reason', () => {
+    // `token: null` is the recorded outcome of a decision. One reaching here with no reason was
+    // hand-built or corrupted, and both are the unexplained-open state the reason exists to
+    // prevent — so it is refused rather than passed through.
+    expect(() => resolveAdmission({ token: null })).toThrow(/requires `openReason`/);
+  });
+});
+
+describe('resolveAdmission refuses a contradiction', () => {
+  it('throws when a token and `open: true` are asked for together', () => {
+    // Review: `WebRtcTransport` already refused the analogous `secret` + `open` pair in its own
+    // constructor, so only WebRTC callers were protected. The old seam gave silent precedence to
+    // the token — the safe DIRECTION, but the wrong ANSWER: a caller that wrote both does not know
+    // what it is asking for, and one of the two things it believes is false.
+    expect(() =>
+      resolveAdmission({ token: 'a-credential', open: true, openReason: OPEN_REASON }),
+    ).toThrow(/contradictory/);
+  });
+
+  it('still accepts `open: false` beside a token, which is not a contradiction', () => {
+    // `open: false` says the same thing the token does. Refusing it would turn a redundant but
+    // coherent config into an error, which is over-blocking for nothing.
+    expect(resolveAdmission({ token: 'a-credential', open: false })).toEqual({
+      token: 'a-credential',
+    });
+  });
+});
+
+describe('bearerCredential reads the header the way RFC 7235 defines it', () => {
+  it('matches the SCHEME without regard to case', () => {
+    // `auth-scheme` is a token, and tokens compare case-insensitively. The exact-case match refused
+    // a conformant client with a 401 it could not act on — a refusal that reads as a server bug and
+    // gets worked around rather than fixed. Review found it.
+    expect(bearerCredential('bearer abc123')).toBe('abc123');
+    expect(bearerCredential('BEARER abc123')).toBe('abc123');
+    expect(bearerCredential('BeArEr abc123')).toBe('abc123');
+  });
+
+  it('leaves the CREDENTIAL exactly as sent', () => {
+    // Only the scheme is case-insensitive. The credential is compared byte for byte, so folding it
+    // would make two different secrets the same secret.
+    expect(bearerCredential('Bearer AbC')).toBe('AbC');
+  });
+
+  it('accepts more than one space between the two', () => {
+    expect(bearerCredential('Bearer   abc123')).toBe('abc123');
+    expect(bearerCredential('Bearer\tabc123')).toBe('abc123');
+  });
+
+  it('refuses a header that merely STARTS with the word', () => {
+    // `Bearerness xyz` is a different scheme, and reading it as a bearer token would admit a peer
+    // that never claimed to be one.
+    expect(bearerCredential('Bearerness xyz')).toBeUndefined();
+    expect(bearerCredential('Basic abc123')).toBeUndefined();
+    expect(bearerCredential('Bearer')).toBeUndefined();
+    expect(bearerCredential('Bearer ')).toBeUndefined();
+    expect(bearerCredential(undefined)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,214 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  CHANNEL_FRAME_MAGIC,
+  decodeChannelFrame,
+  encodeBinaryFrame,
+  encodeChannelEventFrame,
+} from '../channel-frames.js';
+
+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: '음성-채널',
+      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('음성-채널');
+  });
+
+  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() }));
+  });
+});