@knowttl/checkpoint-axi 0.0.0-stage → 0.1.0

package/inventory/specs.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "email-security-api",
+    "title": "Email Security API Reference Guide",
+    "revision": "2026-10-23",
+    "url": "https://sc1.checkpoint.com/documents/Harmony_Email_and_Collaboration_API_Reference/CP_Check_Point_Email_Security_API_Reference_Guide.pdf",
+    "sha256": "77d99a258462f13890743811aaaae797843a3d1890bf5726b0b008f0296f5825",
+    "bytes": 2596219,
+    "pages": 138,
+    "redistributed": false
+  }
+]

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@knowttl/checkpoint-axi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Inspect Check Point Email Security through compact, guarded AXI commands",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "checkpoint-axi": "bin/checkpoint-axi.js",
+    "checkpoint-axi-hook": "bin/checkpoint-axi-hook.js"
+  },
+  "exports": {
+    "./catalogue": "./dist/src/catalogue.js",
+    "./inventory": "./inventory/capabilities.json",
+    "./axi-credential.schema.json": "./axi-credential.schema.json"
+  },
+  "files": [
+    "bin",
+    "dist/src",
+    "inventory",
+    "axi-credential.schema.json",
+    "docs/commands.md",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knowttl/checkpoint-axi.git"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "packageManager": "pnpm@10.34.6",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "corepack pnpm run typecheck",
+    "test": "node scripts/isolated.mjs node scripts/test-changes.mjs",
+    "docs:generate": "node scripts/generate-docs.mjs",
+    "docs:check": "node scripts/generate-docs.mjs --check",
+    "spec:generate": "node scripts/specs.mjs --generate",
+    "spec:check": "node scripts/specs.mjs --check",
+    "identifiers:check": "node scripts/check-identifiers.mjs"
+  },
+  "dependencies": {
+    "@toon-format/toon": "2.3.1",
+    "axi-sdk-js": "0.1.13",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.5",
+    "typescript": "5.9.3",
+    "vitest": "5.0.2"
+  }
+}

package/skills/checkpoint-axi/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: checkpoint-axi
+description: "Inspect Check Point Email Security emails, events, tasks and exceptions, request guarded mutations and private downloads, validate profiles and diagnose API authentication with compact TOON output."
+---
+
+<!-- Generated by scripts/generate-docs.mjs from src/catalogue.ts. Do not hand-edit. -->
+
+# 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.
+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.
+Secrets use environment/file SecretRefs, never inline values, argv or chat.
+Regions are us, eu, ca, au, uk, uae and in; arbitrary origins are refused.
+
+```sh
+npx -y @knowttl/checkpoint-axi
+npx -y @knowttl/checkpoint-axi home --profile example
+npx -y @knowttl/checkpoint-axi auth status
+npx -y @knowttl/checkpoint-axi doctor
+npx -y @knowttl/checkpoint-axi email search
+npx -y @knowttl/checkpoint-axi email show <id>
+```
+
+Home and the optional checkpoint-axi-hook binary read local context only.
+Configure a session hook only on explicit request; it is never installed automatically.
+Use the hook for ambient discovery or this skill for on-demand discovery.
+Local auth status validates secret availability and file security without authenticating to the API.
+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.
+Both are bounded by 8 MiB of JSON and 60 seconds including auth and read retries; binary downloads have a separate 50 MiB cap per response.
+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.
+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.
+Downloads require file-profile downloads.allow and an absolute new --out file, created exclusively with mode 0600 or a protected Windows DACL.
+Use email download <entity-id> [--original], attachment download <entity-id> <attachment-id> or attachment download-all <entity-id>, always with --out /absolute/new-file.
+Downloads buffer at most 50 MiB per response, require a valid matching x-av-sha256 and sync verified bytes to disk; failures remove the new output.
+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.
+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.
+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.
+Accepted actions return task IDs; use task show <taskId> to inspect asynchronous execution without replaying ambiguous outcomes.
+Event list supports documented selectors and shares email search bounds and continuation; event show preserves actions and task show reads asynchronous status without polling (guide pages 30-42).
+Exception list/show accept phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url and dlp (guide pages 49-123).
+For malware, url and dlp, --type is required; run exception list --help for the documented values.
+Click-time --items selects item routes; by default list routes are used.
+Exception show takes an ID or value as a positional argument after the kind; values are encoded as one path segment.
+Anomaly show refuses with ENDPOINT_UNVERIFIED because no detail endpoint or response identity is documented (pages 83-84).
+Exception lists default to 50 rows; --limit or --all bounds results at 1000 rows within transport budgets.
+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.
+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.
+
+| Command | Purpose |
+|---|---|
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/checkpoint-axi auth status` | Validate the selected local profile and secret source without API calls |
+| `npx -y @knowttl/checkpoint-axi config path` | Show config and state paths without reading files; --profile does not affect paths |
+| `npx -y @knowttl/checkpoint-axi doctor` | Check regional API authentication and one bounded email search without printing tenant data |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/checkpoint-axi email quarantine` | Preview or request asynchronous email quarantine through the gated write coordinator (guide pages 28-30) |
+| `npx -y @knowttl/checkpoint-axi email restore` | Preview or request asynchronous email restore through the gated write coordinator (guide pages 28-30) |
+| `npx -y @knowttl/checkpoint-axi email search` | Search emails with a bounded date window and scroll continuation (API guide pages 18-27) |
+| `npx -y @knowttl/checkpoint-axi email show` | Show one email with verdicts, actions and available actions (API guide pages 10-18) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/checkpoint-axi event list` | List security events with bounded scroll continuation (API guide pages 37-42) |
+| `npx -y @knowttl/checkpoint-axi event show` | Show one event, actions taken and available actions (API guide pages 34-37) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/checkpoint-axi exception remove-items` | Preview or remove 1-20 click-time items by caller-supplied IDs; existence is unverified (guide pages 97-98) |
+| `npx -y @knowttl/checkpoint-axi exception show` | Show an exception by kind and ID/value; anomaly refuses ENDPOINT_UNVERIFIED pending commissioning (guide pages 52-123) |
+| `npx -y @knowttl/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) |
+| `npx -y @knowttl/checkpoint-axi home` | Show local profile context without resolving secrets or making API calls |
+| `npx -y @knowttl/checkpoint-axi profile list` | List file profiles without resolving secrets; --profile does not filter this list |
+| `npx -y @knowttl/checkpoint-axi task show` | Show asynchronous task status and per-action details (API guide pages 30-33) |