@indigoai-us/hq-cli 5.77.12 → 5.77.14

package/src/outpost/session-heartbeat-publisher.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Tests for the on-box realtime publisher (mission-control US-009):
+ *   - defaultRealtimeCredentialsFetcher POSTs the box's JWT to
+ *     /v1/realtime/credentials and parses the response
+ *   - createIotPublishPort vends scoped creds, builds an IoT client, publishes
+ *     to the caller's topic, caches the client until near-expiry, and re-guards
+ *     the no-secrets contract at the transport boundary
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mockClient } from "aws-sdk-client-mock";
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import {
+  createIotPublishPort,
+  defaultRealtimeCredentialsFetcher,
+  type RealtimeCredentialsResponse,
+} from "./session-heartbeat-publisher";
+import type { SessionsHeartbeatPayload } from "./session-heartbeat";
+
+const PERSON = "prs_alice";
+const TOPIC = `hq/${PERSON}/sessions`;
+const NOW = new Date("2026-06-15T18:55:00.000Z");
+
+function credsResponse(
+  expiresInMs: number,
+): RealtimeCredentialsResponse {
+  return {
+    credentials: {
+      accessKeyId: "ASIAEXAMPLE",
+      secretAccessKey: "secret",
+      sessionToken: "token",
+      expiration: new Date(NOW.getTime() + expiresInMs).toISOString(),
+    },
+    iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+    region: "us-east-1",
+    topic: TOPIC,
+    expiresAt: new Date(NOW.getTime() + expiresInMs).toISOString(),
+  };
+}
+
+function cleanPayload(): SessionsHeartbeatPayload {
+  return {
+    type: "sessions",
+    origin: "outpost",
+    emittedAt: NOW.toISOString(),
+    sessions: [
+      {
+        id: "x",
+        tool: "claude",
+        origin: "outpost",
+        cwd: "/home/ec2-user/hq",
+        project: "hq",
+        company: null,
+        model: "claude-opus-4",
+        status: "running",
+        startedAt: null,
+        lastActivityAt: NOW.toISOString(),
+        source: "/home/ec2-user/.claude/projects/p/x.jsonl",
+      },
+    ],
+  };
+}
+
+describe("defaultRealtimeCredentialsFetcher", () => {
+  it("POSTs the JWT to /v1/realtime/credentials and returns the parsed body", async () => {
+    const body = credsResponse(3_600_000);
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      json: async () => body,
+    } as Response);
+    const fetcher = defaultRealtimeCredentialsFetcher({
+      apiBaseUrl: "https://hqapi.hq.computer",
+      getJwt: async () => "JWT123",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    const out = await fetcher();
+    expect(out).toEqual(body);
+    const [url, init] = fetchImpl.mock.calls[0];
+    expect(url).toBe("https://hqapi.hq.computer/v1/realtime/credentials");
+    expect(init.method).toBe("POST");
+    expect(init.headers.authorization).toBe("Bearer JWT123");
+  });
+
+  it("throws on a non-ok response", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      statusText: "Forbidden",
+      json: async () => ({}),
+    } as Response);
+    const fetcher = defaultRealtimeCredentialsFetcher({
+      apiBaseUrl: "https://hqapi.hq.computer",
+      getJwt: async () => "JWT",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await expect(fetcher()).rejects.toThrow(/403/);
+  });
+});
+
+describe("createIotPublishPort", () => {
+  const iotMock = mockClient(IoTDataPlaneClient);
+  beforeEach(() => iotMock.reset());
+
+  it("publishes the payload to the caller's topic via IoT", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    const payload = cleanPayload();
+    await publish(TOPIC, payload);
+
+    const call = iotMock.commandCalls(PublishCommand)[0];
+    expect(call.args[0].input.topic).toBe(TOPIC);
+    const sent = JSON.parse(
+      Buffer.from(call.args[0].input.payload as Uint8Array).toString("utf8"),
+    );
+    expect(sent.type).toBe("sessions");
+    expect(sent.sessions[0].id).toBe("x");
+  });
+
+  it("caches the vended creds/client until near expiry, then re-vends", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi
+      .fn()
+      .mockResolvedValueOnce(credsResponse(3_600_000))
+      .mockResolvedValueOnce(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    await publish(TOPIC, cleanPayload());
+    await publish(TOPIC, cleanPayload());
+    // Second publish reuses the cached client — creds vended once.
+    expect(fetchCredentials).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-vends when the cached creds are within the refresh skew of expiry", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi
+      .fn()
+      // expires in 30s — inside the 60s refresh skew, so every call re-vends
+      .mockResolvedValue(credsResponse(30_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+    await publish(TOPIC, cleanPayload());
+    await publish(TOPIC, cleanPayload());
+    expect(fetchCredentials).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-guards the no-secrets contract at the transport boundary", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+    const dirty = cleanPayload();
+    // Smuggle a secret into a whitelisted field — the publisher must refuse.
+    dirty.sessions[0].model = "sk-ant-leaked-key";
+    await expect(publish(TOPIC, dirty)).rejects.toThrow(/secret marker/);
+    expect(iotMock.commandCalls(PublishCommand)).toHaveLength(0);
+  });
+});

package/src/outpost/session-heartbeat-publisher.ts

@@ -0,0 +1,186 @@
+/**
+ * Outpost on-box realtime publisher — mission-control US-009.
+ *
+ * The box already holds a Cognito session (seeded from the caller's refresh
+ * token in user-data, kept fresh by the box's auth timers — see provision.ts).
+ * This module turns that session into a `PublishPort` for the session-heartbeat
+ * emitter using the EXACT on-box credential pattern the rest of the realtime
+ * fabric uses (docs/realtime-fabric.md):
+ *
+ *   1. POST {HQAPI}/v1/realtime/credentials with the box's Cognito JWT.
+ *      The Lambda resolves the caller's `personUid` from the verified JWT
+ *      (never request input) and vends short-lived STS creds whose session
+ *      policy scopes `iot:Connect/Publish/...` to `hq/{personUid}/*` only.
+ *   2. SigV4-sign an IoT Data-plane publish with those creds to
+ *      `hq/{personUid}/sessions`.
+ *
+ * No new auth surface, no embedded long-lived key, no per-device cert — the
+ * per-identity STS session policy is the isolation boundary (US-010).
+ *
+ * The HTTP fetch + IoT client are injected so this is unit-testable without a
+ * live endpoint; `defaultRealtimeCredentialsFetcher` and the IoT publish are
+ * the production wiring.
+ */
+
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import type {
+  PublishPort,
+  SessionsHeartbeatPayload,
+} from "./session-heartbeat.js";
+import {
+  assertNoSecretsInPayload,
+  sessionsTopicForPerson,
+} from "./session-heartbeat.js";
+
+/** Shape returned by `POST /v1/realtime/credentials` (mirrors the handler). */
+export interface RealtimeCredentialsResponse {
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration: string;
+  };
+  iotEndpoint: string;
+  region: string;
+  /** The caller's own topic — `hq/{personUid}/...`. */
+  topic: string;
+  expiresAt: string;
+}
+
+/** Fetches scoped realtime credentials for the box. Injected for tests. */
+export type RealtimeCredentialsFetcher = () => Promise<RealtimeCredentialsResponse>;
+
+/** Ceiling on a single credentials request. */
+export const DEFAULT_CREDENTIALS_TIMEOUT_MS = 10_000;
+
+/**
+ * Build the production credentials fetcher. Reads the box's current Cognito
+ * id/access token via the injected `getJwt` and POSTs it to the
+ * realtime-credentials endpoint.
+ */
+export function defaultRealtimeCredentialsFetcher(opts: {
+  apiBaseUrl: string;
+  getJwt: () => Promise<string>;
+  fetchImpl?: typeof fetch;
+  /** Bound the request. Defaults to {@link DEFAULT_CREDENTIALS_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}): RealtimeCredentialsFetcher {
+  const doFetch = opts.fetchImpl ?? fetch;
+  return async () => {
+    const jwt = await opts.getJwt();
+    const res = await doFetch(`${opts.apiBaseUrl}/v1/realtime/credentials`, {
+      method: "POST",
+      // Bounded. An endpoint that accepts the connection but never answers
+      // would otherwise park the tick forever: the loop stops beating, the
+      // liveness marker goes stale, and SIGTERM cannot finish the in-flight
+      // tick — a hang that reads exactly like a healthy quiet box.
+      signal: AbortSignal.timeout(
+        opts.timeoutMs ?? DEFAULT_CREDENTIALS_TIMEOUT_MS,
+      ),
+      headers: {
+        authorization: `Bearer ${jwt}`,
+        "content-type": "application/json",
+      },
+    });
+    if (!res.ok) {
+      throw new Error(
+        `realtime/credentials returned ${res.status} ${res.statusText}`,
+      );
+    }
+    return (await res.json()) as RealtimeCredentialsResponse;
+  };
+}
+
+/** A cached IoT client keyed by endpoint+creds so we don't rebuild per tick. */
+interface CachedClient {
+  client: IoTDataPlaneClient;
+  endpoint: string;
+  accessKeyId: string;
+  expiresAtMs: number;
+}
+
+/**
+ * Create a `PublishPort` that vends scoped creds (refreshing before expiry) and
+ * publishes the compact payload to the box's own sessions topic over MQTT/IoT.
+ *
+ * @param fetchCredentials  vends per-identity-scoped STS creds + IoT endpoint
+ * @param makeClient        builds an IoT client from creds (injected for tests)
+ * @param now               clock injection
+ */
+export function createIotPublishPort(opts: {
+  fetchCredentials: RealtimeCredentialsFetcher;
+  makeClient?: (args: {
+    endpoint: string;
+    region: string;
+    credentials: RealtimeCredentialsResponse["credentials"];
+  }) => IoTDataPlaneClient;
+  now?: () => Date;
+}): PublishPort {
+  const now = opts.now ?? (() => new Date());
+  const makeClient =
+    opts.makeClient ??
+    (({ endpoint, region, credentials }) => {
+      const url = endpoint.startsWith("http")
+        ? endpoint
+        : `https://${endpoint}`;
+      return new IoTDataPlaneClient({
+        endpoint: url,
+        region,
+        credentials: {
+          accessKeyId: credentials.accessKeyId,
+          secretAccessKey: credentials.secretAccessKey,
+          sessionToken: credentials.sessionToken,
+        },
+      });
+    });
+
+  let cached: CachedClient | null = null;
+  // Refresh creds this many ms before they actually expire so a publish never
+  // races expiry mid-flight.
+  const REFRESH_SKEW_MS = 60_000;
+
+  async function clientFor(): Promise<{
+    client: IoTDataPlaneClient;
+  }> {
+    const nowMs = now().getTime();
+    if (cached && cached.expiresAtMs - REFRESH_SKEW_MS > nowMs) {
+      return { client: cached.client };
+    }
+    const vended = await opts.fetchCredentials();
+    const client = makeClient({
+      endpoint: vended.iotEndpoint,
+      region: vended.region,
+      credentials: vended.credentials,
+    });
+    cached = {
+      client,
+      endpoint: vended.iotEndpoint,
+      accessKeyId: vended.credentials.accessKeyId,
+      expiresAtMs: Date.parse(vended.credentials.expiration),
+    };
+    return { client };
+  }
+
+  return async (
+    topic: string,
+    payload: SessionsHeartbeatPayload,
+  ): Promise<void> => {
+    // Re-guard at the transport boundary — a publisher must never ship a
+    // payload that fails the no-secrets contract, regardless of caller.
+    assertNoSecretsInPayload(payload);
+    const { client } = await clientFor();
+    await client.send(
+      new PublishCommand({
+        topic,
+        qos: 0,
+        payload: Buffer.from(JSON.stringify(payload)),
+      }),
+    );
+  };
+}
+
+/** Re-export for the runner so it imports one module. */
+export { sessionsTopicForPerson };

package/src/outpost/session-heartbeat-retain-guard.test.ts

@@ -0,0 +1,126 @@
+/**
+ * company-work-corpus US-006 AC7 — no retained MQTT publishes for transcript
+ * objects.
+ *
+ * Session transcripts are pulled on demand via the presign GET path (structural
+ * owner+creator gate); they are NEVER pushed as message bodies over the realtime
+ * fabric. The on-box sessions publisher emits only a COMPACT liveness heartbeat
+ * (`SessionsHeartbeatPayload` — path-only session summaries, guarded by
+ * `assertNoSecretsInPayload`), and it must publish NON-RETAINED so a stale
+ * summary is never re-delivered from the broker to a late subscriber.
+ *
+ * This is a GUARD suite: it asserts the current (correct) behavior so a future
+ * change that (a) turns on `retain` for the sessions topic, or (b) starts
+ * shipping transcript/vault-file bytes over MQTT, fails loudly. No product code
+ * change is expected from US-006 here.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { mockClient } from "aws-sdk-client-mock";
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import {
+  createIotPublishPort,
+  type RealtimeCredentialsResponse,
+} from "./session-heartbeat-publisher";
+import type { SessionsHeartbeatPayload } from "./session-heartbeat";
+
+const PERSON = "prs_alice";
+const TOPIC = `hq/${PERSON}/sessions`;
+const NOW = new Date("2026-07-11T18:55:00.000Z");
+
+function credsResponse(): RealtimeCredentialsResponse {
+  return {
+    credentials: {
+      accessKeyId: "ASIAEXAMPLE",
+      secretAccessKey: "secret",
+      sessionToken: "token",
+      expiration: new Date(NOW.getTime() + 3_600_000).toISOString(),
+    },
+    iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+    region: "us-east-1",
+    topic: TOPIC,
+    expiresAt: new Date(NOW.getTime() + 3_600_000).toISOString(),
+  };
+}
+
+function cleanPayload(): SessionsHeartbeatPayload {
+  return {
+    type: "sessions",
+    origin: "outpost",
+    emittedAt: NOW.toISOString(),
+    sessions: [
+      {
+        id: "x",
+        tool: "claude",
+        origin: "outpost",
+        cwd: "/home/ec2-user/hq",
+        project: "hq",
+        company: null,
+        model: "claude-opus-4",
+        status: "running",
+        startedAt: null,
+        lastActivityAt: NOW.toISOString(),
+        source: "/home/ec2-user/.claude/projects/p/x.jsonl",
+      },
+    ],
+  };
+}
+
+describe("US-006 AC7 — sessions heartbeat is published NON-RETAINED", () => {
+  const iotMock = mockClient(IoTDataPlaneClient);
+  beforeEach(() => iotMock.reset());
+
+  it("the PublishCommand never sets retain=true", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const publish = createIotPublishPort({
+      fetchCredentials: vi.fn().mockResolvedValue(credsResponse()),
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    await publish(TOPIC, cleanPayload());
+
+    const call = iotMock.commandCalls(PublishCommand)[0];
+    // retain must be absent or explicitly false — never true (no broker
+    // re-delivery of a stale session summary; transcripts are pull-only).
+    expect(call.args[0].input.retain).not.toBe(true);
+    // The wire body is the compact summary envelope — no transcript body field.
+    const sent = JSON.parse(
+      Buffer.from(call.args[0].input.payload as Uint8Array).toString("utf8"),
+    ) as Record<string, unknown> & {
+      sessions: Array<Record<string, unknown>>;
+    };
+    expect(sent.type).toBe("sessions");
+    // The session summary carries a `source` PATH only, never file/transcript
+    // content — assert no body/content/transcript key ever rides the wire.
+    for (const s of sent.sessions) {
+      expect(s).not.toHaveProperty("body");
+      expect(s).not.toHaveProperty("content");
+      expect(s).not.toHaveProperty("transcript");
+    }
+  });
+});
+
+describe("US-006 AC7 — static guard: sessions/realtime publishers never retain", () => {
+  // The sessions publisher is the ONLY realtime path in this package that
+  // touches session data, and it may never set retain=true — a retained
+  // message would leave the last session summary sitting on the broker after
+  // the box goes away. (The server-side DM-wake publisher is guarded by the
+  // matching test in hq-pro, which is where that file lives.)
+  const guardedSources = [
+    new URL("./session-heartbeat-publisher.ts", import.meta.url),
+    new URL("./session-heartbeat.ts", import.meta.url),
+  ];
+
+  it("no guarded publisher sets retain: true", () => {
+    for (const url of guardedSources) {
+      const src = readFileSync(url, "utf8");
+      // Tolerate any whitespace between `retain` and `true`.
+      expect(src).not.toMatch(/retain\s*:\s*true/);
+    }
+  });
+});