@indigoai-us/hq-cli 5.345.105 → 5.345.107

package/dist/utils/cognito-revoke.js

@@ -0,0 +1,42 @@
+/**
+ * Server-side revocation of a Cognito refresh token.
+ *
+ * `hq logout` calls this before it deletes the local token file so that a
+ * copied token file stops working too. Cognito's `/oauth2/revoke` endpoint on
+ * the hosted domain (the same domain the CLI already uses for `/oauth2/token`)
+ * revokes the refresh token and every access/ID token issued from it. The CLI
+ * app client is public (no client secret), so the body carries only the token
+ * and the client id.
+ *
+ * This never throws and never includes the token in its result: callers get a
+ * plain outcome they can print.
+ */
+/** Upper bound on the revoke request so logout never hangs on a dead network. */
+export const REVOKE_TIMEOUT_MS = 5_000;
+export function cognitoRevokeEndpoint(config) {
+    return `https://${config.userPoolDomain}.auth.${config.region}.amazoncognito.com/oauth2/revoke`;
+}
+export async function revokeRefreshToken(refreshToken, config, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const body = new URLSearchParams({ token: refreshToken, client_id: config.clientId });
+    try {
+        const response = await fetchImpl(cognitoRevokeEndpoint(config), {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? REVOKE_TIMEOUT_MS),
+        });
+        // Drain the body so the socket is released; its content is not needed.
+        await response.text().catch(() => undefined);
+        if (response.ok)
+            return { ok: true };
+        return { ok: false, reason: "rejected", status: response.status };
+    }
+    catch (error) {
+        const name = error instanceof Error ? error.name : "";
+        if (name === "TimeoutError" || name === "AbortError")
+            return { ok: false, reason: "timeout" };
+        return { ok: false, reason: "network" };
+    }
+}
+//# sourceMappingURL=cognito-revoke.js.map

package/dist/utils/cognito-session.d.ts

