@knowttl/checkpoint-axi 0.1.0 → 0.1.2

package/axi-credential.schema.json

@@ -6,29 +6,48 @@
   "additionalProperties": false,
   "required": ["region", "clientId"],
   "properties": {
-    "region": { "type": "string", "enum": ["us", "eu", "ca", "au", "uk", "uae", "in"] },
-    "clientId": { "type": "string", "minLength": 1, "pattern": "\\S" },
-    "clientSecret": { "$ref": "#/$defs/secretRef", "x-secret": true, "default": { "env": "CHECKPOINT_AXI_CLIENT_SECRET" } },
-    "saas": { "type": "string", "minLength": 1, "pattern": "\\S", "default": "office365_emails" },
-    "scope": { "type": "string", "minLength": 1, "pattern": "\\S" },
+    "region": {
+      "title": "Region", "description": "Required region code for your tenant's regional gateway: us, eu, ca, au, uk, uae or in. Obtain it from your tenant administrator. There is no default; URLs are not accepted.",
+      "type": "string", "enum": ["us", "eu", "ca", "au", "uk", "uae", "in"]
+    },
+    "clientId": {
+      "title": "Client ID", "description": "Required non-blank API client ID from your tenant's API credentials. There is no default.",
+      "type": "string", "minLength": 1, "pattern": "\\S"
+    },
+    "clientSecret": {
+      "title": "Client secret reference", "description": "Reference the environment variable or absolute private file containing your API client secret, never the secret itself. If omitted, reads CHECKPOINT_AXI_CLIENT_SECRET; a missing or blank secret prevents authentication.",
+      "$ref": "#/$defs/secretRef", "x-secret": true, "default": { "env": "CHECKPOINT_AXI_CLIENT_SECRET" }
+    },
+    "saas": {
+      "title": "SaaS application name",
+      "description": "One non-blank SaaS application name for the tenant, not a gateway, host or authentication URL; slash (/) is not allowed. Obtain the exact API application name from your tenant administrator or Check Point support. If omitted, defaults to office365_emails, selecting Microsoft 365 email; supply the appropriate name for another application. A profile takes one value, while --saas on event list accepts a comma-separated list.",
+      "type": "string", "minLength": 1, "pattern": "\\S", "not": { "pattern": "/" }, "default": "office365_emails"
+    },
+    "scope": {
+      "title": "Download scope",
+      "description": "Download scope value supplied by your tenant administrator or Check Point support for the intended download. Use printable ASCII with no spaces (characters ! through ~); comma-separated values are sent verbatim. There is no default: omitted means unset, so email download fails because it requires the profile scope as its scopes header. Attachment download uses this only as the default scope query; --scope overrides it, and neither supplied means no scope query. Tenant scope authorization and the relationship between these selectors remain unverified; do not guess a value.",
+      "type": "string", "minLength": 1, "pattern": "^[!-~]+$"
+    },
     "downloads": {
+      "title": "Download permission", "description": "Separate file-profile download opt-in. If omitted, downloads are disabled. Environment profiles cannot enable downloads.",
       "type": "object", "additionalProperties": false, "required": ["allow"], "default": { "allow": false },
-      "properties": { "allow": { "type": "boolean" } }
+      "properties": { "allow": { "title": "Allow downloads", "description": "Set true to permit download commands; each command still requires a new private output file.", "type": "boolean" } }
     },
     "writes": {
+      "title": "Write permissions", "description": "File-profile write opt-in and exact operation allow-list. If omitted, writes are disabled with no allowed operations. Forced read-only always wins.",
       "type": "object", "additionalProperties": false, "required": ["allowWrites", "operations"],
       "default": { "allowWrites": false, "operations": [] },
       "properties": {
-        "allowWrites": { "type": "boolean" },
-        "operations": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][A-Za-z0-9_.-]*$" } }
+        "allowWrites": { "title": "Allow writes", "description": "Set true to permit listed operations, subject to preview, exact confirmation and durable redacted intent.", "type": "boolean" },
+        "operations": { "title": "Allowed write operations", "description": "Exact operation names to allow, such as email.quarantine. An empty list permits no writes.", "type": "array", "items": { "type": "string", "pattern": "^[a-z][A-Za-z0-9_.-]*$" } }
       }
     }
   },
   "$defs": {
     "secretRef": {
       "oneOf": [
-        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
-        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "type": "string", "pattern": "^(?:/|[A-Za-z]:[\\\\/])" } } }
+        { "type": "object", "additionalProperties": false, "required": ["env"], "properties": { "env": { "title": "Secret environment variable", "description": "Name of the environment variable holding the secret, such as CHECKPOINT_AXI_CLIENT_SECRET. Use letters, digits and underscores, starting with a letter or underscore.", "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
+        { "type": "object", "additionalProperties": false, "required": ["file"], "properties": { "file": { "title": "Secret file path", "description": "Absolute path to a private UTF-8 file holding the secret. Symlinks and insecure permissions are rejected; a leading BOM and trailing whitespace are removed from its content.", "type": "string", "pattern": "^(?:/|[A-Za-z]:[\\\\/])" } } }
       ]
     }
   }

