@knowttl/checkpoint-axi 0.0.0-stage → 0.1.0

package/dist/src/reads.js

@@ -0,0 +1,169 @@
+import { AxiError } from "axi-sdk-js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { REGIONS } from "./regions.js";
+import { gateway, READ_LIMITS } from "./transport.js";
+const day = 86_400_000;
+const timestamp = z.iso.datetime({ offset: true });
+const filters = z.array(z.strictObject({ saasAttrName: z.string().min(1),
+    saasAttrOp: z.enum(["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"]),
+    saasAttrValue: z.string() }));
+const continuation = z.strictObject({ version: z.literal(1), binding: z.string(), start: timestamp, end: timestamp,
+    scroll: z.string().optional(), offset: z.number().int().nonnegative(), replayRisk: z.literal(true).optional() });
+// Entity schemas and SaaS-specific payloads: guide pages 11-15 and 21-24.
+const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().optional() }).passthrough(),
+    entityPayload: z.object({ subject: z.string().optional() }).passthrough(),
+    entitySecurityResults: z.object({ combinedVerdict: z.unknown().optional() }).passthrough().optional(),
+}).passthrough();
+// Event and task fields: guide pages 31-32, 35-36 and 40-41.
+const event = z.object({ eventId: z.string().min(1), type: z.string(), state: z.string(), severity: z.string() }).passthrough();
+const task = z.object({ id: z.union([z.string().min(1), z.number().int().nonnegative()]),
+    status: z.enum(["init", "inprogress", "completed", "failed", "stopped", "paused"]),
+    actions: z.array(z.object({ action_status: z.string() }).passthrough()),
+    progress: z.number().nonnegative(), total: z.number().nonnegative(),
+}).passthrough();
+const invalid = (message) => { throw new AxiError(message, "VALIDATION_ERROR", ["Run checkpoint-axi <email search|email show|event list|event show|task show> --help"]); };
+export async function readCommand(name, id, flags, store, transport) {
+    const isEvent = name.startsWith("event ");
+    if (name.endsWith(" show") && (!id || !/^[A-Za-z0-9_-]+$/.test(id)))
+        invalid(`${name} requires one ID containing letters, digits, underscores or hyphens`);
+    const limitText = flags.get("--limit") ?? "50";
+    if (!/^[1-9][0-9]*$/.test(limitText) || Number(limitText) > READ_LIMITS.rows)
+        invalid("--limit must be an integer from 1 to 1000");
+    if (flags.has("--all") && flags.has("--limit"))
+        invalid("Use either --all or --limit");
+    const limit = flags.has("--all") ? READ_LIMITS.rows : Number(limitText);
+    let extended;
+    if (flags.has("--filter")) {
+        let raw;
+        try {
+            raw = JSON.parse(flags.get("--filter"));
+        }
+        catch {
+            invalid("--filter must be a JSON array of attribute filters");
+        }
+        const parsed = filters.safeParse(raw);
+        if (!parsed.success)
+            invalid("--filter must contain saasAttrName, a documented saasAttrOp and saasAttrValue");
+        extended = parsed.data;
+    }
+    let cursor;
+    if (flags.has("--cursor")) {
+        try {
+            const encoded = flags.get("--cursor");
+            if (!/^[A-Za-z0-9_-]+$/.test(encoded))
+                invalid("Invalid continuation cursor");
+            cursor = continuation.parse(JSON.parse(Buffer.from(encoded, "base64url").toString("utf8")));
+        }
+        catch {
+            invalid("Invalid continuation cursor");
+        }
+    }
+    const end = flags.get("--end-date") ?? cursor?.end ?? new Date().toISOString();
+    if (!timestamp.safeParse(end).success)
+        invalid("--end-date must be an ISO timestamp with timezone");
+    const start = flags.get("--start-date") ?? cursor?.start ?? new Date(Date.parse(end) - day).toISOString();
+    if (!timestamp.safeParse(start).success)
+        invalid("--start-date must be an ISO timestamp with timezone");
+    const window = Date.parse(end) - Date.parse(start);
+    if (window <= 0 || window > 31 * day)
+        invalid("Search window must be positive and at most 31 days");
+    for (const flag of ["--saas", "--saas-entity"])
+        if (flags.has(flag) && !flags.get(flag).trim())
+            invalid(`${flag} must not be blank`);
+    const eventSelectors = {};
+    for (const [flag, key] of [["event-types", "eventTypes"], ["event-states", "eventStates"], ["severities", "severities"], ["event-ids", "eventIds"], ["saas", "saas"]]) {
+        if (!isEvent || !flags.has(`--${flag}`))
+            continue;
+        const values = flags.get(`--${flag}`).split(",").map((value) => value.trim());
+        if (values.some((value) => !value))
+            invalid(`--${flag} must contain nonempty comma-separated values`);
+        eventSelectors[key] = values;
+    }
+    for (const [flag, key] of [["confidence-indicator", "confidenceIndicator"], ["description", "description"]]) {
+        if (!flags.has(`--${flag}`))
+            continue;
+        const value = flags.get(`--${flag}`).trim();
+        if (!value)
+            invalid(`--${flag} must not be blank`);
+        eventSelectors[key] = value;
+    }
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const saas = flags.get("--saas")?.trim() ?? profile.saas;
+    const entityFilter = { saas, ...(flags.has("--saas-entity") ? { saasEntity: flags.get("--saas-entity").trim() } : {}), startDate: start, endDate: end };
+    const selectors = { ...eventSelectors, saas: eventSelectors.saas ?? [saas], startDate: start, endDate: end };
+    const binding = createHash("sha256").update(JSON.stringify({ profile: profile.name, client: profile.clientId,
+        origin: REGIONS[profile.region], operation: name, ...(isEvent ? { selectors } : { entityFilter, extended }) })).digest("hex");
+    if (cursor && cursor.binding !== binding)
+        invalid("Cursor does not match this profile, region or search selectors; repeat the original selectors");
+    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
+    if (name.endsWith(" show")) {
+        const kind = name.split(" ")[0];
+        const page = await api.read({ path: name === "task show" ? `/task/${id}` : isEvent ? `/event/${id}` : `/search/entity/${id}` });
+        if (page.records.length === 0)
+            throw new AxiError(`${kind} was not found`, "NOT_FOUND", []);
+        const parsed = (name === "task show" ? task : isEvent ? event : entity).safeParse(page.records[0]);
+        if (page.records.length !== 1 || !parsed.success)
+            throw new AxiError(`Invalid ${kind} detail response`, "RESPONSE_INVALID", []);
+        const record = page.records[0];
+        const returnedId = name === "task show" ? String(record.id) : isEvent ? record.eventId : record.entityInfo?.entityId;
+        if (returnedId !== id)
+            throw new AxiError(`Invalid ${kind} detail response`, "RESPONSE_INVALID", []);
+        return { [kind]: parsed.data };
+    }
+    const results = [];
+    let scroll = cursor?.scroll;
+    let offset = cursor?.offset ?? 0;
+    let replayRisk = cursor?.replayRisk ?? offset > 0;
+    let total;
+    let exhausted = false;
+    while (results.length < limit) {
+        let page;
+        try {
+            page = await api.read(isEvent ? { path: "/event/query", body: { ...selectors, ...(scroll === undefined ? {} : { scrollId: scroll }) } }
+                : { path: "/search/query", body: { entityFilter,
+                        ...(extended === undefined ? {} : { entityExtendedFilter: extended }), ...(scroll === undefined ? {} : { scrollId: scroll }) } });
+        }
+        catch (error) {
+            if (results.length && error instanceof AxiError && ["REQUEST_BUDGET", "TIME_BUDGET", "RESPONSE_TOO_LARGE"].includes(error.code))
+                break;
+            throw error;
+        }
+        const parsed = z.array(isEvent ? event : entity).safeParse(page.records);
+        if (!parsed.success || offset > page.records.length)
+            throw new AxiError("Invalid search response", "RESPONSE_INVALID", []);
+        // Never wrap an echoed credential in a reversible continuation cursor.
+        if (page.scrollId && store.redactor.text(page.scrollId) !== page.scrollId)
+            throw new AxiError("Unsafe API scrollId", "RESPONSE_INVALID", []);
+        total = page.total ?? total;
+        const rows = parsed.data.slice(offset, offset + limit - results.length);
+        results.push(...rows.map((record) => {
+            if (isEvent) {
+                const value = event.parse(record);
+                return { id: value.eventId, type: value.type, state: value.state, severity: value.severity };
+            }
+            const value = entity.parse(record);
+            return { id: value.entityInfo.entityId, subject: value.entityPayload.subject ?? "",
+                state: value.entityInfo.entityActionState ?? "", verdict: value.entitySecurityResults?.combinedVerdict ?? null };
+        }));
+        offset += rows.length;
+        if (offset < page.records.length) {
+            replayRisk = true;
+            break;
+        }
+        if (!page.scrollId) {
+            exhausted = true;
+            break;
+        }
+        scroll = page.scrollId;
+        offset = 0;
+    }
+    const next = exhausted ? undefined : Buffer.from(JSON.stringify({ version: 1, binding, start, end, scroll, offset,
+        ...(replayRisk ? { replayRisk: true } : {}) })).toString("base64url");
+    return { [isEvent ? "events" : "emails"]: results, count: results.length, ...(total === undefined ? {} : { total }), complete: exhausted && !replayRisk,
+        ...(replayRisk ? { reason: "replay-may-skip-or-repeat" } : {}), ...(next ? { cursor: next } : {}),
+        help: [...(results.length ? [isEvent ? "Run checkpoint-axi event show <id> for event details and available actions" : "Run checkpoint-axi email show <id> for verdicts, actions and available actions"] : [`No ${isEvent ? "events" : "emails"} matched this search window and selectors`]),
+            ...(next ? ["Repeat this search with --cursor <cursor> and the original selectors to continue"] : []),
+            ...(replayRisk ? ["Results changed between calls may be skipped or repeated during page replay"] : [])] };
+}

