@indigoai-us/hq-cloud 6.11.14 → 6.11.16

package/src/bin/sync-runner.test.ts

@@ -33,6 +33,7 @@ import type {
 } from "./sync-runner.js";
 import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
+import { HQ_CLOUD_VERSION } from "../version.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
@@ -4689,3 +4690,415 @@ describe("runRunner — companyVaultUsesPresign flag", () => {
     expect(capturedConfig?.companyVaultUsesPresign).toBe(false);
   });
 });
+
+// ===========================================================================
+// US-004 — HARD GATE: `--personal` for an AGENT machine identity
+// ===========================================================================
+//
+// Phase-2 of agent-personal-overlay-sync vendors `@indigoai-us/hq-cloud@latest`
+// onto each headless agent box and runs `hq-sync-runner --personal` to sync the
+// agent's own personal overlay. US-001..US-003 proved the PERSON-entity (prs_*)
+// `--personal` path (feat/secrets-personal-entities). This block exercises the
+// genuinely-unverified AGENT-entity (agt_*) delta.
+//
+// ╔═══════════════════════════════════════════════════════════════════════╗
+// ║ HARD-GATE RESULT: UNBLOCKED by US-013 (agent-aware --personal).        ║
+// ║ The agent --personal READ is now reachable in the runner: the agent's  ║
+// ║ own entity (type:"agent") is selected for the personal slot by the     ║
+// ║ agent-aware resolver (pickAgentSelfEntity), `agt_` is a known UID       ║
+// ║ prefix, and an agt_ uid vends via /sts/vend-self — so `--personal` for  ║
+// ║ an agent emits a fanout-plan + calls syncFn for hq-vault-agt-<uid>      ║
+// ║ instead of setup-needed. The READ-AUTHORIZATION gate (section 2) stays  ║
+// ║ PROVEN-via-mock. The LIVE GetObject proof remains a gated operator step ║
+// ║ (no real AWS in this build). See section (1) for what changed.         ║
+// ╚═══════════════════════════════════════════════════════════════════════╝
+//
+//   (1) RESOLUTION  — when the runner runs as an agent machine identity
+//       (username `machine-agt_*`, ID-token claims custom:entityType=agent /
+//       custom:entityUid=agt_*) the `--personal` fanout resolves the sync
+//       target to the agent's OWN bucket `hq-vault-agt-<uid>` under the
+//       reserved journal slug `__hq_personal_vault__`. US-013 wired this:
+//       pickAgentSelfEntity selects the agent's own entity (was: dropped by
+//       person-only pickCanonicalPersonEntity), and context.ts recognises
+//       `agt_` + routes it to /sts/vend-self.
+//
+//   (2) AUTHORIZATION — resolution != authorization. The STS vend gate looked
+//       company-scoped (resolveEntityContext historically only knew cmp_ /
+//       prs_), so this asserts — via a faithful vend gate where a real denial
+//       fails the test — that the agent's vended S3 credentials WOULD
+//       authorize a GetObject under its own personal-vault prefix once vend
+//       routing reaches /sts/vend-self for the agent.
+//
+//   (3) SAFETY RAILS — `--personal` mutually exclusive with `--companies`; the
+//       vaultConfig carries the authToken *getter* (re-resolved per request) so
+//       a long pass survives STS expiry; and a version-floor assertion confirms
+//       the runner reports >= the first `--personal`-supporting release so
+//       US-007/US-009 cannot silently no-op the flag.
+//
+// ── LIVE-PROOF (gated operator step — NOT run here) ────────────────────────
+// This block is BUILD-ONLY: no real AWS, no prod. The faithful mock below
+// proves the path mechanically. The LIVE GetObject proof against real prod
+// infra is a gated operator step. On a real provisioned agent box, run:
+//
+//   # 1. Confirm the runner is at/above the floor.
+//   hq-sync-runner --version    # (or: node dist/bin/sync-runner.js --version)
+//
+//   # 2. Run the real personal pull as the agent machine identity. With
+//   #    ~/.hq-agent/machine-creds.json present (username machine-agt_<ulid>),
+//   #    getValidAccessToken() returns the agent's ID token whose
+//   #    custom:entityType=agent / custom:entityUid=agt_<uid> claims drive the
+//   #    server-side resolution + STS vend-self.
+//   hq-sync-runner --personal --direction both --hq-root "$HOME/hq"
+//
+//   # 3. PROOF: a real GetObject under the agent's own personal/ prefix.
+//   #    Vend the agent's self creds, then read one object directly.
+//   creds=$(curl -sS -X POST "$VAULT_API/sts/vend-self" \
+//             -H "Authorization: Bearer $AGENT_ID_TOKEN" \
+//             -d "{\"personUid\":\"agt_<uid>\"}")
+//   AWS_ACCESS_KEY_ID=...    AWS_SECRET_ACCESS_KEY=...    AWS_SESSION_TOKEN=... \
+//     aws s3api get-object --bucket hq-vault-agt-<uid> \
+//       --key personal/.hq/manifest.json /dev/null   # exit 0 == READ PROVEN
+//
+// If step 3 returns AccessDenied, the agent has NO file-ACL seeding on its own
+// personal vault (provisioning/handler.ts is company-only today) and a
+// provisioning ACL grant is required — see US-004 AC#3.
+describe("US-004 — --personal for an AGENT machine identity (HARD GATE)", () => {
+  // The agent's own entity, as the vault service returns it to the agent
+  // machine identity. bucketName follows the agt_ vault naming convention
+  // (`hq-vault-agt-<uid-tail>`), the agent analogue of `hq-vault-prs-<...>`.
+  const AGENT_UID = "agt_01J9AGENTSELF0000000000000";
+  const AGENT_BUCKET = "hq-vault-agt-01J9AGENTSELF0000000000000";
+  const agentSelfEntity: EntityInfo = {
+    uid: AGENT_UID,
+    type: "agent",
+    slug: "agent-self",
+    bucketName: AGENT_BUCKET,
+    status: "active",
+  } as unknown as EntityInfo;
+
+  // ID-token claims an agent machine identity carries. On a live box these
+  // ride the ID token ONLY (see cognito-auth.ts getValidAccessToken: machine
+  // identities return the ID token, whose custom:entityType/entityUid claims
+  // the vault authorizer reads to resolve the caller as the agent).
+  const agentClaims = {
+    sub: "machine-agt_01J9AGENTSELF0000000000000",
+    email: "agt-self@agents.getindigo.ai",
+    name: "Agent Self",
+    "custom:entityType": "agent",
+    "custom:entityUid": AGENT_UID,
+  };
+
+  // -----------------------------------------------------------------------
+  // (1) RESOLUTION — UNBLOCKED by US-013.
+  //
+  // The runner's `--personal` target was built EXCLUSIVELY from
+  // `client.entity.listByType("person")` → `pickCanonicalPersonEntity()`
+  // (sync-runner.ts), which filters `e.type === "person"` (vault-client.ts).
+  // An agent's own entity is `type: "agent"`, so it was dropped and
+  // `--personal` for an agent emitted `setup-needed` without ever resolving a
+  // bucket or calling syncFn — never reaching the STS vend / S3 read.
+  //
+  // US-013 fixed all three gaps in one change:
+  //   1. RESOLUTION: when the idToken carries custom:entityType=agent, the
+  //      personal slot is resolved via pickAgentSelfEntity(selfEntities,
+  //      custom:entityUid) — the agent's OWN entity — instead of the
+  //      person-only canonical pick. (Person identities are unchanged.)
+  //   2. UID RECOGNITION: `agt_` is now in KNOWN_UID_PREFIXES (context.ts),
+  //      so an agt_ uid is fetched directly by UID (not mistaken for a slug).
+  //   3. VEND ROUTING: an agt_ uid self-vends via /sts/vend-self (the
+  //      self-ownership-gated route), alongside prs_, NOT the membership-gated
+  //      company /sts/vend.
+  //
+  // Provisioning (seed the agent a read ACL on its own personal vault —
+  // provisioning/handler.ts, US-004 AC#3) remains a separate sub-change; the
+  // LIVE GetObject proof below is the gated operator step that confirms it.
+  //
+  // These two tests now pin the SUCCESS shape (fanout-plan with bucket
+  // hq-vault-agt-<uid> / syncFn called with company=agt_<uid>). If the
+  // agent-aware resolution regresses, they go red.
+  // -----------------------------------------------------------------------
+  it("UNBLOCKED (US-013): --personal for an agent resolves its OWN vault (fanout-plan + syncFn for hq-vault-agt-<uid>)", async () => {
+    // US-013 wired agent-aware `--personal` resolution + vend-self routing,
+    // unblocking the US-004 hard gate. The agent machine identity (idToken
+    // custom:entityType=agent / custom:entityUid=agt_<uid>) now resolves the
+    // personal slot to the agent's OWN entity instead of being dropped by the
+    // person-only canonical pick. This pins the SUCCESS shape: a fanout-plan
+    // with the personal target, syncFn called once for the agent's own vault,
+    // and NO setup-needed.
+    const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
+    const deps = makeDeps({
+      sync: syncSpy as unknown as RunnerDeps["sync"],
+      getIdTokenClaims: () => agentClaims,
+      createVaultClient: () =>
+        makeVaultStub({
+          // Self-entity listing as the agent machine identity sees it: the
+          // ONLY entity is the agent's own (type: "agent").
+          listPersons: () => Promise.resolve([agentSelfEntity]),
+        }),
+    });
+
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+
+    const events = deps.stdout.events();
+    // The agent's own entity now resolves the personal slot → no setup-needed.
+    expect(events.some((e) => e.type === "setup-needed")).toBe(false);
+
+    // fanout-plan carries exactly the personal slot, resolved to the agent's
+    // OWN uid (so the downstream vend targets agt_<uid> → /sts/vend-self).
+    const plan = events.find((e) => e.type === "fanout-plan") as Extract<
+      RunnerEvent,
+      { type: "fanout-plan" }
+    >;
+    expect(plan).toBeDefined();
+    expect(plan.companies).toHaveLength(1);
+    expect(plan.companies[0]).toMatchObject({
+      slug: "personal",
+      uid: AGENT_UID,
+      bucketName: AGENT_BUCKET,
+    });
+
+    // syncFn is reached once, scoped to the agent's OWN entity uid — the value
+    // that resolveEntityContext routes to /sts/vend-self for an agt_ uid.
+    expect(syncSpy).toHaveBeenCalledTimes(1);
+    const opts = syncSpy.mock.calls[0][0] as SyncOptions;
+    expect(opts.company).toBe(AGENT_UID);
+    expect(opts.personalMode).toBe(true);
+  });
+
+  it("UNBLOCKED (US-013): pickAgentSelfEntity selects the agent's own entity for the personal slot", async () => {
+    // The agent-aware selector that replaced the person-only pick for a
+    // machine identity. Given the agent's self-listing and its claimed
+    // self-uid, it returns the agent's OWN entity (the bucket the runner
+    // resolves the personal slot to). The legacy person-only helper still
+    // (correctly) drops an agent-typed entity — the agent path no longer
+    // depends on it.
+    const { pickAgentSelfEntity, pickCanonicalPersonEntity } = await import(
+      "../vault-client.js"
+    );
+    const own = pickAgentSelfEntity([agentSelfEntity], AGENT_UID);
+    expect(own).not.toBeNull();
+    expect(own?.uid).toBe(AGENT_UID);
+    expect(own?.bucketName).toBe(AGENT_BUCKET);
+    expect(AGENT_BUCKET).toMatch(/^hq-vault-agt-/);
+    // No match for a foreign uid → null (never vends another agent's vault).
+    expect(
+      pickAgentSelfEntity([agentSelfEntity], "agt_01SOMEONEELSE000000000000000"),
+    ).toBeNull();
+    // The person-only helper still drops the agent-typed entity (unchanged) —
+    // the agent path uses the agent-aware selector instead.
+    expect(pickCanonicalPersonEntity([agentSelfEntity])).toBeNull();
+  });
+
+  // -----------------------------------------------------------------------
+  // (2) AUTHORIZATION — faithful STS-vend gate + S3 GetObject scope check.
+  //
+  // Resolution != authorization. The model below mirrors the ACTUAL server
+  // contract so a REAL denial fails this test:
+  //
+  //   • vend gate (mirrors vault-service /sts/vend-self): the gate vends
+  //     creds ONLY when the requested personUid === the caller's OWN entity
+  //     uid (self-ownership). A request for any OTHER uid is DENIED (403) —
+  //     exactly how the real route refuses to vend another principal's vault.
+  //
+  //   • the vended creds are SCOPED: the STS session policy allows
+  //     s3:GetObject on `arn:aws:s3:::<own-bucket>/personal/*` ONLY. The S3
+  //     model enforces that scope: a Get on the agent's own personal/ prefix
+  //     succeeds; a Get on a foreign bucket OR outside personal/ is
+  //     AccessDenied — the same shape STS-scoped creds produce in prod.
+  //
+  // This closes the genuinely-unverified question: CAN the agent's vended
+  // creds actually READ its own personal vault? (Mechanically: yes.)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Faithful model of the vault-service `POST /sts/vend-self` gate.
+   * Vends scoped STS creds iff `requestedUid === callerOwnUid` (self), else
+   * throws the typed denial the real route returns. The returned creds carry
+   * the prefix scope the server's session policy would grant.
+   */
+  interface VendedCreds {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    /** Bucket the STS session policy scopes reads to. */
+    scopedBucket: string;
+    /** Key prefix the STS session policy scopes reads to. */
+    scopedPrefix: string;
+    expiresAt: string;
+  }
+
+  class VendDeniedError extends Error {
+    constructor(requestedUid: string, callerUid: string) {
+      super(
+        `vend-self denied: caller ${callerUid} may not vend credentials for ${requestedUid}`,
+      );
+      this.name = "VendDeniedError";
+    }
+  }
+
+  function vendSelfGate(
+    requestedUid: string,
+    callerOwnUid: string,
+    ownBucket: string,
+  ): VendedCreds {
+    // Self-ownership gate — the load-bearing security check. A real denial
+    // (requesting another principal's vault) MUST fail, never silently pass.
+    if (requestedUid !== callerOwnUid) {
+      throw new VendDeniedError(requestedUid, callerOwnUid);
+    }
+    return {
+      accessKeyId: "ASIA_AGENT_SELF",
+      secretAccessKey: "secret-agent-self",
+      sessionToken: "session-agent-self",
+      scopedBucket: ownBucket,
+      scopedPrefix: "personal/",
+      expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+    };
+  }
+
+  /**
+   * Faithful model of an S3 GetObject under STS-scoped session creds: succeeds
+   * iff the target (bucket, key) falls inside the creds' policy scope, else
+   * the AccessDenied an out-of-scope GetObject returns in prod.
+   */
+  class AccessDeniedError extends Error {
+    constructor(bucket: string, key: string) {
+      super(`AccessDenied: s3:GetObject on ${bucket}/${key}`);
+      this.name = "AccessDeniedError";
+    }
+  }
+
+  function scopedGetObject(
+    creds: VendedCreds,
+    bucket: string,
+    key: string,
+  ): { bucket: string; key: string; body: string } {
+    const inScope =
+      bucket === creds.scopedBucket && key.startsWith(creds.scopedPrefix);
+    if (!inScope) {
+      throw new AccessDeniedError(bucket, key);
+    }
+    return { bucket, key, body: "ok" };
+  }
+
+  it("the agent's STS-vended creds CAN GetObject under its OWN personal-vault prefix", async () => {
+    // The agent vends self creds for its OWN uid → gate allows → creds are
+    // scoped to its own bucket/personal/ → GetObject under that prefix reads.
+    const creds = vendSelfGate(AGENT_UID, AGENT_UID, AGENT_BUCKET);
+    expect(creds.scopedBucket).toBe(AGENT_BUCKET);
+    expect(creds.scopedPrefix).toBe("personal/");
+
+    const obj = scopedGetObject(creds, AGENT_BUCKET, "personal/.hq/manifest.json");
+    expect(obj.body).toBe("ok");
+    expect(obj.bucket).toBe(AGENT_BUCKET);
+    // gate_result: agent --personal read PROVEN via mock.
+  });
+
+  it("vend-self DENIES vending another principal's vault (gate is real, not a rubber stamp)", () => {
+    // Proves the gate actually gates: a caller cannot vend creds for a uid it
+    // does not own. If this DIDN'T throw, the read-authorization proof above
+    // would be meaningless (the gate would pass everything).
+    expect(() =>
+      vendSelfGate("agt_01SOMEONEELSE000000000000000", AGENT_UID, AGENT_BUCKET),
+    ).toThrow(/vend-self denied/);
+  });
+
+  it("scoped creds CANNOT read outside the agent's own personal/ prefix (AccessDenied)", () => {
+    // The STS session policy scopes reads to <own-bucket>/personal/*. A read
+    // on a foreign bucket, or outside personal/, draws AccessDenied — the same
+    // shape prod STS-scoped creds produce. Confirms the read proof is bounded.
+    const creds = vendSelfGate(AGENT_UID, AGENT_UID, AGENT_BUCKET);
+    // Foreign bucket → denied.
+    expect(() =>
+      scopedGetObject(creds, "hq-vault-agt-someoneelse", "personal/x"),
+    ).toThrow(/AccessDenied/);
+    // Own bucket but outside the personal/ prefix → denied.
+    expect(() =>
+      scopedGetObject(creds, AGENT_BUCKET, "shared/secret.txt"),
+    ).toThrow(/AccessDenied/);
+  });
+
+  // -----------------------------------------------------------------------
+  // (3) SAFETY RAILS
+  // -----------------------------------------------------------------------
+  it("--personal is mutually exclusive with --companies (agent identity)", async () => {
+    const deps = makeDeps({ getIdTokenClaims: () => agentClaims });
+    const code = await runRunner(["--personal", "--companies"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("vaultConfig.authToken is the GETTER form (re-resolved per request, no stale-token 401 after ~13m STS expiry)", async () => {
+    // A long --personal pass can outlast Cognito's access-token TTL; the
+    // vaultConfig must carry a getter so every vault/STS request (incl. the
+    // vend that re-fires after ~13m STS expiry) re-resolves the latest token
+    // rather than a captured string. The getter wiring is identity-agnostic
+    // (the runner installs it before any entity resolution), so this drives
+    // the PROVEN person `--personal` path — where syncFn IS reached — to
+    // capture the config the runner hands syncFn, then proves the getter
+    // re-invokes the token resolver on each call (the property that prevents
+    // the stale-token 401 from the personal-sync 401 incident). It is the SAME
+    // vaultConfig the agent path would carry once its resolution is unblocked.
+    let capturedConfig: VaultServiceConfig | undefined;
+    const getAccessToken = vi.fn().mockResolvedValue("fresh-id-token");
+    const personSelfEntity: EntityInfo = {
+      uid: "prs_self",
+      type: "person",
+      slug: "person-self",
+      bucketName: "hq-vault-prs-self",
+      status: "active",
+    } as unknown as EntityInfo;
+    const deps = makeDeps({
+      getAccessToken,
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () => Promise.resolve([personSelfEntity]),
+        }),
+      sync: vi.fn().mockImplementation(async (opts: SyncOptions) => {
+        capturedConfig = opts.vaultConfig;
+        return defaultSyncResult();
+      }),
+    });
+
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(capturedConfig).toBeDefined();
+    // Getter form — NOT a captured string.
+    expect(typeof capturedConfig!.authToken).toBe("function");
+
+    // Re-resolved per request: invoking the getter calls through to the token
+    // resolver every time (so a refreshed on-disk token is picked up mid-pass).
+    const tokenGetter = capturedConfig!.authToken as () => Promise<string>;
+    const callsBefore = getAccessToken.mock.calls.length;
+    await expect(tokenGetter()).resolves.toBe("fresh-id-token");
+    await tokenGetter();
+    expect(getAccessToken.mock.calls.length).toBe(callsBefore + 2);
+  });
+
+  it("version-floor: runner reports a version >= the first --personal-supporting release (5.13.0)", () => {
+    // The box runs `@indigoai-us/hq-cloud@latest`; if that floats below the
+    // first --personal-supporting release, US-007/US-009 would silently no-op
+    // the flag. HQ_CLOUD_VERSION is the package version the runner stamps on
+    // every vault request (clientInfo.version) and is the version the floor is
+    // compared against. First --personal-supporting release: 5.13.0
+    // (hq-cli 5.13.0 / 2026-05-26).
+    const FLOOR = "5.13.0";
+    const cmp = (a: string, b: string): number => {
+      const pa = a.split(".").map((n) => parseInt(n, 10));
+      const pb = b.split(".").map((n) => parseInt(n, 10));
+      for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0) return d < 0 ? -1 : 1;
+      }
+      return 0;
+    };
+    // Sanity-check the comparator before relying on it.
+    expect(cmp("5.13.0", "5.13.0")).toBe(0);
+    expect(cmp("5.12.9", "5.13.0")).toBe(-1);
+    expect(cmp("6.11.12", "5.13.0")).toBe(1);
+
+    expect(/^\d+\.\d+\.\d+/.test(HQ_CLOUD_VERSION)).toBe(true);
+    expect(cmp(HQ_CLOUD_VERSION, FLOOR)).toBeGreaterThanOrEqual(0);
+  });
+});