@indigoai-us/hq-cli 5.12.2 → 5.12.4

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [5.12.4] — 2026-05-12
+
+### Changed
+
+- **`hq files acl <prefix>` now uses a single round-trip.** Previously the
+  command issued `GET /acl` and `GET /acl/tree` in parallel to gather the
+  prefix's own row metadata (creator, open/restricted, effective permission)
+  alongside inherited/descendant grants. The server now folds `directRow`
+  and `effectivePermission` into the `/acl/tree` response, so the CLI makes
+  a single request and dedupes the company-ACL fetch on the server side.
+  Output formatting is unchanged.
+
+## [5.12.3] — 2026-05-12
+
+### Added
+
+- **`hq files share <prefix>...` (no `--with`) — browser-launched share-session flow.**
+  Mints an encrypted single-use token via `POST /files/{companyUid}/share-session`,
+  opens the default browser to `https://hq.{co}.com/share-session/<token>`, and lets
+  the issuer batch-pick recipients (members, groups, "Share with All") with per-recipient
+  read/write before submitting all grants in one round-trip. Variadic — accepts multiple
+  paths in a single invocation: `hq files share path/a/ path/b/ path/c/`.
+
+- **`--no-open` flag on `hq files share`** — prints the share-session URL without
+  launching a browser. Useful for headless contexts (SSH sessions, CI, paste-into-chat
+  workflows). Output includes the URL, paths, and `expiresAt` timestamp.
+
+- **`--with @all` for company-wide grants.** Writes a single ACL entry with
+  `granteeType: 'company-wide'` covering every active member of the company, replacing
+  the legacy `open: true` flag pattern with explicit, individually-revocable grants.
+  Works on both `hq files share` and `hq files unshare`. Members added after the grant
+  resolve through the company-wide entry automatically at vend-time — no ACL re-write
+  needed.
+
+### Fixed
+
+- **`hq --version` now prints the correct version.** The embedded version
+  constant had drifted from `package.json` since 5.12.1 (the 5.12.2 release
+  still reported `5.12.1`).
+
+### Backwards Compatibility
+
+- The legacy direct-grant form (`hq files share <prefix> --with <principal> --permission <level>`)
+  is unchanged. The browser flow only triggers when `--with` is absent. Scripted
+  automation calling the direct-grant form requires no changes.
+
+### Security Notes
+
+- Share-session tokens are AES-256-GCM encrypted with the master key and pin the issuer's
+  identity, the requested paths, and `maxPermissionByPath` at mint time. The web page
+  cannot grant beyond what the issuer had at mint, even if mutated client-side.
+- Default TTL: 15 minutes. Bounded `60s..7d` server-side.
+- Single-use: the submit endpoint claims the token's nonce atomically (DynamoDB
+  `attribute_not_exists`); a second submit returns 409.
+- **Treat share-session URLs as live capabilities** — do not paste them into commits,
+  thread files, journals, or any persistent surface. The 15-minute TTL is defense
+  in depth, not a license to log them.
+
 ## [5.12.2] — 2026-05-10
 
 ### Added

package/dist/commands/files.d.ts

@@ -1,3 +1,44 @@
 import { Command } from "commander";
+/**
+ * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
+ * milliseconds. Returns null on parse failure. Mirrors the parser used in
+ * `secrets generate-link` but kept local so files.ts can be tested in
+ * isolation without importing the much larger secrets command surface.
+ */
+export declare function parseDuration(input: string): number | null;
+/** PRD upper bound on browser-launch share-session expiry. */
+export declare const MAX_SHARE_SESSION_EXPIRY_MS: number;
+export interface ShareSessionResponse {
+    url: string;
+    token?: string;
+    expiresAt: string;
+    nonce?: string;
+    paths?: string[];
+    maxPermissionByPath?: Record<string, string>;
+}
+export interface MintShareSessionParams {
+    token: string;
+    companyUid: string;
+    paths: string[];
+    expiresInMs?: number;
+}
+/**
+ * POST /files/{companyUid}/share-session — mint a browser-launch share
+ * session token. Returns the parsed response. Throws ShareSessionHttpError
+ * with a status + actionable message for any non-2xx so callers can render
+ * a single consistent error path.
+ */
+export declare function mintShareSession(params: MintShareSessionParams): Promise<ShareSessionResponse>;
+export declare class ShareSessionHttpError extends Error {
+    readonly status: number;
+    readonly path?: string | undefined;
+    constructor(status: number, message: string, path?: string | undefined);
+}
+/**
+ * Map a ShareSessionHttpError to user-facing copy. Centralizes the
+ * status → message mapping so the share command and any future caller
+ * stay in sync.
+ */
+export declare function formatShareSessionError(err: ShareSessionHttpError): string;
 export declare function registerFilesCommand(program: Command): void;
 //# sourceMappingURL=files.d.ts.map

