@indigoai-us/hq-cli 5.77.12 → 5.77.14

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## [Unreleased]
 
+## [5.77.14]
+
+### Fixed
+
+- Extend `HQ_API_KEY` fail-closed: reject metadata-only `hq secrets get`
+  without `--reveal`, and hard-error `hq run` / `hq install` when a vault API
+  key is set (Cognito session required). (#273)
+- Keep the Cognito-only gate on the top-level `hq install` route only — not
+  inside shared `installPack()` — so `hq packs update` cannot un-wire a pack
+  and then abort mid-flight under `HQ_API_KEY`. (#273)
+
+## [5.77.13]
+
+### Added
+
+- `hq outposts heartbeat` — the Outpost session-heartbeat runner. The unit on
+  every box invoked `outpost-session-heartbeat-runner`, a command that was
+  never written in any package, so each tick logged `command not found` behind
+  a `|| echo … continuing` while systemd and the box audit both reported
+  healthy. The enumeration and publisher modules existed in hq-pro (a server
+  repo) with no entrypoint; they move here and the cadence runs in-process —
+  no bash loop, no per-tick `npx …@latest`, no per-tick `hq auth refresh`.
+  That removes ~35k process launches per box per day. (#274)
+
+### Fixed
+
+- Heartbeat payloads no longer exceed the AWS IoT 128 KiB limit. A box with
+  9,340 transcripts produced ~1.9 MB and was rejected outright; `ended`
+  sessions are no longer published and the remainder is bounded by serialized
+  bytes, newest first, with `totalSessions`/`truncated` on the envelope so a
+  filtered list cannot read as a complete one. (#274)
+- Transcript bodies are read only for sessions that will be published — the
+  enumerator previously did a 16 KiB bounded read on every file before
+  filtering (~150 MB of disk per tick on a large box). (#274)
+- The no-secrets guard no longer matches ordinary paths. `sk-` and `asia` were
+  bare substrings, so a directory named `task-runner` or `flask-app` made the
+  guard throw and silently stopped the box reporting; markers are now
+  credential-shaped. (#274)
+- `nodeFileSystem.readDir` propagates operational errors instead of treating
+  every failure as an empty directory — an EACCES previously published an
+  empty session list and refreshed the liveness marker as if collection had
+  succeeded. (#274)
+- The realtime-credentials request is bounded, and the cadence sleep races the
+  abort signal so SIGTERM stops the loop cooperatively. (#274)
+- `vaultApiFetch` accepts an optional `baseUrl` so identity resolves against
+  the same control plane as the credentials fetch on non-default
+  deployments. (#274)
+
 ## [5.77.12]
 
 ### Added

package/dist/commands/outposts-heartbeat.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `hq outposts heartbeat` — publish this box's agent-session summary to the
+ * realtime fabric.
+ *
+ * Runs ON an Outpost, under systemd. It enumerates the box's local Claude Code
+ * and Codex sessions with cheap scandir + stat + bounded reads, projects them
+ * down to the compact secret-free `AgentSession[]` payload, and publishes to
+ * `hq/{personUid}/sessions` so Mission Control can see what the box is doing.
+ *
+ * ## Why the cadence lives in here
+ *
+ * The original box-side design was a bash `while` loop that, every 5 seconds,
+ * ran `hq auth refresh` and then `npx -y --package=@indigoai-us/hq-cloud@latest
+ * outpost-session-heartbeat-runner`. That is ~35k process launches a day, and
+ * every `npx` re-resolves the package and re-reads it off disk — on a t3 box
+ * whose EBS budget is the scarce resource, that is a meaningful, permanent tax
+ * for a job that should be nearly free.
+ *
+ * So the loop lives in-process instead:
+ *   - identity is resolved ONCE per process, not once per tick;
+ *   - the Cognito session refreshes itself on demand (`ensureCognitoToken`
+ *     returns the cached token until it is close to expiry), so there is no
+ *     separate per-tick `hq auth refresh`;
+ *   - the IoT client is cached across ticks by the publisher and only rebuilt
+ *     when its credentials near expiry.
+ *
+ * The loop is deliberately unkillable-by-transients: a failed publish, a failed
+ * enumeration, or a not-yet-warm session are all logged and retried on the next
+ * tick. Nothing here should ever take the service down, because a service that
+ * exits looks identical to a service that is quietly failing.
+ */
+import type { Command } from "commander";
+import { type FileSystemPort, type PublishPort, type SessionsHeartbeatPayload } from "../outpost/session-heartbeat.js";
+/** Everything the loop touches, injected so it is testable without a box. */
+export interface HeartbeatLoopDeps {
+    fs: FileSystemPort;
+    publish: PublishPort;
+    /** Resolve the caller's canonical `prs_*` id. Called once per process. */
+    getPersonUid: () => Promise<string>;
+    /**
+     * Wait between ticks. MUST return early when `signal` aborts — otherwise a
+     * SIGTERM arriving mid-sleep is not noticed until the full interval elapses,
+     * and systemd force-kills the process instead of it stopping cooperatively.
+     */
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now: () => Date;
+    log: (line: string) => void;
+    /**
+     * Record that a heartbeat actually LANDED. Called only after a successful
+     * publish — never on failure, or the freshness signal it feeds would always
+     * read fresh and be worth nothing.
+     */
+    onPublished?: (payload: SessionsHeartbeatPayload) => Promise<void>;
+}
+export interface HeartbeatLoopOptions {
+    /** Emit a single heartbeat and return. */
+    once?: boolean;
+    /** Cadence between ticks. Defaults to {@link DEFAULT_HEARTBEAT_INTERVAL_SECONDS}. */
+    intervalSeconds?: number;
+    /** Home directory to scan (defaults to the process HOME). */
+    home?: string;
+    /** Print each published payload as JSON. */
+    json?: boolean;
+    /** Stop the loop cooperatively. */
+    signal?: AbortSignal;
+    /** Bound the loop — used by tests; production runs until aborted. */
+    maxTicks?: number;
+}
+/**
+ * Resolve the cadence from the flag, then the environment, then the default.
+ * Floored at 1s: a sub-second cadence hammers the fabric for no benefit, and a
+ * zero/negative value would spin the loop hot.
+ */
+export declare function resolveIntervalSeconds(flag: string | undefined, env?: NodeJS.ProcessEnv): number;
+/**
+ * Where the box records its last LANDED heartbeat. The post-provision audit
+ * reads this file's freshness, because "systemd says the unit is active" is not
+ * evidence that anything was published — that gap is what let a heartbeat fail
+ * every five seconds for nine days while every dashboard stayed green.
+ *
+ * Lives under the service user's home so the unit (User=ec2-user) can write it
+ * without extra tmpfiles.d wiring; the SSM collector reads it as root.
+ */
+export declare const DEFAULT_HEARTBEAT_STATE_FILE: string;
+/** Persist the liveness marker the box audit reads. */
+export declare function writeHeartbeatState(path: string, payload: SessionsHeartbeatPayload): Promise<void>;
+/**
+ * Run the heartbeat loop. Returns the number of ticks performed.
+ *
+ * A "tick" is one attempt, whether or not it published — the count is the
+ * loop's liveness, not its success rate.
+ */
+export declare function runHeartbeatLoop(options: HeartbeatLoopOptions, deps: HeartbeatLoopDeps): Promise<number>;
+/** Wire the production dependencies and register the subcommand. */
+export declare function registerHeartbeatCommand(outposts: Command): void;
+//# sourceMappingURL=outposts-heartbeat.d.ts.map

package/dist/commands/outposts-heartbeat.js

@@ -0,0 +1,188 @@
+/**
+ * `hq outposts heartbeat` — publish this box's agent-session summary to the
+ * realtime fabric.
+ *
+ * Runs ON an Outpost, under systemd. It enumerates the box's local Claude Code
+ * and Codex sessions with cheap scandir + stat + bounded reads, projects them
+ * down to the compact secret-free `AgentSession[]` payload, and publishes to
+ * `hq/{personUid}/sessions` so Mission Control can see what the box is doing.
+ *
+ * ## Why the cadence lives in here
+ *
+ * The original box-side design was a bash `while` loop that, every 5 seconds,
+ * ran `hq auth refresh` and then `npx -y --package=@indigoai-us/hq-cloud@latest
+ * outpost-session-heartbeat-runner`. That is ~35k process launches a day, and
+ * every `npx` re-resolves the package and re-reads it off disk — on a t3 box
+ * whose EBS budget is the scarce resource, that is a meaningful, permanent tax
+ * for a job that should be nearly free.
+ *
+ * So the loop lives in-process instead:
+ *   - identity is resolved ONCE per process, not once per tick;
+ *   - the Cognito session refreshes itself on demand (`ensureCognitoToken`
+ *     returns the cached token until it is close to expiry), so there is no
+ *     separate per-tick `hq auth refresh`;
+ *   - the IoT client is cached across ticks by the publisher and only rebuilt
+ *     when its credentials near expiry.
+ *
+ * The loop is deliberately unkillable-by-transients: a failed publish, a failed
+ * enumeration, or a not-yet-warm session are all logged and retried on the next
+ * tick. Nothing here should ever take the service down, because a service that
+ * exits looks identical to a service that is quietly failing.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
+import { resolveCallerPersonUid } from "../utils/vault-api.js";
+import { DEFAULT_HEARTBEAT_INTERVAL_SECONDS, collectSessions, nodeFileSystem, sessionsTopicForPerson, } from "../outpost/session-heartbeat.js";
+import { createIotPublishPort, defaultRealtimeCredentialsFetcher, } from "../outpost/session-heartbeat-publisher.js";
+/**
+ * Resolve the cadence from the flag, then the environment, then the default.
+ * Floored at 1s: a sub-second cadence hammers the fabric for no benefit, and a
+ * zero/negative value would spin the loop hot.
+ */
+export function resolveIntervalSeconds(flag, env = process.env) {
+    for (const raw of [flag, env.OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS]) {
+        if (raw === undefined || raw === null || raw === "")
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed))
+            return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
+        return Math.max(1, parsed);
+    }
+    return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
+}
+/**
+ * Where the box records its last LANDED heartbeat. The post-provision audit
+ * reads this file's freshness, because "systemd says the unit is active" is not
+ * evidence that anything was published — that gap is what let a heartbeat fail
+ * every five seconds for nine days while every dashboard stayed green.
+ *
+ * Lives under the service user's home so the unit (User=ec2-user) can write it
+ * without extra tmpfiles.d wiring; the SSM collector reads it as root.
+ */
+export const DEFAULT_HEARTBEAT_STATE_FILE = join(homedir(), ".hq", "outpost-session-heartbeat.json");
+/** Persist the liveness marker the box audit reads. */
+export async function writeHeartbeatState(path, payload) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({
+        lastPublishAt: payload.emittedAt,
+        sessions: payload.sessions.length,
+    })}\n`, "utf8");
+}
+/** Structured one-line log — journald gets JSON, not prose. */
+function logLine(step, outcome, extra, now) {
+    return JSON.stringify({
+        service: "outpost-session-heartbeat",
+        step,
+        outcome,
+        ...extra,
+        timestamp: now().toISOString(),
+    });
+}
+/**
+ * Run the heartbeat loop. Returns the number of ticks performed.
+ *
+ * A "tick" is one attempt, whether or not it published — the count is the
+ * loop's liveness, not its success rate.
+ */
+export async function runHeartbeatLoop(options, deps) {
+    const intervalMs = (options.intervalSeconds ?? DEFAULT_HEARTBEAT_INTERVAL_SECONDS) * 1000;
+    const maxTicks = options.once ? 1 : options.maxTicks;
+    // Resolved once and reused. Re-resolving per tick was the original sin.
+    let personUid = null;
+    let ticks = 0;
+    for (;;) {
+        ticks += 1;
+        try {
+            if (!personUid)
+                personUid = await deps.getPersonUid();
+            const payload = await collectSessions({ personUid, home: options.home, now: deps.now }, { fs: deps.fs });
+            const topic = sessionsTopicForPerson(personUid);
+            await deps.publish(topic, payload);
+            // Ordering matters: the marker is written only once the publish has
+            // resolved, so a stale marker means "nothing landed", not "nothing ran".
+            await deps.onPublished?.(payload);
+            if (options.json)
+                deps.log(JSON.stringify(payload));
+            deps.log(logLine("publish", "ok", { topic, sessions: payload.sessions.length }, deps.now));
+        }
+        catch (err) {
+            // Every failure mode lands here on purpose: a transient must never take
+            // the service down, because systemd restarting a hot-failing loop looks
+            // exactly like a healthy one.
+            deps.log(logLine("tick", "error", { message: err instanceof Error ? err.message : String(err) }, deps.now));
+        }
+        if (options.once)
+            break;
+        if (maxTicks !== undefined && ticks >= maxTicks)
+            break;
+        if (options.signal?.aborted)
+            break;
+        await deps.sleep(intervalMs, options.signal);
+        if (options.signal?.aborted)
+            break;
+    }
+    return ticks;
+}
+/** Wire the production dependencies and register the subcommand. */
+export function registerHeartbeatCommand(outposts) {
+    outposts
+        .command("heartbeat", { hidden: true })
+        .description("Publish this box's agent-session summary to the realtime fabric (runs on the Outpost, under systemd)")
+        .option("--once", "Emit a single heartbeat and exit")
+        .option("--interval <seconds>", "Cadence in seconds (default 5; env OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS)")
+        .option("--home <path>", "Home directory to scan for sessions")
+        .option("--api-base-url <url>", "HQ API base URL")
+        .option("--state-file <path>", `Liveness marker read by the box audit (default ${DEFAULT_HEARTBEAT_STATE_FILE})`)
+        .option("--json", "Print each published payload as JSON")
+        .action(async (opts) => {
+        const apiBaseUrl = opts.apiBaseUrl ??
+            process.env.HQAPI_BASE_URL ??
+            DEFAULT_VAULT_API_URL;
+        const getJwt = () => ensureCognitoToken({ interactive: false });
+        const deps = {
+            fs: nodeFileSystem,
+            publish: createIotPublishPort({
+                fetchCredentials: defaultRealtimeCredentialsFetcher({
+                    apiBaseUrl,
+                    getJwt,
+                }),
+            }),
+            // Same base as the credentials fetch. Resolving identity against the
+            // default plane while vending credentials from another sends a
+            // deployment-specific token to the wrong control plane, which is
+            // rejected — and the loop then retries forever without publishing.
+            getPersonUid: async () => resolveCallerPersonUid(await getJwt(), apiBaseUrl),
+            sleep: (ms, signal) => new Promise((resolve) => {
+                if (signal?.aborted)
+                    return resolve();
+                const t = setTimeout(done, ms);
+                function done() {
+                    clearTimeout(t);
+                    signal?.removeEventListener("abort", done);
+                    resolve();
+                }
+                signal?.addEventListener("abort", done, { once: true });
+            }),
+            now: () => new Date(),
+            log: (line) => console.error(line),
+            onPublished: (payload) => writeHeartbeatState(opts.stateFile ?? DEFAULT_HEARTBEAT_STATE_FILE, payload),
+        };
+        // systemd sends SIGTERM on stop/restart — finish the in-flight tick,
+        // then exit cleanly rather than being killed mid-publish.
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once("SIGTERM", stop);
+        process.once("SIGINT", stop);
+        await runHeartbeatLoop({
+            once: opts.once,
+            intervalSeconds: resolveIntervalSeconds(opts.interval),
+            home: opts.home,
+            json: opts.json,
+            signal: controller.signal,
+        }, deps);
+    });
+}
+//# sourceMappingURL=outposts-heartbeat.js.map

package/dist/commands/outposts.js

@@ -31,6 +31,7 @@ import * as yaml from "js-yaml";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { registerHeartbeatCommand } from "./outposts-heartbeat.js";
 import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
 export function parseCappedPayload(body) {
@@ -738,6 +739,8 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     const outposts = program
         .command("outposts")
         .description("Manage your personal HQ Outposts (EC2 boxes)");
+    // On-box session heartbeat (systemd). Hidden — operators never run it.
+    registerHeartbeatCommand(outposts);
     outposts
         .command("self-deploy", { hidden: true })
         .description("Configure this EC2 host as a locally self-hosted HQ outpost")

package/dist/commands/pack-install.js

@@ -1613,6 +1613,15 @@ export function runScanPackages(hqRoot, opts = {}) {
     }
 }
 export async function installPack(source, opts = {}) {
+    // NOTE: the HQ_API_KEY fail-closed gate is NOT enforced here. `installPack`
+    // is a shared primitive called both by the top-level `hq install` CLI route
+    // (where Cognito-only is the right gate — checked there instead) AND by
+    // `hq packs update` (packs.ts:runUpdate), which un-wires an existing pack's
+    // contributions BEFORE re-installing. Throwing from inside `installPack`
+    // would leave an update mid-flight (unwired, not reinstalled) whenever
+    // HQ_API_KEY happened to be set. Restricting the assertion to the install
+    // entrypoint keeps `hq packs update` fail-closed at its own call site
+    // instead (checked before it un-wires anything).
     const transport = classify(source);
     const hqRoot = findHqRoot();
     // `readHqVersion` (shared with `hq packs`) reads the CANONICAL

package/dist/commands/pkg-install.js

@@ -23,6 +23,7 @@ import { resolveDefaultHqRoot } from '../utils/cognito-session.js';
 import { getRegistryUrl, RegistryClient, } from '../utils/registry-client.js';
 import { verifySha256, verifyRsaSignature } from '../utils/integrity.js';
 import { addToRegistry } from '../utils/registry.js';
+import { assertCognitoOnlyCommand } from '../utils/resolve-vault-credential.js';
 import { MARKETPLACE_PREFIX, installPack, sourceMatchesPackPattern, } from './pack-install.js';
 export function registerPackageInstallCommand(parent) {
     parent
@@ -35,6 +36,11 @@ export function registerPackageInstallCommand(parent) {
         .option('--branch', 'Follow a ref instead of SHA-pinning (git content-pack flow)')
         .action(async (source, opts) => {
         try {
+            // Gate the top-level `hq install` entrypoint only — `installPack`
+            // itself is also called by `hq packs update` (packs.ts), which must
+            // stay able to fail closed at its OWN call site (before it un-wires
+            // an existing pack) rather than mid-flight inside installPack.
+            assertCognitoOnlyCommand('hq install');
             if (sourceMatchesPackPattern(source)) {
                 await installPack(source, {
                     company: opts.company,

package/dist/commands/run.js

@@ -3,6 +3,7 @@ import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { internal } from 'varlock';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
+import { peekHqApiKey } from '../utils/resolve-vault-credential.js';
 import { computeSha256 } from '../utils/integrity.js';
 import { vaultApiFetch, getCompanyUid } from '../utils/vault-api.js';
 import { discoverSchemas } from '../run/discover-schemas.js';
@@ -38,6 +39,9 @@ export function registerRunCommand(program) {
         .allowUnknownOption(true)
         .action(async (opts) => {
         try {
+            if (peekHqApiKey() !== undefined) {
+                throw new Error('HQ_API_KEY is set; `hq run` requires a Cognito session. Unset HQ_API_KEY or use `hq secrets exec`.');
+            }
             const dashIndex = process.argv.indexOf('--');
             const childArgs = dashIndex !== -1 ? process.argv.slice(dashIndex + 1) : [];
             if (!opts.check && childArgs.length === 0) {

package/dist/commands/secrets.js

@@ -732,6 +732,11 @@ export function registerSecretsCommand(program) {
         try {
             const cred = await resolveVaultCredential();
             if (cred.kind === "api-key") {
+                if (!opts.reveal) {
+                    console.error(chalk.red("HQ_API_KEY is set; `hq secrets get` without --reveal is not supported for API keys. " +
+                        "Use --reveal to fetch the value, or unset HQ_API_KEY for metadata-only reads."));
+                    process.exit(1);
+                }
                 const res = await vaultApiFetch({
                     token: cred.token,
                     path: "/v1/keys/secrets/fetch",

package/dist/outpost/session-heartbeat-publisher.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 } from "@aws-sdk/client-iot-data-plane";
+import type { PublishPort } from "./session-heartbeat.js";
+import { 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 declare const DEFAULT_CREDENTIALS_TIMEOUT_MS = 10000;
+/**
+ * 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 declare function defaultRealtimeCredentialsFetcher(opts: {
+    apiBaseUrl: string;
+    getJwt: () => Promise<string>;
+    fetchImpl?: typeof fetch;
+    /** Bound the request. Defaults to {@link DEFAULT_CREDENTIALS_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}): RealtimeCredentialsFetcher;
+/**
+ * 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 declare function createIotPublishPort(opts: {
+    fetchCredentials: RealtimeCredentialsFetcher;
+    makeClient?: (args: {
+        endpoint: string;
+        region: string;
+        credentials: RealtimeCredentialsResponse["credentials"];
+    }) => IoTDataPlaneClient;
+    now?: () => Date;
+}): PublishPort;
+/** Re-export for the runner so it imports one module. */
+export { sessionsTopicForPerson };
+//# sourceMappingURL=session-heartbeat-publisher.d.ts.map

package/dist/outpost/session-heartbeat-publisher.js

@@ -0,0 +1,117 @@
+/**
+ * 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 { assertNoSecretsInPayload, sessionsTopicForPerson, } from "./session-heartbeat.js";
+/** 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) {
+    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());
+    };
+}
+/**
+ * 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) {
+    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 = 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() {
+        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, payload) => {
+        // 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 };
+//# sourceMappingURL=session-heartbeat-publisher.js.map