@knowttl/checkpoint-axi 0.0.0 → 0.1.1

package/dist/src/catalogue.js

@@ -0,0 +1,103 @@
+import { exceptionFamilies } from "./exceptions.js";
+export const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
+export const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
+const common = {
+    config: "Config path; default CHECKPOINT_AXI_CONFIG or platform path",
+    profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
+    fields: "Comma-separated output fields; default all",
+    full: "Show full strings instead of 500-character previews; default false",
+    help: "Show concise command help; default false",
+};
+const paging = {
+    "start-date": "ISO timestamp with timezone; default 24 hours before end-date; maximum window 31 days",
+    "end-date": "ISO timestamp with timezone; default now",
+    limit: "Maximum rows; default 50, range 1-1000; cannot combine with --all",
+    all: "Read up to 1000 rows / 10 HTTP requests / 60 seconds / 8 MiB; default false",
+    cursor: "Opaque continuation bound to profile, region, operation and selectors; repeat original selectors",
+};
+const exceptionType = `Required for ${["malware", "url", "dlp"].map((kind) => `${kind}: ${exceptionFamilies[kind].types.join(",")}`).join("; ")}`;
+const writeFlags = { ...common,
+    ids: "Required comma-separated unique entity IDs; maximum 20",
+    execute: "Send once after all write gates; default false (preview)",
+    "dry-run": "Explicit preview; cannot combine with --execute",
+    confirm: "Exact operation followed by a space and the comma-separated IDs in supplied order",
+};
+const exceptionWriteFlags = { ...common, execute: writeFlags.execute, "dry-run": writeFlags["dry-run"],
+    confirm: "Exact operation followed by a space and every target from preview (payload sha256 for create and malware/url/dlp update, exception ID or comma-separated item IDs otherwise)" };
+const input = "Required absolute private JSON file containing documented requestData fields directly; fields depend on kind; update sends a replacement PUT";
+// Only shipped commands belong here. Inventory records are evidence, never dispatch.
+export const catalogue = {
+    "email download": { description: "Download an email to a new private file with profile opt-in, a 50 MiB cap and mandatory SHA-256 verification; scopes and email hash availability are unverified (guide pages 131-132)",
+        flags: { config: common.config, profile: common.profile, help: common.help, out: "Required absolute new output file; mode 0600, never stdout or overwrite", original: "Download original email without processing modifications; default false" },
+        examples: ["checkpoint-axi email download <entity-id> --out /absolute/message", "checkpoint-axi email download <entity-id> --original --out /absolute/original"] },
+    "attachment download": { description: "Download one attachment to a new private file with profile opt-in, a 50 MiB cap and verified x-av-sha256; scope behavior is unverified (guide pages 133-135)",
+        flags: { config: common.config, profile: common.profile, help: common.help, out: "Required absolute new output file; mode 0600, never stdout or overwrite", scope: "Optional authorized scope query; default profile scope when configured; live behavior unverified" },
+        examples: ["checkpoint-axi attachment download <entity-id> <attachment-id> --out /absolute/attachment", "checkpoint-axi attachment download <entity-id> <attachment-id> --scope <scope> --out /absolute/attachment"] },
+    "attachment download-all": { description: "Download available attachments as a ZIP to a new private file with opt-in, a 50 MiB cap and mandatory SHA-256 verification; ZIP hash availability and scopes are unverified; HTTP 200 may contain only some attachments (guide pages 135-137)",
+        flags: { config: common.config, profile: common.profile, help: common.help, out: "Required absolute new output file; mode 0600, never stdout or overwrite", scope: "Optional authorized scope query; default profile scope when configured; live behavior unverified" },
+        examples: ["checkpoint-axi attachment download-all <entity-id> --out /absolute/attachments", "checkpoint-axi attachment download-all <entity-id> --scope <scope> --out /absolute/attachments"] },
+    "exception create": { description: "Preview or create one exception of any kind; anomaly/click-time/malware/url/dlp response identities are unverified (guide pages 61-64, 75-78, 84-85, 91-93, 102-105, 113-116, 123-126)",
+        flags: { ...exceptionWriteFlags, input, specific: "Malware/url/dlp only: use the documented create-specific /exceptions route; default false; included in confirmation digest" },
+        examples: ["checkpoint-axi exception create phishing-allow --input /absolute/rule.json", "checkpoint-axi exception create spam-allow --input /absolute/rule.json --execute --confirm 'exception.spam-allow.create sha256:<preview-digest>'"] },
+    "exception update": { description: "Preview or replace one exception; phishing/spam/click-time require an ID; malware/url/dlp identify it in --input without an ID; anomaly unsupported (guide pages 64-67, 78-81, 94-96, 105-107, 116-117, 126-127)",
+        flags: { ...exceptionWriteFlags, input },
+        examples: ["checkpoint-axi exception update phishing-block <id> --input /absolute/rule.json", "checkpoint-axi exception update spam-allow <id> --input /absolute/rule.json --execute --confirm 'exception.spam-allow.update <id>'"] },
+    "exception remove": { description: "Preview or remove one phishing/spam/anomaly/click-time exception by ID; malware/url/dlp refuse ENDPOINT_UNVERIFIED before authentication (guide pages 67-69, 81-82, 85-87, 98-99, 108-110, 119-120, 129-131)",
+        flags: exceptionWriteFlags,
+        examples: ["checkpoint-axi exception remove phishing-allow <id>", "checkpoint-axi exception remove spam-allow <id> --execute --confirm 'exception.spam-allow.remove <id>'"] },
+    "exception remove-items": { description: "Preview or remove 1-20 click-time items by caller-supplied IDs; existence is unverified (guide pages 97-98)",
+        flags: { ...exceptionWriteFlags, ids: "Required 1-20 unique comma-separated click-time item IDs" },
+        examples: ["checkpoint-axi exception remove-items click-time --ids <id1>,<id2>", "checkpoint-axi exception remove-items click-time --ids <id1>,<id2> --execute --confirm 'exception.click-time.remove-items <id1>,<id2>'"] },
+    "exception clear": { description: "Refuse click-time/malware/url/dlp clear with ENDPOINT_UNVERIFIED until commissioning establishes counts and delete contracts (guide pages 87-88, 96-97, 107-110, 117-120, 128-131)",
+        flags: exceptionWriteFlags,
+        examples: ["checkpoint-axi exception clear click-time", "checkpoint-axi exception clear click-time --dry-run"] },
+    "event action": { description: "Preview or request a name-only event action; parameterized actions refuse ENDPOINT_UNVERIFIED pending commissioning (guide pages 35-37, 42-45)",
+        flags: { ...writeFlags, ids: "Required comma-separated unique event IDs; maximum 20", name: "Required available action name; nonempty action parameters are unverified" },
+        examples: ["checkpoint-axi event action --ids <id> --name dismiss", "checkpoint-axi event action --ids <id> --name dismiss --execute --confirm 'event.action.dismiss <id>'"] },
+    "email quarantine": { description: "Preview or request asynchronous email quarantine through the gated write coordinator (guide pages 28-30)", flags: writeFlags,
+        examples: ["checkpoint-axi email quarantine --ids <id>", "checkpoint-axi email quarantine --ids <id> --execute --confirm 'email.quarantine <id>'"] },
+    "email restore": { description: "Preview or request asynchronous email restore through the gated write coordinator (guide pages 28-30)", flags: writeFlags,
+        examples: ["checkpoint-axi email restore --ids <id>", "checkpoint-axi email restore --ids <id> --execute --confirm 'email.restore <id>'"] },
+    "exception list": { description: "List bounded exceptions for phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url or dlp (guide pages 49-123)",
+        flags: { ...common, type: exceptionType,
+            items: "Click-time item routes instead of list routes; default false", limit: paging.limit, all: "Return up to 1000 rows within transport budgets; no server continuation parameter is documented" },
+        examples: ["checkpoint-axi exception list phishing-allow", "checkpoint-axi exception list malware --type hash", "checkpoint-axi exception list click-time --items --all"] },
+    "exception show": { description: "Show an exception by kind and ID/value; anomaly refuses ENDPOINT_UNVERIFIED pending commissioning (guide pages 52-123)",
+        flags: { ...common, type: exceptionType, items: "Click-time item route instead of list route; default false" },
+        examples: ["checkpoint-axi exception show phishing-block <id>", "checkpoint-axi exception show url <value> --type allow-url", "checkpoint-axi exception show click-time <id> --items --full"] },
+    "event list": { description: "List security events with bounded scroll continuation (API guide pages 37-42)", flags: { ...common, ...paging,
+            saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails",
+            "event-types": "Comma-separated event types; default unfiltered",
+            "event-states": "Comma-separated event states; default unfiltered",
+            severities: "Comma-separated severities; default unfiltered",
+            "event-ids": "Comma-separated event IDs; default unfiltered",
+            "confidence-indicator": "Confidence indicator selector; default unfiltered",
+            description: "Description selector; default unfiltered",
+        }, examples: ["checkpoint-axi event list", "checkpoint-axi event list --all --event-types phishing", "checkpoint-axi event list --cursor <cursor>"] },
+    "event show": { description: "Show one event, actions taken and available actions (API guide pages 34-37)", flags: common,
+        examples: ["checkpoint-axi event show <id>", "checkpoint-axi event show <id> --full"] },
+    "task show": { description: "Show asynchronous task status and per-action details (API guide pages 30-33)", flags: common,
+        examples: ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --full"] },
+    "email search": { description: "Search emails with a bounded date window and scroll continuation (API guide pages 18-27)", flags: { ...common,
+            saas: "SaaS override; default selected profile saas or office365_emails",
+            "saas-entity": "Optional SaaS entity type selector",
+            ...paging,
+            filter: "JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters (guide pages 19-20)",
+        }, examples: ["checkpoint-axi email search", "checkpoint-axi email search --all --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"] },
+    "email show": { description: "Show one email with verdicts, actions and available actions (API guide pages 10-18)", flags: common,
+        examples: ["checkpoint-axi email show <id>", "checkpoint-axi email show <id> --full"] },
+    doctor: { description: "Check regional API authentication and one bounded email search without printing tenant data", flags: { ...common, saas: "SaaS override; default selected profile saas or office365_emails" },
+        examples: ["checkpoint-axi doctor", "checkpoint-axi doctor --profile example --saas office365_emails"] },
+    home: { description: "Show local profile context without resolving secrets or making API calls", flags: common,
+        examples: ["checkpoint-axi", "checkpoint-axi home --profile example"] },
+    "auth status": { description: "Validate the selected local profile and secret source without API calls", flags: common,
+        examples: ["checkpoint-axi auth status", "checkpoint-axi auth status --profile example"] },
+    "profile list": { description: "List file profiles without resolving secrets; --profile does not filter this list", flags: common,
+        examples: ["checkpoint-axi profile list", "checkpoint-axi profile list --config /example/config.json"] },
+    "config path": { description: "Show config and state paths without reading files; --profile does not affect paths", flags: common,
+        examples: ["checkpoint-axi config path", "checkpoint-axi config path --fields config"] },
+};
+export function help() {
+    return { description: DESCRIPTION, commands: Object.fromEntries(Object.entries(catalogue).map(([name, entry]) => [name, entry.description])),
+        flags: common, version: "-v, -V, --version: print the bare version", examples: catalogue.home.examples };
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,9 @@
+import { type CredentialContext } from "./profiles.js";
+import type { gateway } from "./transport.js";
+export declare function main(argv?: string[], options?: {
+    credentials?: CredentialContext;
+    transport?: Parameters<typeof gateway>[3];
+    stdout?: {
+        write: (chunk: string) => unknown;
+    };
+}): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,22 @@
+import { AxiError, runAxiCli } from "axi-sdk-js";
+import { encode } from "@toon-format/toon";
+import { DESCRIPTION } from "./catalogue.js";
+import { credentialStore } from "./profiles.js";
+import { localCommand } from "./local-commands.js";
+export async function main(argv = process.argv.slice(2), options = {}) {
+    const store = credentialStore(options.credentials);
+    await runAxiCli({
+        description: DESCRIPTION,
+        argv: ["local"],
+        topLevelHelp: "",
+        home: () => localCommand([], store),
+        stdout: { write: (chunk) => (options.stdout ?? process.stdout).write(store.redactor.text(chunk)) },
+        formatError: (error) => ({
+            output: `${encode(store.redactor.value(error instanceof AxiError
+                ? { error: { code: error.code, message: error.message }, help: error.suggestions }
+                : { error: { code: "CONFIG_INVALID", message: "Command could not complete" }, help: ["Check local configuration; run checkpoint-axi config path"] }))}\n`,
+            exitCode: error instanceof AxiError && error.code === "VALIDATION_ERROR" ? 2 : 1,
+        }),
+        commands: { local: async () => store.redactor.value(await localCommand(argv, store, options.transport)) },
+    });
+}

package/dist/src/doctor.d.ts

@@ -0,0 +1,3 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+export declare function doctor(store: ReturnType<typeof credentialStore>, config?: string, selected?: string, override?: string, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/doctor.js

@@ -0,0 +1,37 @@
+import { AxiError } from "axi-sdk-js";
+import { gateway } from "./transport.js";
+export async function doctor(store, config, selected, override, transport) {
+    store.readOnly();
+    const profile = store.select(store.load(config, true).config, selected);
+    const saas = override?.trim() ?? profile.saas;
+    if (!saas)
+        throw new AxiError("--saas must not be blank", "VALIDATION_ERROR", ["Run checkpoint-axi doctor --help"]);
+    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
+    const checks = [];
+    for (const check of ["auth", "read"]) {
+        try {
+            if (check === "auth")
+                await api.authenticate();
+            else {
+                const end = new Date();
+                // One page of the default 24-hour window, not an --all scan (guide pages 18-21).
+                await api.read({ path: "/search/query", body: { entityFilter: { saas,
+                            startDate: new Date(end.getTime() - 86_400_000).toISOString(), endDate: end.toISOString() } } });
+            }
+            checks.push({ check, pass: true });
+        }
+        catch (error) {
+            checks.push({ check, pass: false, code: error instanceof AxiError ? error.code : "API_ERROR" });
+            if (check === "auth")
+                checks.push({ check: "read", pass: false, code: "AUTH_NOT_PASSED" });
+            break;
+        }
+    }
+    const pass = checks.every((check) => check.pass);
+    if (!pass)
+        process.exitCode = 1;
+    return { region: profile.region, saas, checks, pass, ...(!pass ? { help: [
+                "Check the regional credentials and API access; AUTH_SHAPE_UNVERIFIED requires owner commissioning of the undocumented token response (guide page 8)",
+                "Run checkpoint-axi auth status to check local credential readiness; never share credentials or raw API responses",
+            ] } : {}) };
+}

package/dist/src/downloads.d.ts

@@ -0,0 +1,3 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+export declare function downloadCommand(name: string, entityId: string | undefined, attachmentId: string | undefined, flags: Map<string, string>, store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/downloads.js

@@ -0,0 +1,52 @@
+import { AxiError } from "axi-sdk-js";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fchmodSync, fsyncSync, openSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { protectWindowsFile } from "./private-file.js";
+import { gateway } from "./transport.js";
+export async function downloadCommand(name, entityId, attachmentId, flags, store, transport) {
+    const out = flags.get("--out");
+    if (!entityId || !/^[A-Za-z0-9_-]{1,256}$/.test(entityId) || name === "attachment download" && (!attachmentId || !/^[A-Za-z0-9_-]{1,256}$/.test(attachmentId))
+        || !out || !isAbsolute(out) || out === "-" || out.includes("\0")) {
+        throw new AxiError("Supply download IDs and an absolute new --out file path", "VALIDATION_ERROR", ["Run checkpoint-axi " + name + " --help"]);
+    }
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    if (!profile.downloads.allow)
+        throw new AxiError("Downloads are disabled", "DOWNLOADS_DISABLED", ["Enable downloads.allow in the selected file profile"]);
+    const path = resolve(out);
+    let fd;
+    try {
+        fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (process.platform === "win32" ? 0 : constants.O_NOFOLLOW), 0o600);
+    }
+    catch {
+        throw new AxiError("Cannot create a new output file", "DOWNLOAD_OUTPUT_INVALID", ["Choose a new --out path in an existing directory; existing files are never overwritten"]);
+    }
+    let complete = false;
+    try {
+        if (process.platform === "win32")
+            protectWindowsFile(path);
+        else
+            fchmodSync(fd, 0o600);
+        const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
+        const result = await api.download({ entityId, attachmentId, all: name === "attachment download-all", original: name === "email download" ? flags.has("--original") : undefined,
+            scope: flags.get("--scope") ?? (name === "email download" ? undefined : profile.scope) });
+        const sha256 = createHash("sha256").update(result.content).digest("hex");
+        if (sha256 !== result.sha256)
+            throw new AxiError("Download SHA-256 does not match", "DOWNLOAD_HASH_MISMATCH", ["Discard the failed download and investigate before trying again"]);
+        writeFileSync(fd, result.content);
+        fsyncSync(fd);
+        complete = true;
+        return { path, size: result.content.length, sha256 };
+    }
+    catch (error) {
+        if (error instanceof AxiError)
+            throw error;
+        throw new AxiError("Download could not complete", "DOWNLOAD_FAILED", ["Check the output directory and selected profile"]);
+    }
+    finally {
+        closeSync(fd);
+        if (!complete)
+            unlinkSync(path);
+    }
+}

package/dist/src/exceptions.d.ts

@@ -0,0 +1,37 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+export declare const exceptionFamilies: {
+    readonly "phishing-allow": {
+        readonly path: "/exceptions/whitelist";
+        readonly types: readonly [];
+    };
+    readonly "phishing-block": {
+        readonly path: "/exceptions/blacklist";
+        readonly types: readonly [];
+    };
+    readonly "spam-allow": {
+        readonly path: "/exceptions/spam_whitelist";
+        readonly types: readonly [];
+    };
+    readonly anomaly: {
+        readonly path: "/sectools/anomaly/exceptions";
+        readonly types: readonly [];
+    };
+    readonly "click-time": {
+        readonly path: "/sectools/click_time_protection/exceptions";
+        readonly types: readonly [];
+    };
+    readonly malware: {
+        readonly path: "/sectool-exceptions/checkpoint2/exceptions";
+        readonly types: readonly ["hash", "micro_hash", "file_type", "ppat_sender_name", "allow_file_type", "sender_email"];
+    };
+    readonly url: {
+        readonly path: "/sectool-exceptions/avanan_url/exceptions";
+        readonly types: readonly ["allow-url", "allow-domain", "block-url", "block-domain"];
+    };
+    readonly dlp: {
+        readonly path: "/sectool-exceptions/avanan_dlp/exceptions";
+        readonly types: readonly ["hash", "text_content", "sender_email", "recipient_email"];
+    };
+};
+export declare function exceptionCommand(name: "exception list" | "exception show", kind: string | undefined, value: string | undefined, flags: Map<string, string>, store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/exceptions.js

@@ -0,0 +1,81 @@
+import { AxiError } from "axi-sdk-js";
+import { z } from "zod";
+import { gateway, READ_LIMITS } from "./transport.js";
+// Read routes and selectors: guide pages 49-60, 69-74, 83, 87-91, 100-102, 110-112 and 120-123.
+export const exceptionFamilies = {
+    "phishing-allow": { path: "/exceptions/whitelist", types: [] },
+    "phishing-block": { path: "/exceptions/blacklist", types: [] },
+    "spam-allow": { path: "/exceptions/spam_whitelist", types: [] },
+    anomaly: { path: "/sectools/anomaly/exceptions", types: [] },
+    "click-time": { path: "/sectools/click_time_protection/exceptions", types: [] },
+    malware: { path: "/sectool-exceptions/checkpoint2/exceptions", types: ["hash", "micro_hash", "file_type", "ppat_sender_name", "allow_file_type", "sender_email"] },
+    url: { path: "/sectool-exceptions/avanan_url/exceptions", types: ["allow-url", "allow-domain", "block-url", "block-domain"] },
+    dlp: { path: "/sectool-exceptions/avanan_dlp/exceptions", types: ["hash", "text_content", "sender_email", "recipient_email"] },
+};
+// Only these families have published response fields (pages 50, 56-60 and 70-74).
+const exception = z.object({ entityId: z.string().min(1), senderEmail: z.string().nullish(),
+    subject: z.string().nullish(), comment: z.string().nullish() }).passthrough();
+export async function exceptionCommand(name, kind, value, flags, store, transport) {
+    const invalid = (message) => { throw new AxiError(message, "VALIDATION_ERROR", [`Run checkpoint-axi ${name} --help`]); };
+    if (!kind || !Object.hasOwn(exceptionFamilies, kind))
+        invalid(`Choose an exception kind: ${Object.keys(exceptionFamilies).join(", ")}`);
+    const family = exceptionFamilies[kind];
+    const show = name === "exception show";
+    const documented = family.path.startsWith("/exceptions/");
+    const type = flags.get("--type");
+    if (family.types.length ? !type || !family.types.includes(type) : type !== undefined) {
+        invalid(family.types.length ? `--type must be one of: ${family.types.join(", ")}` : "--type is only valid for malware, url and dlp");
+    }
+    if (flags.has("--items") && kind !== "click-time")
+        invalid("--items is only valid for click-time");
+    if (show && (!value?.trim() || /[\u0000-\u001f\u007f]/.test(value) || value === "." || value === ".."))
+        invalid("show requires one nonempty exception ID or value");
+    if (show && documented && !/^[A-Za-z0-9_-]+$/.test(value))
+        invalid("Exception ID must contain letters, digits, underscores or hyphens");
+    const limitText = flags.get("--limit") ?? "50";
+    if (!/^[1-9][0-9]*$/.test(limitText) || Number(limitText) > READ_LIMITS.rows)
+        invalid("--limit must be an integer from 1 to 1000");
+    if (flags.has("--all") && flags.has("--limit"))
+        invalid("Use either --all or --limit");
+    if (show && kind === "anomaly")
+        throw new AxiError("Anomaly detail endpoint and response identity are undocumented (guide pages 83-84)", "ENDPOINT_UNVERIFIED", ["Use checkpoint-axi exception list anomaly; owner commissioning happens later through Artium"]);
+    let path = family.path;
+    if (type)
+        path += `/${type}`;
+    if (flags.has("--items"))
+        path += "/items";
+    if (show) {
+        try {
+            path += `/${encodeURIComponent(value)}`;
+        }
+        catch {
+            invalid("Exception value must be valid Unicode");
+        }
+    }
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
+    const page = await api.read({ path: path });
+    if (documented && !z.array(exception).safeParse(page.records).success)
+        throw new AxiError("Invalid exception response", "RESPONSE_INVALID", []);
+    const unverified = documented ? {} : { responseSchema: "unverified" };
+    if (show) {
+        if (!page.records.length)
+            throw new AxiError("Exception was not found", "NOT_FOUND", []);
+        if (documented && (page.records.length !== 1 || exception.parse(page.records[0]).entityId !== value)) {
+            throw new AxiError("Invalid exception detail response", "RESPONSE_INVALID", []);
+        }
+        return { exception: documented ? page.records[0] : page.records, ...unverified };
+    }
+    const limit = flags.has("--all") ? READ_LIMITS.rows : Number(limitText);
+    const rows = page.records.slice(0, limit);
+    const complete = rows.length === page.records.length && !page.scrollId && (page.total === undefined || page.total <= rows.length);
+    return { exceptions: documented ? rows.map((row) => {
+            const record = exception.parse(row);
+            return { id: record.entityId, sender: record.senderEmail ?? "", subject: record.subject ?? "", comment: record.comment ?? "" };
+        }) : rows, count: rows.length, ...(page.total === undefined ? {} : { total: page.total }), complete, ...unverified,
+        ...(!complete ? { reason: "No continuation request parameter is documented for this exception route" } : {}),
+        help: [rows.length ? kind === "anomaly" ? "Anomaly detail remains unavailable pending response identity commissioning"
+                : `Run checkpoint-axi exception show ${kind} <id-or-value>${type ? ` --type ${type}` : ""}${flags.has("--items") ? " --items" : ""} for details`
+                : `No ${kind} exceptions found`, ...(!complete && limit < READ_LIMITS.rows ? ["Repeat with --all for up to 1000 rows; server-side continuation remains undocumented"] : [])] };
+}

package/dist/src/local-commands.d.ts

@@ -0,0 +1,3 @@
+import { credentialStore } from "./profiles.js";
+import type { gateway } from "./transport.js";
+export declare function localCommand(argv: string[], store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/local-commands.js

@@ -0,0 +1,123 @@
+import { AxiError } from "axi-sdk-js";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { catalogue, DESCRIPTION, help, SETUP_GUIDANCE } from "./catalogue.js";
+import { doctor } from "./doctor.js";
+import { readCommand } from "./reads.js";
+import { exceptionCommand } from "./exceptions.js";
+import { emailWriteCommand, eventWriteCommand } from "./writes.js";
+import { exceptionWriteCommand } from "./write-exceptions.js";
+import { downloadCommand } from "./downloads.js";
+export async function localCommand(argv, store, transport) {
+    if (argv.length === 1 && argv[0] === "--help")
+        return help();
+    const name = !argv.length || argv[0]?.startsWith("--") ? "home" : argv[0] === "home" || argv[0] === "doctor" ? argv[0] : argv.slice(0, 2).join(" ");
+    const entry = Object.hasOwn(catalogue, name) ? catalogue[name] : undefined;
+    const usage = (message = "Unknown command, argument, duplicate or invalid flag") => {
+        throw new AxiError(message, "VALIDATION_ERROR", [
+            `Valid commands: ${Object.keys(catalogue).join(", ")}; valid flags: ${entry ? Object.keys(entry.flags).map((flag) => `--${flag}`).join(", ") : "run checkpoint-axi --help"}`,
+        ]);
+    };
+    if (!entry)
+        return usage();
+    const flags = new Map();
+    const isExceptionWrite = name === "exception create" || name === "exception update" || name === "exception remove" || name === "exception remove-items" || name === "exception clear";
+    const isException = name === "exception list" || name === "exception show" || isExceptionWrite;
+    const isDownload = name === "email download" || name === "attachment download" || name === "attachment download-all";
+    const kind = isException && !argv[2]?.startsWith("--") ? argv[2] : undefined;
+    const idIndex = isException ? 3 : 2;
+    const entityId = (isDownload || name.endsWith(" show") || name === "exception update" || name === "exception remove") && !argv[idIndex]?.startsWith("--") ? argv[idIndex] : undefined;
+    const attachmentId = name === "attachment download" && entityId !== undefined && !argv[3]?.startsWith("--") ? argv[3] : undefined;
+    const start = name === "home" ? (argv[0] === "home" ? 1 : 0) : name === "doctor" ? 1
+        : isException ? 2 + Number(kind !== undefined) + Number(entityId !== undefined) : entityId === undefined ? 2 : 3 + Number(attachmentId !== undefined);
+    for (let index = start; index < argv.length; index++) {
+        const flag = argv[index];
+        if (!flag.startsWith("--"))
+            usage();
+        if (!Object.hasOwn(entry.flags, flag.slice(2)) || flags.has(flag)) {
+            const label = flag.split("=")[0];
+            usage(/^--[A-Za-z][A-Za-z0-9-]*$/.test(label) ? `Unknown or duplicate flag ${label}` : undefined);
+        }
+        if (["--help", "--full", "--all", "--items", "--specific", "--original", "--execute", "--dry-run"].includes(flag))
+            flags.set(flag, "true");
+        else {
+            const value = argv[++index];
+            if (!value || value.startsWith("--"))
+                usage();
+            flags.set(flag, value);
+        }
+    }
+    if (flags.has("--help"))
+        return { command: name, ...entry };
+    const available = isException ? name === "exception list" ? ["exceptions", "count", "total", "complete", "reason", "responseSchema", "help"] : ["exception", "responseSchema"]
+        : name === "email search" || name === "event list" ? [name === "event list" ? "events" : "emails", "count", "total", "complete", "reason", "cursor", "help"] : name.endsWith(" show") ? [name.split(" ")[0]]
+            : name === "doctor" ? ["region", "saas", "checks", "pass", "help"] : name === "auth status" ? ["profile", "source", "region", "origin", "saas", "clientSecret", "readOnly"]
+                : name === "profile list" ? ["profiles", "count", "config"] : name === "config path" ? ["config", "state"]
+                    : ["bin", "description", "status", "profiles", "count", "help"];
+    const isWrite = name === "email quarantine" || name === "email restore" || name === "event action" || isExceptionWrite;
+    if (isWrite)
+        available.splice(0, available.length, "outcome", "preview", "auditId", "tasks", "response", "responseSchema", "help");
+    if (isDownload)
+        available.splice(0, available.length, "path", "size", "sha256");
+    const fields = flags.get("--fields")?.split(",") ?? available;
+    if (fields.some((field) => !available.includes(field)) || new Set(fields).size !== fields.length)
+        usage();
+    const config = flags.get("--config");
+    let result;
+    if (isDownload)
+        result = await downloadCommand(name, entityId, attachmentId, flags, store, transport);
+    else if (name === "exception create" || name === "exception update" || name === "exception remove" || name === "exception remove-items" || name === "exception clear")
+        result = await exceptionWriteCommand(name, kind, entityId, flags, store, transport);
+    else if (name === "event action")
+        result = await eventWriteCommand(flags, store, transport);
+    else if (name === "email quarantine" || name === "email restore")
+        result = await emailWriteCommand(name, flags, store, transport);
+    else if (name === "exception list" || name === "exception show")
+        result = await exceptionCommand(name, kind, entityId, flags, store, transport);
+    else if (name === "email search" || name === "email show" || name === "event list" || name === "event show" || name === "task show")
+        result = await readCommand(name, entityId, flags, store, transport);
+    else if (name === "doctor")
+        result = await doctor(store, config, flags.get("--profile"), flags.get("--saas"), transport);
+    else if (name === "auth status")
+        result = store.status(config, flags.get("--profile"));
+    else if (name === "profile list")
+        result = store.list(config);
+    else if (name === "config path")
+        result = { config: store.configPath(config), state: store.statePath() };
+    else {
+        const listed = store.list(config);
+        // Selection errors matter when context exists, but a new installation has a useful empty home.
+        const loaded = store.load(config);
+        let status = "not configured";
+        try {
+            const selected = store.select(loaded.config, flags.get("--profile"));
+            status = `configured: ${selected.name} (${selected.region}); not verified with the API`;
+        }
+        catch (error) {
+            if (!(error instanceof AxiError) || error.code !== "PROFILE_REQUIRED")
+                throw error;
+        }
+        const executable = resolve(process.argv[1] ?? "bin/checkpoint-axi.js");
+        const home = homedir();
+        result = { bin: executable.startsWith(`${home}/`) ? `~${executable.slice(home.length)}` : executable,
+            description: DESCRIPTION, status, profiles: listed.profiles, count: listed.count,
+            help: [SETUP_GUIDANCE, "Run checkpoint-axi auth status to validate local credentials", "Run checkpoint-axi profile list to inspect configured profiles"] };
+    }
+    let truncated = false;
+    const preview = (value) => {
+        if (typeof value === "string" && value.length > 500 && !flags.has("--full")) {
+            truncated = true;
+            return `${value.slice(0, 500)}... (truncated, ${value.length} chars total)`;
+        }
+        if (Array.isArray(value))
+            return value.map(preview);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, preview(child)]));
+        return value;
+    };
+    const projected = Object.fromEntries(fields.filter((field) => result[field] !== undefined).map((field) => [field,
+        field === "cursor" || isDownload ? store.redactor.value(result[field]) : preview(store.redactor.value(result[field]))]));
+    if (truncated && !isWrite)
+        projected.help = [...(Array.isArray(projected.help) ? projected.help : []), "Repeat the command with --full to see complete strings"];
+    return projected;
+}

package/dist/src/private-file.d.ts

@@ -0,0 +1,10 @@
+export type WindowsAcl = (path: string, verify: boolean) => void;
+export declare const windowsAcl: WindowsAcl;
+export declare function protectWindowsFile(path: string): void;
+export declare function toolDirectory(kind: "config" | "state", env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+export type PrivateFileOptions = {
+    platform?: NodeJS.Platform;
+    acl?: WindowsAcl;
+    uid?: number;
+};
+export declare function readPrivateFile(path: string, secret: boolean, verifyAcl: boolean, options?: PrivateFileOptions): string;

package/dist/src/private-file.js

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, join, win32 } from "node:path";
+import { AxiError } from "axi-sdk-js";
+export const windowsAcl = (path, verify) => {
+    const quoted = `'${path.replaceAll("'", "''")}'`;
+    const script = `$ErrorActionPreference='Stop'; $p=${quoted}; $item=Get-Item -LiteralPath $p -Force; `
+        + `if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Reparse point' }; `
+        + (verify ? `$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User; $allowed=@($sid.Value,'S-1-5-18','S-1-5-32-544'); `
+            + `$acl=Get-Acl -LiteralPath $p; if (!$acl.AreAccessRulesProtected -or ($acl.Owner -ne $sid.Translate([Security.Principal.NTAccount]).Value -and $acl.Owner -ne $sid.Value)) { throw 'Unprotected ACL' }; `
+            + `$seen=@(); foreach ($r in $acl.Access) { $s=$r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value; if ($s -notin $allowed -or $r.IsInherited -or $r.AccessControlType -ne 'Allow' -or $r.FileSystemRights -ne [Security.AccessControl.FileSystemRights]::FullControl) { throw 'Unexpected ACL' }; $seen+=$s }; foreach ($s in $allowed) { if ($s -notin $seen) { throw 'Missing ACL' } }` : "");
+    execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { stdio: "pipe" });
+};
+export function protectWindowsFile(path) {
+    const quoted = `'${path.replaceAll("'", "''")}'`;
+    const script = `$ErrorActionPreference='Stop'; $p=${quoted}; $item=Get-Item -LiteralPath $p -Force; `
+        + `if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Reparse point' }; `
+        + `$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User; $acl=Get-Acl -LiteralPath $p; `
+        + `$acl.SetAccessRuleProtection($true,$false); foreach ($r in @($acl.Access)) { [void]$acl.RemoveAccessRuleSpecific($r) }; $acl.SetOwner($sid); `
+        + `foreach ($s in @($sid.Value,'S-1-5-18','S-1-5-32-544')) { $id=New-Object Security.Principal.SecurityIdentifier($s); `
+        + `$rule=New-Object Security.AccessControl.FileSystemAccessRule($id,'FullControl','Allow'); $acl.AddAccessRule($rule) }; Set-Acl -LiteralPath $p -AclObject $acl`;
+    execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { stdio: "pipe" });
+    windowsAcl(path, true);
+}
+export function toolDirectory(kind, env = process.env, platform = process.platform, home = homedir()) {
+    if (platform === "win32") {
+        const base = env[kind === "config" ? "APPDATA" : "LOCALAPPDATA"];
+        return win32.join(base && win32.isAbsolute(base) ? base : win32.join(home, "AppData", kind === "config" ? "Roaming" : "Local"), "checkpoint-axi");
+    }
+    const xdg = env[kind === "config" ? "XDG_CONFIG_HOME" : "XDG_STATE_HOME"];
+    return join(xdg && isAbsolute(xdg) ? xdg : join(home, kind === "config" ? ".config" : ".local/state"), "checkpoint-axi");
+}
+export function readPrivateFile(path, secret, verifyAcl, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const insecure = () => {
+        throw new AxiError("Insecure private file", "CONFIG_INSECURE", [
+            platform === "win32" ? "Apply a protected DACL granting FullControl only to the current user, SYSTEM and Administrators"
+                : "Ensure the file is regular, owned by the current user and has mode 600",
+        ]);
+    };
+    function validate(stat) {
+        if (!stat.isFile() || stat.isSymbolicLink())
+            insecure();
+        if (platform !== "win32" && (stat.uid !== (options.uid ?? process.getuid()) || (stat.mode & (secret ? 0o077 : 0o022)) !== 0))
+            insecure();
+    }
+    validate(lstatSync(path));
+    if (platform === "win32") {
+        try {
+            (options.acl ?? windowsAcl)(path, verifyAcl);
+        }
+        catch {
+            insecure();
+        }
+    }
+    const fd = openSync(path, constants.O_RDONLY | (platform === "win32" ? 0 : constants.O_NOFOLLOW));
+    try {
+        validate(fstatSync(fd));
+        return readFileSync(fd, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}