@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/context.ts

@@ -1,378 +0,0 @@
-/**
- * Entity context resolution (VLT-5 US-001).
- *
- * Resolves an entity (company) via vault-service, vends STS-scoped credentials,
- * and returns an EntityContext for S3 operations. Handles auto-refresh when
- * credentials are within 2 minutes of expiry.
- */
-
-import type { EntityContext, VaultServiceConfig } from "./types.js";
-import { buildClientHeaders } from "./client-info.js";
-
-/** Minimum remaining TTL before auto-refresh triggers (2 minutes). */
-const REFRESH_THRESHOLD_MS = 2 * 60 * 1000;
-
-/** STS session duration requested from vault-service (15 minutes). */
-const DEFAULT_SESSION_DURATION_SECONDS = 900;
-
-/**
- * `expiresAt` stamped on a presign-only company context (HQ-59). No STS vend
- * happened, so there is nothing to expire — a far-future sentinel keeps
- * `isExpiringSoon` false forever, so the auto-refresh path never re-vends (and
- * thus never re-hits) the company `/sts/vend` route the gate keys on.
- */
-const PRESIGN_NO_VEND_EXPIRES_AT = "9999-12-31T23:59:59.000Z";
-
-/**
- * Cached contexts.
- *
- * Two keying schemes share the map:
- *   - UID keys: bare `cmp_xxx` / `prs_xxx`. Globally unique by ULID, so
- *     the cached context is safe to return to any caller asking by uid.
- *   - Slug keys: `slug:${callerSub}#${slug}`. Under the per-user-namespace
- *     model on hq-pro (PR 67, live 2026-05-15), the same slug can
- *     legitimately resolve to different company UIDs for different
- *     callers. Keying slug entries by `(callerSub, slug)` prevents one
- *     caller's resolution from being served to another caller against
- *     the wrong tenant. Codex flagged this as a P1 on PR 67's hq-cloud
- *     follow-up.
- */
-const contextCache = new Map<string, EntityContext>();
-
-/**
- * Extract the Cognito sub claim from a JWT without verifying the
- * signature. We don't need verification here — the token already
- * authorized the upstream API call; we're only using `sub` as a
- * per-caller cache discriminator. If the token is malformed or
- * missing a sub, fall back to a hash of the whole token (slightly
- * larger key space, same correctness — different tokens still
- * get distinct cache entries).
- */
-function callerKeyFromAccessToken(accessToken: string): string {
-  const parts = accessToken.split(".");
-  if (parts.length === 3) {
-    try {
-      // base64url decode (Node-compatible, no padding required)
-      const padded = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-      const payload = Buffer.from(padded, "base64").toString("utf8");
-      const claims = JSON.parse(payload) as { sub?: unknown };
-      if (typeof claims.sub === "string" && claims.sub.length > 0) {
-        return claims.sub;
-      }
-    } catch {
-      // fall through to token-hash fallback
-    }
-  }
-  // Stable fallback — same token → same key, different tokens → different keys.
-  // (Avoids importing crypto for a sha; the raw token suffix is sufficient as
-  // a cache discriminator and isn't exposed outside this process.)
-  return `tok:${accessToken.slice(-32)}`;
-}
-
-function slugCacheKey(callerKey: string, slug: string): string {
-  return `slug:${callerKey}#${slug}`;
-}
-
-/**
- * Closed-set of recognised entity-UID prefixes. Adding a new entity type
- * means appending one entry here AND extending the dispatch in
- * `resolveEntityContext` (cmp_ → /sts/vend, prs_/agt_ → /sts/vend-self).
- *
- * `agt_` (US-013, unblocks US-004): a headless agent box syncs its OWN
- * personal overlay via `hq-sync-runner --personal`, which resolves the
- * agent's own entity (`agt_*`, bucket `hq-vault-agt-<uid>`). Without `agt_`
- * here an agt_ uid is mistaken for a SLUG and routed through the company
- * by-slug lookup; with it, the uid is recognised and self-vended below.
- */
-export const KNOWN_UID_PREFIXES = ["cmp_", "prs_", "agt_"] as const;
-
-/**
- * Look up an entity by slug or UID via vault-service, then vend STS-scoped
- * credentials for that entity. Returns an EntityContext ready for S3 ops.
- *
- * Caches the result and auto-refreshes when the credentials are within
- * 2 minutes of expiry.
- *
- * HQ-59: when `config.companyVaultUsesPresign` is set, COMPANY (`cmp_*`)
- * contexts skip the `POST /sts/vend` call and come back credential-less with a
- * far-future expiry — the presign transport needs no STS creds, and skipping
- * the vend keeps a compliant sync-runner off the company vend route. Personal
- * (`prs_*`) contexts always vend self.
- */
-export async function resolveEntityContext(
-  companyUidOrSlug: string,
-  config: VaultServiceConfig,
-): Promise<EntityContext> {
-  // Step 0: Determine whether the input is a UID (globally unique) or a
-  // slug (per-caller). The cache key differs accordingly — see the
-  // `contextCache` jsdoc.
-  const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
-    companyUidOrSlug.startsWith(p),
-  );
-  // Self-vend covers BOTH person (`prs_`) and agent (`agt_`) entities — each
-  // owns a personal vault gated by self-ownership at `POST /sts/vend-self`,
-  // not the membership-gated company `POST /sts/vend`. (US-013, unblocks
-  // US-004: an agent box self-vends its own `hq-vault-agt-<uid>` vault.)
-  const looksLikePerson =
-    companyUidOrSlug.startsWith("prs_") || companyUidOrSlug.startsWith("agt_");
-
-  // For slug lookups, scope the cache key by the caller. Resolving the
-  // access token here (once) doubles as a way to extract the sub for
-  // the key — same hop the downstream fetch makes anyway.
-  let cacheKey: string;
-  let callerKey: string | null = null;
-  if (looksLikeUid) {
-    cacheKey = companyUidOrSlug;
-  } else {
-    const token = await resolveAuthToken(config);
-    callerKey = callerKeyFromAccessToken(token);
-    cacheKey = slugCacheKey(callerKey, companyUidOrSlug);
-  }
-
-  // Check cache — return if credentials still fresh.
-  const cached = contextCache.get(cacheKey);
-  if (cached && !isExpiringSoon(cached.expiresAt)) {
-    return cached;
-  }
-
-  // Step 1: Resolve entity — direct fetch by UID or namespace lookup by slug.
-  const entity = looksLikeUid
-    ? await fetchEntity(companyUidOrSlug, config)
-    : await fetchEntityBySlug("company", companyUidOrSlug, config);
-
-  if (!entity.bucketName) {
-    throw new Error(
-      `Entity ${entity.uid} (${entity.slug}) has no bucket provisioned. ` +
-      `Run VLT-2 bucket provisioning first.`,
-    );
-  }
-
-  // Step 2: Dispatch credential vending by RESOLVED-uid prefix.
-  //   cmp_*        → POST /sts/vend      (company path; membership-gated)
-  //   prs_* / agt_* → POST /sts/vend-self (self path; self-ownership-gated)
-  //   slug         → resolves to a cmp_* (the slug path is company-only)
-  //
-  // HQ-59 vend-skip: when the run uses the presigned-URL transport for company
-  // vaults, a `cmp_*` context needs no STS creds (the presign transport
-  // authorizes every object server-side) AND a compliant sync-runner must not
-  // call the company `/sts/vend` route at all — its mere presence is the
-  // pre-6.11.6 signal the hq-pro min-version gate denies on. So skip the vend
-  // entirely and return a credential-less context with a sentinel expiry. The
-  // discriminator is the RESOLVED entity uid (`cmp_`), the exact same prefix
-  // `presignObjectIOFactory` uses to route to `PresignObjectIO` — so the
-  // vend-skip and the transport choice can never disagree. Personal vaults
-  // (`prs_*`) always vend self.
-  const isCompanyEntity = entity.uid.startsWith("cmp_");
-  const skipCompanyVend =
-    config.companyVaultUsesPresign === true && isCompanyEntity;
-
-  let ctx: EntityContext;
-  if (skipCompanyVend) {
-    ctx = {
-      uid: entity.uid,
-      slug: entity.slug,
-      bucketName: entity.bucketName,
-      region: config.region ?? "us-east-1",
-      // No STS vend on the presign path — see PRESIGN_NO_VEND_EXPIRES_AT.
-      credentials: undefined,
-      expiresAt: PRESIGN_NO_VEND_EXPIRES_AT,
-    };
-  } else {
-    const vendResult = looksLikePerson
-      ? await vendSelfCredentials(entity.uid, config)
-      : await vendCredentials(entity.uid, config);
-
-    ctx = {
-      uid: entity.uid,
-      slug: entity.slug,
-      bucketName: entity.bucketName,
-      region: config.region ?? "us-east-1",
-      credentials: {
-        accessKeyId: vendResult.credentials.accessKeyId,
-        secretAccessKey: vendResult.credentials.secretAccessKey,
-        sessionToken: vendResult.credentials.sessionToken,
-      },
-      expiresAt: vendResult.expiresAt,
-    };
-  }
-
-  // Cache by UID (globally unique) and — if the caller asked by slug —
-  // by `(callerSub, slug)` so the same slug can resolve to different
-  // entities per caller without cross-caller poisoning.
-  contextCache.set(entity.uid, ctx);
-  if (callerKey) {
-    contextCache.set(slugCacheKey(callerKey, entity.slug), ctx);
-  }
-
-  return ctx;
-}
-
-/**
- * Check if credentials are expiring within the refresh threshold.
- */
-export function isExpiringSoon(expiresAt: string): boolean {
-  const expiryMs = new Date(expiresAt).getTime();
-  const nowMs = Date.now();
-  return expiryMs - nowMs < REFRESH_THRESHOLD_MS;
-}
-
-/**
- * Force-refresh a cached context. Useful when an S3 operation fails with
- * an expired credentials error.
- */
-export async function refreshEntityContext(
-  companyUidOrSlug: string,
-  config: VaultServiceConfig,
-): Promise<EntityContext> {
-  // Evict the entry under whichever key shape applies. UID inputs key
-  // the cache by the bare uid; slug inputs key by `(callerSub, slug)`.
-  const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
-    companyUidOrSlug.startsWith(p),
-  );
-  if (looksLikeUid) {
-    contextCache.delete(companyUidOrSlug);
-  } else {
-    const token = await resolveAuthToken(config);
-    const callerKey = callerKeyFromAccessToken(token);
-    contextCache.delete(slugCacheKey(callerKey, companyUidOrSlug));
-  }
-  return resolveEntityContext(companyUidOrSlug, config);
-}
-
-/**
- * Clear the entire context cache. Useful for tests.
- */
-export function clearContextCache(): void {
-  contextCache.clear();
-}
-
-// ---------------------------------------------------------------------------
-// Vault-service API calls
-// ---------------------------------------------------------------------------
-
-interface EntityResponse {
-  uid: string;
-  slug: string;
-  bucketName?: string;
-  status: string;
-}
-
-interface VendResponse {
-  credentials: {
-    accessKeyId: string;
-    secretAccessKey: string;
-    sessionToken: string;
-    expiration: string;
-  };
-  expiresAt: string;
-}
-
-/**
- * Resolve the current bearer token from a VaultServiceConfig. Accepts either
- * a static string (back-compat with short-lived tools) or an async getter
- * (long-running callers like `hq-sync-runner` pass `() => getValidAccessToken(...)`
- * so each request picks up token refreshes that landed in
- * `~/.hq/cognito-tokens.json` since the run started).
- */
-async function resolveAuthToken(config: VaultServiceConfig): Promise<string> {
-  return typeof config.authToken === "function"
-    ? config.authToken()
-    : config.authToken;
-}
-
-async function fetchEntity(
-  uid: string,
-  config: VaultServiceConfig,
-): Promise<EntityResponse> {
-  const res = await fetch(`${config.apiUrl}/entity/${uid}`, {
-    headers: {
-      Authorization: `Bearer ${await resolveAuthToken(config)}`,
-      ...buildClientHeaders(config.clientInfo),
-    },
-  });
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Failed to fetch entity ${uid}: ${res.status} ${body}`);
-  }
-  const data = (await res.json()) as { entity: EntityResponse };
-  return data.entity;
-}
-
-async function fetchEntityBySlug(
-  type: string,
-  slug: string,
-  config: VaultServiceConfig,
-): Promise<EntityResponse> {
-  // Resolve the slug inside the CALLER's namespace via the new
-  // `/entity/check-slug/me` endpoint added in hq-pro PR 67 (live
-  // in prod 2026-05-15). Under the per-user-namespace model the
-  // legacy `/entity/by-slug/{type}/{slug}` either over-matches
-  // (returns another tenant's entity when more than one user holds
-  // the slug) or 409s with SlugNotUniqueError — both wrong for the
-  // sync runner's "I want MY company" intent.
-  const checkUrl = `${config.apiUrl}/entity/check-slug/me?type=${encodeURIComponent(type)}&slug=${encodeURIComponent(slug)}`;
-  const checkRes = await fetch(checkUrl, {
-    headers: {
-      Authorization: `Bearer ${await resolveAuthToken(config)}`,
-      ...buildClientHeaders(config.clientInfo),
-    },
-  });
-  if (!checkRes.ok) {
-    const body = await checkRes.text();
-    throw new Error(
-      `Failed to check slug ${type}/${slug}: ${checkRes.status} ${body}`,
-    );
-  }
-  const check = (await checkRes.json()) as {
-    available: boolean;
-    conflictingCompanyUid?: string;
-  };
-  if (check.available || !check.conflictingCompanyUid) {
-    // The slug isn't in the caller's namespace. From the sync
-    // runner's perspective this is a genuine "not found" — the
-    // caller doesn't have a `${slug}` to sync, even if some other
-    // user does.
-    throw new Error(
-      `No entity in caller's namespace matches ${type}/${slug}. ` +
-        `If you expected to find one, verify you're signed in to the right HQ identity.`,
-    );
-  }
-  return fetchEntity(check.conflictingCompanyUid, config);
-}
-
-async function postVend(
-  route: string,
-  body: Record<string, unknown>,
-  config: VaultServiceConfig,
-): Promise<VendResponse> {
-  const res = await fetch(`${config.apiUrl}${route}`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${await resolveAuthToken(config)}`,
-      ...buildClientHeaders(config.clientInfo),
-    },
-    body: JSON.stringify({ ...body, durationSeconds: DEFAULT_SESSION_DURATION_SECONDS }),
-  });
-  if (!res.ok) {
-    const text = await res.text();
-    throw new Error(`STS ${route} failed: ${res.status} ${text}`);
-  }
-  return (await res.json()) as VendResponse;
-}
-
-async function vendCredentials(
-  companyUid: string,
-  config: VaultServiceConfig,
-): Promise<VendResponse> {
-  return postVend("/sts/vend", { companyUid }, config);
-}
-
-async function vendSelfCredentials(
-  personUid: string,
-  config: VaultServiceConfig,
-): Promise<VendResponse> {
-  // Use `+` concat at the literal so guard 5 (grep "/sts/vend-self") still finds it
-  const route = "/sts/vend-self";
-  return postVend(route, { personUid }, config);
-}

package/src/daemon-worker.ts

@@ -1,26 +0,0 @@
-/**
- * Daemon worker — runs as a detached child process
- * Watches HQ directory and syncs changes to S3
- *
- * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
- * When re-enabled, this worker will need to resolve an EntityContext before
- * constructing the active watcher/runner path. The process argv will need to
- * include company context (slug or UID) and vault-service config.
- */
-
-// Day 1: this worker still requires EntityContext-aware startup wiring.
-// This file is retained for the automatic-sync milestone but is not functional
-// until the daemon startup path is updated to resolve entity context.
-
-const hqRoot = process.argv[2];
-
-if (!hqRoot) {
-  console.error("Usage: daemon-worker <hq-root>");
-  process.exit(1);
-}
-
-console.error(
-  "Day 1: daemon-worker is not yet wired to entity context resolution. " +
-  "Use 'hq share' and 'hq sync' for manual sync.",
-);
-process.exit(1);

package/src/daemon.ts

@@ -1,99 +0,0 @@
-/**
- * Background sync daemon management
- * Manages a child process that runs the file watcher
- *
- * Day 1: not invoked by CLI surface; retained for future automatic-sync milestone.
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { fork } from "child_process";
-import { fileURLToPath } from "url";
-import type { DaemonState } from "./types.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-function getPidFile(hqRoot: string): string {
-  return path.join(hqRoot, ".hq-sync.pid");
-}
-
-function getStateFile(hqRoot: string): string {
-  return path.join(hqRoot, ".hq-sync-daemon.json");
-}
-
-export function isDaemonRunning(hqRoot: string): boolean {
-  const pidFile = getPidFile(hqRoot);
-  if (!fs.existsSync(pidFile)) return false;
-
-  const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
-  try {
-    // signal 0 tests if process exists without killing it
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    // Process not running, clean up stale PID file
-    fs.unlinkSync(pidFile);
-    return false;
-  }
-}
-
-export function startDaemon(hqRoot: string): void {
-  if (isDaemonRunning(hqRoot)) {
-    console.log("  Sync daemon is already running.");
-    return;
-  }
-
-  const workerScript = path.join(__dirname, "daemon-worker.js");
-
-  const child = fork(workerScript, [hqRoot], {
-    detached: true,
-    stdio: "ignore",
-  });
-
-  child.unref();
-
-  if (child.pid) {
-    // Write PID file
-    fs.writeFileSync(getPidFile(hqRoot), String(child.pid));
-
-    // Write state
-    const state: DaemonState = {
-      pid: child.pid,
-      startedAt: new Date().toISOString(),
-      hqRoot,
-    };
-    fs.writeFileSync(getStateFile(hqRoot), JSON.stringify(state, null, 2));
-  }
-}
-
-export function stopDaemon(hqRoot: string): void {
-  const pidFile = getPidFile(hqRoot);
-  if (!fs.existsSync(pidFile)) {
-    console.log("  No sync daemon running.");
-    return;
-  }
-
-  const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
-  try {
-    process.kill(pid, "SIGTERM");
-  } catch {
-    // Already dead
-  }
-
-  // Clean up files
-  if (fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
-  const stateFile = getStateFile(hqRoot);
-  if (fs.existsSync(stateFile)) fs.unlinkSync(stateFile);
-}
-
-export function getDaemonState(hqRoot: string): DaemonState | null {
-  const stateFile = getStateFile(hqRoot);
-  if (!fs.existsSync(stateFile)) return null;
-  try {
-    const content = fs.readFileSync(stateFile, "utf-8");
-    return JSON.parse(content) as DaemonState;
-  } catch {
-    return null;
-  }
-}