package/dist/src/redact.d.ts

@@ -0,0 +1,6 @@
+export declare class SecretRedactor {
+    private readonly secrets;
+    add(secret: string | undefined): void;
+    text(value: string): string;
+    value(value: unknown): unknown;
+}

package/dist/src/redact.js

@@ -0,0 +1,25 @@
+export class SecretRedactor {
+    secrets = new Set();
+    add(secret) {
+        if (!secret)
+            return;
+        this.secrets.add(secret);
+        this.secrets.add(JSON.stringify(secret).slice(1, -1));
+        if (secret.isWellFormed())
+            this.secrets.add(encodeURIComponent(secret));
+    }
+    text(value) {
+        for (const secret of [...this.secrets].sort((a, b) => b.length - a.length))
+            value = value.split(secret).join("***redacted***");
+        return value;
+    }
+    value(value) {
+        if (typeof value === "string")
+            return this.text(value);
+        if (Array.isArray(value))
+            return value.map((child) => this.value(child));
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [this.text(key), this.value(child)]));
+        return value;
+    }
+}

package/dist/src/regions.d.ts

@@ -0,0 +1,9 @@
+export declare const REGIONS: {
+    readonly us: "https://cloudinfra-gw-us.portal.checkpoint.com";
+    readonly eu: "https://cloudinfra-gw.portal.checkpoint.com";
+    readonly ca: "https://cloudinfra-gw.ca.portal.checkpoint.com";
+    readonly au: "https://cloudinfra-gw.ap.portal.checkpoint.com";
+    readonly uk: "https://cloudinfra-gw.uk.portal.checkpoint.com";
+    readonly uae: "https://cloudinfra-gw.me.portal.checkpoint.com";
+    readonly in: "https://cloudinfra-gw.in.portal.checkpoint.com";
+};

