@knowttl/checkpoint-axi 0.1.0 → 0.1.2

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,32 @@
+# 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.
+Without it, email download fails before authentication.
+See [SaaS and scope](configuration.md#saas-and-scope) for the profile value's source and format.
+`--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,93 @@
+# 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.
+The [generated search reference](commands.md#email-search) lists documented field paths and operators, also available in `email search --help`.
+The guide uses field paths rather than a closed attribute enum and does not specify a per-field operator compatibility matrix.
+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.
+
+The vendor PDF describes `entitySecurityResults` as an array in its prose/table (pages 11 and 14), while its JSON examples use an object.
+Both documented forms are accepted; detail preserves them, and search reports `verdict: null` for an array because no combined verdict object is documented there.
+Other response constraints remain unchanged.
+`RESPONSE_INVALID` diagnostics for these reads name failing JSON paths and received types, including `missing`, without response values.
+Non-identifier path keys appear as `<key>`.
+These diagnostics support owner commissioning; the actual failing fields behind TD-049's live unfiltered-search and spam-detail failures remain unverified.
+
+## 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.
+

package/docs/writes.md

@@ -0,0 +1,200 @@
+# Write safety and operation reference
+
+[Email](#email-writes) | [Events](#event-actions) | [Phishing and Spam](#anti-phishing-and-spam-writes) | [Anomaly and click-time](#anomaly-and-click-time-writes) | [Malware, URL and DLP](#malware-url-and-dlp-writes)
+
+Read-only by default.
+[Profile permissions](configuration.md) grant exact operations; previews also require these permissions.
+See [downloads](downloads.md) for the separate local file opt-in and [the safety design](design.md#read-write-and-download-safety) for journal invariants.
+
+## Email writes
+
+`checkpoint-axi email quarantine --ids <id1>,<id2>` and `email restore --ids <id1>,<id2>` preview asynchronous email actions (guide pages 28-30).
+The selected file profile must opt in with `writes: { "allowWrites": true, "operations": ["email.quarantine", "email.restore"] }`, listing only the exact operations it needs.
+Wildcards never grant scope, environment-only profiles cannot write, and `CHECKPOINT_AXI_READ_ONLY` always wins.
+These gates apply to previews too.
+Supply 1-20 unique entity IDs, comma-separated without spaces.
+Previews read each entity, verify its identity and email type, check the available action and show current state.
+An explicit `--dry-run` also previews and cannot combine with `--execute`.
+
+Every action is disruptive.
+Sending an action requires `--execute` plus exact confirmation containing the operation, a space and the comma-separated supplied IDs in order:
+
+```sh
+checkpoint-axi email restore --ids synthetic-email-1 --execute --confirm 'email.restore synthetic-email-1'
+```
+
+Quarantine is a no-op when `isQuarantined` is true; restore is a no-op only when `isRestored` is true and `isQuarantined` is false.
+An entirely no-op batch returns without confirmation or a send; a mixed batch sends only targets still needing the action after re-read.
+The confirmation still names the full requested batch.
+Before sending, the coordinator records and syncs a redacted JSON-lines `kind: intent` record with `auditId`, operation, profile, region and targets.
+It re-reads every target, checks the profile has not changed, and sends at most one action request.
+Previews and initial no-ops create no journal.
+The [write safety design](design.md#read-write-and-download-safety) defines journal privacy, durability and file requirements.
+An intent-recording failure returns `INTENT_NOT_RECORDED` before sending.
+An outcome-recording failure returns `OUTCOME_NOT_RECORDED` and requires reconciliation.
+
+Successful submission returns `outcome: accepted`, `auditId` and per-entity `tasks` containing `entityId`, `taskId` and `outcome: accepted`.
+Use `checkpoint-axi task show <taskId>` to inspect execution; submission does not establish that an email was changed.
+Action requests never retry, including on 401 or 429, and never follow redirects.
+A disconnected, invalid, incomplete or otherwise unsuccessful acknowledgement returns `OUTCOME_UNKNOWN` with its audit ID.
+Read back every target and reconcile the journal before any further action; never replay automatically.
+Write preflights, authentication and the action share the [transport limits](reads.md#doctor-and-transport); read retries also consume that budget.
+Automated write verification is offline and synthetic; live action behavior, auth shape and token lifetime require manual verification.
+
+## Event actions
+
+`checkpoint-axi event action --ids <id>[,<id>] --name <action>` previews an action against 1-20 unique events (guide pages 35-37, 42-45).
+Enable `writes.allowWrites` and the exact `event.action.<name>` operation in the selected profile; forced read-only always wins.
+Execution requires `--execute --confirm 'event.action.<name> <ids>'`, with IDs in the supplied order.
+The write coordinator durably records intent, re-reads every event and sends one batch only if the action remains available on every target.
+Accepted responses identify a task for every event; use `checkpoint-axi task show <taskId>` to inspect execution.
+Ambiguous outcomes are never retried.
+
+`event show <id>` lists all available actions, including parameterized actions that require manual verification before support can be added.
+Nonempty `actionParameter` objects and repeated action names refuse `ENDPOINT_UNVERIFIED`, including during preview.
+The guide exposes parameter objects on pages 36-37 but requires `eventActionParam` strings on page 43; the CLI does not guess serialization or add a parameter selector.
+Name-only actions send `eventActionParam: [""]`; this and all live-only behavior remain uncommissioned.
+
+## Anti-Phishing and Spam writes
+
+`exception create <kind>`, `exception update <kind> <id>` and `exception remove <kind> <id>` support `phishing-allow`, `phishing-block` and `spam-allow` (guide pages 61-69, 75-83).
+Every command uses the write coordinator, including previews: the selected file profile needs `writes.allowWrites: true` and the exact operation `exception.<kind>.<create|update|remove>`.
+`CHECKPOINT_AXI_READ_ONLY` always wins.
+Each invocation targets one rule; update/remove require its exception ID.
+Create/update require `--input /absolute/rule.json`, a private regular JSON file (POSIX mode 0600; Windows protected DACL) containing the documented `requestData` fields directly, without an envelope:
+
+```json
+{
+  "senderEmail": "sender@example.com",
+  "senderEmailMatching": "contains",
+  "subject": "Synthetic exception",
+  "subjectMatching": "contains",
+  "comment": "Synthetic rule",
+  "ignoringSpfCheck": false
+}
+```
+
+Allowed string fields are `entityId`, `attachmentMd5`, `senderEmail`, `senderName`, `recipient`, `senderClientIp`, `senderDomain`, `senderIp`, `linkDomains`, `subject`, `comment`, `actionNeeded`, `subjectMatching`, `linkDomainMatching`, `senderNameMatching`, `senderDomainMatching`, `senderEmailMatching` and `recipientMatching`.
+`ignoringSpfCheck` is boolean, following the parameter tables rather than the guide's string-boolean examples.
+At least one nonempty matching criterion is required; metadata or matching operators alone cannot create a rule.
+Unknown fields and a supplied update `entityId` that differs from the positional ID are rejected before authentication.
+Update sends the supplied fields as a replacement PUT, so supply the complete intended rule rather than a partial patch.
+Remove sends a bodyless POST to the documented delete route.
+
+```sh
+checkpoint-axi exception create phishing-allow --input /absolute/rule.json
+checkpoint-axi exception update spam-allow synthetic-exception-1 --input /absolute/rule.json
+checkpoint-axi exception remove phishing-block synthetic-exception-1
+```
+
+Commands preview by default; `--dry-run` makes that explicit.
+Inspect the requested rule and current state, then repeat with `--execute` and the exact `--confirm` emitted by the preview.
+Create confirmation is `exception.<kind>.create sha256:<digest>`, binding the canonical payload; update/remove confirmation is `exception.<kind>.<action> <id>`.
+Create reads a complete bounded list to detect an identical rule; incomplete lists refuse execution because no continuation parameter is documented.
+Update/remove validate one matching detail response or an empty result; an absent update returns `NOT_FOUND`.
+Identical creates/replacements and absent removals detected on the initial read are no-ops without confirmation, a journal or a send.
+If the final read detects a no-op, the command returns `outcome: noop` with `auditId` and records `NOT_SENT` in the journal.
+After exact confirmation, durable redacted intent precedes a final state read, profile check and single send.
+The journal contains operation/target metadata, never the JSON payload.
+Preflight reads and the mutation share the exception rate spacer and the write transport budgets.
+
+Successful envelopes return `outcome: accepted` and `auditId`; these exception endpoints provide no task ID or created ID.
+Use `exception list <kind>` after create or `exception show <kind> <id>` after update/remove to reconcile.
+The remove acknowledgement also accepts the guide's envelope code 204.
+HTTP errors, redirects, disconnections and invalid acknowledgements become `OUTCOME_UNKNOWN`, without retries or token re-exchange.
+Reconcile before any further action and never replay automatically.
+Automated exception write verification uses offline synthetic fixtures; live exception behavior, auth shape and token lifetime require manual verification.
+
+## Anomaly and click-time writes
+
+`exception create anomaly`, `exception remove anomaly <rule-id>`, `exception create click-time`, `exception update click-time <item-id>`, `exception remove click-time <item-id>` and `exception remove-items click-time --ids <id1>,<id2>` implement the documented requests on guide pages 84-99.
+Every operation uses the write coordinator and requires configured writes.allowWrites, exact operation scope `exception.<kind>.<action>` and no forced read-only override, including for previews.
+Create and update read a private absolute `--input` JSON file containing the requestData fields directly, without an envelope.
+Anomaly create accepts `addedBy` and `requestJson` with `whitelist-option:new_country`, `apply-to-past` (`Yes` or `No`), `anomaly-comment` and `event_id`:
+
+```json
+{
+  "addedBy": "",
+  "requestJson": {
+    "whitelist-option:new_country": "synthetic-country-1",
+    "apply-to-past": "Yes",
+    "anomaly-comment": "Synthetic rule",
+    "event_id": "synthetic-event-1"
+  }
+}
+```
+
+Click-time create accepts `listItemName`, `listId` and `createdBy`; update additionally requires `listItemId` matching the positional item ID:
+
+```json
+{
+  "listItemName": "https://example.com/path",
+  "listId": "synthetic-list-1",
+  "createdBy": ""
+}
+```
+
+IDs contain 1-256 letters, digits, underscores or hyphens; remove-items requires 1-20 unique IDs.
+Unknown fields fail before authentication.
+Anomaly create/remove share a POST route, distinguished by their documented request bodies; remove sends `{ "requestData": { "ruleId": "<rule-id>" } }`.
+Click-time create and remove-items share POST items, distinguished by create fields or listItemIds; update sends PUT items/{item_id}, and remove sends a bodyless POST items/{item_id}.
+Collection PUT items (pages 93-94) is deferred until commissioning; update requires one positional item ID.
+
+The guide does not document response schemas for anomaly/click-time reads or acknowledgements.
+These previews explicitly show targetState: unverified and do not infer existence, identity or no-op state from arbitrary JSON.
+Execution requires `--execute` and the preview's exact `--confirm`, even if a target might already be absent or a rule already exists.
+Create confirms the complete private payload SHA-256; other commands confirm every caller-supplied ID in order.
+Durable redacted intent and final configuration/scope checks precede one send; requests never retry or reauthenticate after a mutation response.
+The journal holds metadata only, never input or response bodies.
+Successful HTTP status and any supplied successful response envelope return outcome: accepted, auditId, responseSchema: unverified and the bounded raw JSON response, redacted before the usual 500-character string previews.
+Never repeat a mutation to retrieve truncated strings; use read-only list or item commands to reconcile.
+An empty HTTP 204 is represented as response: null.
+No created ID, task ID or count is derived; reconcile using list or item reads, whose response identities also remain unverified.
+
+`exception clear click-time` refuses ENDPOINT_UNVERIFIED before authentication, including previews: the required freshly read count cannot be trusted from an undocumented list shape (pages 87-88, 96-97).
+Clear, collection PUT, response identities, existence/no-op detection and acknowledgement shapes require manual verification.
+All tests are offline and synthetic; no live behavior or token lifetime has been commissioned.
+
+## Malware, URL and DLP writes
+
+`exception create <malware|url|dlp> --input /absolute/rule.json` sends POST to the family route; add `--specific` to use its documented `/exceptions` create-specific route (guide pages 102-105, 113-116, 123-126).
+`exception update <malware|url|dlp> --input /absolute/rule.json` sends PUT to the family route (pages 105-107, 116-117, 126-127).
+Updates take no positional ID: `exception_type` and `exception_str` in the body identify the target.
+Families map to `checkpoint2`, `avanan_url` and `avanan_dlp` under `/sectool-exceptions/`.
+The private input file contains requestData fields directly, without an envelope.
+Create requires `exception_type`, `exception_str`, `comment`, `entity_type`, `entity_id`, `file_name`, `created_by_email` and boolean `is_exclusive`.
+Malware create additionally requires `exception_payload` with a nonempty string `condition`, for example `{ "condition": "with_link" }`.
+Update requires only `exception_type`, `exception_str`, `comment` and `exception_payload` with a nonempty string `condition`.
+Types are the same family-specific values listed in [exception reads](reads.md#exception-reads); type, value and entity selectors must be nonempty.
+Unknown fields are rejected, including nested payload fields.
+These provisional input contracts follow the guide's request bodies: it publishes no parameter tables defining optionality or additional payload fields.
+
+```json
+{
+  "exception_type": "allow-url",
+  "exception_str": "https://example.com/path",
+  "comment": "Synthetic rule",
+  "entity_type": "user",
+  "entity_id": "synthetic-user-1",
+  "file_name": "synthetic.json",
+  "created_by_email": "sender@example.com",
+  "is_exclusive": true
+}
+```
+
+Every command uses the write coordinator, with the exact operation `exception.<kind>.<create|update>`, configured write opt-in and forced read-only taking precedence.
+Commands preview by default; execution requires `--execute` and the exact preview confirmation.
+Both create and update confirmations bind the complete normalized payload and create-specific route choice by SHA-256, so changing either requires a new confirmation.
+The guide provides no response schemas for existence or no-op checks, so previews mark target state unverified, and initial/final state callbacks retain uncertainty without inferring identity or no-op state.
+Durable redacted intent and final scope/configuration checks precede one send; the journal contains metadata only.
+Requests never retry or reauthenticate after a mutation response.
+Successful HTTP status with valid JSON (or empty HTTP 204) and any supplied successful response envelope returns `accepted`, `auditId`, `responseSchema: unverified` and the bounded redacted response.
+No created ID or task ID is inferred; reconcile with `exception list <kind> --type <type>`.
+Ambiguous acknowledgements return `OUTCOME_UNKNOWN`; never replay automatically.
+
+All six `exception remove <malware|url|dlp> <value>` and `exception clear <malware|url|dlp>` commands refuse `ENDPOINT_UNVERIFIED` before configuration, credentials, authentication or journaling, including previews.
+The guide documents them as identical to create requests (pages 102 vs 107, 104 vs 108, 113 vs 117, 114 vs 119, 123 vs 128, 124 vs 129).
+No guessed delete request can be sent through the transport.
+Delete contracts, response identities, input optionality, existence/no-op detection, acknowledgement shapes, auth and token lifetime require manual verification.
+All automated verification is offline with synthetic requests and arbitrary provisional acknowledgements.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/checkpoint-axi",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Inspect Check Point Email Security through compact, guarded AXI commands",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
     "dist/src",
     "inventory",
     "axi-credential.schema.json",
-    "docs/commands.md",
+    "docs",
     "skills"
   ],
   "publishConfig": {

package/skills/checkpoint-axi/SKILL.md

@@ -8,8 +8,9 @@ description: "Inspect Check Point Email Security emails, events, tasks and excep
 # checkpoint-axi
 
 Inspect Check Point Email Security through compact, guarded AXI commands.
-See [README's introduction](../../README.md#checkpoint-axi) for shipped capabilities and [write guidance](../../README.md#email-writes-c6) before requesting mutations.
-Use `npx -y @knowttl/checkpoint-axi` after publication without a global install.
+Start investigations with the compact [agent guide](../../docs/agent-guide.md), which includes the read allowlist, bounded one-call forms and failure recovery.
+See [README's introduction](../../README.md#checkpoint-axi) for shipped capabilities and [write guidance](../../docs/writes.md#email-writes) before requesting mutations.
+Use `npx -y @knowttl/checkpoint-axi` without a global install.
 Bare `--version`, `-v` and `-V` print the package version.
 
 Run npx -y @knowttl/checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef.
@@ -33,7 +34,6 @@ Do not infer API access from a local pass.
 Doctor explicitly authenticates and checks one email search page over the past 24 hours.
 It reports region, SaaS and pass/fail per check without tenant data; a failed check exits 1.
 Use --saas to override the profile SaaS for doctor, email search or event list; the default is office365_emails.
-The owner commissions all slices together through Artium after the full build; only a pass/fail note enters the repository.
 AUTH_SHAPE_UNVERIFIED requires commissioning of the undocumented token response shape (guide page 8).
 Tokens stay in memory; verified TLS and the fixed region map are mandatory.
 Read sessions allow at most 10 HTTP requests; write sessions allow at most 44.
@@ -41,7 +41,13 @@ Both are bounded by 8 MiB of JSON and 60 seconds including auth and read retries
 Email search defaults to 50 compact rows and a 24-hour window; --start-date and --end-date require ISO timestamps with timezones and a positive window of at most 31 days (guide pages 18-27).
 Use --limit <1-1000> or --all, which caps output at 1000 rows within the shared transport budget.
 Use --saas-entity for an entity type or --filter for a JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters (guide pages 19-20).
-See [README's email-read guidance](../../README.md#email-reads-c3) for continuation, completion status, cursor safety and page replay limitations.
+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.
+See [email-read guidance](../../docs/reads.md#email-reads) for continuation, completion status, cursor safety and page replay limitations.
 Email show <id> includes payload, verdicts, actions taken and available actions (guide pages 10-18).
 Use --full for strings truncated at 500 characters and --fields for top-level output projection.
 Cursor strings are never truncated; secret-derived strings are redacted before previews.
@@ -51,9 +57,9 @@ Downloads buffer at most 50 MiB per response, require a valid matching x-av-sha2
 Only path, size and sha256 are printed; binary content never enters stdout and server filenames are ignored.
 Email requires profile scope as the scopes header; attachments take optional --scope query overriding profile scope.
 Scope authorization remains unverified, as does email/ZIP hash availability because the guide only documents x-av-sha256 for individual attachments (pages 131-137).
-The mandatory hash policy fails closed on missing headers; commission through Artium before assuming live download support.
+The mandatory hash policy fails closed on missing headers; verify manually before assuming live download support.
 ZIP HTTP 200 may contain only some attachments; archives are never automatically extracted.
-See [download guidance](../../README.md#downloads-c11) for retry limits, output safety and commissioning limitations.
+See [download guidance](../../docs/downloads.md) for retry limits, output safety and commissioning limitations.
 Event action --ids <ids> --name <action> previews by default and requires the exact profile operation event.action.<name>, --execute and the preview's exact --confirm to send once.
 Every target must offer the action on both reads; nonempty actionParameter objects or repeated action names refuse ENDPOINT_UNVERIFIED until live commissioning resolves the object/string contradiction (guide pages 36-37, 43).
 Use event show <id> to inspect all available actions, including deferred parameterized actions.
@@ -68,10 +74,10 @@ Exception lists default to 50 rows; --limit or --all bounds results at 1000 rows
 No exception continuation request parameter is documented; incomplete results report complete: false without inventing scroll requests.
 Anti-Phishing requests are spaced at 1 request/second; other exception requests at 10 requests/second, including read retries.
 Undocumented exception response shapes are preserved as JSON values and marked responseSchema: unverified; live behavior remains uncommissioned.
-For exception create/update/remove on phishing-allow, phishing-block and spam-allow, follow [README's Anti-Phishing and Spam write guidance](../../README.md#anti-phishing-and-spam-writes-c8) for private input, replacement semantics, scope, confirmation and preflight/no-op behavior.
-For anomaly create/remove and click-time create/update/remove/remove-items, follow [README's C9 write guidance](../../README.md#anomaly-and-click-time-writes-c9) for documented inputs, exact scope and confirmation, unverified target/response contracts and read-only reconciliation.
-That C9 guidance also owns the approved clear and collection-PUT commissioning deferrals; do not infer existence, identities or no-op state from undocumented JSON or replay a mutation to retrieve truncated output.
-For malware/URL/DLP create, create-specific and update, follow [C10 write guidance](../../README.md#malware-url-and-dlp-writes-c10) for private inputs, payload confirmation and unverified responses.
+For exception create/update/remove on phishing-allow, phishing-block and spam-allow, follow [Anti-Phishing and Spam write guidance](../../docs/writes.md#anti-phishing-and-spam-writes) for private input, replacement semantics, scope, confirmation and preflight/no-op behavior.
+For anomaly create/remove and click-time create/update/remove/remove-items, follow [anomaly and click-time write guidance](../../docs/writes.md#anomaly-and-click-time-writes) for documented inputs, exact scope and confirmation, unverified target/response contracts and read-only reconciliation.
+That guidance also owns the approved clear and collection-PUT commissioning deferrals; do not infer existence, identities or no-op state from undocumented JSON or replay a mutation to retrieve truncated output.
+For malware/URL/DLP create, create-specific and update, follow [malware, URL and DLP write guidance](../../docs/writes.md#malware-url-and-dlp-writes) for private inputs, payload confirmation and unverified responses.
 The six malware/URL/DLP remove/clear commands refuse ENDPOINT_UNVERIFIED before configuration or authentication; the guide duplicates create/delete requests, so live commissioning must establish their actual contracts.
 All live-only facts remain unverified, including token response shape and lifetime, delete requests and download scopes.