@knowttl/checkpoint-axi 0.0.0-stage → 0.1.0

package/dist/src/catalogue.d.ts

@@ -0,0 +1,317 @@
+export declare const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
+export declare const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
+export declare const catalogue: {
+    readonly "email download": {
+        readonly 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)";
+        readonly flags: {
+            readonly config: string;
+            readonly profile: string;
+            readonly help: string;
+            readonly out: "Required absolute new output file; mode 0600, never stdout or overwrite";
+            readonly original: "Download original email without processing modifications; default false";
+        };
+        readonly examples: readonly ["checkpoint-axi email download <entity-id> --out /absolute/message", "checkpoint-axi email download <entity-id> --original --out /absolute/original"];
+    };
+    readonly "attachment download": {
+        readonly 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)";
+        readonly flags: {
+            readonly config: string;
+            readonly profile: string;
+            readonly help: string;
+            readonly out: "Required absolute new output file; mode 0600, never stdout or overwrite";
+            readonly scope: "Optional authorized scope query; default profile scope when configured; live behavior unverified";
+        };
+        readonly examples: readonly ["checkpoint-axi attachment download <entity-id> <attachment-id> --out /absolute/attachment", "checkpoint-axi attachment download <entity-id> <attachment-id> --scope <scope> --out /absolute/attachment"];
+    };
+    readonly "attachment download-all": {
+        readonly 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)";
+        readonly flags: {
+            readonly config: string;
+            readonly profile: string;
+            readonly help: string;
+            readonly out: "Required absolute new output file; mode 0600, never stdout or overwrite";
+            readonly scope: "Optional authorized scope query; default profile scope when configured; live behavior unverified";
+        };
+        readonly examples: readonly ["checkpoint-axi attachment download-all <entity-id> --out /absolute/attachments", "checkpoint-axi attachment download-all <entity-id> --scope <scope> --out /absolute/attachments"];
+    };
+    readonly "exception create": {
+        readonly 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)";
+        readonly flags: {
+            readonly input: "Required absolute private JSON file containing documented requestData fields directly; fields depend on kind; update sends a replacement PUT";
+            readonly specific: "Malware/url/dlp only: use the documented create-specific /exceptions route; default false; included in confirmation digest";
+            readonly execute: string;
+            readonly "dry-run": string;
+            readonly confirm: string;
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["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>'"];
+    };
+    readonly "exception update": {
+        readonly 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)";
+        readonly flags: {
+            readonly input: "Required absolute private JSON file containing documented requestData fields directly; fields depend on kind; update sends a replacement PUT";
+            readonly execute: string;
+            readonly "dry-run": string;
+            readonly confirm: string;
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["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>'"];
+    };
+    readonly "exception remove": {
+        readonly 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)";
+        readonly flags: {
+            execute: string;
+            "dry-run": string;
+            confirm: string;
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi exception remove phishing-allow <id>", "checkpoint-axi exception remove spam-allow <id> --execute --confirm 'exception.spam-allow.remove <id>'"];
+    };
+    readonly "exception remove-items": {
+        readonly description: "Preview or remove 1-20 click-time items by caller-supplied IDs; existence is unverified (guide pages 97-98)";
+        readonly flags: {
+            readonly ids: "Required 1-20 unique comma-separated click-time item IDs";
+            readonly execute: string;
+            readonly "dry-run": string;
+            readonly confirm: string;
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["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>'"];
+    };
+    readonly "exception clear": {
+        readonly 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)";
+        readonly flags: {
+            execute: string;
+            "dry-run": string;
+            confirm: string;
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi exception clear click-time", "checkpoint-axi exception clear click-time --dry-run"];
+    };
+    readonly "event action": {
+        readonly description: "Preview or request a name-only event action; parameterized actions refuse ENDPOINT_UNVERIFIED pending commissioning (guide pages 35-37, 42-45)";
+        readonly flags: {
+            readonly ids: "Required comma-separated unique event IDs; maximum 20";
+            readonly name: "Required available action name; nonempty action parameters are unverified";
+            readonly execute: string;
+            readonly "dry-run": string;
+            readonly confirm: string;
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi event action --ids <id> --name dismiss", "checkpoint-axi event action --ids <id> --name dismiss --execute --confirm 'event.action.dismiss <id>'"];
+    };
+    readonly "email quarantine": {
+        readonly description: "Preview or request asynchronous email quarantine through the gated write coordinator (guide pages 28-30)";
+        readonly flags: {
+            ids: string;
+            execute: string;
+            "dry-run": string;
+            confirm: string;
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi email quarantine --ids <id>", "checkpoint-axi email quarantine --ids <id> --execute --confirm 'email.quarantine <id>'"];
+    };
+    readonly "email restore": {
+        readonly description: "Preview or request asynchronous email restore through the gated write coordinator (guide pages 28-30)";
+        readonly flags: {
+            ids: string;
+            execute: string;
+            "dry-run": string;
+            confirm: string;
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi email restore --ids <id>", "checkpoint-axi email restore --ids <id> --execute --confirm 'email.restore <id>'"];
+    };
+    readonly "exception list": {
+        readonly description: "List bounded exceptions for phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url or dlp (guide pages 49-123)";
+        readonly flags: {
+            readonly type: string;
+            readonly items: "Click-time item routes instead of list routes; default false";
+            readonly limit: string;
+            readonly all: "Return up to 1000 rows within transport budgets; no server continuation parameter is documented";
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi exception list phishing-allow", "checkpoint-axi exception list malware --type hash", "checkpoint-axi exception list click-time --items --all"];
+    };
+    readonly "exception show": {
+        readonly description: "Show an exception by kind and ID/value; anomaly refuses ENDPOINT_UNVERIFIED pending commissioning (guide pages 52-123)";
+        readonly flags: {
+            readonly type: string;
+            readonly items: "Click-time item route instead of list route; default false";
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["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"];
+    };
+    readonly "event list": {
+        readonly description: "List security events with bounded scroll continuation (API guide pages 37-42)";
+        readonly flags: {
+            readonly saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails";
+            readonly "event-types": "Comma-separated event types; default unfiltered";
+            readonly "event-states": "Comma-separated event states; default unfiltered";
+            readonly severities: "Comma-separated severities; default unfiltered";
+            readonly "event-ids": "Comma-separated event IDs; default unfiltered";
+            readonly "confidence-indicator": "Confidence indicator selector; default unfiltered";
+            readonly description: "Description selector; default unfiltered";
+            readonly "start-date": string;
+            readonly "end-date": string;
+            readonly limit: string;
+            readonly all: string;
+            readonly cursor: string;
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi event list", "checkpoint-axi event list --all --event-types phishing", "checkpoint-axi event list --cursor <cursor>"];
+    };
+    readonly "event show": {
+        readonly description: "Show one event, actions taken and available actions (API guide pages 34-37)";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi event show <id>", "checkpoint-axi event show <id> --full"];
+    };
+    readonly "task show": {
+        readonly description: "Show asynchronous task status and per-action details (API guide pages 30-33)";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --full"];
+    };
+    readonly "email search": {
+        readonly description: "Search emails with a bounded date window and scroll continuation (API guide pages 18-27)";
+        readonly flags: {
+            readonly filter: "JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters (guide pages 19-20)";
+            readonly "start-date": string;
+            readonly "end-date": string;
+            readonly limit: string;
+            readonly all: string;
+            readonly cursor: string;
+            readonly saas: "SaaS override; default selected profile saas or office365_emails";
+            readonly "saas-entity": "Optional SaaS entity type selector";
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi email search", "checkpoint-axi email search --all --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"];
+    };
+    readonly "email show": {
+        readonly description: "Show one email with verdicts, actions and available actions (API guide pages 10-18)";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi email show <id>", "checkpoint-axi email show <id> --full"];
+    };
+    readonly doctor: {
+        readonly description: "Check regional API authentication and one bounded email search without printing tenant data";
+        readonly flags: {
+            readonly saas: "SaaS override; default selected profile saas or office365_emails";
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi doctor", "checkpoint-axi doctor --profile example --saas office365_emails"];
+    };
+    readonly home: {
+        readonly description: "Show local profile context without resolving secrets or making API calls";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi", "checkpoint-axi home --profile example"];
+    };
+    readonly "auth status": {
+        readonly description: "Validate the selected local profile and secret source without API calls";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi auth status", "checkpoint-axi auth status --profile example"];
+    };
+    readonly "profile list": {
+        readonly description: "List file profiles without resolving secrets; --profile does not filter this list";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi profile list", "checkpoint-axi profile list --config /example/config.json"];
+    };
+    readonly "config path": {
+        readonly description: "Show config and state paths without reading files; --profile does not affect paths";
+        readonly flags: {
+            config: string;
+            profile: string;
+            fields: string;
+            full: string;
+            help: string;
+        };
+        readonly examples: readonly ["checkpoint-axi config path", "checkpoint-axi config path --fields config"];
+    };
+};
+export declare function help(): Record<string, unknown>;

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>>;