package/dist/src/regions.js

@@ -0,0 +1,10 @@
+// Email Security API Reference Guide, 23 October 2026, page 8.
+export const REGIONS = {
+    us: "https://cloudinfra-gw-us.portal.checkpoint.com",
+    eu: "https://cloudinfra-gw.portal.checkpoint.com",
+    ca: "https://cloudinfra-gw.ca.portal.checkpoint.com",
+    au: "https://cloudinfra-gw.ap.portal.checkpoint.com",
+    uk: "https://cloudinfra-gw.uk.portal.checkpoint.com",
+    uae: "https://cloudinfra-gw.me.portal.checkpoint.com",
+    in: "https://cloudinfra-gw.in.portal.checkpoint.com",
+};

package/dist/src/transport.d.ts

@@ -0,0 +1,86 @@
+import { type Agent } from "node:https";
+import type { SelectedProfile } from "./profiles.js";
+import type { SecretRedactor } from "./redact.js";
+import { type WriteAuthorization } from "./writes.js";
+export declare const READ_LIMITS: {
+    readonly requests: 10;
+    readonly rows: 1000;
+    readonly milliseconds: 60000;
+    readonly bytes: number;
+};
+export declare const DOWNLOAD_LIMIT: number;
+export type DownloadRequest = {
+    entityId: string;
+    attachmentId?: string;
+    all?: boolean;
+    original?: boolean;
+    scope?: string;
+};
+export type ExceptionPath = `/exceptions/${"whitelist" | "blacklist" | "spam_whitelist"}${"" | `/${string}`}` | `/sectools/${"anomaly" | "click_time_protection"}/exceptions${"" | `/${string}`}` | `/sectool-exceptions/${"checkpoint2" | "avanan_url" | "avanan_dlp"}/exceptions/${string}`;
+export type ReadRequest = {
+    path: "/search/query";
+    body: {
+        entityFilter: {
+            saas: string;
+            saasEntity?: string;
+            startDate: string;
+            endDate: string;
+        };
+        entityExtendedFilter?: {
+            saasAttrName: string;
+            saasAttrOp: string;
+            saasAttrValue: string;
+        }[];
+        scrollId?: string;
+    };
+} | {
+    path: `/search/entity/${string}`;
+    body?: never;
+} | {
+    path: "/event/query";
+    body: {
+        startDate?: string;
+        endDate?: string;
+        saas?: string[];
+        eventTypes?: string[];
+        eventStates?: string[];
+        severities?: string[];
+        eventIds?: string[];
+        confidenceIndicator?: string;
+        description?: string;
+        scrollId?: string;
+    };
+} | {
+    path: `/event/${string}` | `/task/${string}`;
+    body?: never;
+} | {
+    path: ExceptionPath;
+    body?: never;
+};
+export type Page = {
+    records: unknown[];
+    scrollId?: string;
+    total?: number;
+};
+type Dependencies = {
+    agent?: Agent;
+    now?: () => number;
+    wait?: (milliseconds: number) => Promise<unknown>;
+};
+export declare function decodePage(value: unknown, unverified?: boolean): Page;
+export declare function gateway(profile: SelectedProfile, credentials: {
+    clientId: string;
+    clientSecret: string;
+}, redactor: SecretRedactor, dependencies?: Dependencies, mutation?: boolean): {
+    authenticate: () => Promise<void>;
+    read: (query: ReadRequest) => Promise<Page>;
+    download: (query: DownloadRequest) => Promise<{
+        content: Buffer;
+        sha256: string;
+    }>;
+    emailAction: (authorization: WriteAuthorization, action: "quarantine" | "restore", targets: readonly string[]) => Promise<Page>;
+    eventAction: (authorization: WriteAuthorization, action: string, targets: readonly string[]) => Promise<Page>;
+    exceptionWrite: (authorization: WriteAuthorization, kind: "phishing-allow" | "phishing-block" | "spam-allow", action: "create" | "update" | "remove", target: string, checkScopeBeforeSend: () => void, data?: Record<string, unknown>) => Promise<void>;
+    sectoolsWrite: (authorization: WriteAuthorization, kind: "anomaly" | "click-time" | "malware" | "url" | "dlp", action: "create" | "update" | "remove" | "remove-items", targets: readonly string[], checkScopeBeforeSend: () => void, data?: Record<string, unknown>, specific?: boolean) => Promise<unknown>;
+};
+export {};

