@indigoai-us/hq-cli 5.101.7 → 5.103.0

package/dist/commands/integrations-manage.js

@@ -0,0 +1,556 @@
+/**
+ * `hq integrations show | policy | grants | grant | ungrant | access | share |
+ * unshare | audit | pending | disconnect`.
+ *
+ * The govern-and-remove half of the lifecycle. Two different permission
+ * surfaces live here and are easy to confuse, so they get separate verbs:
+ *
+ *   ACCESS  (`access` / `share` / `unshare`) — who inside the company may use
+ *           the connection at all. Managed by the connection's creator or a
+ *           company admin.
+ *   GRANTS  (`grants` / `grant` / `ungrant`) — which of those people may call
+ *           a specific WRITE tool without an approval round trip. Owner-only,
+ *           and layered under the connection's write policy.
+ */
+import readline from "node:readline";
+import chalk from "chalk";
+import { ensureCognitoIdToken } from "../utils/cognito-session.js";
+import { getCompanyUid } from "../utils/vault-api.js";
+import { IntegrationsCliError, bareProvider, fetchAdminSurface, printJson, resolveConnection, selectConnection, } from "./integrations-core.js";
+import { getConnectionAccess, mutateConnectionAccess, uninstallIntegration, updateGovernance, } from "./integrations-api.js";
+const WRITE_POLICIES = ["auto-allow", "confirm", "deny"];
+const PERMISSIONS = ["read", "write", "admin"];
+/** Plain-English gloss for each write policy, used in every policy readout. */
+const POLICY_BLURB = {
+    "auto-allow": "changes run immediately, no approval",
+    confirm: "a company owner approves each change first",
+    deny: "changes are refused",
+};
+/**
+ * Parse a grantee from the one string a person would actually type.
+ *
+ * Accepts an explicit `person:`/`group:`/`email:` prefix, the word `everyone`,
+ * a bare email address, or a bare uid. Refuses anything ambiguous rather than
+ * guessing — a misparsed principal silently grants access to the wrong party.
+ */
+export function parsePrincipal(raw) {
+    const value = raw.trim();
+    if (!value) {
+        throw new IntegrationsCliError("Name who to share with.", { expected: true });
+    }
+    if (/^(everyone|company-wide|all)$/i.test(value)) {
+        return { granteeType: "company-wide" };
+    }
+    const prefixed = /^(person|group|email):(.+)$/i.exec(value);
+    if (prefixed) {
+        return {
+            granteeType: prefixed[1].toLowerCase(),
+            granteeId: prefixed[2].trim(),
+        };
+    }
+    if (value.includes("@"))
+        return { granteeType: "email", granteeId: value };
+    if (/^grp_[A-Za-z0-9_-]+$/i.test(value))
+        return { granteeType: "group", granteeId: value };
+    // Agents are people to the ACL: they hold an identity and a membership, so a
+    // grant to `agt_…` is a person grant, not a separate grantee kind.
+    if (/^(prs|psn|agt)_[A-Za-z0-9_-]+$/i.test(value)) {
+        return { granteeType: "person", granteeId: value };
+    }
+    throw new IntegrationsCliError(`Could not tell what '${raw}' refers to. Use an email address, a uid (prs_… / agt_… / grp_…), \`everyone\`, or an explicit \`person:<id>\` / \`group:<id>\` form.`, { expected: true });
+}
+/** How a principal reads back in output, without leaking a raw uid as a name. */
+function describePrincipal(entry) {
+    if (entry.granteeType === "company-wide")
+        return "everyone in the company";
+    return entry.granteeName ? `${entry.granteeName} (${entry.granteeId})` : entry.granteeId;
+}
+/** Interactive yes/no. Refuses (never assumes yes) when there is nobody to ask. */
+function confirm(message) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(false);
+    // stderr, so `--json` stdout stays machine-readable.
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+function connectionLabel(connection) {
+    return connection.installation?.displayName ?? bareProvider(connection.provider);
+}
+/**
+ * Governance writes are owner-only on hq-pro AND the allowlist PATCH is a
+ * whole-list REPLACE. A non-owner reads an identity-redacted grant list, so
+ * merging into it and writing it back would erase real grantees. Refuse before
+ * reading rather than after — the redacted list must never reach a mutation.
+ */
+function requireGovernanceManager(viewer) {
+    if (!viewer.canManageGovernance) {
+        throw new IntegrationsCliError("Only a company owner can change an app's approval settings. Ask an owner to run this.", { expected: true });
+    }
+}
+function printAccess(access) {
+    const mode = access.access.mode === "legacy-open"
+        ? "everyone (not yet restricted)"
+        : access.access.mode;
+    console.log(`${chalk.bold(access.provider)}  ${chalk.dim(`shared: ${mode}`)}`);
+    console.log(chalk.dim(`  connected by ${access.creator.name ?? access.creator.uid}`));
+    if (access.entries.length === 0) {
+        console.log(chalk.dim("  No individual grants."));
+    }
+    for (const entry of access.entries) {
+        console.log(`  ${describePrincipal(entry)}  ${chalk.dim(entry.permission)}`);
+    }
+    if (!access.canManage) {
+        console.log(chalk.dim("\n  You cannot change this — ask its owner or a company admin."));
+    }
+}
+export function registerManageCommands(integrations) {
+    integrations
+        .command("show [app]")
+        .description("Show one connected app in full")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        const connection = app && !opts.provider && !opts.connection
+            ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
+            : selectConnection(surface.connections, opts);
+        if (opts.json) {
+            printJson(connection);
+            return;
+        }
+        const install = connection.installation;
+        console.log(`${chalk.bold(connectionLabel(connection))}  ${chalk.dim(bareProvider(connection.provider))}`);
+        console.log(chalk.dim(`  connection:  ${connection.id}`));
+        if (install?.id)
+            console.log(chalk.dim(`  installation: ${install.id}`));
+        console.log(chalk.dim(`  status:      ${connection.status}`));
+        if (install?.domain)
+            console.log(chalk.dim(`  domain:      ${install.domain}`));
+        if (install?.surface?.url)
+            console.log(chalk.dim(`  endpoint:    ${install.surface.url}`));
+        const policy = connection.writePolicy;
+        if (policy) {
+            console.log(chalk.dim(`  changes:     ${policy} — ${POLICY_BLURB[policy] ?? ""}`));
+        }
+        if (connection.access?.mode) {
+            console.log(chalk.dim(`  shared:      ${connection.access.mode}${connection.access.grantCount ? ` (${connection.access.grantCount} grants)` : ""}`));
+        }
+        if (connection.createdByName || connection.createdBy) {
+            console.log(chalk.dim(`  connected by ${connection.createdByName ?? connection.createdBy}`));
+        }
+        if (install?.status === "needs_credentials") {
+            console.log(chalk.yellow("  Needs sign-in — run `hq integrations reconnect` to fix it."));
+        }
+    });
+    integrations
+        .command("policy [app]")
+        .description("Show or change whether an app's changes need approval")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--set <mode>", "auto-allow, confirm, or deny")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        const connection = app && !opts.provider && !opts.connection
+            ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
+            : selectConnection(surface.connections, opts);
+        if (!opts.set) {
+            // An absent writePolicy is UNKNOWN, not `confirm`. Defaulting to the
+            // safe-sounding value would tell someone their writes are gated when
+            // the response simply never said so.
+            const current = connection.writePolicy;
+            if (opts.json) {
+                printJson({ connectionId: connection.id, writePolicy: current ?? null });
+                return;
+            }
+            if (!current) {
+                console.log(`${connectionLabel(connection)}: approval setting not reported by this HQ backend.`);
+                return;
+            }
+            console.log(`${connectionLabel(connection)}: ${chalk.bold(current)} — ${POLICY_BLURB[current]}`);
+            console.log(chalk.dim(`\nChange it with: hq integrations policy ${bareProvider(connection.provider)} --set <${WRITE_POLICIES.join("|")}>`));
+            return;
+        }
+        if (!WRITE_POLICIES.includes(opts.set)) {
+            throw new IntegrationsCliError(`--set must be one of: ${WRITE_POLICIES.join(", ")}.`, { expected: true });
+        }
+        requireGovernanceManager(surface.viewer);
+        const writePolicy = opts.set;
+        const result = await updateGovernance(token, companyUid, {
+            connectionId: connection.id,
+            writePolicy,
+        });
+        if (opts.json) {
+            printJson(result);
+            return;
+        }
+        console.log(chalk.green(`${connectionLabel(connection)}: ${writePolicy} — ${POLICY_BLURB[writePolicy]}`));
+    });
+    integrations
+        .command("grants [app]")
+        .description("Show who may run an app's change-making tools without approval")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, app, opts);
+        const grants = connection.writeAllowlist ?? [];
+        if (opts.json) {
+            printJson(grants);
+            return;
+        }
+        if (grants.length === 0) {
+            console.log("No per-tool exceptions — this app follows its overall approval setting.");
+            return;
+        }
+        for (const grant of grants) {
+            console.log(chalk.bold(grant.toolName));
+            for (const entry of grant.entries) {
+                console.log(`  ${describePrincipal(entry)}  ${chalk.dim(entry.permission)}`);
+            }
+        }
+    });
+    /*
+     * grant / ungrant are read-modify-write: hq-pro's PATCH REPLACES the whole
+     * per-tool allowlist, so both verbs must send the merged list, never a delta.
+     */
+    integrations
+        .command("grant [app]")
+        .description("Let someone run one of an app's change-making tools without approval")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .requiredOption("--tool <name>", "The tool to allow")
+        .requiredOption("--to <principal>", "Email, uid, or `everyone`")
+        .option("--permission <level>", "read, write, or admin", "write")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        if (!PERMISSIONS.includes(opts.permission)) {
+            throw new IntegrationsCliError(`--permission must be one of: ${PERMISSIONS.join(", ")}.`, { expected: true });
+        }
+        const toolName = opts.tool.trim();
+        if (!toolName) {
+            throw new IntegrationsCliError("--tool cannot be empty.", { expected: true });
+        }
+        const principal = parsePrincipal(opts.to);
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        requireGovernanceManager(surface.viewer);
+        const connection = app && !opts.provider && !opts.connection
+            ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
+            : selectConnection(surface.connections, opts);
+        const snapshot = connection.writeAllowlist ?? [];
+        const merged = mergeGrant(snapshot, toolName, {
+            granteeType: principal.granteeType,
+            granteeId: principal.granteeId ?? "",
+            permission: opts.permission,
+        });
+        const result = await patchAllowlistIfUnchanged(token, companyUid, connection.id, snapshot, merged);
+        if (opts.json) {
+            printJson(result);
+            return;
+        }
+        console.log(chalk.green(`${describePrincipal({ ...principal, granteeId: principal.granteeId ?? "" })} can now run ${toolName} on ${connectionLabel(connection)} without approval.`));
+    });
+    integrations
+        .command("ungrant [app]")
+        .description("Remove a per-tool exception, so the tool needs approval again")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .requiredOption("--tool <name>", "The tool to stop allowing")
+        .requiredOption("--from <principal>", "Email, uid, or `everyone`")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const principal = parsePrincipal(opts.from);
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        requireGovernanceManager(surface.viewer);
+        const connection = app && !opts.provider && !opts.connection
+            ? selectConnection(surface.connections, app.startsWith("acct_") ? { connection: app } : { provider: app })
+            : selectConnection(surface.connections, opts);
+        const current = connection.writeAllowlist ?? [];
+        const merged = removeGrant(current, opts.tool.trim(), principal);
+        if (merged === null) {
+            throw new IntegrationsCliError(`No exception for ${opts.from} on ${opts.tool} — nothing to remove.`, { expected: true });
+        }
+        const result = await patchAllowlistIfUnchanged(token, companyUid, connection.id, current, merged);
+        if (opts.json) {
+            printJson(result);
+            return;
+        }
+        console.log(chalk.green(`${opts.tool} on ${connectionLabel(connection)} needs approval again.`));
+    });
+    integrations
+        .command("access [app]")
+        .description("Show who in the company can use a connected app")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, app, opts);
+        const access = await getConnectionAccess(token, companyUid, connection.id);
+        if (opts.json) {
+            printJson(access);
+            return;
+        }
+        printAccess(access);
+    });
+    integrations
+        .command("share [app]")
+        .description("Let someone in the company use a connected app")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .requiredOption("--with <principal>", "Email, uid, or `everyone`")
+        .option("--permission <level>", "read, write, or admin", "write")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        if (!PERMISSIONS.includes(opts.permission)) {
+            throw new IntegrationsCliError(`--permission must be one of: ${PERMISSIONS.join(", ")}.`, { expected: true });
+        }
+        const principal = parsePrincipal(opts.with);
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, app, opts);
+        const access = await mutateConnectionAccess(token, companyUid, "grant", {
+            connectionId: connection.id,
+            granteeType: principal.granteeType,
+            ...(principal.granteeId ? { granteeId: principal.granteeId } : {}),
+            permission: opts.permission,
+        });
+        if (opts.json) {
+            printJson(access);
+            return;
+        }
+        console.log(chalk.green(`Shared ${connectionLabel(connection)}.`));
+        printAccess(access);
+    });
+    integrations
+        .command("unshare [app]")
+        .description("Stop someone from using a connected app")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .requiredOption("--from <principal>", "Email, uid, or `everyone`")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const principal = parsePrincipal(opts.from);
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, app, opts);
+        const access = await mutateConnectionAccess(token, companyUid, "revoke", {
+            connectionId: connection.id,
+            granteeType: principal.granteeType,
+            ...(principal.granteeId ? { granteeId: principal.granteeId } : {}),
+        });
+        if (opts.json) {
+            printJson(access);
+            return;
+        }
+        console.log(chalk.green(`Removed access to ${connectionLabel(connection)}.`));
+        printAccess(access);
+    });
+    integrations
+        .command("audit")
+        .description("Recent activity across the company's connected apps")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Only this app")
+        .option("--limit <n>", "How many events to show", "20")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        const limit = Number(opts.limit);
+        if (!Number.isFinite(limit) || limit < 1) {
+            throw new IntegrationsCliError("--limit must be a positive number.", { expected: true });
+        }
+        // Normalize BOTH sides: `--provider` is routinely copied from JSON
+        // output, which carries the qualified `factory:linear` form, while every
+        // audit row is stored bare. Comparing them raw silently reports "no
+        // activity" for an app that has plenty.
+        const want = opts.provider ? bareProvider(opts.provider.trim()).toLowerCase() : undefined;
+        const rows = surface.audit
+            .filter((row) => !want || bareProvider(row.provider ?? "").toLowerCase() === want)
+            .slice(0, limit);
+        if (opts.json) {
+            printJson(rows);
+            return;
+        }
+        if (rows.length === 0) {
+            console.log("No recorded activity yet.");
+            return;
+        }
+        for (const row of rows) {
+            const who = row.memberOrAgentName ?? row.memberOrAgent;
+            console.log(`${chalk.dim(row.timestamp)}  ${chalk.bold(row.outcome)}  ${row.toolName}  ${chalk.dim(who)}`);
+            if (row.reason)
+                console.log(chalk.dim(`    ${row.reason}`));
+        }
+        // hq-pro caps its own feed at 50 events; say so rather than letting a
+        // truncated list read as "that is everything that ever happened".
+        if (surface.audit.length > rows.length) {
+            console.log(chalk.dim(`\nShowing ${rows.length} of ${surface.audit.length} recent events.`));
+        }
+    });
+    integrations
+        .command("pending")
+        .description("Calls that were queued for an owner's approval")
+        .option("--company <slug>", "Company slug")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const surface = await fetchAdminSurface(token, companyUid);
+        const queued = surface.audit.filter((row) => row.outcome === "queued" && row.queueId);
+        if (opts.json) {
+            printJson(queued);
+            return;
+        }
+        if (queued.length === 0) {
+            console.log("Nothing is waiting for approval.");
+            return;
+        }
+        for (const row of queued) {
+            const who = row.memberOrAgentName ?? row.memberOrAgent;
+            console.log(`${chalk.bold(row.toolName)}  ${chalk.dim(`${who} · ${row.timestamp}`)}`);
+            console.log(chalk.dim(`  hq integrations approve ${row.queueId}${row.provider ? ` --provider ${bareProvider(row.provider)}` : ""}`));
+        }
+        // hq-pro exposes no "list open queue entries" route, so this is derived
+        // from the activity feed — and the feed records the QUEUING, never the
+        // later decision. Saying so is the difference between a useful list and
+        // a misleading one.
+        console.log(chalk.dim("\nDerived from recent activity — an entry already approved, rejected, or expired may still appear here."));
+    });
+    integrations
+        .command("disconnect [app]")
+        .alias("remove")
+        .description("Disconnect an app and delete its stored credentials")
+        .option("--company <slug>", "Company slug")
+        .option("--provider <slug>", "Connected app (e.g. linear)")
+        .option("--connection <id>", "Connection id (acct_…)")
+        .option("--yes", "Skip the confirmation prompt")
+        .option("--json", "Machine-readable output")
+        .action(async (app, opts) => {
+        const token = await ensureCognitoIdToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const connection = await resolveConnection(token, companyUid, app, opts);
+        const installationId = connection.installation?.id;
+        if (!installationId) {
+            throw new IntegrationsCliError(`${connectionLabel(connection)} was not installed through the app catalog, so it cannot be disconnected from here.`, { expected: true });
+        }
+        if (!opts.yes) {
+            const label = connectionLabel(connection);
+            // Warning + prompt go to stderr: with --json, stdout must stay parseable,
+            // and prose ahead of the result would make it invalid.
+            console.error(`Disconnecting ${chalk.bold(label)} deletes its stored credentials, revokes the connection, and clears its approval exceptions. Anything relying on it stops working. Reconnecting requires signing in again.`);
+            const ok = await confirm(`Disconnect ${label}?`);
+            if (!ok) {
+                // A non-TTY run lands here too: refusing is the only safe default
+                // when there is nobody to ask about an irreversible removal.
+                throw new IntegrationsCliError("Not disconnected. Re-run with --yes if you are sure.", { expected: true });
+            }
+        }
+        const result = await uninstallIntegration(token, companyUid, installationId);
+        if (opts.json) {
+            printJson(result);
+            return;
+        }
+        console.log(chalk.green(`Disconnected ${connectionLabel(connection)}.`));
+    });
+}
+/** Order-insensitive identity of an allowlist, for change detection. */
+export function allowlistFingerprint(grants) {
+    return JSON.stringify([...grants]
+        .map((grant) => ({
+        toolName: grant.toolName,
+        entries: [...grant.entries]
+            .map((e) => `${e.granteeType}:${e.granteeId}:${e.permission}`)
+            .sort(),
+    }))
+        .sort((a, b) => a.toolName.localeCompare(b.toolName)));
+}
+/**
+ * Send a merged allowlist, but only if nobody changed it in between.
+ *
+ * hq-pro's PATCH replaces the whole list and offers no compare-and-set, so two
+ * owners running `grant`/`ungrant` at once would each merge into the same
+ * snapshot and the later write would silently discard the earlier one. Re-read
+ * immediately before writing and refuse on drift: this cannot close the window
+ * entirely (there is no server-side CAS to close it with), but it turns a
+ * silent lost update into a visible, retryable error.
+ */
+async function patchAllowlistIfUnchanged(token, companyUid, connectionId, snapshot, merged) {
+    const fresh = await fetchAdminSurface(token, companyUid);
+    const current = fresh.connections.find((c) => c.id === connectionId)?.writeAllowlist ?? [];
+    if (allowlistFingerprint(current) !== allowlistFingerprint(snapshot)) {
+        throw new IntegrationsCliError("Someone else changed this app's approval exceptions while this command was running. Nothing was written — re-run to apply your change on top of theirs.", { expected: true });
+    }
+    return await updateGovernance(token, companyUid, { connectionId, writeAllowlist: merged });
+}
+/**
+ * Add (or upgrade) one grantee's permission on one tool, returning the FULL
+ * allowlist to send back. Exported for tests: the merge is the part that would
+ * silently destroy other people's grants if it drifted.
+ */
+export function mergeGrant(current, toolName, entry) {
+    const next = current.map((grant) => ({ ...grant, entries: [...grant.entries] }));
+    const existing = next.find((grant) => grant.toolName === toolName);
+    const target = existing ?? { toolName, entries: [] };
+    if (!existing)
+        next.push(target);
+    const at = target.entries.findIndex((candidate) => candidate.granteeType === entry.granteeType && candidate.granteeId === entry.granteeId);
+    if (at >= 0)
+        target.entries[at] = { ...target.entries[at], permission: entry.permission };
+    else
+        target.entries.push(entry);
+    return next;
+}
+/**
+ * Remove one grantee from one tool, returning the FULL allowlist to send back,
+ * or `null` when the grant was not there (so the caller can say "nothing to
+ * remove" instead of issuing a no-op write). A tool left with no entries is
+ * dropped entirely rather than persisted as an empty rule.
+ */
+export function removeGrant(current, toolName, principal) {
+    const granteeId = principal.granteeId ?? "";
+    let removed = false;
+    const next = [];
+    for (const grant of current) {
+        if (grant.toolName !== toolName) {
+            next.push(grant);
+            continue;
+        }
+        const entries = grant.entries.filter((entry) => {
+            const match = entry.granteeType === principal.granteeType && entry.granteeId === granteeId;
+            if (match)
+                removed = true;
+            return !match;
+        });
+        if (entries.length > 0)
+            next.push({ ...grant, entries });
+    }
+    return removed ? next : null;
+}
+//# sourceMappingURL=integrations-manage.js.map