@@ -18,8 +18,9 @@
  *   HQ_COGNITO_CALLBACK_PORT   — Loopback OAuth callback port
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
-import { loadCachedTokens, isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
-export { isExpiring, isMachineIdentity, loadCachedTokens };
+import { isExpiring, isMachineIdentity, type CognitoAuthConfig, type CognitoTokens, type ClientInfo, type VaultServiceConfig } from "@indigoai-us/hq-cloud";
+import { type KeychainReadOptions } from "./token-keychain.js";
+export { isExpiring, isMachineIdentity };
 /** Person browser/login cache vs machine-creds USER_PASSWORD_AUTH mint. */
 export type CognitoTokenSource = "person" | "machine";
 /** Actor kind derived from the active token / machine-creds signal. */
@@ -186,11 +187,18 @@ export declare function formatCognitoSubject(tokens: {
     accessToken?: string;
 } | null | undefined): string;
 /**
- * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * Person session for `env`: the Keychain item and the token file, the newer
+ * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
  * in-memory fallback, which can surface a different session when the file
  * is missing or unreadable.
  */
-export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv): CognitoTokens | null;
+export declare function readPersonTokenFile(home?: string, env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
+/**
+ * The person's cached session: the shared Keychain item and hq-cloud's file
+ * loader, the newer by `expiresAt`. Writes still go only to the file in this
+ * step.
+ */
+export declare function loadCachedTokens(env?: NodeJS.ProcessEnv, keychain?: KeychainReadOptions): CognitoTokens | null;
 /**
  * Refresh the active person session and refuse a subject change.
  *

package/dist/utils/cognito-session.js

@@ -25,15 +25,16 @@ import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens, isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens as loadCachedTokensFromFile, isExpiring, refreshTokens, saveCachedTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, CognitoRefreshError, accessTokenFingerprint, invalidateCachedTokensByFingerprint, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 import { daemonDir } from "../lib/mesh/live/daemon/paths.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
 import { acquireLockFileExclusively } from "./exclusive-lock.js";
 import { reportNoninteractivePersonRefreshRejection } from "./cognito-refresh-sentry.js";
+import { pickNewerSession, readKeychainTokens } from "./token-keychain.js";
 // Re-export the cached-session primitives for callers that must deliberately
 // avoid the refresh/login behavior in the higher-level helpers below.
-export { isExpiring, isMachineIdentity, loadCachedTokens };
+export { isExpiring, isMachineIdentity };
 /**
  * Override for where machine-minted Cognito tokens are cached.
  * Default: the work-mesh daemon state dir (`~/.hq/work-mesh/daemon`), so a
@@ -313,10 +314,9 @@ export function personTokenCacheFile(home = os.homedir(), env = process.env) {
 export function hasPersonCachedSession(env = process.env) {
     try {
         const file = personTokenCacheFile(os.homedir(), env);
-        if (!fs.existsSync(file))
-            return false;
-        const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (typeof raw.accessToken !== "string" ||
+        const raw = readPersonTokenFile(os.homedir(), env);
+        if (!raw ||
+            typeof raw.accessToken !== "string" ||
             raw.accessToken.length === 0 ||
             typeof raw.idToken !== "string" ||
             raw.idToken.length === 0) {
@@ -474,12 +474,45 @@ function readTokenFile(file) {
     }
 }
 /**
- * Person cache as stored on disk for `env`. Does not consult hq-cloud's
+ * The person session from the shared macOS Keychain item (see
+ * ./token-keychain.ts), or null. Not read when the token file is missing:
+ * no file means signed out. Machine-identity and invalidated tokens are
+ * refused, the same as the file loader.
+ */
+function personKeychainTokens(file, home, env, keychain = {}) {
+    if (!fs.existsSync(file))
+        return null;
+    const tokens = readKeychainTokens({ env, home, ...keychain });
+    if (!tokens)
+        return null;
+    const claims = decodeJwtPayload(tokens.idToken);
+    const entityType = claims?.["custom:entityType"];
+    if (typeof entityType === "string" && entityType.trim().length > 0)
+        return null;
+    if (fs.existsSync(`${file}.invalid.${accessTokenFingerprint(tokens.accessToken)}`))
+        return null;
+    return tokens;
+}
+/**
+ * Person session for `env`: the Keychain item and the token file, the newer
+ * by `expiresAt` (see ./token-keychain.ts). Does not consult hq-cloud's
  * in-memory fallback, which can surface a different session when the file
  * is missing or unreadable.
  */
-export function readPersonTokenFile(home = os.homedir(), env = process.env) {
-    return readTokenFile(personTokenCacheFile(home, env));
+export function readPersonTokenFile(home = os.homedir(), env = process.env, keychain = {}) {
+    const file = personTokenCacheFile(home, env);
+    return pickNewerSession(personKeychainTokens(file, home, env, keychain), readTokenFile(file));
+}
+/**
+ * The person's cached session: the shared Keychain item and hq-cloud's file
+ * loader, the newer by `expiresAt`. Writes still go only to the file in this
+ * step.
+ */
+export function loadCachedTokens(env = process.env, keychain = {}) {
+    const home = os.homedir();
+    const file = personTokenCacheFile(home, env);
+    const fromFile = loadCachedTokensFromFile();
+    return pickNewerSession(personKeychainTokens(file, home, env, keychain), fromFile);
 }
 function restoreTokenFile(file, before) {
     if (before) {

package/dist/utils/token-keychain.d.ts

@@ -0,0 +1,96 @@
+/**
+ * macOS Keychain read of the person Cognito session (step 1 of moving the
+ * session off `~/.hq/cognito-tokens.json`).
+ *
+ * Shared item (must match hq-desktop-app `token_keychain.rs`, desktop #1586,
+ * and hq-cloud `src/token-keychain.ts`):
+ *   - class:   generic password, login keychain
+ *   - service: `ai.indigo.hq.cognito-tokens`
+ *   - account: `person`
+ *   - value:   the same camelCase JSON as the token file
+ *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
+ *
+ * The read goes through `/usr/bin/security`, so there is no native module.
+ * macOS asks the user once whether `security` may read the item; HQ accepts
+ * that prompt (owner decision) and explains it first:
+ *   - Before the first read, a one-line note is printed to stderr. It is only
+ *     shown, and the first read only happens, in an interactive terminal, so
+ *     a background process never raises the prompt unexplained.
+ *   - A denied prompt, a timeout or any other failure falls back to the file
+ *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
+ *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *   - "Item not found" is a plain miss and is not remembered as a denial.
+ *
+ * Choosing between the Keychain and the file (writes still go to the file):
+ *   - No file means signed out; the Keychain is not read. Older tools sign
+ *     out by deleting only the file, and the desktop clears the stale item.
+ *   - Both valid: the newer session by `expiresAt` wins; a tie keeps the
+ *     Keychain value. This matches the installer's rule.
+ *   - Only one valid: that one.
+ *
+ * Non-macOS, an `HQ_STATE_DIR` override and `HQ_TOKEN_KEYCHAIN=0` read the
+ * file only. Token values are never printed or logged.
+ */
+export declare const KEYCHAIN_SERVICE = "ai.indigo.hq.cognito-tokens";
+export declare const KEYCHAIN_ACCOUNT = "person";
+export declare const KEYCHAIN_TEAM_ID = "HWFZ2QDTMR";
+/** Read timeout once access has been allowed (no prompt expected). */
+export declare const KEYCHAIN_READ_TIMEOUT_MS = 3000;
+/** First read: long enough for a person to answer the macOS prompt. */
+export declare const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60000;
+export declare const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+export interface KeychainTokenShape {
+    accessToken: string;
+    idToken: string;
+    refreshToken?: string;
+    expiresAt?: string | number;
+}
+export interface SecurityResult {
+    status: number | null;
+    stdout: string;
+    timedOut: boolean;
+}
+export type SecurityRunner = (args: string[], timeoutMs: number) => SecurityResult;
+export interface KeychainAccessState {
+    noteShownAt?: string;
+    allowedAt?: string;
+    deniedAt?: string;
+}
+export interface KeychainReadOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    runSecurity?: SecurityRunner;
+    /** Defaults to whether stderr is a terminal. */
+    interactive?: boolean;
+    /** Where the first-read note goes. Defaults to stderr. */
+    notify?: (line: string) => void;
+    /** Ignore a remembered denial and the read cache (`hq auth keychain --retry`). */
+    retry?: boolean;
+    now?: () => Date;
+}
+export type KeychainReadOutcome = "hit" | "miss" | "denied" | "skipped-denied" | "skipped-not-interactive" | "disabled";
+export declare function keychainTokenReadEnabled(opts?: KeychainReadOptions): boolean;
+export declare function keychainAccessStateFile(home?: string): string;
+export declare function readKeychainAccessState(home?: string): KeychainAccessState;
+export declare function parseTokenJson(raw: string): KeychainTokenShape | null;
+/** Test seam: forget the in-process read cache. */
+export declare function resetKeychainReadCacheForTests(): void;
+/**
+ * Read the shared item, applying the first-read note, the remembered denial
+ * and the timeouts described above. Never throws.
+ */
+export declare function readKeychainTokensDetailed(opts?: KeychainReadOptions): {
+    tokens: KeychainTokenShape | null;
+    outcome: KeychainReadOutcome;
+};
+export declare function readKeychainTokens(opts?: KeychainReadOptions): KeychainTokenShape | null;
+/** Newer session by `expiresAt`; a tie keeps the Keychain value. */
+export declare function pickNewerSession<T extends KeychainTokenShape>(fromKeychain: T | null, fromFile: T | null): T | null;
+export type PersonTokenSource = "file" | "keychain" | "none";
+/** The person session from the Keychain and the file, by the rules above. */
+export declare function readPersonTokensWithKeychain(file?: string, opts?: KeychainReadOptions): {
+    tokens: KeychainTokenShape | null;
+    source: PersonTokenSource;
+};
+//# sourceMappingURL=token-keychain.d.ts.map

package/dist/utils/token-keychain.js

@@ -0,0 +1,218 @@
+/**
+ * macOS Keychain read of the person Cognito session (step 1 of moving the
+ * session off `~/.hq/cognito-tokens.json`).
+ *
+ * Shared item (must match hq-desktop-app `token_keychain.rs`, desktop #1586,
+ * and hq-cloud `src/token-keychain.ts`):
+ *   - class:   generic password, login keychain
+ *   - service: `ai.indigo.hq.cognito-tokens`
+ *   - account: `person`
+ *   - value:   the same camelCase JSON as the token file
+ *   - signer:  Team ID HWFZ2QDTMR (login-keychain partition `teamid:HWFZ2QDTMR`)
+ *
+ * The read goes through `/usr/bin/security`, so there is no native module.
+ * macOS asks the user once whether `security` may read the item; HQ accepts
+ * that prompt (owner decision) and explains it first:
+ *   - Before the first read, a one-line note is printed to stderr. It is only
+ *     shown, and the first read only happens, in an interactive terminal, so
+ *     a background process never raises the prompt unexplained.
+ *   - A denied prompt, a timeout or any other failure falls back to the file
+ *     quietly and is remembered in `~/.hq/keychain-access.json`, so HQ does
+ *     not ask again on every run. `hq auth keychain --retry` clears it.
+ *   - "Item not found" is a plain miss and is not remembered as a denial.
+ *
+ * Choosing between the Keychain and the file (writes still go to the file):
+ *   - No file means signed out; the Keychain is not read. Older tools sign
+ *     out by deleting only the file, and the desktop clears the stale item.
+ *   - Both valid: the newer session by `expiresAt` wins; a tie keeps the
+ *     Keychain value. This matches the installer's rule.
+ *   - Only one valid: that one.
+ *
+ * Non-macOS, an `HQ_STATE_DIR` override and `HQ_TOKEN_KEYCHAIN=0` read the
+ * file only. Token values are never printed or logged.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const KEYCHAIN_SERVICE = "ai.indigo.hq.cognito-tokens";
+export const KEYCHAIN_ACCOUNT = "person";
+export const KEYCHAIN_TEAM_ID = "HWFZ2QDTMR";
+/** Read timeout once access has been allowed (no prompt expected). */
+export const KEYCHAIN_READ_TIMEOUT_MS = 3_000;
+/** First read: long enough for a person to answer the macOS prompt. */
+export const KEYCHAIN_FIRST_READ_TIMEOUT_MS = 60_000;
+/** `security` exit status for errSecItemNotFound. */
+const SECURITY_ITEM_NOT_FOUND = 44;
+/** Reuse a read within one process for this long (avoids a spawn per request). */
+const READ_CACHE_MS = 30_000;
+export const KEYCHAIN_FIRST_READ_NOTE = "macOS will ask once whether HQ can read your sign-in from the Keychain. Choose Always Allow.";
+const defaultRunner = (args, timeoutMs) => {
+    try {
+        const result = spawnSync("/usr/bin/security", args, {
+            encoding: "utf8",
+            timeout: timeoutMs,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const timedOut = result.error?.code === "ETIMEDOUT";
+        return { status: result.status, stdout: typeof result.stdout === "string" ? result.stdout : "", timedOut };
+    }
+    catch {
+        return { status: null, stdout: "", timedOut: false };
+    }
+};
+export function keychainTokenReadEnabled(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    if (platform !== "darwin")
+        return false;
+    const flag = env.HQ_TOKEN_KEYCHAIN?.trim().toLowerCase();
+    if (flag === "0" || flag === "false" || flag === "off")
+        return false;
+    // Only the default ~/.hq cache is mirrored into the shared item.
+    if (env.HQ_STATE_DIR?.trim())
+        return false;
+    return true;
+}
+export function keychainAccessStateFile(home = os.homedir()) {
+    return path.join(home, ".hq", "keychain-access.json");
+}
+export function readKeychainAccessState(home = os.homedir()) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(keychainAccessStateFile(home), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeKeychainAccessState(home, state) {
+    try {
+        const file = keychainAccessStateFile(home);
+        fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = `${file}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // Best effort: without the marker HQ may ask again, which is safe.
+    }
+}
+/** `security -w` prints hex when the secret has non-printable bytes (newlines). */
+function decodeSecurityOutput(stdout) {
+    const trimmed = stdout.replace(/\r?\n$/, "");
+    if (!trimmed.startsWith("{") && /^(?:[0-9a-fA-F]{2})+$/.test(trimmed)) {
+        return Buffer.from(trimmed, "hex").toString("utf8");
+    }
+    return trimmed;
+}
+export function parseTokenJson(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (!value ||
+            typeof value.accessToken !== "string" ||
+            value.accessToken.length === 0 ||
+            typeof value.idToken !== "string" ||
+            value.idToken.length === 0) {
+            return null;
+        }
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+let readCache = null;
+/** Test seam: forget the in-process read cache. */
+export function resetKeychainReadCacheForTests() {
+    readCache = null;
+}
+/**
+ * Read the shared item, applying the first-read note, the remembered denial
+ * and the timeouts described above. Never throws.
+ */
+export function readKeychainTokensDetailed(opts = {}) {
+    if (!keychainTokenReadEnabled(opts))
+        return { tokens: null, outcome: "disabled" };
+    const home = opts.home ?? os.homedir();
+    const now = opts.now ?? (() => new Date());
+    if (!opts.retry && readCache && readCache.home === home && now().getTime() - readCache.at < READ_CACHE_MS) {
+        return { tokens: readCache.tokens, outcome: readCache.outcome };
+    }
+    const remember = (tokens, outcome) => {
+        readCache = { at: now().getTime(), home, tokens, outcome };
+        return { tokens, outcome };
+    };
+    let state = readKeychainAccessState(home);
+    if (opts.retry && state.deniedAt) {
+        const { deniedAt: _cleared, ...rest } = state;
+        state = rest;
+        writeKeychainAccessState(home, state);
+    }
+    if (state.deniedAt)
+        return remember(null, "skipped-denied");
+    // Until a read has succeeded, a read may raise the macOS prompt, so it only
+    // happens in a terminal, after the note (shown once).
+    if (!state.allowedAt) {
+        const interactive = opts.interactive ?? Boolean(process.stderr.isTTY);
+        if (!interactive)
+            return remember(null, "skipped-not-interactive");
+        if (!state.noteShownAt) {
+            (opts.notify ?? ((line) => process.stderr.write(`${line}\n`)))(KEYCHAIN_FIRST_READ_NOTE);
+            state = { ...state, noteShownAt: now().toISOString() };
+            writeKeychainAccessState(home, state);
+        }
+    }
+    const run = opts.runSecurity ?? defaultRunner;
+    const result = run(["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", KEYCHAIN_ACCOUNT, "-w"], state.allowedAt ? KEYCHAIN_READ_TIMEOUT_MS : KEYCHAIN_FIRST_READ_TIMEOUT_MS);
+    if (result.status === 0 && !result.timedOut) {
+        if (!state.allowedAt)
+            writeKeychainAccessState(home, { ...state, allowedAt: now().toISOString() });
+        return remember(parseTokenJson(decodeSecurityOutput(result.stdout)), "hit");
+    }
+    if (result.status === SECURITY_ITEM_NOT_FOUND && !result.timedOut)
+        return remember(null, "miss");
+    // Denied, timed out, or failed: fall back quietly and don't ask again.
+    writeKeychainAccessState(home, { ...state, deniedAt: now().toISOString() });
+    return remember(null, "denied");
+}
+export function readKeychainTokens(opts = {}) {
+    return readKeychainTokensDetailed(opts).tokens;
+}
+function expiresAtMs(tokens) {
+    const value = tokens.expiresAt;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return Number.NEGATIVE_INFINITY;
+}
+/** Newer session by `expiresAt`; a tie keeps the Keychain value. */
+export function pickNewerSession(fromKeychain, fromFile) {
+    if (!fromKeychain)
+        return fromFile;
+    if (!fromFile)
+        return fromKeychain;
+    return expiresAtMs(fromFile) > expiresAtMs(fromKeychain) ? fromFile : fromKeychain;
+}
+/** The person session from the Keychain and the file, by the rules above. */
+export function readPersonTokensWithKeychain(file = path.join(os.homedir(), ".hq", "cognito-tokens.json"), opts = {}) {
+    if (!fs.existsSync(file))
+        return { tokens: null, source: "none" };
+    let fromFile;
+    try {
+        fromFile = parseTokenJson(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        fromFile = null;
+    }
+    const fromKeychain = readKeychainTokens(opts);
+    const chosen = pickNewerSession(fromKeychain, fromFile);
+    if (!chosen)
+        return { tokens: null, source: "none" };
+    return { tokens: chosen, source: chosen === fromKeychain ? "keychain" : "file" };
+}
+//# sourceMappingURL=token-keychain.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.105",
+  "version": "5.345.107",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -48,7 +48,7 @@
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
     "@aws-sdk/dsql-signer": "^3.1146.0",
-    "@indigoai-us/hq-cloud": "~6.18.61",
+    "@indigoai-us/hq-cloud": "~6.18.66",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@sentry/node": "^10.49.0",

package/assets/scaffold/core/scripts/ontology-audience-grant.sh

@@ -1,81 +0,0 @@
-#!/usr/bin/env bash
-# ontology-audience-grant.sh — grant each scoped audience folder to exactly the
-# people in its audience, and prove every grant by readback.
-# Spec: core/knowledge/public/hq-core/ontology-local-spec.md
-#
-# Usage: ontology-audience-grant.sh --company <co> [--dry-run]
-#
-# For every signals/@{key}/_audience.yaml under companies/<co>/:
-#   - grants read on signals/@{key}/, ontology/facts/@{key}/, and each
-#     sources/{channel}/@{key}/ that exists, to each principal that is an
-#     active company member (non-members are skipped with a warning);
-#   - one prefix grant per principal per folder, never per file;
-#   - each grant is the recursive shared glob `<folder>/*` (a bare `<folder>/`
-#     is a private create-only folder since hq-pro #3662);
-#   - reads every grant back with `hq files acl --json`; a missing grant exits 3.
-# Company-audience paths get @all read on signals/{type}/ and
-# ontology/facts/@company/ only. Nothing else under ontology/, signals/,
-# sources/ is granted to @all.
-# Local-only companies (company.yaml cloud: false or absent cloud_uid) exit 0
-# with "local-only, no grants".
-set -uo pipefail
-HQ="${HQ_BIN:-hq}"
-root="${HQ_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
-co="" dry=0
-while [ $# -gt 0 ]; do
-  case "$1" in --company) co="$2"; shift 2 ;; --dry-run) dry=1; shift ;; *) echo "unknown flag $1" >&2; exit 2 ;; esac
-done
-[ -n "$co" ] || { echo "usage: ontology-audience-grant.sh --company <co> [--dry-run]" >&2; exit 2; }
-C="$root/companies/$co"; [ -d "$C" ] || { echo "no company $co" >&2; exit 2; }
-
-cloud=no
-grep -Eq '^cloud:[[:space:]]*true' "$C/company.yaml" 2>/dev/null && cloud=yes
-if [ "$cloud" = no ] && [ -f "$root/companies/manifest.yaml" ]; then
-  # manifest: companies:\n  <co>:\n    cloud_uid: ...  (two-space company keys)
-  awk -v co="$co" '/^  [^ #][^:]*:/{inco=($1==co":")} inco && /^    cloud_uid:[[:space:]]*[^[:space:]]/{f=1} END{exit !f}' "$root/companies/manifest.yaml" && cloud=yes
-fi
-[ "$cloud" = yes ] || { echo "local-only, no grants"; exit 0; }
-
-members="$("$HQ" members --company "$co" list 2>/dev/null | awk 'NR>1{print tolower($1)}')"
-[ -n "$members" ] || { echo "could not list members of $co" >&2; exit 3; }
-
-granted=0 skipped=0 failed=0
-grant() { # <folder/> <principal>
-  # Grant the recursive shared glob `<folder>/*`, never the bare `<folder>/`:
-  # since hq-pro #3662 a bare trailing slash is a private create-only folder
-  # (read on it exposes no children) and ACL reads echo the pattern verbatim.
-  local p="${1%/}/*" who="$2"
-  if [ "$dry" = 1 ]; then echo "would grant read $p -> $who"; return 0; fi
-  "$HQ" files --company "$co" share "$p" --with "$who" --permission read >/dev/null 2>&1 || true
-  if "$HQ" files --company "$co" acl "$p" --json 2>/dev/null | jq -e --arg w "$who" \
-      '.direct[]? | select((.granteeId==$w) or ($w=="@all" and .granteeType=="company-wide")) | select(.permission=="read" or .permission=="write" or .permission=="admin")' >/dev/null; then
-    granted=$((granted+1)); echo "granted read $p -> $who"
-  else
-    failed=$((failed+1)); echo "READBACK FAILED: $p -> $who" >&2
-  fi
-}
-
-for aud in "$C"/signals/@*/_audience.yaml; do
-  [ -f "$aud" ] || continue
-  key="$(basename "$(dirname "$aud")")"; key="${key#@}"
-  principals="$(sed -n 's/^principals:[[:space:]]*\[\(.*\)\]/\1/p' "$aud" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | awk '/@/ { print tolower($0); next } { print }' | grep -v '^$')"
-  prefixes="signals/@$key/"
-  [ -d "$C/ontology/facts/@$key" ] && prefixes="$prefixes ontology/facts/@$key/"
-  for d in "$C"/sources/*/@"$key"; do [ -d "$d" ] && prefixes="$prefixes sources/$(basename "$(dirname "$d")")/@$key/"; done
-  for who in $principals; do
-    # prs_/agt_ principals come from the source's own vault ACL (e.g. meeting
-    # attendees), so they are already company identities; emails must be members.
-    case "$who" in
-      prs_*|agt_*) ;;
-      *) if ! grep -qxF "$who" <<<"$members"; then echo "skip $who (not a member of $co)" >&2; skipped=$((skipped+1)); continue; fi ;;
-    esac
-    for p in $prefixes; do grant "$p" "$who"; done
-  done
-done
-[ -d "$C/ontology/facts/@company" ] && grant "ontology/facts/@company/" "@all"
-for t in action_item commitment decision risk question key_point participant_contribution summary; do
-  [ -d "$C/signals/$t" ] && grant "signals/$t/" "@all"
-done
-
-echo "audience grants for $co: $granted granted, $skipped skipped, $failed failed"
-[ "$failed" -eq 0 ] || exit 3