package/dist/src/catalogue.d.ts

@@ -1,5 +1,7 @@
 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 EMAIL_PAYLOAD_ATTRIBUTES: string[];
+export declare const EMAIL_FILTER_GUIDANCE: string;
 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)";
@@ -230,7 +232,7 @@ export declare const catalogue: {
     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 filter: `JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. ${string}`;
             readonly "start-date": string;
             readonly "end-date": string;
             readonly limit: string;

package/dist/src/catalogue.js

@@ -1,6 +1,11 @@
 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";
+export const EMAIL_PAYLOAD_ATTRIBUTES = ["subject", "fromEmail", "attachmentCount", "internetMessageId", "received", "size", "emailLinks", "attachments", "mode", "recipients", "fromDomain", "fromUser", "fromName", "to", "toUser", "cc", "ccUser", "bcc", "bccUser", "replyToEmail", "replyToNickname", "isRead", "isDeleted", "isIncoming", "isInternal", "isOutgoing", "isQuarantined", "isQuarantineNotification", "isRestored", "isRestoreRequested", "isRestoreDeclined", "saasSpamVerdict", "SpfResult"].map((name) => `entityPayload.${name}`);
+export const EMAIL_FILTER_GUIDANCE = "saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: "
+    + EMAIL_PAYLOAD_ATTRIBUTES.slice(0, 3).join(", ") + ". Other documented email payload paths (pages 15-16, 24-25): "
+    + EMAIL_PAYLOAD_ATTRIBUTES.slice(3).join(", ")
+    + ". saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string.";
 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",
@@ -82,7 +87,7 @@ export const catalogue = {
             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)",
+            filter: `JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. ${EMAIL_FILTER_GUIDANCE}`,
         }, 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"] },

package/dist/src/profiles.js

@@ -8,6 +8,7 @@ import { SecretRedactor } from "./redact.js";
 const profileName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/);
 const region = z.enum(Object.keys(REGIONS));
 const nonempty = z.string().trim().min(1);