package/dist/src/transport.js

@@ -0,0 +1,306 @@
+import { AxiError } from "axi-sdk-js";
+import { randomUUID } from "node:crypto";
+import { request } from "node:https";
+import { setTimeout as delay } from "node:timers/promises";
+import { REGIONS } from "./regions.js";
+import { consumeWriteAuthorization } from "./writes.js";
+export const READ_LIMITS = { requests: 10, rows: 1_000, milliseconds: 60_000, bytes: 8 * 1024 * 1024 };
+export const DOWNLOAD_LIMIT = 50 * 1024 * 1024;
+const failure = (code, message) => new AxiError(message, code, ["Check the selected region and credentials; run checkpoint-axi doctor"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+// Object/array responseData inconsistency is documented on guide pages 35-37.
+export function decodePage(value, unverified = false) {
+    // These exception families publish no response schema (guide pages 83-123).
+    if (unverified && (!object(value) || !Object.hasOwn(value, "responseEnvelope"))) {
+        return { records: Array.isArray(value) ? value : [value] };
+    }
+    if (!object(value) || !object(value.responseEnvelope))
+        throw failure("RESPONSE_INVALID", "Missing API response envelope");
+    const envelope = value.responseEnvelope;
+    if (envelope.responseCode !== 0 && envelope.responseCode !== "0" && envelope.responseCode !== 200 && envelope.responseCode !== "200") {
+        throw failure("API_ERROR", "API response envelope did not report success");
+    }
+    const data = value.responseData;
+    if ((!unverified && !Array.isArray(data) && !object(data)) || data === undefined)
+        throw failure("RESPONSE_INVALID", "Expected responseData");
+    if (envelope.scrollId !== undefined && envelope.scrollId !== null && typeof envelope.scrollId !== "string") {
+        throw failure("RESPONSE_INVALID", "Invalid API scrollId");
+    }
+    if (envelope.totalRecordsNumber !== undefined && (!Number.isSafeInteger(envelope.totalRecordsNumber) || Number(envelope.totalRecordsNumber) < 0)) {
+        throw failure("RESPONSE_INVALID", "Invalid API totalRecordsNumber");
+    }
+    return { records: Array.isArray(data) ? data : [data], scrollId: typeof envelope.scrollId === "string" && envelope.scrollId ? envelope.scrollId : undefined,
+        total: envelope.totalRecordsNumber };
+}
+// No field name or lifetime is commissioned yet (guide page 8).
+function tokenFrom(value, redactor) {
+    const register = (child) => {
+        if (typeof child === "string")
+            redactor.add(child);
+        else if (Array.isArray(child))
+            child.forEach(register);
+        else if (object(child))
+            Object.values(child).forEach(register);
+    };
+    register(value);
+    const tokens = new Set();
+    let invalid = false;
+    if (object(value))
+        for (const container of [value, value.data, value.responseData]) {
+            if (!object(container))
+                continue;
+            for (const key of ["token", "access_token", "accessToken"]) {
+                const candidate = container[key];
+                if (candidate === undefined)
+                    continue;
+                if (typeof candidate === "string" && candidate.length > 0 && /^[\x21-\x7E]+$/.test(candidate))
+                    tokens.add(candidate);
+                else
+                    invalid = true;
+            }
+        }
+    if (invalid || tokens.size !== 1)
+        throw failure("AUTH_SHAPE_UNVERIFIED", "Unverified auth token response shape; owner commissioning is required (API guide page 8 does not specify the shape)");
+    return [...tokens][0];
+}
+export function gateway(profile, credentials, redactor, dependencies = {}, mutation = false) {
+    const now = dependencies.now ?? Date.now;
+    const wait = dependencies.wait ?? delay;
+    const deadline = now() + READ_LIMITS.milliseconds;
+    let bytes = 0;
+    let requests = 0;
+    let token;
+    let refreshed = false;
+    const nextException = new Map();
+    redactor.add(credentials.clientSecret);
+    redactor.add(JSON.stringify({ clientId: credentials.clientId, accessKey: credentials.clientSecret }));
+    async function pause(milliseconds) {
+        if (!Number.isFinite(milliseconds) || milliseconds < 0 || now() + milliseconds >= deadline)
+            throw failure("TIME_BUDGET", "Read time budget exhausted");
+        await wait(milliseconds);
+    }
+    async function send(path, body, bearer, method = body === undefined ? "GET" : "POST", allowEmpty = false, binary = false, scopes) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw failure("TIME_BUDGET", "Read time budget exhausted");
+        if (++requests > (mutation ? 44 : READ_LIMITS.requests))
+            throw failure("REQUEST_BUDGET", "Request budget exhausted");
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        if (bearer)
+            redactor.add(`Bearer ${bearer}`);
+        return new Promise((resolve, reject) => {
+            const req = request(new URL(path, REGIONS[profile.region]), {
+                method, agent: dependencies.agent,
+                headers: { "x-av-req-id": randomUUID(), accept: "application/json", ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+                    ...(scopes === undefined ? {} : { scopes }),
+                    ...(payload === undefined ? {} : { "content-type": "application/json", "content-length": Buffer.byteLength(payload) }) },
+            }, (response) => {
+                const chunks = [];
+                let received = 0;
+                response.on("data", (chunk) => {
+                    received += chunk.length;
+                    if (!binary)
+                        bytes += chunk.length;
+                    if (binary ? received > DOWNLOAD_LIMIT : bytes > READ_LIMITS.bytes)
+                        req.destroy(failure("RESPONSE_TOO_LARGE", "Response byte budget exhausted"));
+                    else
+                        chunks.push(chunk);
+                });
+                response.on("error", () => {
+                    clearTimeout(timer);
+                    reject(failure("NETWORK_ERROR", "API response stream failed"));
+                });
+                response.on("end", () => {
+                    clearTimeout(timer);
+                    const status = response.statusCode ?? 0;
+                    // Error bodies are untrusted and may echo credentials. Never render them.
+                    if (status < 200 || status >= 300)
+                        return resolve({ status, retryAfter: response.headers["retry-after"], value: undefined });
+                    if (binary)
+                        return resolve({ status, value: Buffer.concat(chunks), sha256: typeof response.headers["x-av-sha256"] === "string" ? response.headers["x-av-sha256"] : undefined });
+                    const json = Buffer.concat(chunks).toString("utf8");
+                    if (allowEmpty && status === 204 && !json)
+                        return resolve({ status, value: null });
+                    try {
+                        resolve({ status, value: JSON.parse(json) });
+                    }
+                    catch {
+                        reject(failure("RESPONSE_INVALID", "API returned invalid JSON"));
+                    }
+                });
+            });
+            const timer = setTimeout(() => req.destroy(failure("TIME_BUDGET", "Read time budget exhausted")), remaining);
+            req.on("error", (error) => {
+                clearTimeout(timer);
+                reject(error instanceof AxiError ? error : failure("NETWORK_ERROR", "Cannot reach the regional API with verified TLS"));
+            });
+            req.end(payload);
+        });
+    }
+    async function authenticate() {
+        if (token)
+            return;
+        const response = await send("/auth/external", { clientId: credentials.clientId, accessKey: credentials.clientSecret });
+        if (response.status < 200 || response.status >= 300)
+            throw failure("AUTH_FAILED", "Regional API authentication failed");
+        token = tokenFrom(response.value, redactor);
+    }
+    async function spaceException(path) {
+        const group = /^\/exceptions\/(whitelist|blacklist)(\/|$)/.test(path) ? "phishing"
+            : /^\/(exceptions|sectools|sectool-exceptions)\//.test(path) ? "other" : undefined;
+        if (group) {
+            const remaining = (nextException.get(group) ?? 0) - now();
+            if (remaining > 0)
+                await pause(remaining);
+            nextException.set(group, now() + (group === "phishing" ? 1_000 : 100));
+        }
+    }
+    async function read(query) {
+        await authenticate();
+        for (let retries = 0;;) {
+            await spaceException(query.path);
+            const response = await send(`/app/hec-api/v1.0${query.path}`, query.body === undefined ? undefined : { requestData: query.body }, token);
+            if (response.status === 401 && !refreshed) {
+                refreshed = true;
+                token = undefined;
+                await authenticate();
+                continue;
+            }
+            if (response.status === 429 && retries++ < 2) {
+                const header = response.retryAfter;
+                const milliseconds = header === undefined ? 1_000 : /^\d+$/.test(header) ? Number(header) * 1_000 : Math.max(0, Date.parse(header) - now());
+                await pause(Number.isFinite(milliseconds) ? milliseconds : 1_000);
+                continue;
+            }
+            if (response.status === 401)
+                throw failure("AUTH_FAILED", "API rejected authentication after one re-exchange");
+            if (response.status === 429)
+                throw failure("RATE_LIMITED", "API rate limit remains after two read retries");
+            if (response.status < 200 || response.status >= 300)
+                throw failure("HTTP_ERROR", `Regional API returned HTTP ${response.status}`);
+            return decodePage(response.value, /^\/(sectools|sectool-exceptions)\//.test(query.path));
+        }
+    }
+    async function download(query) {
+        if (!profile.downloads.allow)
+            throw failure("DOWNLOADS_DISABLED", "Enable downloads.allow in the selected file profile");
+        const validId = (value) => /^[A-Za-z0-9_-]{1,256}$/.test(value);
+        if (!validId(query.entityId) || query.attachmentId !== undefined && !validId(query.attachmentId)
+            || query.all && query.attachmentId !== undefined || (query.all || query.attachmentId !== undefined) && query.original !== undefined
+            || query.scope !== undefined && !/^[\x21-\x7E]+$/.test(query.scope)
+            || profile.scope !== undefined && !/^[\x21-\x7E]+$/.test(profile.scope))
+            throw failure("VALIDATION_ERROR", "Invalid download selectors or scopes");
+        const attachment = query.all || query.attachmentId !== undefined;
+        if (!attachment && !profile.scope)
+            throw failure("DOWNLOAD_SCOPE_REQUIRED", "Email downloads require the profile scope for the scopes header");
+        const params = new URLSearchParams();
+        if (attachment && query.scope)
+            params.set("scope", query.scope);
+        if (!attachment)
+            params.set("original", String(query.original ?? false));
+        const path = `/app/hec-api/v1.0/download/entity/${encodeURIComponent(query.entityId)}${query.all ? "/attachments" : query.attachmentId ? `/attachment/${encodeURIComponent(query.attachmentId)}` : ""}${params.size ? `?${params}` : ""}`;
+        await authenticate();
+        for (let retries = 0;;) {
+            const response = await send(path, undefined, token, "GET", false, true, attachment ? undefined : profile.scope);
+            if (response.status === 401 && !refreshed) {
+                refreshed = true;
+                token = undefined;
+                await authenticate();
+                continue;
+            }
+            if (response.status === 429 && retries++ < 2) {
+                const header = response.retryAfter;
+                const milliseconds = header === undefined ? 1_000 : /^\d+$/.test(header) ? Number(header) * 1_000 : Math.max(0, Date.parse(header) - now());
+                await pause(Number.isFinite(milliseconds) ? milliseconds : 1_000);
+                continue;
+            }
+            if (response.status === 401)
+                throw failure("AUTH_FAILED", "API rejected authentication after one re-exchange");
+            if (response.status === 429)
+                throw failure("RATE_LIMITED", "API rate limit remains after two download retries");
+            if (response.status !== 200)
+                throw failure("HTTP_ERROR", `Regional API returned HTTP ${response.status}`);
+            if (!response.sha256 || !/^[a-fA-F0-9]{64}$/.test(response.sha256))
+                throw failure("DOWNLOAD_HASH_INVALID", "Download SHA-256 header is missing or invalid; commissioning may be required");
+            return { content: response.value, sha256: response.sha256.toLowerCase() };
+        }
+    }
+    // Closed entity-action route; mutations never enter the read retry loop.
+    async function emailAction(authorization, action, targets) {
+        if (!mutation || !consumeWriteAuthorization(authorization, `email.${action}`, targets, profile.name, profile.region)) {
+            throw failure("WRITES_DISABLED", "A one-use coordinator authorization is required");
+        }
+        await authenticate();
+        try {
+            const response = await send("/app/hec-api/v1.0/action/entity", { requestData: {
+                    entityIds: targets, entityActionName: [action], entityActionParam: [""],
+                } }, token);
+            if (response.status < 200 || response.status >= 300)
+                throw new Error("Action response requires reconciliation");
+            return decodePage(response.value);
+        }
+        catch {
+            throw new AxiError("Email action outcome is unknown; never replay automatically", "OUTCOME_UNKNOWN", [
+                "Inspect the write journal and read back every target before deciding what to do next",
+            ]);
+        }
+    }
+    // Closed event-action route; authorization cannot be reused or supplied by argv.
+    async function eventAction(authorization, action, targets) {
+        if (!mutation || !consumeWriteAuthorization(authorization, `event.action.${action}`, targets, profile.name, profile.region)) {
+            throw failure("WRITES_DISABLED", "A one-use coordinator authorization is required");
+        }
+        await authenticate();
+        const response = await send("/app/hec-api/v1.0/action/event", { requestData: {
+                eventIds: targets, eventActionName: [action], eventActionParam: [""],
+            } }, token);
+        if (response.status < 200 || response.status >= 300)
+            throw failure("OUTCOME_UNKNOWN", "Event action outcome requires reconciliation; never replay automatically");
+        return decodePage(response.value);
+    }
+    // Guide pp.61-69, 75-82: closed C8 routes; deletion is a bodyless POST.
+    async function exceptionWrite(authorization, kind, action, target, checkScopeBeforeSend, data) {
+        const routes = { "phishing-allow": "whitelist", "phishing-block": "blacklist", "spam-allow": "spam_whitelist" };
+        if (!mutation || !Object.hasOwn(routes, kind) || !["create", "update", "remove"].includes(action)
+            || !consumeWriteAuthorization(authorization, `exception.${kind}.${action}`, [target], profile.name, profile.region)) {
+            throw failure("WRITES_DISABLED", "A one-use coordinator authorization is required");
+        }
+        await authenticate();
+        const path = `/exceptions/${routes[kind]}${action === "create" ? "" : action === "remove" ? `/delete/${encodeURIComponent(target)}` : `/${encodeURIComponent(target)}`}`;
+        await spaceException(path);
+        checkScopeBeforeSend();
+        const response = await send(`/app/hec-api/v1.0${path}`, action === "remove" ? undefined : { requestData: data }, token, action === "update" ? "PUT" : "POST");
+        if (response.status < 200 || response.status >= 300 || !object(response.value) || !object(response.value.responseEnvelope)
+            || ![0, "0", 200, "200", ...(action === "remove" ? [204, "204"] : [])].includes(response.value.responseEnvelope.responseCode)) {
+            throw failure("OUTCOME_UNKNOWN", "Exception write acknowledgement requires reconciliation; never replay automatically");
+        }
+    }
+    // Guide pp.84-99,102-127: closed routes; request bodies distinguish shared POSTs.
+    // Response schemas are unpublished; preserve JSON, interpreting only HTTP/envelope status.
+    async function sectoolsWrite(authorization, kind, action, targets, checkScopeBeforeSend, data, specific = false) {
+        const sectools = { malware: "checkpoint2", url: "avanan_url", dlp: "avanan_dlp" };
+        const sectool = Object.hasOwn(sectools, kind);
+        if (sectool && action !== "create" && action !== "update")
+            throw failure("ENDPOINT_UNVERIFIED", "Sectool deletes require commissioning; nothing was sent");
+        if (!mutation || !["anomaly", "click-time", "malware", "url", "dlp"].includes(kind) || !["create", "update", "remove", "remove-items"].includes(action)
+            || kind === "anomaly" && action !== "create" && action !== "remove"
+            || specific && (!sectool || action !== "create")
+            || action !== "remove-items" && targets.length !== 1
+            || !consumeWriteAuthorization(authorization, `exception.${kind}.${action}`, targets, profile.name, profile.region)) {
+            throw failure("WRITES_DISABLED", "A one-use coordinator authorization is required");
+        }
+        const path = sectool ? `/sectool-exceptions/${sectools[kind]}${specific ? "/exceptions" : ""}`
+            : kind === "anomaly" ? "/sectools/anomaly/exceptions"
+                : `/sectools/click_time_protection/exceptions/items${action === "update" || action === "remove" ? `/${encodeURIComponent(targets[0])}` : ""}`;
+        await authenticate();
+        await spaceException(path);
+        checkScopeBeforeSend();
+        const response = await send(`/app/hec-api/v1.0${path}`, kind === "click-time" && action === "remove" ? undefined : { requestData: data }, token, action === "update" ? "PUT" : "POST", true);
+        if (response.status < 200 || response.status >= 300 || object(response.value) && Object.hasOwn(response.value, "responseEnvelope")
+            && (!object(response.value.responseEnvelope) || ![0, "0", 200, "200", 204, "204"].includes(response.value.responseEnvelope.responseCode))) {
+            throw failure("OUTCOME_UNKNOWN", "Exception write status requires reconciliation; never replay automatically");
+        }
+        return response.value;
+    }
+    return { authenticate, read, download, emailAction, eventAction, exceptionWrite, sectoolsWrite };
+}

package/dist/src/write-exceptions.d.ts

@@ -0,0 +1,4 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+import { type SectoolsAction } from "./write-sectools.js";
+export declare function exceptionWriteCommand(name: `exception ${SectoolsAction}`, kind: string | undefined, id: string | undefined, flags: Map<string, string>, store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;