@indigoai-us/hq-cli 5.77.13 → 5.78.0

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

@@ -1,186 +0,0 @@
-/**
- * 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

@@ -1,126 +0,0 @@
-/**
- * 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/);
-    }
-  });
-});