@knowttl/checkpoint-axi 0.1.0 → 0.1.1

package/docs/agent-guide.md

@@ -0,0 +1,108 @@
+<!-- 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}).
+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)

package/docs/configuration.md

@@ -0,0 +1,63 @@
+# 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.
+Optional `saas` defaults to `office365_emails`; `doctor`, `email search` and `event list` accept `--saas <name>` to override it for that call.
+Optional `scope` supplies the required email download `scopes` header and the default optional attachment `scope` query.
+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.
+
+## 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.
+

package/docs/design.md

@@ -0,0 +1,165 @@
+# Design and delivery boundaries
+
+[Credentials and transport](#credentials-and-transport) | [Safety](#read-write-and-download-safety) | [API coverage](#api-coverage-ledger) | [Slices](#slices-and-integration) | [Change recipe](#change-recipe-and-tests)
+
+The v1 design covers the full Harmony Email & Collaboration API in twelve slices.
+See the [API coverage ledger](#api-coverage-ledger) for shipped capabilities and commissioning deferrals by slice.
+The executable catalogue is separate from the planned inventory; inventory metadata never enables dispatch.
+The source is the [Email Security API Reference Guide, 23 October 2026](https://sc1.checkpoint.com/documents/Harmony_Email_and_Collaboration_API_Reference/CP_Check_Point_Email_Security_API_Reference_Guide.pdf).
+`inventory/specs.json` pins its URL, SHA-256, byte length and page count.
+Unlike Tenable's committed JSON specs, the vendor PDF stays outside git because redistribution permission is unconfirmed.
+This inventory is a page-cited coverage ledger, not a generated OpenAPI schema or a claim of endpoint completeness inferred from PDF samples.
+Default spec checks are offline; explicit `--pdf` verification checks supplied bytes.
+
+## Credentials and transport
+
+One strict profile contains `region`, `clientId`, a `clientSecret` SecretRef, optional `saas`, optional `scope`, `downloads` and `writes`.
+`saas` defaults to `office365_emails`; `doctor`, `email search` and `event list` expose `--saas` as a per-call override.
+Only the fixed seven-gateway region map is supported; profiles cannot supply an origin.
+`src/private-file.ts` owns platform read security; configuration and secret source rules follow the AXI credential standard.
+Config/profile precedence, strict env-profile completeness and private-file rules are documented in [configuration](configuration.md).
+C1-C2 have no private writes or token persistence.
+All resolved secret forms are registered for raw, JSON-escaped and URL-encoded output redaction before use.
+
+C2 provides one closed HTTPS transport boundary with TLS verification, redirect refusal and a fresh `x-av-req-id` UUID per request.
+The guide uses `POST /auth/external` with `clientId` and `accessKey` (the client secret), then Bearer authorization under `/app/hec-api/v1.0` (pages 8-10).
+Tokens stay in memory and are never cached to disk; reads permit at most one token re-exchange per invocation after a 401.
+Action requests never reauthenticate or retry, including on 401 or 429.
+Token response shape and lifetime are undocumented; the owner will commission all slices together through Artium after the full build.
+Only a pass/fail commissioning note may enter this public repository.
+Automated tests never contact that tenant.
+The provisional token field candidates and commissioning failure code are documented in [read transport](reads.md#doctor-and-transport).
+Doctor performs one page of the default 24-hour entity search for the selected SaaS and discards the data.
+The transport normalizes object/array response data and preserves scroll metadata for the read slices.
+Auth, re-exchange, retries and delays share the [invocation budgets](reads.md#doctor-and-transport).
+C3-C4 share bound continuation cursors and collection row limits for email search and event list in `src/reads.ts`.
+
+## Read, write and download safety
+
+Email reads decode schema-derived synthetic responses rather than copy inconsistent JSON samples.
+Scroll cursors bind profile, client identity, origin, operation and selectors, including the original date window.
+Search limits, page replay limitations, completion status and output previews are documented in [read guidance](reads.md#email-reads).
+Exception requests are spaced at 1 request/second for Anti-Phishing and 10 requests/second otherwise.
+Reads retry 429 at most twice, respecting `Retry-After`; writes never retry.
+
+The C6 write coordinator requires configured `allowWrites` and exact operation scope, preview, `--execute`, exact confirmation naming every target, and durable redacted intent before a single send.
+`CHECKPOINT_AXI_READ_ONLY` overrides configured write permission.
+Target batches stop at 20; ambiguous outcomes report `OUTCOME_UNKNOWN` and are never replayed.
+Entity/event actions return `accepted` and `taskId`, since execution is asynchronous.
+Each write transport consumes a one-use coordinator authorization bound to the operation, targets, profile and region.
+Before a send, the coordinator repeats the slice-specific state check described below and checks that the selected profile has not changed.
+The API offers no conditional entity-action request, so this cannot prevent a concurrent server-side change after preflight.
+The journal and its lock must be private regular files in a private directory; symlinks, hard-linked journals, insecure modes, an incomplete journal or an existing lock block execution.
+POSIX files are created with mode 0600 and the directory with 0700.
+On Windows, newly created files and the journal directory receive protected DACLs granting FullControl only to the current user, SYSTEM and Administrators; existing paths must already satisfy this policy.
+Journal records contain only redacted metadata, never headers, message bodies, credentials or tokens.
+The intent is synced before the final state check and send; POSIX directory entries are also synced for crash durability.
+`src/writes.ts` owns these checks; `test/writes.test.ts` exercises ordering, unsafe journals, scope changes and ambiguous acknowledgements with synthetic data.
+Operation names are `email.quarantine`, `email.restore`, `event.action.<name>` and `exception.<kind>.<create|update|remove|remove-items|clear>`.
+Event action names must be validated against `availableEventActions`.
+C7 validates each event's identity and available action on initial and final reads through the C6 coordinator, with exact operation `event.action.<name>` and at most 20 targets.
+The event transport consumes a one-use authorization and sends `eventIds`, `eventActionName: [name]` and `eventActionParam: [""]` to the closed `/action/event` route (pages 42-45).
+Acknowledgements must identify every requested event, its freshly read entity and a task ID; any ambiguous response becomes `OUTCOME_UNKNOWN` without replay.
+No generic event no-op is inferred from action history or event state.
+The guide contradicts itself on parameters: `availableEventActions` contains parameter objects and repeated `severityChange` names (pages 36-37), while `eventActionParam` is an array of strings (page 43).
+Per the C7 decision, no parameter selector is added: nonempty parameter objects or repeated action names refuse `ENDPOINT_UNVERIFIED`, while event show preserves them for inspection.
+Serialization and parameterized execution are deferred to live commissioning through Artium; name-only request behavior is also uncommissioned.
+C8 creates, replaces and removes one Anti-Phishing allow/block or Spam allow exception through the same coordinator (pages 61-69, 75-82).
+Private JSON input contains documented requestData fields directly, with a nonempty matching criterion and a boolean ignoringSpfCheck when supplied.
+Create confirmation identifies the canonical payload SHA-256; update/remove confirmation identifies the exception ID.
+Create preflight requires a complete bounded list to detect an identical rule; update/remove preflight validates one matching detail or an empty result.
+An identical create/replacement or absent remove is a no-op; incomplete or malformed preflight fails closed.
+The closed transport consumes one authorization and sends POST create, PUT replacement or bodyless POST remove, without retry or reauthentication.
+Exception reads and sends share their family rate spacer.
+C8 rechecks forced read-only, exact operation scope and profile identity after send pacing, immediately before the mutation request.
+Revocation at that check aborts with the original scope/configuration error and records `NOT_SENT`; `test/exception-writes.test.ts` covers revocation during pacing for every C8 operation.
+Only a successful response envelope is acknowledged as accepted; remove also accepts the documented envelope code 204.
+No task ID or created exception ID is invented; reconcile with list/show after submission.
+Live exception behavior remains uncommissioned until the owner tests all slices through Artium.
+C9 sends documented anomaly create/remove and click-time create/single-item update/remove/remove-items requests through the C6 coordinator (pages 84-99).
+The guide supplies no response schemas for these reads or acknowledgements, so C9 does not invent identities, existence checks or no-op detection.
+Previews explicitly mark target state unverified; the coordinator's initial and final state callbacks retain that uncertainty without making an undocumented existence preflight.
+All writes still require exact operation scope, explicit execution, confirmation of every caller-supplied target, durable redacted intent and a scope/configuration check immediately before the single send.
+Create confirmations bind the complete private input by payload SHA-256; anomaly remove confirms the caller's ruleId; click-time update/remove confirms the item ID and remove-items confirms 1-20 unique IDs in order.
+Successful HTTP status with valid JSON (or an empty HTTP 204) is accepted, provided any supplied responseEnvelope also reports success; raw bounded JSON is preserved as response with responseSchema: unverified.
+No created ID, task ID or count is inferred from the acknowledgement; ambiguous responses are never retried.
+Fixtures for these undocumented responses are arbitrary provisional JSON, not claimed schema-derived vendor responses.
+Clearing a list requires confirmation including the freshly read count, which C9 cannot establish from an undocumented list shape.
+Therefore exception clear click-time refuses ENDPOINT_UNVERIFIED before authentication, including previews, until commissioning supplies a trustworthy count contract (pages 87-88, 96-97).
+Click-time update exposes only PUT items/{item_id}; collection PUT items (pages 93-94) is deferred to commissioning.
+Clear, collection PUT, response identities, existence/no-op detection and acknowledgement shapes are explicit live-commissioning follow-ups through Artium.
+C10 sends malware/URL/DLP POST create, POST create-specific at /exceptions and PUT update at the family root through the C6 coordinator (pages 102-107, 113-117, 123-127).
+Create-specific is selected with --specific; updates identify the target in the private input body and take no positional ID.
+Both operations confirm a SHA-256 binding the complete normalized payload and route choice.
+Input contracts follow documented request bodies, not unpublished parameter tables; optionality and additional payload fields remain unverified.
+Like C9, response identities and no-op state remain explicitly unverified, without invented existence reads.
+Durable intent, final scope checks, rate spacing, single-send behavior and unverified JSON acknowledgements follow the C9 contract.
+All six malware/URL/DLP remove/clear commands refuse `ENDPOINT_UNVERIFIED` before configuration or authentication until manual commissioning resolves the guide's identical create/delete descriptions.
+The closed transport also refuses sectool deletes; no guessed request is executable.
+Downloads require `downloads.allow`, a new exclusive 0600 `--out` file, a 50 MiB cap and verified `x-av-sha256`.
+They never stream to stdout and report only path, size and SHA-256.
+The C11 download module buffers at most 50 MiB per response, validates the mandatory hash and writes only verified bytes to the exclusively created private file; failures remove that file.
+Windows output receives the same protected DACL used for other private writes.
+The closed transport exposes only the three documented download routes, with read retry and token re-exchange bounds.
+Email requires profile scope as the scopes header; attachment downloads use the optional scope query, with --scope overriding profile scope.
+Email/ZIP hash headers are absent from the guide, so their availability and all download scope behavior remain explicitly unverified until commissioning.
+The approved mandatory hash check applies to all three commands even when an uncommissioned server omits the header.
+An HTTP 200 attachment ZIP may be partial (page 136); no completeness or automatic extraction is implied.
+Hosted downloads will reuse Artium's artifact mechanism in C12.
+
+## API coverage ledger
+
+Page numbers are printed guide pages.
+Rows remain planned or excluded except the shipped C2-C11 capabilities (with explicit commissioning deferrals).
+Inventory metadata never enables command dispatch.
+Legacy whitelist/blacklist reads remain recorded separately from the eight exception kinds: phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url and dlp.
+
+| Capability | Pages | Slice | Disposition | Reason |
+|---|---|---|---|---|
+| `auth exchange and doctor` | 8-9 | C2 | auth | Shipped in C2; commission the undocumented token contract manually. |
+| `email search and show` | 10-27 | C3 | read | Shipped in C3; GET entity detail and POST search/query with bounded scroll. |
+| `event list and show` | 34-42 | C4 | read | Shipped in C4; GET event detail and POST event/query with bounded scroll. |
+| `task show` | 30-33 | C4 | read | Shipped in C4; GET task status and per-action details for asynchronous actions. |
+| `legacy exception reads` | 49-55 | C5 | read | Shipped in C5 through phishing-allow and phishing-block list/show; same whitelist/blacklist routes. |
+| `exception list and show for eight kinds` | 55-131 | C5 | read | Shipped in C5; documented family/item reads; anomaly show refuses ENDPOINT_UNVERIFIED pending response identity commissioning. |
+| `email quarantine and restore` | 28-30 | C6 | write | Shipped in C6; POST action/entity through the gated coordinator with durable intent, exact confirmation, re-read and no retry. |
+| `event action` | 42-45 | C7 | write | Shipped in C7; gated POST action/event validates availableEventActions; parameterized actions refuse ENDPOINT_UNVERIFIED pending commissioning. |
+| `phishing create update remove` | 61-69 | C8 | write | Shipped in C8; gated allow/block create, PUT replacement and bodyless POST remove with exact scope and confirmation. |
+| `spam create update remove` | 75-83 | C8 | write | Shipped in C8; gated allow-list create, PUT replacement and bodyless POST remove with exact scope and confirmation. |
+| `anomaly create remove` | 84-87 | C9 | write | Shipped in C9; gated shared POST distinguished by documented request bodies; response identities remain unverified. |
+| `click-time create update remove remove-items clear` | 91-100 | C9 | write | Shipped in C9; gated item writes; clear refuses ENDPOINT_UNVERIFIED and collection PUT is deferred until commissioning. |
+| `malware create update` | 102-106 | C10 | write | Shipped in C10; gated create, create-specific and PUT modify checkpoint2; response identities remain unverified. |
+| `url create update` | 113-117 | C10 | write | Shipped in C10; gated create, create-specific and PUT modify avanan_url; response identities remain unverified. |
+| `dlp create update` | 123-127 | C10 | write | Shipped in C10; gated create, create-specific and PUT modify avanan_dlp; response identities remain unverified. |
+| `malware remove clear` | 107-110 | C10 | unverified | Refuse two ambiguous deletes with ENDPOINT_UNVERIFIED pending commissioning. |
+| `url remove clear` | 117-120 | C10 | unverified | Refuse two ambiguous deletes with ENDPOINT_UNVERIFIED pending commissioning. |
+| `dlp remove clear` | 128-131 | C10 | unverified | Refuse two ambiguous deletes with ENDPOINT_UNVERIFIED pending commissioning. |
+| `email and attachment downloads` | 131-137 | C11 | download | Shipped in C11; opt-in private files, 50 MiB cap and mandatory SHA-256; scopes and email/ZIP hash availability remain unverified. |
+| `audit logs` | 138 | C12 | excluded | Outside this API; use Check Point Portal APIs separately. |
+
+## Slices and integration
+
+1. C1: package, strict ESM, local commands, credentials schema, generated docs, PDF provenance and offline checks.
+2. C2: regional authentication, transport and bounded `doctor`; owner commissioning follows the full build through Artium.
+3. C3: email reads.
+4. C4: event and task reads.
+5. C5: every exception family's reads.
+6. C6: write coordinator and email quarantine/restore.
+7. C7: event actions.
+8. C8: Anti-Phishing and Spam writes.
+9. C9: anomaly and click-time writes.
+10. C10: malware, URL and DLP create/update; six deletes implemented but refused.
+11. C11: downloads, final skills/docs and release preparation; see [release guidance](../CONTRIBUTING.md#releases) for publication mechanics.
+12. C12: separate Artium PR with credential schema, adapter, write policy, hosted artifacts, tool schema/maps, inventory, exact package/integrity pins and full-content skill overlay.
+
+## Change recipe and tests
+
+`scripts/generate-docs.mjs` generates the README group overview, full command reference and skill from the command catalogue, and owns the compact [investigation guide](agent-guide.md) prose.
+`docs:check` detects drift after build, and `spec:check` detects coverage/provenance drift without networking.
+The identifier guard permits public vendor gateways, documentation hosts, reserved example domains, documentation IP ranges and explicitly synthetic UUIDs only.
+It is a guardrail alongside staged review, not a substitute for checking public-repository hygiene.
+Tests use real local commands, isolated HOME/XDG directories, synthetic fixtures and a deny-network preload inherited by subprocesses.
+The packaged baseline packs and installs real local dependency tarballs offline before running both bins.
+Affected-test selection always includes packaged CLI, profiles, identifier and network safety; shared infrastructure runs all tests.
+C2 transport tests use a registered loopback TLS fake gateway without enabling external networking.
+There is no hosted test workflow; release publication alone runs hosted verification.

package/docs/downloads.md

@@ -0,0 +1,30 @@
+# Private downloads
+
+Enable `downloads.allow: true` in a file profile before using `email download <entity-id>`, `attachment download <entity-id> <attachment-id>` or `attachment download-all <entity-id>` (guide pages 131-137).
+Every command requires an absolute `--out` path to a new file in an existing directory.
+Existing files and symlinks are refused before authentication; filenames from response headers are ignored.
+The file is created exclusively with mode 0600 on POSIX or a protected DACL on Windows before any content is written.
+Binary content is buffered up to 50 MiB per response, verified against the required `x-av-sha256` header, then written and synced; failed downloads remove their new output file.
+No binary content, server filename, headers or response body enters stdout; success prints only `path`, `size` and `sha256`.
+Downloads permit one token re-exchange after 401 and two 429 retries respecting Retry-After, within 10 total requests and 60 seconds including authentication.
+TLS verification and the fixed regional gateway restriction apply throughout; redirects are refused.
+
+```sh
+checkpoint-axi email download <entity-id> --out /absolute/message
+checkpoint-axi email download <entity-id> --original --out /absolute/original
+checkpoint-axi attachment download <entity-id> <attachment-id> --out /absolute/attachment
+checkpoint-axi attachment download-all <entity-id> --out /absolute/attachments
+```
+
+Email downloads require profile `scope`, sent verbatim as the comma-separated `scopes` header required on page 131.
+`--original` selects the unmodified email; default false includes the service's processing headers.
+Attachment commands use optional `--scope` as a query selector, defaulting to profile `scope` when configured; no scope query is sent when both are absent.
+Scope authorization and the relationship between the email `scopes` header and attachment `scope` query require manual verification.
+The guide specifies `x-av-sha256` for individual attachments (page 134) but omits it for email and ZIP responses (pages 132, 136).
+All three commands enforce the approved hash requirement: a missing or malformed header returns `DOWNLOAD_HASH_INVALID`, and a mismatch returns `DOWNLOAD_HASH_MISMATCH`, with output removed.
+Email/ZIP hash availability therefore remains unverified and may require a commissioning follow-up before those downloads can succeed live.
+An attachment ZIP may contain only the attachments the service could retrieve even on HTTP 200 (page 136); a successful download does not prove attachment completeness.
+Archives are saved as received, never extracted automatically.
+Environment profiles cannot enable downloads; remote mutation scope and write confirmation remain separate from this download opt-in.
+All live-only facts, including token shape/lifetime, delete requests and download scopes, remain unverified; automated tests use only synthetic offline data.
+

package/docs/reads.md

@@ -0,0 +1,84 @@
+# Reads and transport
+
+[Doctor and transport](#doctor-and-transport) | [Email reads](#email-reads) | [Events and tasks](#event-and-task-reads) | [Exceptions](#exception-reads)
+
+## Doctor and transport
+
+`checkpoint-axi doctor --profile <name>` explicitly contacts the selected public regional gateway.
+It authenticates and runs one page of email search over the past 24 hours for the selected SaaS.
+It reports region, SaaS and pass/fail for auth and read, without email data or credentials; a failed check exits 1.
+Home, the hook, command help and `auth status` remain offline.
+No commissioning run has been performed by the automated tests.
+
+The vendor guide does not document the token response shape or lifetime (page 8).
+The provisional parser accepts one distinct nonempty printable ASCII token without whitespace from `token`, `access_token` or `accessToken` at the root or within `data` or `responseData`.
+Unsupported, conflicting or invalid values fail with `AUTH_SHAPE_UNVERIFIED`, requiring owner commissioning rather than printing the response.
+Token persistence and reauthentication rules are defined in [the transport design](design.md#credentials-and-transport).
+All requests carry a new request UUID; authenticated API calls carry Bearer authorization.
+TLS certificate verification stays enabled and redirects are refused.
+Read sessions allow at most 10 HTTP requests; write sessions allow at most 44.
+Both are bounded by 8 MiB of JSON response bytes and 60 seconds, including auth, re-exchange, read retries and delays.
+Download bodies have a separate 50 MiB cap per response within the same request/time budgets.
+Reads retry HTTP 429 at most twice, honoring numeric or HTTP-date `Retry-After` within that budget.
+Exception reads and writes share separate 1 request/second Anti-Phishing and 10 requests/second other-exception spacers.
+
+## Email reads
+
+`checkpoint-axi email search` reads compact ID, subject, action state and combined verdict rows (guide pages 18-27).
+`checkpoint-axi email show <id>` returns the entity payload, security results, actions taken and available actions (guide pages 10-18).
+Search defaults to the past 24 hours and 50 rows; `--start-date` and `--end-date` accept ISO timestamps with timezones, with a positive window of at most 31 days.
+`--saas` overrides the selected profile and `--saas-entity` optionally selects the entity type.
+`--filter` accepts a JSON array of the documented `saasAttrName`, `saasAttrOp` and `saasAttrValue` filters (guide pages 19-20).
+For example, `--filter '[{"saasAttrName":"entityPayload.subject","saasAttrOp":"contains","saasAttrValue":"Synthetic"}]'` selects a subject substring.
+Use `--limit <1-1000>` or `--all`, which stops at 1,000 rows, 10 HTTP requests, 60 seconds or 8 MiB, including authentication and retries.
+Incomplete searches return `complete: false`; when an opaque `cursor` is present, repeat with `--cursor <cursor>` and the same original selectors to continue.
+Cursors preserve the original window, bind profile/client identity, regional origin, operation and selectors, and retain an offset when a row limit splits a server page.
+The API has no page-size parameter, so continuation within a page replays that page; results changed between calls may be skipped or repeated.
+Searches that split a page and all their continuations report `complete: false` with `reason: replay-may-skip-or-repeat`, even after reaching the final page, when no cursor is returned.
+Continuation at a whole-page boundary can report `complete: true` on reaching the final page if no earlier page was split.
+Treat cursors as sensitive search state and do not edit them.
+Cursor strings are never truncated; email text is redacted before 500-character previews, with `--full` for complete text.
+See [downloads](downloads.md) for private file output.
+
+## Event and task reads
+
+`checkpoint-axi event list` returns compact ID, type, state and severity rows (guide pages 37-42).
+`checkpoint-axi event show <id>` preserves event details, action history and available actions (guide pages 34-37).
+`checkpoint-axi task show <id>` returns task status, progress and per-action details for asynchronous actions (guide pages 30-33).
+Task states are `init`, `inprogress`, `completed`, `failed`, `stopped` and `paused`; task show performs one read without polling.
+Event list accepts comma-separated `--event-types`, `--event-states`, `--severities`, `--event-ids` and `--saas`, plus `--confidence-indicator` and `--description` text selectors.
+SaaS defaults to the selected profile's value or `office365_emails`; other event selectors default to unfiltered.
+Event list uses the same date windows, row and transport budgets, bound continuation and honest page replay flags as [email search](reads.md#email-reads).
+Repeat all original event selectors with `--cursor`; the cursor preserves the original date window.
+Event and task text is redacted before 500-character previews; use `--full` for full strings and `--fields` to select top-level fields.
+For writes, see [event actions](writes.md#event-actions).
+These reads are verified offline with synthetic fixtures; authentication, token lifetime and live API behavior require manual verification.
+
+## Exception reads
+
+`checkpoint-axi exception list <kind>` and `exception show <kind> <id-or-value>` cover `phishing-allow`, `phishing-block`, `spam-allow`, `anomaly`, `click-time`, `malware`, `url` and `dlp` (guide pages 49-123).
+Legacy whitelist/blacklist reads use the same routes as phishing-allow/phishing-block, without duplicate commands (pages 49-60).
+Phishing and Spam lists return compact ID, sender, subject and comment fields; show preserves the full record and verifies the returned entity ID (pages 56-60, 70-74).
+Click-time defaults to list routes; add `--items` to list or show for item routes (pages 87-91).
+Malware, URL and DLP require `--type` on both commands:
+
+| Kind | Types | Guide pages |
+|---|---|---|
+| malware | `hash`, `micro_hash`, `file_type`, `ppat_sender_name`, `allow_file_type`, `sender_email` | 100-102 |
+| url | `allow-url`, `allow-domain`, `block-url`, `block-domain` | 110-112 |
+| dlp | `hash`, `text_content`, `sender_email`, `recipient_email` | 120-123 |
+
+For example, `checkpoint-axi exception show url 'https://example.com/path' --type allow-url` encodes the supplied value as one path segment.
+Anomaly has only a documented list GET, with no detail endpoint or response identity schema (pages 83-84).
+`exception show anomaly <id>` therefore refuses with `ENDPOINT_UNVERIFIED` before authentication until owner commissioning settles the contract.
+The guide also publishes no response schemas for click-time, malware, URL or DLP reads.
+These families and anomaly list preserve JSON values, marked `responseSchema: unverified`, without inventing identity fields or claiming live compatibility.
+Unknown-shape detail results are arrays of returned JSON values; documented Phishing/Spam details return one validated object.
+These contracts require manual verification against the live API.
+
+Lists default to 50 rows, accept `--limit <1-1000>` or `--all` capped at 1000 rows, and share the 10-request, 8 MiB and 60-second transport budgets.
+No paging request parameter is documented for these GET routes, so each command reads one response without guessing a scroll query.
+Truncation, nonempty scroll metadata or a larger advertised total returns `complete: false` and an explanation; there is no exception continuation cursor.
+Anti-Phishing list/detail requests share a 1 request/second spacer; all other exception routes share a 10 requests/second spacer within each invocation, including retries and reauthentication replays.
+Text is redacted before 500-character previews; `--full` restores complete strings, and `--fields` selects top-level output fields.
+