package/dist/commands/integrations-oauth.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Native-client OAuth loopback listener for `hq integrations connect`.
+ *
+ * An OAuth-protected MCP server signs the admin in through a browser, so the
+ * authorization code comes back as an HTTP redirect. RFC 8252 §7.3 defines the
+ * native-app answer: bind an ephemeral port on the loopback interface and use
+ * `http://127.0.0.1:<port>/…` as the redirect URI. hq-pro validates that shape
+ * on `/oauth/start` (see `isCliLoopbackRedirectUri`) and keeps everything that
+ * matters server-side — the PKCE verifier, the single-use state row, and the
+ * code exchange — so a code captured here is useless on its own.
+ *
+ * Ordering matters: the listener must be bound BEFORE `/oauth/start` is called,
+ * because the port is part of the redirect URI hq-pro registers with the remote
+ * authorization server. Bind → start → open browser → await → exchange.
+ */
+/**
+ * The one callback path hq-pro admits for a loopback redirect. Must stay
+ * byte-identical to hq-pro's `CLI_LOOPBACK_REDIRECT_PATH`; a drift here reads
+ * as `OAUTH_REDIRECT_URI_NOT_ALLOWED` at connect time.
+ */
+export declare const LOOPBACK_CALLBACK_PATH = "/hq/integrations/oauth/callback";
+export interface LoopbackListener {
+    /** The redirect URI to hand hq-pro — includes the OS-assigned port. */
+    redirectUri: string;
+    /**
+     * Resolves once the authorization server redirects back. Rejects on timeout,
+     * on an `?error=` response (the person clicked Deny), or on a state mismatch.
+     */
+    waitForCode(expectedState: string): Promise<string>;
+    close(): void;
+}
+/**
+ * Bind a loopback listener on an ephemeral port and return its redirect URI.
+ *
+ * Binds to `127.0.0.1` explicitly rather than the default wildcard: a wildcard
+ * bind would expose the callback to the local network for the life of the
+ * sign-in, and the whole reason hq-pro admits this URI is that it cannot leave
+ * the machine.
+ */
+export declare function startLoopbackListener(opts?: {
+    timeoutMs?: number;
+}): Promise<LoopbackListener>;
+//# sourceMappingURL=integrations-oauth.d.ts.map