package/dist/commands/files.js

@@ -1,86 +1,133 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a754383e-f129-5052-a8d8-59ea590b4f3d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7a4bfaa9-c578-5cd8-8955-ec965faada13")}catch(e){}}();
 import chalk from "chalk";
+import open from "open";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a human-friendly duration string ("15m", "1h", "24h", "2d") into
+ * milliseconds. Returns null on parse failure. Mirrors the parser used in
+ * `secrets generate-link` but kept local so files.ts can be tested in
+ * isolation without importing the much larger secrets command surface.
+ */
+export function parseDuration(input) {
+    const match = input.match(/^(\d+)(m|h|d)$/);
+    if (!match)
+        return null;
+    const value = parseInt(match[1], 10);
+    const unit = match[2];
+    if (unit === "m")
+        return value * 60 * 1000;
+    if (unit === "h")
+        return value * 60 * 60 * 1000;
+    if (unit === "d")
+        return value * 24 * 60 * 60 * 1000;
+    return null;
+}
+/** PRD upper bound on browser-launch share-session expiry. */
+export const MAX_SHARE_SESSION_EXPIRY_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * POST /files/{companyUid}/share-session — mint a browser-launch share
+ * session token. Returns the parsed response. Throws ShareSessionHttpError
+ * with a status + actionable message for any non-2xx so callers can render
+ * a single consistent error path.
+ */
+export async function mintShareSession(params) {
+    const body = { paths: params.paths };
+    if (params.expiresInMs != null)
+        body.expiresInMs = params.expiresInMs;
+    const res = await vaultApiFetch({
+        token: params.token,
+        path: `/files/${encodeURIComponent(params.companyUid)}/share-session`,
+        method: "POST",
+        body,
+    });
+    if (!res.ok) {
+        const errBody = (await res.json().catch(() => ({})));
+        throw new ShareSessionHttpError(res.status, errBody.message ?? errBody.error ?? res.statusText, errBody.path);
+    }
+    return (await res.json());
+}
+export class ShareSessionHttpError extends Error {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = "ShareSessionHttpError";
+    }
+}
+/**
+ * Map a ShareSessionHttpError to user-facing copy. Centralizes the
+ * status → message mapping so the share command and any future caller
+ * stay in sync.
+ */
+export function formatShareSessionError(err) {
+    if (err.status === 401) {
+        return "Not authenticated — please run `hq login`";
+    }
+    if (err.status === 403) {
+        if (err.path) {
+            return `Not authorized to share '${err.path}' — you need read access on every path`;
+        }
+        return "Not authorized — you need to be a company member with read access on every path";
+    }
+    if (err.status === 400) {
+        return `Invalid request: ${err.message}`;
+    }
+    if (err.status >= 500) {
+        return `Server error: ${err.message}`;
+    }
+    return err.message || `Request failed (${err.status})`;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
 export function registerFilesCommand(program) {
     const files = program
         .command("files")
         .description("Manage file access controls in HQ vault")
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     files
-        .command("share <prefix>")
-        .description("Share a file prefix with a person or group")
-        .requiredOption("--with <principal>", "Email address or group id to share with")
-        .requiredOption("--permission <level>", "Permission level: read | write")
-        .action(async (prefix, opts) => {
+        .command("share [paths...]")
+        .description("Share file paths. Without --with: mint a share-session URL and open it in the browser. With --with: grant access directly to a person, group, or @all.")
+        .option("--with <principal>", "Email address, group id, or '@all' to share with every active company member")
+        .option("--permission <level>", "Permission level (only with --with): read | write")
+        .option("--expires <duration>", "Token expiry duration for share-session URL (e.g. 15m, 1h, 24h). Default 15m. Max 24h.")
+        .option("--no-open", "Print the share-session URL but do not launch the browser")
+        .action(async (paths, opts) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
-            if (!["read", "write"].includes(opts.permission)) {
-                console.error(chalk.red(`Invalid permission '${opts.permission}': must be one of read, write`));
+            if (!paths || paths.length === 0) {
+                console.error(chalk.red("usage: hq files share <paths...> [--with <principal>]"));
                 process.exit(1);
             }
-            const principal = opts.with;
-            const isEmail = EMAIL_PATTERN.test(principal);
-            const isGroup = GROUP_ID_PATTERN.test(principal);
-            if (!isEmail && !isGroup) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
-                process.exit(1);
-            }
-            const granteeType = isEmail ? "email" : "group";
-            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
-            const token = await ensureCognitoToken();
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
-            let res = await vaultApiFetch({
-                token,
-                path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
-                method: "POST",
-                body: { prefix: canonicalPrefix, granteeType, granteeId, permission: opts.permission },
-            });
-            // No ACL row exists yet for this prefix. Auto-create one with this
-            // grant as its first entry, then report success — saves the caller
-            // from needing a separate "create" step.
-            let autoCreated = false;
-            if (res.status === 404) {
-                res = await vaultApiFetch({
-                    token,
-                    path: `/files/${encodeURIComponent(companyUid)}/acl`,
-                    method: "POST",
-                    body: {
-                        prefix: canonicalPrefix,
-                        entries: [{ granteeType, granteeId, permission: opts.permission }],
-                    },
-                });
-                autoCreated = res.ok;
-            }
-            if (!res.ok) {
-                const body = await res.json().catch(() => ({}));
-                if (res.status === 401) {
-                    console.error(chalk.red("Not authenticated — please run `hq login`"));
-                }
-                else if (res.status === 403) {
-                    console.error(chalk.red("Not authorized to share this file prefix"));
-                }
-                else if (res.status === 404) {
-                    console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
-                }
-                else if (res.status === 409) {
-                    console.error(chalk.red("Concurrent modification — please retry"));
-                }
-                else if (res.status >= 500) {
-                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
-                }
-                else {
-                    console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+            // Fork: --with present → existing direct-grant path. No --with →
+            // browser-launch share-session path. Per PRD, the direct-grant
+            // path is unchanged from US-001 and operates on a single prefix.
+            if (opts.with !== undefined) {
+                if (paths.length !== 1) {
+                    console.error(chalk.red("Direct grant (--with) takes exactly one prefix. Pass multiple paths only when minting a share-session URL."));
+                    process.exit(1);
                 }
-                process.exit(1);
+                await runDirectGrant({
+                    prefix: paths[0],
+                    principal: opts.with,
+                    permission: opts.permission,
+                    companySlug: files.opts().company,
+                });
+                return;
             }
-            const data = await res.json();
-            const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
-            const verb = autoCreated ? "Created ACL and granted" : "Granted";
-            console.log(chalk.green(`${verb} ${opts.permission} on ${printedPrefix} to ${granteeId}`));
+            await runShareSession({
+                paths,
+                expires: opts.expires,
+                launchBrowser: opts.open,
+                companySlug: files.opts().company,
+            });
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -90,19 +137,29 @@ export function registerFilesCommand(program) {
     files
         .command("unshare <prefix>")
         .description("Remove a file access grant")
-        .requiredOption("--with <principal>", "Email address or group id to remove")
+        .requiredOption("--with <principal>", "Email address, group id, or '@all' to remove the company-wide grant")
         .action(async (prefix, opts) => {
         try {
             const canonicalPrefix = normalizeFilePrefix(prefix);
             const principal = opts.with;
-            const isEmail = EMAIL_PATTERN.test(principal);
-            const isGroup = GROUP_ID_PATTERN.test(principal);
-            if (!isEmail && !isGroup) {
-                console.error(chalk.red(`Invalid principal '${principal}': must be an email address or a group id matching grp_<alphanumeric>`));
+            const isAll = principal === "@all";
+            const isEmail = !isAll && EMAIL_PATTERN.test(principal);
+            const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
+            if (!isAll && !isEmail && !isGroup) {
+                console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
                 process.exit(1);
             }
-            const granteeType = isEmail ? "email" : "group";
-            const granteeId = isEmail ? principal.trim().toLowerCase() : principal;
+            const granteeType = isAll
+                ? "company-wide"
+                : isEmail
+                    ? "email"
+                    : "group";
+            const granteeId = isAll
+                ? ""
+                : isEmail
+                    ? principal.trim().toLowerCase()
+                    : principal;
+            const principalLabel = isAll ? "everyone in the company" : granteeId;
             const token = await ensureCognitoToken();
             const companySlug = files.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
@@ -121,7 +178,7 @@ export function registerFilesCommand(program) {
                     console.error(chalk.red("Not authorized to modify this file prefix's ACL"));
                 }
                 else if (res.status === 404) {
-                    console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${granteeId}`));
+                    console.log(chalk.green(`Grant already absent for '${canonicalPrefix}' / ${principalLabel}`));
                     return;
                 }
                 else if (res.status >= 500) {
@@ -132,7 +189,7 @@ export function registerFilesCommand(program) {
                 }
                 process.exit(1);
             }
-            console.log(chalk.green(`Removed grant for ${granteeId} on '${canonicalPrefix}'`));
+            console.log(chalk.green(`Removed grant for ${principalLabel} on '${canonicalPrefix}'`));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -148,67 +205,60 @@ export function registerFilesCommand(program) {
             const token = await ensureCognitoToken();
             const companySlug = files.opts().company;
             const companyUid = await getCompanyUid(token, companySlug);
-            // Fetch the prefix's own ACL row (creator, open flag, effective
-            // permission) and the inherited/descendant tree in parallel so the
-            // user sees every grant that affects this prefix in one shot.
-            const [aclRes, treeRes] = await Promise.all([
-                vaultApiFetch({
-                    token,
-                    path: `/files/${encodeURIComponent(companyUid)}/acl`,
-                    query: { prefix: canonicalPrefix },
-                }),
-                vaultApiFetch({
-                    token,
-                    path: `/files/${encodeURIComponent(companyUid)}/acl/tree`,
-                    query: { prefix: canonicalPrefix },
-                }),
-            ]);
-            async function readErrorBody(res) {
-                return (await res.json().catch(() => ({})));
-            }
-            // Auth/server failures from either call are treated identically — bail
-            // out with a single message rather than printing a half-rendered view.
-            for (const res of [aclRes, treeRes]) {
-                if (res.ok || res.status === 404)
-                    continue;
-                const body = await readErrorBody(res);
-                if (res.status === 401) {
+            // `/acl/tree` carries the prefix's own row metadata (directRow) and the
+            // caller's effectivePermission alongside direct/inherited/children, so
+            // a single request returns everything the "files acl" view needs.
+            const treeRes = await vaultApiFetch({
+                token,
+                path: `/files/${encodeURIComponent(companyUid)}/acl/tree`,
+                query: { prefix: canonicalPrefix },
+            });
+            if (!treeRes.ok) {
+                const body = (await treeRes.json().catch(() => ({})));
+                if (treeRes.status === 401) {
                     console.error(chalk.red("Not authenticated — please run `hq login`"));
                 }
-                else if (res.status === 403) {
+                else if (treeRes.status === 403) {
                     console.error(chalk.red("Not authorized to view this file prefix's ACL"));
                 }
-                else if (res.status >= 500) {
-                    console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+                else if (treeRes.status >= 500) {
+                    console.error(chalk.red(`Server error: ${body.error ?? treeRes.statusText}`));
                 }
                 else {
                     console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
                 }
                 process.exit(1);
             }
-            const acl = aclRes.ok ? (await aclRes.json()).acl : null;
-            const tree = treeRes.ok ? (await treeRes.json()) : null;
-            // No own row AND nothing inherited or granted below — original
-            // "no ACL record" exit path.
-            if (!acl && (!tree || (tree.inherited.length === 0 && tree.children.length === 0))) {
+            const tree = (await treeRes.json());
+            const row = tree.directRow;
+            // No own row AND nothing inherited or granted below — preserve the
+            // original "no ACL record" exit path.
+            if (!row && tree.inherited.length === 0 && tree.children.length === 0) {
                 console.error(chalk.red(`No ACL record exists for '${canonicalPrefix}'`));
                 process.exit(1);
             }
-            const aclPrefix = acl?.path ?? acl?.prefix ?? tree?.prefix ?? canonicalPrefix;
-            const aclStatus = acl?.open ? "open" : "restricted";
-            console.log(chalk.green(`ACL for ${aclPrefix} (${aclStatus})`));
-            if (acl) {
-                console.log(`Creator: ${acl.creatorUid}`);
-                if (acl.effectivePermission) {
-                    console.log(`Your effective permission: ${acl.effectivePermission}`);
-                }
+            const aclStatus = row?.open ? "open" : "restricted";
+            console.log(chalk.green(`ACL for ${tree.prefix} (${aclStatus})`));
+            if (row) {
+                console.log(`Creator: ${row.creatorUid}`);
             }
             else {
                 console.log(chalk.gray("No direct ACL row — access flows from the inherited/descendant grants below."));
             }
+            if (tree.effectivePermission) {
+                console.log(`Your effective permission: ${tree.effectivePermission}`);
+            }
+            // Display labels for grantee identifiers — `company-wide` entries
+            // store `granteeId === ""` on the wire, but a blank cell is confusing
+            // in tabular output, so we render a human-readable phrase instead.
+            function displayGrantee(e) {
+                if (e.granteeType === "company-wide")
+                    return "Everyone in company";
+                return e.granteeId;
+            }
             function printEntryTable(rows, showSource) {
                 const TYPE_W = Math.max(4, ...rows.map((e) => e.granteeType.length));
-                const GRANTEE_W = Math.max(7, ...rows.map((e) => e.granteeId.length));
+                const GRANTEE_W = Math.max(7, ...rows.map((e) => displayGrantee(e).length));
                 const PERM_W = Math.max(10, ...rows.map((e) => e.permission.length));
                 const BY_W = Math.max(10, ...rows.map((e) => e.grantedBy.length));
                 const SRC_W = showSource
@@ -228,7 +278,7 @@ export function registerFilesCommand(program) {
                     const grantedAt = e.grantedAt.slice(0, 10);
                     const cols = [
                         e.granteeType.padEnd(TYPE_W),
-                        e.granteeId.padEnd(GRANTEE_W),
+                        displayGrantee(e).padEnd(GRANTEE_W),
                         e.permission.padEnd(PERM_W),
                         e.grantedBy.padEnd(BY_W),
                         grantedAt,
@@ -238,12 +288,12 @@ export function registerFilesCommand(program) {
                     console.log(cols.join("  "));
                 }
             }
-            const directEntries = acl?.entries ?? tree?.direct ?? [];
+            const directEntries = tree.direct;
             if (directEntries.length === 0) {
-                if (acl?.open) {
+                if (row?.open) {
                     console.log(chalk.gray("Open ACL — all active members have read access."));
                 }
-                else if (acl) {
+                else if (row) {
                     console.log(chalk.gray("No explicit grants on this prefix — only creator has access."));
                 }
             }
@@ -251,11 +301,11 @@ export function registerFilesCommand(program) {
                 console.log("\nDirect entries (granted on this prefix):");
                 printEntryTable(directEntries, false);
             }
-            if (tree && tree.inherited.length > 0) {
+            if (tree.inherited.length > 0) {
                 console.log("\nInherited (granted on an ancestor prefix):");
                 printEntryTable(tree.inherited, true);
             }
-            if (tree && tree.children.length > 0) {
+            if (tree.children.length > 0) {
                 console.log("\nGranted on descendant prefixes (do not affect this prefix's access):");
                 printEntryTable(tree.children, true);
             }
@@ -266,5 +316,144 @@ export function registerFilesCommand(program) {
         }
     });
 }
+async function runDirectGrant(params) {
+    const canonicalPrefix = normalizeFilePrefix(params.prefix);
+    if (!params.permission) {
+        console.error(chalk.red("--permission is required when --with is set (read | write)"));
+        process.exit(1);
+    }
+    if (!["read", "write"].includes(params.permission)) {
+        console.error(chalk.red(`Invalid permission '${params.permission}': must be one of read, write`));
+        process.exit(1);
+    }
+    const principal = params.principal;
+    // `@all` is the company-wide sentinel — maps to a single typed
+    // 'company-wide' ACL entry whose applicability is computed at resolve
+    // time from the active-member list. We send granteeId as the empty
+    // string to match the canonical storage form on the server.
+    const isAll = principal === "@all";
+    const isEmail = !isAll && EMAIL_PATTERN.test(principal);
+    const isGroup = !isAll && GROUP_ID_PATTERN.test(principal);
+    if (!isAll && !isEmail && !isGroup) {
+        console.error(chalk.red(`Invalid principal '${principal}': must be '@all', an email address, or a group id matching grp_<alphanumeric>`));
+        process.exit(1);
+    }
+    const granteeType = isAll ? "company-wide" : isEmail ? "email" : "group";
+    const granteeId = isAll
+        ? ""
+        : isEmail
+            ? principal.trim().toLowerCase()
+            : principal;
+    // Display label used in success messages — `@all` reads better than `""`.
+    const principalLabel = isAll ? "everyone in the company" : granteeId;
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, params.companySlug);
+    let res = await vaultApiFetch({
+        token,
+        path: `/files/${encodeURIComponent(companyUid)}/acl/grant`,
+        method: "POST",
+        body: {
+            prefix: canonicalPrefix,
+            granteeType,
+            granteeId,
+            permission: params.permission,
+        },
+    });
+    // No ACL row exists yet for this prefix. Auto-create one with this
+    // grant as its first entry, then report success — saves the caller
+    // from needing a separate "create" step.
+    let autoCreated = false;
+    if (res.status === 404) {
+        res = await vaultApiFetch({
+            token,
+            path: `/files/${encodeURIComponent(companyUid)}/acl`,
+            method: "POST",
+            body: {
+                prefix: canonicalPrefix,
+                entries: [{ granteeType, granteeId, permission: params.permission }],
+            },
+        });
+        autoCreated = res.ok;
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        if (res.status === 401) {
+            console.error(chalk.red("Not authenticated — please run `hq login`"));
+        }
+        else if (res.status === 403) {
+            console.error(chalk.red("Not authorized to share this file prefix"));
+        }
+        else if (res.status === 404) {
+            console.error(chalk.red("ACL record not found — the prefix may not have an ACL yet"));
+        }
+        else if (res.status === 409) {
+            console.error(chalk.red("Concurrent modification — please retry"));
+        }
+        else if (res.status >= 500) {
+            console.error(chalk.red(`Server error: ${body.error ?? res.statusText}`));
+        }
+        else {
+            console.error(chalk.red(body.message ?? body.error ?? "Invalid request"));
+        }
+        process.exit(1);
+    }
+    const data = (await res.json());
+    const printedPrefix = data.acl?.path ?? data.acl?.prefix ?? canonicalPrefix;
+    const verb = autoCreated ? "Created ACL and granted" : "Granted";
+    console.log(chalk.green(`${verb} ${params.permission} on ${printedPrefix} to ${principalLabel}`));
+}
+async function runShareSession(params) {
+    // Normalize every path through the shared prefix helper so a trailing
+    // `/` becomes `/*` consistently with the direct-grant path.
+    const normalizedPaths = params.paths.map(normalizeFilePrefix);
+    let expiresInMs;
+    if (params.expires !== undefined) {
+        const parsed = parseDuration(params.expires);
+        if (parsed === null) {
+            console.error(chalk.red(`Invalid duration '${params.expires}'. Use formats like 15m, 1h, 24h.`));
+            process.exit(1);
+        }
+        if (parsed > MAX_SHARE_SESSION_EXPIRY_MS) {
+            console.error(chalk.red("Maximum share-session expiry is 24h. For longer sharing, use `hq files share <prefix> --with <principal>`."));
+            process.exit(1);
+        }
+        expiresInMs = parsed;
+    }
+    const token = await ensureCognitoToken();
+    const companyUid = await getCompanyUid(token, params.companySlug);
+    let session;
+    try {
+        session = await mintShareSession({
+            token,
+            companyUid,
+            paths: normalizedPaths,
+            expiresInMs,
+        });
+    }
+    catch (err) {
+        if (err instanceof ShareSessionHttpError) {
+            console.error(chalk.red(formatShareSessionError(err)));
+            process.exit(1);
+        }
+        throw err;
+    }
+    console.log(chalk.green("Share-session URL generated:"));
+    console.log(`\n  ${session.url}\n`);
+    console.log(chalk.dim(`  Paths:   ${normalizedPaths.join(", ")}`));
+    console.log(chalk.dim(`  Expires: ${session.expiresAt}`));
+    if (params.launchBrowser) {
+        // Best-effort browser launch — failures (no display, missing handler)
+        // shouldn't fail the command since the URL is already printed.
+        try {
+            await open(session.url);
+        }
+        catch (err) {
+            console.error(chalk.yellow(`Couldn't launch browser automatically (${err instanceof Error ? err.message : String(err)}). Copy the URL above.`));
+        }
+    }
+    else {
+        console.log(chalk.dim("  --no-open: copy the URL above to share manually."));
+    }
+}
 //# sourceMappingURL=files.js.map
-//# debugId=a754383e-f129-5052-a8d8-59ea590b4f3d
+//# debugId=7a4bfaa9-c578-5cd8-8955-ec965faada13