+const saasName = nonempty.refine((value) => !value.includes("/"));
 function schema(platform) {
     const secretRef = z.union([
         z.strictObject({ env: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/) }),
@@ -17,7 +18,7 @@ function schema(platform) {
         region,
         clientId: nonempty,
         clientSecret: secretRef.default({ env: "CHECKPOINT_AXI_CLIENT_SECRET" }),
-        saas: nonempty.default("office365_emails"),
+        saas: saasName.default("office365_emails"),
         scope: nonempty.optional(),
         downloads: z.strictObject({ allow: z.boolean() }).default({ allow: false }),
         writes: z.strictObject({ allowWrites: z.boolean(), operations: z.array(z.string().regex(/^[a-z][A-Za-z0-9_.-]*$/)) })
@@ -78,7 +79,7 @@ export function credentialStore(options = {}, redactor = new SecretRedactor()) {
         }
         const parsed = schema(platform).safeParse(raw);
         if (!parsed.success)
-            return invalid("Invalid configuration: check profile names, region, defaultProfile, unknown fields and clientSecret SecretRef");
+            return invalid("Invalid configuration: check profile names, region, defaultProfile, unknown fields, clientSecret SecretRef and saas (use a SaaS application name, not a URL)");
         return { path, config: parsed.data };
     }
     function select(config, flag) {
@@ -87,8 +88,11 @@ export function credentialStore(options = {}, redactor = new SecretRedactor()) {
             invalid("Invalid selected profile name");
         const envFields = ["REGION", "CLIENT_ID", "SAAS", "SCOPE"];
         if (selected === undefined && envFields.some((field) => env[`CHECKPOINT_AXI_${field}`] !== undefined)) {
+            if (env.CHECKPOINT_AXI_SAAS !== undefined && !saasName.safeParse(env.CHECKPOINT_AXI_SAAS).success) {
+                return invalid("saas must be a SaaS application name, not a URL");
+            }
             if (!region.safeParse(env.CHECKPOINT_AXI_REGION).success || !env.CHECKPOINT_AXI_CLIENT_ID?.trim() || !env.CHECKPOINT_AXI_CLIENT_SECRET?.trim()
-                || (env.CHECKPOINT_AXI_SAAS !== undefined && !env.CHECKPOINT_AXI_SAAS.trim()) || (env.CHECKPOINT_AXI_SCOPE !== undefined && !env.CHECKPOINT_AXI_SCOPE.trim())) {
+                || (env.CHECKPOINT_AXI_SCOPE !== undefined && !env.CHECKPOINT_AXI_SCOPE.trim())) {
                 return invalid("Incomplete or invalid env profile; set REGION, CLIENT_ID and CLIENT_SECRET together");
             }
             return { region: env.CHECKPOINT_AXI_REGION, clientId: env.CHECKPOINT_AXI_CLIENT_ID.trim(),

package/dist/src/reads.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { REGIONS } from "./regions.js";
 import { gateway, READ_LIMITS } from "./transport.js";
+import { responseInvalid } from "./response-invalid.js";
 const day = 86_400_000;
 const timestamp = z.iso.datetime({ offset: true });
 const filters = z.array(z.strictObject({ saasAttrName: z.string().min(1),
@@ -10,10 +11,12 @@ const filters = z.array(z.strictObject({ saasAttrName: z.string().min(1),
     saasAttrValue: z.string() }));
 const continuation = z.strictObject({ version: z.literal(1), binding: z.string(), start: timestamp, end: timestamp,
     scroll: z.string().optional(), offset: z.number().int().nonnegative(), replayRisk: z.literal(true).optional() });
+// The guide's prose/table (pp.11,14) says security-result array; its JSON examples use an object.
+const securityResults = z.object({ combinedVerdict: z.unknown().optional() }).passthrough();
 // Entity schemas and SaaS-specific payloads: guide pages 11-15 and 21-24.
 const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().optional() }).passthrough(),
     entityPayload: z.object({ subject: z.string().optional() }).passthrough(),
-    entitySecurityResults: z.object({ combinedVerdict: z.unknown().optional() }).passthrough().optional(),
+    entitySecurityResults: z.union([securityResults, z.array(z.object({}).passthrough())]).optional(),
 }).passthrough();
 // Event and task fields: guide pages 31-32, 35-36 and 40-41.
 const event = z.object({ eventId: z.string().min(1), type: z.string(), state: z.string(), severity: z.string() }).passthrough();
@@ -101,15 +104,19 @@ export async function readCommand(name, id, flags, store, transport) {
     if (name.endsWith(" show")) {
         const kind = name.split(" ")[0];
         const page = await api.read({ path: name === "task show" ? `/task/${id}` : isEvent ? `/event/${id}` : `/search/entity/${id}` });
+        const response = { responseData: page.dataIsArray ? page.records : page.records[0] };
+        const recordPath = page.dataIsArray ? ["responseData", 0] : ["responseData"];
         if (page.records.length === 0)
             throw new AxiError(`${kind} was not found`, "NOT_FOUND", []);
         const parsed = (name === "task show" ? task : isEvent ? event : entity).safeParse(page.records[0]);
-        if (page.records.length !== 1 || !parsed.success)
-            throw new AxiError(`Invalid ${kind} detail response`, "RESPONSE_INVALID", []);
+        if (page.records.length !== 1)
+            throw responseInvalid(`Invalid ${kind} detail response`, response, [["responseData"]]);
+        if (!parsed.success)
+            throw responseInvalid(`Invalid ${kind} detail response`, response, parsed.error.issues.map((issue) => [...recordPath, ...issue.path]));
         const record = page.records[0];
         const returnedId = name === "task show" ? String(record.id) : isEvent ? record.eventId : record.entityInfo?.entityId;
         if (returnedId !== id)
-            throw new AxiError(`Invalid ${kind} detail response`, "RESPONSE_INVALID", []);
+            throw responseInvalid(`Invalid ${kind} detail response`, response, [[...recordPath, ...(name === "task show" ? ["id"] : isEvent ? ["eventId"] : ["entityInfo", "entityId"])]]);
         return { [kind]: parsed.data };
     }
     const results = [];
@@ -131,11 +138,14 @@ export async function readCommand(name, id, flags, store, transport) {
             throw error;
         }
         const parsed = z.array(isEvent ? event : entity).safeParse(page.records);
-        if (!parsed.success || offset > page.records.length)
-            throw new AxiError("Invalid search response", "RESPONSE_INVALID", []);
+        const response = { responseData: page.dataIsArray ? page.records : page.records[0] };
+        if (!parsed.success)
+            throw responseInvalid("Invalid search response", response, parsed.error.issues.map((issue) => ["responseData", ...(page.dataIsArray ? issue.path : issue.path.slice(1))]));
+        if (offset > page.records.length)
+            throw responseInvalid("Invalid search response", response, [["responseData"]]);
         // Never wrap an echoed credential in a reversible continuation cursor.
         if (page.scrollId && store.redactor.text(page.scrollId) !== page.scrollId)
-            throw new AxiError("Unsafe API scrollId", "RESPONSE_INVALID", []);
+            throw responseInvalid("Unsafe API scrollId", { responseEnvelope: { scrollId: page.scrollId } }, [["responseEnvelope", "scrollId"]]);
         total = page.total ?? total;
         const rows = parsed.data.slice(offset, offset + limit - results.length);
         results.push(...rows.map((record) => {
@@ -145,7 +155,7 @@ export async function readCommand(name, id, flags, store, transport) {
             }
             const value = entity.parse(record);
             return { id: value.entityInfo.entityId, subject: value.entityPayload.subject ?? "",
-                state: value.entityInfo.entityActionState ?? "", verdict: value.entitySecurityResults?.combinedVerdict ?? null };
+                state: value.entityInfo.entityActionState ?? "", verdict: Array.isArray(value.entitySecurityResults) ? null : value.entitySecurityResults?.combinedVerdict ?? null };
         }));
         offset += rows.length;
         if (offset < page.records.length) {

package/dist/src/response-invalid.d.ts

@@ -0,0 +1,2 @@
+import { AxiError } from "axi-sdk-js";
+export declare function responseInvalid(message: string, value: unknown, paths: readonly (readonly PropertyKey[])[]): AxiError;

package/dist/src/response-invalid.js

@@ -0,0 +1,17 @@
+import { AxiError } from "axi-sdk-js";
+// Never format validator messages or received values: both may contain tenant data.
+export function responseInvalid(message, value, paths) {
+    const failures = paths.map((path) => {
+        let received = value;
+        let location = "$";
+        for (const key of path) {
+            location += typeof key === "number" ? `[${key}]`
+                : `.${typeof key === "string" && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key) ? key : "<key>"}`;
+            received = received !== null && typeof received === "object" && Object.hasOwn(received, key)
+                ? received[key] : undefined;
+        }
+        const type = received === undefined ? "missing" : received === null ? "null" : Array.isArray(received) ? "array" : typeof received;
+        return `${location}: ${type}`;
+    });
+    return new AxiError(`${message} (${[...new Set(failures)].join("; ")})`, "RESPONSE_INVALID", []);
+}

package/dist/src/transport.d.ts

@@ -59,6 +59,7 @@ export type ReadRequest = {
 };
 export type Page = {
     records: unknown[];
+    dataIsArray: boolean;
     scrollId?: string;
     total?: number;
 };

package/dist/src/transport.js

@@ -4,6 +4,7 @@ import { request } from "node:https";
 import { setTimeout as delay } from "node:timers/promises";
 import { REGIONS } from "./regions.js";
 import { consumeWriteAuthorization } from "./writes.js";
+import { responseInvalid } from "./response-invalid.js";
 export const READ_LIMITS = { requests: 10, rows: 1_000, milliseconds: 60_000, bytes: 8 * 1024 * 1024 };
 export const DOWNLOAD_LIMIT = 50 * 1024 * 1024;
 const failure = (code, message) => new AxiError(message, code, ["Check the selected region and credentials; run checkpoint-axi doctor"]);
@@ -12,24 +13,26 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
 export function decodePage(value, unverified = false) {
     // These exception families publish no response schema (guide pages 83-123).
     if (unverified && (!object(value) || !Object.hasOwn(value, "responseEnvelope"))) {
-        return { records: Array.isArray(value) ? value : [value] };
+        return { records: Array.isArray(value) ? value : [value], dataIsArray: Array.isArray(value) };
     }
-    if (!object(value) || !object(value.responseEnvelope))
-        throw failure("RESPONSE_INVALID", "Missing API response envelope");
+    if (!object(value))
+        throw responseInvalid("Missing API response envelope", value, [[]]);
+    if (!object(value.responseEnvelope))
+        throw responseInvalid("Missing API response envelope", value, [["responseEnvelope"]]);
     const envelope = value.responseEnvelope;
     if (envelope.responseCode !== 0 && envelope.responseCode !== "0" && envelope.responseCode !== 200 && envelope.responseCode !== "200") {
         throw failure("API_ERROR", "API response envelope did not report success");
     }
     const data = value.responseData;
     if ((!unverified && !Array.isArray(data) && !object(data)) || data === undefined)
-        throw failure("RESPONSE_INVALID", "Expected responseData");
+        throw responseInvalid("Expected responseData", value, [["responseData"]]);
     if (envelope.scrollId !== undefined && envelope.scrollId !== null && typeof envelope.scrollId !== "string") {
-        throw failure("RESPONSE_INVALID", "Invalid API scrollId");
+        throw responseInvalid("Invalid API scrollId", value, [["responseEnvelope", "scrollId"]]);
     }
     if (envelope.totalRecordsNumber !== undefined && (!Number.isSafeInteger(envelope.totalRecordsNumber) || Number(envelope.totalRecordsNumber) < 0)) {
-        throw failure("RESPONSE_INVALID", "Invalid API totalRecordsNumber");
+        throw responseInvalid("Invalid API totalRecordsNumber", value, [["responseEnvelope", "totalRecordsNumber"]]);
     }
-    return { records: Array.isArray(data) ? data : [data], scrollId: typeof envelope.scrollId === "string" && envelope.scrollId ? envelope.scrollId : undefined,
+    return { records: Array.isArray(data) ? data : [data], dataIsArray: Array.isArray(data), scrollId: typeof envelope.scrollId === "string" && envelope.scrollId ? envelope.scrollId : undefined,
         total: envelope.totalRecordsNumber };
 }
 // No field name or lifetime is commissioned yet (guide page 8).
@@ -125,7 +128,7 @@ export function gateway(profile, credentials, redactor, dependencies = {}, mutat
                         resolve({ status, value: JSON.parse(json) });
                     }
                     catch {
-                        reject(failure("RESPONSE_INVALID", "API returned invalid JSON"));
+                        reject(responseInvalid("API returned invalid JSON", json, [[]]));
                     }
                 });
             });

package/docs/agent-guide.md

@@ -0,0 +1,114 @@
+<!-- Generated by scripts/generate-docs.mjs from src/catalogue.ts. Do not hand-edit. -->
+
+# Investigation agent guide
+
+Start with these reads; use command help only to recover from a failed command or inspect an unfamiliar selector.
+Examples assume an installed checkpoint-axi and an operator-provisioned read-only profile (the repository tests use synthetic credentials and a fake gateway).
+Without a global install, replace checkpoint-axi with npx -y @knowttl/checkpoint-axi.
+Never pass credentials in argv; use environment/file SecretRefs as described in [configuration](configuration.md).
+Force read-only with CHECKPOINT_AXI_READ_ONLY=1; this overrides profile write permissions.
+Live API contracts remain uncommissioned; fixture success does not establish live compatibility.
+
+## Read commands and examples
+
+Local readiness checks make no API calls:
+
+```sh
+checkpoint-axi
+checkpoint-axi config path
+checkpoint-axi profile list
+checkpoint-axi auth status
+```
+
+The home view shows local profile context, config path shows effective paths, profile list lists file profiles, and auth status validates the selected secret source locally.
+Add --profile <name> or --config <absolute-path> to select provisioned configuration; profile list ignores --profile.
+Doctor authenticates and checks one search page without printing email data:
+
+```sh
+checkpoint-axi doctor
+```
+
+Search emails, then inspect a returned entity ID for payload, verdicts, actions taken and available actions:
+
+```sh
+checkpoint-axi email search --limit 5 --fields emails,count,total,complete,reason,cursor
+checkpoint-axi email show synthetic-email-1 --fields email
+```
+
+Search flags: --saas (default profile SaaS or office365_emails), --saas-entity, and --filter (JSON array of {saasAttrName, saasAttrOp, saasAttrValue}).
+saasAttrName is a field path, not a closed enum (guide pages 19-20).
+Documented examples: entityPayload.subject, entityPayload.fromEmail, entityPayload.attachmentCount.
+Other documented email payload paths (pages 15-16, 24-25): entityPayload.internetMessageId, entityPayload.received, entityPayload.size, entityPayload.emailLinks, entityPayload.attachments, entityPayload.mode, entityPayload.recipients, entityPayload.fromDomain, entityPayload.fromUser, entityPayload.fromName, entityPayload.to, entityPayload.toUser, entityPayload.cc, entityPayload.ccUser, entityPayload.bcc, entityPayload.bccUser, entityPayload.replyToEmail, entityPayload.replyToNickname, entityPayload.isRead, entityPayload.isDeleted, entityPayload.isIncoming, entityPayload.isInternal, entityPayload.isOutgoing, entityPayload.isQuarantined, entityPayload.isQuarantineNotification, entityPayload.isRestored, entityPayload.isRestoreRequested, entityPayload.isRestoreDeclined, entityPayload.saasSpamVerdict, entityPayload.SpfResult.
+saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan.
+The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan.
+saasAttrValue is a string.
+Event selectors include --event-types, --event-states, --severities, --event-ids (comma-separated), --confidence-indicator and --description; --saas accepts comma-separated SaaS values here.
+Event detail includes available actions; task detail reads status and per-action results once, without waiting or polling:
+
+```sh
+checkpoint-axi event list --all --event-types phishing --fields events,count,total,complete,reason,cursor
+checkpoint-axi event show synthetic-event-1 --fields event
+checkpoint-axi task show synthetic-task-1 --fields task
+```
+
+Inspect exception rules with exception list <kind> or exception show <kind> <id-or-value>:
+
+```sh
+checkpoint-axi exception list phishing-block --limit 5 --fields exceptions,count,total,complete,reason
+checkpoint-axi exception show phishing-block synthetic-exception-1 --fields exception
+```
+
+Kinds: phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url, dlp.
+For malware, --type is required: hash, micro_hash, file_type, ppat_sender_name, allow_file_type or sender_email.
+For url, --type is allow-url, allow-domain, block-url or block-domain; for dlp, hash, text_content, sender_email or recipient_email.
+Click-time --items selects item routes instead of list routes.
+Anomaly show is refused with ENDPOINT_UNVERIFIED; use anomaly list.
+Undocumented response shapes carry responseSchema: unverified; do not infer identities from them.
+
+## One-call forms and output bounds
+
+Email search and event list --all follow scroll pages in one invocation, capped at 1000 rows, 10 HTTP requests, 60 seconds and 8 MiB of JSON, including authentication and read retries.
+Both default to 50 rows over the past 24 hours; --limit accepts 1-1000 and cannot combine with --all.
+Use --start-date and --end-date with ISO timestamps including timezones; the positive window cannot exceed 31 days.
+Inspect complete, reason and cursor even on exit 0; limits and page replay can leave results incomplete.
+Resume with --cursor <returned-cursor> and the original selectors/profile; see [continuation limitations](reads.md#email-reads).
+Exception --all bounds returned rows at 1000 but cannot fetch additional pages: no continuation parameter is documented.
+Email/event detail already includes available actions, avoiding a separate action lookup.
+There is no bulk detail expansion, cross-resource pivot or task wait flag; use returned IDs for individual reads and never replay an action to obtain its status.
+
+--fields selects top-level output keys, not nested row columns: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+Email rows contain id,subject,state,verdict; event rows contain id,type,state,severity; documented exception rows contain id,sender,subject,comment.
+TOON strings preview at 500 characters; --full expands strings after redaction, while cursors are never truncated.
+
+## Help and safety
+
+Top-level --help returns the full command catalogue, common flags, version flags and home examples.
+Group --help (such as email --help) is unsupported and returns VALIDATION_ERROR with the valid command list; select a leaf command directly.
+Leaf command --help returns its description, accepted flags with defaults, and examples; positional arguments appear in those examples.
+Use the failing leaf's help to correct syntax; do not run a help sweep before investigating.
+
+Reviewed read allowlist: home (also no arguments), config path, profile list, auth status, doctor, email search, email show, event list, event show, task show, exception list, exception show (except unsupported anomaly detail).
+These commands never mutate remote state or save downloaded files; API authentication exchanges tokens held only in memory.
+Exclude email quarantine/restore, event action and every exception create/update/remove/remove-items/clear command, including previews and --specific creates, from an investigation read allowlist.
+Writes require exact profile operation scope, preview, --execute, exact --confirm and durable redacted intent; forced read-only always wins.
+Email download and attachment download/download-all write local files and require separate download opt-in; they are outside the read allowlist.
+See [write safety](writes.md) and [download safety](downloads.md) before requesting them.
+
+## Failure recovery
+
+Exit 0 means success, preview or no-op; 2 means invalid syntax (VALIDATION_ERROR); 1 means configuration, authentication, transport or operation failure.
+Structured errors and suggestions are on stdout; follow the code and suggestion instead of retrying blindly.
+
+| Code | Meaning and next action |
+|---|---|
+| VALIDATION_ERROR | Invalid flags, IDs, date window or mismatched cursor selectors; correct the failed command. |
+| PROFILE_REQUIRED / CONFIG_INVALID | Missing or invalid configuration; select a complete provisioned profile. |
+| CONFIG_INSECURE | Fix private-file permissions using the configuration guide. |
+| AUTH_FAILED | Check region and secret source; the CLI already attempts one token re-exchange after API rejection. |
+| AUTH_SHAPE_UNVERIFIED / ENDPOINT_UNVERIFIED | Contract is undocumented; request owner commissioning, never guess a route or token shape. |
+| NOT_FOUND | No matching detail record; verify the ID and profile using a list read. |
+| RESPONSE_INVALID / API_ERROR / HTTP_ERROR | Unexpected response or upstream failure; inspect the redacted error and verify service/profile before retrying. |
+| RATE_LIMITED | Two read retries exhausted; defer work instead of immediate repeated calls. |
+| REQUEST_BUDGET / TIME_BUDGET / RESPONSE_TOO_LARGE | Reduce date window or limit; inspect incomplete results and continuation before another bounded read. |
+| WRITES_DISABLED / DOWNLOADS_DISABLED | Operation is outside profile permissions; do not loosen permissions during investigation. |
+| OUTCOME_UNKNOWN | A mutation may have happened; reconcile with reads and the journal, never replay automatically. |

package/docs/commands.md

@@ -6,6 +6,34 @@ Inspect Check Point Email Security through compact, guarded AXI commands.
 Email, event, task and exception reads use the regional API; doctor checks authentication and one bounded search, while discovery commands stay local.
 Run each command with `--help` for concise help.
 
+[attachment download](#attachment-download) | [attachment download-all](#attachment-download-all) | [auth status](#auth-status) | [config path](#config-path) | [doctor](#doctor) | [email download](#email-download) | [email quarantine](#email-quarantine) | [email restore](#email-restore) | [email search](#email-search) | [email show](#email-show) | [event action](#event-action) | [event list](#event-list) | [event show](#event-show) | [exception clear](#exception-clear) | [exception create](#exception-create) | [exception list](#exception-list) | [exception remove](#exception-remove) | [exception remove-items](#exception-remove-items) | [exception show](#exception-show) | [exception update](#exception-update) | [home](#home) | [profile list](#profile-list) | [task show](#task-show)
+
+| Command | Purpose |
+|---|---|
+| `checkpoint-axi attachment download` | 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) |
+| `checkpoint-axi attachment download-all` | 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) |
+| `checkpoint-axi auth status` | Validate the selected local profile and secret source without API calls |
+| `checkpoint-axi config path` | Show config and state paths without reading files; --profile does not affect paths |
+| `checkpoint-axi doctor` | Check regional API authentication and one bounded email search without printing tenant data |
+| `checkpoint-axi email download` | 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) |
+| `checkpoint-axi email quarantine` | Preview or request asynchronous email quarantine through the gated write coordinator (guide pages 28-30) |
+| `checkpoint-axi email restore` | Preview or request asynchronous email restore through the gated write coordinator (guide pages 28-30) |
+| `checkpoint-axi email search` | Search emails with a bounded date window and scroll continuation (API guide pages 18-27) |
+| `checkpoint-axi email show` | Show one email with verdicts, actions and available actions (API guide pages 10-18) |
+| `checkpoint-axi event action` | Preview or request a name-only event action; parameterized actions refuse ENDPOINT_UNVERIFIED pending commissioning (guide pages 35-37, 42-45) |
+| `checkpoint-axi event list` | List security events with bounded scroll continuation (API guide pages 37-42) |
+| `checkpoint-axi event show` | Show one event, actions taken and available actions (API guide pages 34-37) |
+| `checkpoint-axi exception clear` | 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) |
+| `checkpoint-axi exception create` | 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) |
+| `checkpoint-axi exception list` | List bounded exceptions for phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url or dlp (guide pages 49-123) |
+| `checkpoint-axi exception remove` | 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) |
+| `checkpoint-axi exception remove-items` | Preview or remove 1-20 click-time items by caller-supplied IDs; existence is unverified (guide pages 97-98) |
+| `checkpoint-axi exception show` | Show an exception by kind and ID/value; anomaly refuses ENDPOINT_UNVERIFIED pending commissioning (guide pages 52-123) |
+| `checkpoint-axi exception update` | 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) |
+| `checkpoint-axi home` | Show local profile context without resolving secrets or making API calls |
+| `checkpoint-axi profile list` | List file profiles without resolving secrets; --profile does not filter this list |
+| `checkpoint-axi task show` | Show asynchronous task status and per-action details (API guide pages 30-33) |
+
 ## attachment download
 
 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)
