@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/commands/group-grants.ts

@@ -1,455 +0,0 @@
-import { Command } from "commander";
-import chalk from "chalk";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
-import { GROUP_ID_PATTERN } from "./_patterns.js";
-
-/**
- * `hq group-grants` — manage cross-company group access grants.
- *
- * A *group grant* lets a group defined in a SOURCE company be granted a role
- * on a TARGET company. The hq-pro API authorizes the operation against the
- * TARGET company (the caller must be able to invite into it). The CLI is a
- * thin client — it passes the right params and surfaces the server's 403 as an
- * actionable cross-tenant permission error. NO authorization is reimplemented
- * here.
- *
- * Backend contract (hq-pro feature/agency-cross-company-group-grants):
- *   - POST /group-grants            { groupId, sourceCompanyUid, targetCompanyUid, role }
- *   - POST /group-grants/revoke     { groupId, sourceCompanyUid, targetCompanyUid }
- *   - GET  /group-grants/outbound?sourceCompanyUid&groupId
- *   - GET  /group-grants/inbound?companyUid
- *
- * All require a Cognito idToken bearer; 403 (code FORBIDDEN) on authz failure.
- */
-
-export const VALID_GRANT_ROLES = new Set(["owner", "admin", "member", "guest"]);
-
-export type GrantRole = "owner" | "admin" | "member" | "guest";
-
-export interface GroupGrant {
-  groupId: string;
-  sourceCompanyUid: string;
-  targetCompanyUid: string;
-  role: string;
-  grantedBy?: string;
-  grantedAt?: string;
-}
-
-export interface GrantGroupOptions {
-  groupId: string;
-  sourceCompanyUid: string;
-  targetCompanyUid: string;
-  role: string;
-  token: string;
-}
-
-export interface RevokeGroupGrantOptions {
-  groupId: string;
-  sourceCompanyUid: string;
-  targetCompanyUid: string;
-  token: string;
-}
-
-/**
- * Typed HTTP error mirroring members.ts's `InviteHttpError`. Carries the
- * server status + optional error `code` (e.g. `FORBIDDEN`) so the command
- * layer can render an actionable message and exit non-zero.
- */
-export class GrantHttpError extends Error {
-  constructor(
-    public status: number,
-    message: string,
-    public code?: string,
-  ) {
-    super(message);
-    this.name = "GrantHttpError";
-  }
-}
-
-/**
- * Map a `GrantHttpError` onto an actionable, human-readable message. The 403
- * branch is the story's key cross-tenant case: authorization is enforced
- * against the TARGET company, so the message names the target the caller
- * lacks rights on.
- */
-export function formatGrantHttpError(
-  status: number,
-  fallback: string,
-  ctx: { targetCompany?: string; code?: string } = {},
-): string {
-  if (status === 401) return "Not authenticated — please run `hq login`";
-  if (status === 403) {
-    const target = ctx.targetCompany ? ` '${ctx.targetCompany}'` : "";
-    return (
-      `Permission denied: you must be an owner or admin of the target company${target} to grant a group into it. ` +
-      "The grant is authorized against the target company — ask an owner/admin there, or have them enable adminCanInvite."
-    );
-  }
-  if (status === 404) {
-    return `Not found: ${fallback}. Check the group id and that both companies exist.`;
-  }
-  if (status === 409) {
-    return `That grant already exists: ${fallback}`;
-  }
-  if (status >= 500) return `Server error: ${fallback}`;
-  return fallback;
-}
-
-function shortDate(iso: string): string {
-  return iso.slice(0, 10);
-}
-
-/**
- * POST /group-grants — grant a group's access to a target company at a role.
- * Pure-ish: validates inputs, then calls the API client. Throws
- * `GrantHttpError` on non-2xx so the command layer surfaces it.
- */
-export async function grantGroup(options: GrantGroupOptions): Promise<GroupGrant> {
-  if (!GROUP_ID_PATTERN.test(options.groupId)) {
-    throw new Error(
-      `Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
-    );
-  }
-  if (!VALID_GRANT_ROLES.has(options.role)) {
-    throw new Error(
-      `Invalid role '${options.role}': must be one of owner, admin, member, guest`,
-    );
-  }
-  if (options.sourceCompanyUid === options.targetCompanyUid) {
-    throw new Error(
-      "Source and target companies are the same — a group grant must cross company boundaries.",
-    );
-  }
-
-  const res = await vaultApiFetch({
-    token: options.token,
-    path: "/group-grants",
-    method: "POST",
-    body: {
-      groupId: options.groupId,
-      sourceCompanyUid: options.sourceCompanyUid,
-      targetCompanyUid: options.targetCompanyUid,
-      role: options.role,
-    },
-  });
-
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new GrantHttpError(
-      res.status,
-      err.message ?? err.error ?? res.statusText,
-      err.code,
-    );
-  }
-
-  const data = (await res.json()) as { grant?: GroupGrant };
-  return (
-    data.grant ?? {
-      groupId: options.groupId,
-      sourceCompanyUid: options.sourceCompanyUid,
-      targetCompanyUid: options.targetCompanyUid,
-      role: options.role,
-    }
-  );
-}
-
-/** POST /group-grants/revoke — remove a group's grant on a target company. */
-export async function revokeGroupGrant(
-  options: RevokeGroupGrantOptions,
-): Promise<void> {
-  if (!GROUP_ID_PATTERN.test(options.groupId)) {
-    throw new Error(
-      `Invalid group id '${options.groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
-    );
-  }
-
-  const res = await vaultApiFetch({
-    token: options.token,
-    path: "/group-grants/revoke",
-    method: "POST",
-    body: {
-      groupId: options.groupId,
-      sourceCompanyUid: options.sourceCompanyUid,
-      targetCompanyUid: options.targetCompanyUid,
-    },
-  });
-
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new GrantHttpError(
-      res.status,
-      err.message ?? err.error ?? res.statusText,
-      err.code,
-    );
-  }
-}
-
-/** GET /group-grants/outbound — grants a source company's group(s) hold. */
-export async function listOutboundGrants(
-  token: string,
-  sourceCompanyUid: string,
-  groupId: string,
-): Promise<GroupGrant[]> {
-  if (!GROUP_ID_PATTERN.test(groupId)) {
-    throw new Error(
-      `Invalid group id '${groupId}': must match grp_<alphanumeric, underscore, hyphen>`,
-    );
-  }
-
-  const res = await vaultApiFetch({
-    token,
-    path: "/group-grants/outbound",
-    query: { sourceCompanyUid, groupId },
-  });
-
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new GrantHttpError(
-      res.status,
-      err.message ?? err.error ?? res.statusText,
-      err.code,
-    );
-  }
-
-  const data = (await res.json()) as { grants?: GroupGrant[] | null };
-  return data.grants ?? [];
-}
-
-/** GET /group-grants/inbound — grants other companies' groups hold on us. */
-export async function listInboundGrants(
-  token: string,
-  companyUid: string,
-): Promise<GroupGrant[]> {
-  const res = await vaultApiFetch({
-    token,
-    path: "/group-grants/inbound",
-    query: { companyUid },
-  });
-
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new GrantHttpError(
-      res.status,
-      err.message ?? err.error ?? res.statusText,
-      err.code,
-    );
-  }
-
-  const data = (await res.json()) as { grants?: GroupGrant[] | null };
-  return data.grants ?? [];
-}
-
-function printGrantsTable(grants: GroupGrant[]): void {
-  const idW = Math.max(8, ...grants.map((g) => g.groupId.length));
-  const srcW = Math.max(6, ...grants.map((g) => g.sourceCompanyUid.length));
-  const tgtW = Math.max(6, ...grants.map((g) => g.targetCompanyUid.length));
-  const roleW = Math.max(4, ...grants.map((g) => g.role.length));
-  console.log(
-    chalk.bold(
-      [
-        "GROUP_ID".padEnd(idW),
-        "SOURCE".padEnd(srcW),
-        "TARGET".padEnd(tgtW),
-        "ROLE".padEnd(roleW),
-        "GRANTED_AT",
-      ].join("  "),
-    ),
-  );
-  for (const g of grants) {
-    console.log(
-      [
-        g.groupId.padEnd(idW),
-        g.sourceCompanyUid.padEnd(srcW),
-        g.targetCompanyUid.padEnd(tgtW),
-        g.role.padEnd(roleW),
-        g.grantedAt ? shortDate(g.grantedAt) : "",
-      ].join("  "),
-    );
-  }
-}
-
-export function registerGroupGrantsCommand(program: Command): void {
-  const grants = program
-    .command("group-grants")
-    .description(
-      "Grant a group's access to another company (cross-company), and revoke or inspect those grants",
-    )
-    .option(
-      "--company <slug>",
-      "Source company slug (the company that owns the group; resolves to sourceCompanyUid)",
-    );
-
-  grants
-    .command("grant <groupId> <targetCompany>")
-    .description(
-      "Grant a group (from the source company) access to <targetCompany> at a role",
-    )
-    .option(
-      "--role <role>",
-      "Role the group receives on the target company: owner, admin, member, or guest",
-      "member",
-    )
-    .action(
-      async (
-        groupId: string,
-        targetCompany: string,
-        opts: { role: string },
-      ) => {
-        try {
-          const token = await ensureCognitoToken();
-          const sourceSlug = grants.opts().company as string | undefined;
-          const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
-          const targetCompanyUid = await getCompanyUid(token, targetCompany);
-
-          const grant = await grantGroup({
-            groupId,
-            sourceCompanyUid,
-            targetCompanyUid,
-            role: opts.role,
-            token,
-          });
-
-          console.log(
-            chalk.green(
-              `Granted group '${grant.groupId}' access to '${targetCompany}' as ${grant.role}`,
-            ),
-          );
-          console.log(
-            chalk.dim(
-              `  source: ${grant.sourceCompanyUid}  →  target: ${grant.targetCompanyUid}`,
-            ),
-          );
-        } catch (err) {
-          if (err instanceof GrantHttpError) {
-            console.error(
-              chalk.red(
-                formatGrantHttpError(err.status, err.message, {
-                  targetCompany,
-                  code: err.code,
-                }),
-              ),
-            );
-            process.exit(1);
-          }
-          console.error(
-            chalk.red("Error:"),
-            err instanceof Error ? err.message : String(err),
-          );
-          process.exit(1);
-        }
-      },
-    );
-
-  grants
-    .command("revoke <groupId> <targetCompany>")
-    .description(
-      "Revoke a group's grant on <targetCompany>",
-    )
-    .action(async (groupId: string, targetCompany: string) => {
-      try {
-        const token = await ensureCognitoToken();
-        const sourceSlug = grants.opts().company as string | undefined;
-        const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
-        const targetCompanyUid = await getCompanyUid(token, targetCompany);
-
-        await revokeGroupGrant({
-          groupId,
-          sourceCompanyUid,
-          targetCompanyUid,
-          token,
-        });
-
-        console.log(
-          chalk.green(
-            `Revoked group '${groupId}' grant on '${targetCompany}'`,
-          ),
-        );
-      } catch (err) {
-        if (err instanceof GrantHttpError) {
-          console.error(
-            chalk.red(
-              formatGrantHttpError(err.status, err.message, {
-                targetCompany,
-                code: err.code,
-              }),
-            ),
-          );
-          process.exit(1);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  grants
-    .command("outbound")
-    .description(
-      "List grants a source-company group holds on other companies",
-    )
-    .requiredOption(
-      "--group <groupId>",
-      "Group id to inspect",
-    )
-    .action(async (opts: { group: string }) => {
-      try {
-        const token = await ensureCognitoToken();
-        const sourceSlug = grants.opts().company as string | undefined;
-        const sourceCompanyUid = await getCompanyUid(token, sourceSlug);
-
-        const list = await listOutboundGrants(token, sourceCompanyUid, opts.group);
-        if (list.length === 0) {
-          console.log(chalk.gray("No outbound group grants."));
-          return;
-        }
-        printGrantsTable(list);
-      } catch (err) {
-        if (err instanceof GrantHttpError) {
-          console.error(
-            chalk.red(formatGrantHttpError(err.status, err.message)),
-          );
-          process.exit(1);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-
-  grants
-    .command("inbound")
-    .description(
-      "List grants other companies' groups hold on this company",
-    )
-    .action(async () => {
-      try {
-        const token = await ensureCognitoToken();
-        const companySlug = grants.opts().company as string | undefined;
-        const companyUid = await getCompanyUid(token, companySlug);
-
-        const list = await listInboundGrants(token, companyUid);
-        if (list.length === 0) {
-          console.log(chalk.gray("No inbound group grants."));
-          return;
-        }
-        printGrantsTable(list);
-      } catch (err) {
-        if (err instanceof GrantHttpError) {
-          console.error(
-            chalk.red(formatGrantHttpError(err.status, err.message)),
-          );
-          process.exit(1);
-        }
-        console.error(
-          chalk.red("Error:"),
-          err instanceof Error ? err.message : String(err),
-        );
-        process.exit(1);
-      }
-    });
-}

package/src/commands/groups.test.ts

@@ -1,44 +0,0 @@
-/**
- * Unit tests for `hq groups` principal detection (groups.ts).
- *
- * Regression coverage for feedback_edb1796a-24be-4b9f-bc60-a06f39d1c9f2:
- * `hq groups add` rejected agent identities (agt_<ULID>), forcing per-agent
- * secret shares instead of group-carried ACLs. Agent uids ride the same
- * personUid wire slot as people (server contract — the group-members handler
- * accepts granteeType "person" with an agt_* granteeId, and every ACL
- * evaluation keys off caller.personUid, which for agent JWTs IS the agt_ uid).
- */
-
-import { describe, expect, it } from "vitest";
-
-import { detectPrincipalType } from "./groups.js";
-
-describe("detectPrincipalType", () => {
-  it("detects an email principal and normalizes it", () => {
-    expect(detectPrincipalType("Jane@Example.COM")).toEqual({
-      granteeType: "email",
-      granteeId: "jane@example.com",
-    });
-  });
-
-  it("detects a personUid principal", () => {
-    expect(detectPrincipalType("prs_01ABCDEF")).toEqual({
-      granteeType: "person",
-      granteeId: "prs_01ABCDEF",
-    });
-  });
-
-  it("detects an agentUid principal and sends it in the person slot (regression)", () => {
-    expect(detectPrincipalType("agt_01KWFVWZYX8H1DN57ZPNZNKM6C")).toEqual({
-      granteeType: "person",
-      granteeId: "agt_01KWFVWZYX8H1DN57ZPNZNKM6C",
-    });
-  });
-
-  it("rejects malformed principals", () => {
-    expect(detectPrincipalType("agt_")).toBeNull();
-    expect(detectPrincipalType("prs_")).toBeNull();
-    expect(detectPrincipalType("grp_finance")).toBeNull();
-    expect(detectPrincipalType("not a principal")).toBeNull();
-  });
-});