@@ -169,7 +197,7 @@ Search emails with a bounded date window and scroll continuation (API guide page
 | `--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 |
-| `--filter` | JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters (guide pages 19-20) |
+| `--filter` | JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: entityPayload.subject, entityPayload.fromEmail, entityPayload.attachmentCount. Other documented email payload paths (pages 15-16, 24-25): entityPayload.internetMessageId, entityPayload.received, entityPayload.size, entityPayload.emailLinks, entityPayload.attachments, entityPayload.mode, entityPayload.recipients, entityPayload.fromDomain, entityPayload.fromUser, entityPayload.fromName, entityPayload.to, entityPayload.toUser, entityPayload.cc, entityPayload.ccUser, entityPayload.bcc, entityPayload.bccUser, entityPayload.replyToEmail, entityPayload.replyToNickname, entityPayload.isRead, entityPayload.isDeleted, entityPayload.isIncoming, entityPayload.isInternal, entityPayload.isOutgoing, entityPayload.isQuarantined, entityPayload.isQuarantineNotification, entityPayload.isRestored, entityPayload.isRestoreRequested, entityPayload.isRestoreDeclined, entityPayload.saasSpamVerdict, entityPayload.SpfResult. saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string. |
 
 ```sh
 checkpoint-axi email search

package/docs/configuration.md

@@ -0,0 +1,77 @@
+# Configuration
+
+See [environment variables and platform defaults](../README.md#configuration) for the complete variable table.
+
+`config path` reports platform paths without reading files.
+Config defaults to `$XDG_CONFIG_HOME/checkpoint-axi/config.json` (or `~/.config/checkpoint-axi/config.json`) on Linux/macOS, and `%APPDATA%\checkpoint-axi\config.json` on Windows.
+State defaults to `$XDG_STATE_HOME/checkpoint-axi` (or `~/.local/state/checkpoint-axi`), and `%LOCALAPPDATA%\checkpoint-axi` on Windows.
+Windows ignores XDG variables.
+XDG and Windows base-directory overrides must be absolute; relative values use the platform defaults.
+If APPDATA or LOCALAPPDATA is absent or relative, the Windows defaults are `~/AppData/Roaming` and `~/AppData/Local` respectively.
+No command discovers config from the current directory or writes configuration.
+
+Create a config file with this synthetic shape and protect it from group/other writes:
+
+```json
+{
+  "version": 1,
+  "defaultProfile": "example",
+  "profiles": {
+    "example": {
+      "region": "eu",
+      "clientId": "synthetic-client",
+      "clientSecret": { "env": "CHECKPOINT_AXI_CLIENT_SECRET" },
+      "saas": "office365_emails",
+      "downloads": { "allow": false },
+      "writes": { "allowWrites": false, "operations": [] }
+    }
+  }
+}
+```
+
+Supply the secret through your environment or an absolute private file SecretRef, never chat, argv or an inline config value.
+Omitting `clientSecret` defaults its reference to `CHECKPOINT_AXI_CLIENT_SECRET`.
+`auth status` resolves the selected reference locally and reports only its kind (`env` or `file`); it never prints the value, client ID, variable name or secret file path.
+It confirms local readiness, not API authentication.
+`profile list` and home never resolve secret files.
+Supported regions are `us`, `eu`, `ca`, `au`, `uk`, `uae` and `in`; there is no origin override.
+The host-facing [credential schema](../axi-credential.schema.json) describes one strict profile.
+
+Config precedence is `--config`, then `CHECKPOINT_AXI_CONFIG`, then the platform path.
+Profile precedence is `--profile`, `CHECKPOINT_AXI_PROFILE`, complete env profile, config default, sole file profile, then an explicit missing/ambiguous error.
+An env profile requires `CHECKPOINT_AXI_REGION`, `CHECKPOINT_AXI_CLIENT_ID` and `CHECKPOINT_AXI_CLIENT_SECRET` together; optional `CHECKPOINT_AXI_SAAS` and `CHECKPOINT_AXI_SCOPE` cannot stand alone.
+File-selected metadata never mixes with env-profile fields, though an explicit SecretRef can name an environment variable.
+Environment profiles always disable writes and downloads.
+`CHECKPOINT_AXI_READ_ONLY` accepts `1`/`true` or `0`/`false` case-insensitively; any other value fails closed.
+`CHECKPOINT_AXI_WRITE_LOG` overrides the write journal, defaulting to `writes.log` in the platform state directory.
+An empty override uses that default.
+
+POSIX reads reject symlinks, foreign ownership, group/other-writable config and any group/other access to secret files.
+Secret file content is UTF-8 with a leading BOM and trailing whitespace removed.
+On Windows, regular files and reparse points are checked without interpreting mode bits; `auth status`, `doctor` and email, event, task and exception API commands also verify a protected DACL for the current user, SYSTEM and Administrators.
+
+## SaaS and scope
+
+`saas` is one non-blank SaaS application name, not a gateway, host or authentication URL.
+Obtain the exact API application name for your tenant from its administrator or Check Point support.
+If omitted, it defaults to `office365_emails`, selecting Microsoft 365 email; choose the appropriate name when targeting another application.
+`office365_emails` is valid; `https://example.test/auth` and `example.test/auth` are invalid because slash (`/`) is not allowed.
+A profile takes one value, not a comma-separated list.
+`doctor` and `email search` accept `--saas <name>` for a single-call override; `event list --saas <names>` accepts a comma-separated list.
+
+`scope` is a download scope value supplied by your tenant administrator or Check Point support for the intended download.
+Use printable ASCII with no spaces (characters `!` through `~`); comma-separated values are sent verbatim.
+For example, `synthetic:scope` has a valid form, while `synthetic scope` does not; the example is not a tenant-authorized value.
+There is no default: omitted means unset.
+Do not guess a tenant-authorized value.
+See [download requirements](downloads.md) for how email and attachment commands use scope, the remaining verification limits, and the separate download opt-in and output checks.
+
+## Write and download permissions
+
+File profiles are read-only by default.
+Set `writes.allowWrites` to true and list each exact operation in the `writes` object's `operations` array only when that permission is intended.
+Environment profiles cannot enable writes or downloads.
+`CHECKPOINT_AXI_READ_ONLY=1` overrides all configured write permission.
+Downloads require the separate `downloads.allow: true` file-profile opt-in.
+See [operation gates](writes.md) and [download requirements](downloads.md); profile permission alone does not execute an operation.
+