@knowttl/checkpoint-axi 0.0.0 → 0.1.1

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>>;

package/dist/src/write-exceptions.js

@@ -0,0 +1,97 @@
+import { AxiError } from "axi-sdk-js";
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { exceptionFamilies } from "./exceptions.js";
+import { readPrivateFile } from "./private-file.js";
+import { gateway, READ_LIMITS } from "./transport.js";
+import { coordinateWrite } from "./writes.js";
+import { sectoolsWriteCommand } from "./write-sectools.js";
+// Request parameter tables, not the contradictory string-boolean samples: guide pp.62-66, 76-80.
+const criteria = { attachmentMd5: z.string(), senderEmail: z.string(), senderName: z.string(), recipient: z.string(),
+    senderClientIp: z.string(), senderDomain: z.string(), senderIp: z.string(), linkDomains: z.string(), subject: z.string() };
+const fields = { ...criteria, comment: z.string(), actionNeeded: z.string(), ignoringSpfCheck: z.boolean(),
+    subjectMatching: z.string(), linkDomainMatching: z.string(), senderNameMatching: z.string(),
+    senderDomainMatching: z.string(), senderEmailMatching: z.string(), recipientMatching: z.string() };
+const payload = z.strictObject({ ...fields, entityId: z.string().regex(/^[A-Za-z0-9_-]+$/) }).partial();
+const record = z.object({ entityId: z.string().regex(/^[A-Za-z0-9_-]+$/),
+    ...Object.fromEntries(Object.entries(fields).map(([key, value]) => [key, value.nullish()])) }).passthrough();
+const fail = (code, message) => { throw new AxiError(message, code, ["Run checkpoint-axi exception create --help; inspect the preview before execution"]); };
+export async function exceptionWriteCommand(name, kind, id, flags, store, transport) {
+    const action = name.slice("exception ".length);
+    if (kind === "anomaly" || kind === "click-time" || kind === "malware" || kind === "url" || kind === "dlp" || action === "remove-items" || action === "clear") {
+        return sectoolsWriteCommand(action, kind ?? "", id, flags, store, transport);
+    }
+    if (flags.has("--specific"))
+        return fail("VALIDATION_ERROR", "--specific is only valid for malware, url or dlp create");
+    if (kind !== "phishing-allow" && kind !== "phishing-block" && kind !== "spam-allow") {
+        return fail("VALIDATION_ERROR", "Choose phishing-allow, phishing-block, spam-allow, anomaly or click-time for exception writes");
+    }
+    if (action !== "create" && (!id || !/^[A-Za-z0-9_-]{1,256}$/.test(id)))
+        return fail("VALIDATION_ERROR", "Supply one exception ID containing letters, digits, underscores or hyphens");
+    if (flags.has("--execute") && flags.has("--dry-run"))
+        return fail("VALIDATION_ERROR", "--execute cannot combine with --dry-run");
+    let data;
+    if (action !== "remove") {
+        const path = flags.get("--input");
+        if (!path || !isAbsolute(path))
+            return fail("VALIDATION_ERROR", "--input requires an absolute private JSON file path");
+        let value;
+        try {
+            value = JSON.parse(readPrivateFile(path, true, true));
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            return fail("VALIDATION_ERROR", "Cannot read a valid private JSON input file");
+        }
+        const parsed = payload.safeParse(value);
+        if (!parsed.success || !Object.keys(criteria).some((key) => typeof parsed.data[key] === "string"
+            && String(parsed.data[key]).trim())) {
+            return fail("VALIDATION_ERROR", "Input must contain documented requestData fields and at least one nonempty matching criterion; ignoringSpfCheck is boolean");
+        }
+        data = parsed.data;
+        if (action === "update" && data.entityId !== undefined && data.entityId !== id)
+            return fail("VALIDATION_ERROR", "Input entityId must match the exception ID");
+    }
+    // Canonical payload identity binds a new rule's confirmation without putting its contents in the journal.
+    const canonical = data === undefined ? "" : JSON.stringify(Object.fromEntries(Object.entries(data).sort(([a], [b]) => a.localeCompare(b))));
+    const target = action === "create" ? `sha256:${createHash("sha256").update(canonical).digest("hex")}` : id;
+    const operation = `exception.${kind}.${action}`;
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const checkScope = () => {
+        if (store.readOnly() || !profile.writes.allowWrites)
+            fail("WRITES_DISABLED", "Writes are disabled for the selected profile");
+        if (!profile.writes.operations.includes(operation))
+            fail("OPERATION_NOT_WRITABLE", "Operation is outside the selected profile's exact write scope");
+        const fresh = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+        if (JSON.stringify(fresh) !== JSON.stringify(profile))
+            fail("CONFIG_CHANGED", "Profile changed during the write; nothing was sent");
+    };
+    checkScope();
+    const session = gateway(profile, store.credentials(profile, true), store.redactor, transport, true);
+    const path = exceptionFamilies[kind].path;
+    const normalize = (value) => value === "" ? undefined : value ?? undefined;
+    const same = (item) => Object.keys(fields).every((key) => normalize(item[key]) === normalize(data[key]))
+        && (data.entityId === undefined || item.entityId === data.entityId);
+    const readState = async () => {
+        const page = await session.read({ path: (action === "create" ? path : `${path}/${id}`) });
+        const parsed = z.array(record).safeParse(page.records);
+        if (!parsed.success || page.scrollId || page.total !== undefined && page.total > page.records.length
+            || page.records.length > (action === "create" ? READ_LIMITS.rows : 1)
+            || action !== "create" && parsed.data.some((item) => item.entityId !== id)
+            || new Set(parsed.data.map((item) => item.entityId)).size !== parsed.data.length) {
+            return fail("RESPONSE_INVALID", "Exception preflight returned incomplete, mismatched or malformed state");
+        }
+        if (action === "update" && !parsed.data.length)
+            return fail("NOT_FOUND", "Exception to update was not found");
+        const noop = action === "remove" ? parsed.data.length === 0 : parsed.data.some(same);
+        return { noop, state: { existing: action === "create" ? parsed.data.filter(same) : parsed.data, ...(data ? { requested: data } : {}) } };
+    };
+    return coordinateWrite({ operation, targets: [target], flags, store, scope: { profile: profile.name, region: profile.region }, checkScope, readState,
+        send: async (authorization, checkScopeBeforeSend) => {
+            await session.exceptionWrite(authorization, kind, action, target, checkScopeBeforeSend, data);
+            return { help: [`Run checkpoint-axi exception ${action === "create" ? `list ${kind}` : `show ${kind} ${id}`} to reconcile the accepted request; live behavior is uncommissioned`] };
+        } });
+}

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

@@ -0,0 +1,5 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+export type SectoolsAction = "create" | "update" | "remove" | "remove-items" | "clear";
+export type SectoolKind = "malware" | "url" | "dlp";
+export declare function sectoolsWriteCommand(action: SectoolsAction, kind: string, id: string | undefined, flags: Map<string, string>, store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/write-sectools.js

@@ -0,0 +1,107 @@
+import { AxiError } from "axi-sdk-js";
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { readPrivateFile } from "./private-file.js";
+import { gateway } from "./transport.js";
+import { coordinateWrite } from "./writes.js";
+import { exceptionFamilies } from "./exceptions.js";
+const identifier = z.string().regex(/^[A-Za-z0-9_-]{1,256}$/);
+const text = z.string().refine((value) => value.trim().length > 0);
+// Request bodies only: guide pp.84,86,92-95,97-99 publishes no response schemas.
+const anomalyInput = z.strictObject({ addedBy: z.string(), requestJson: z.strictObject({
+        "whitelist-option:new_country": identifier, "apply-to-past": z.enum(["Yes", "No"]),
+        "anomaly-comment": z.string(), event_id: identifier,
+    }) });
+const clickInput = z.strictObject({ listItemName: text, listId: identifier, createdBy: z.string() });
+const clickUpdate = clickInput.extend({ listItemId: identifier });
+const condition = z.strictObject({ condition: text });
+// Guide pp.103-106,113-117,123-127 supplies request examples, but no parameter tables.
+const sectoolFields = { exception_type: text, exception_str: text, comment: z.string() };
+const sectoolCreate = z.strictObject({ ...sectoolFields, entity_type: text, entity_id: text,
+    file_name: z.string(), created_by_email: z.string(), is_exclusive: z.boolean() });
+const malwareCreate = sectoolCreate.extend({ exception_payload: condition });
+const sectoolUpdate = z.strictObject({ ...sectoolFields, exception_payload: condition });
+const fail = (code, message) => {
+    throw new AxiError(message, code, ["Run checkpoint-axi exception create --help; live response identities remain unverified until commissioning through Artium"]);
+};
+export async function sectoolsWriteCommand(action, kind, id, flags, store, transport) {
+    const sectool = kind === "malware" || kind === "url" || kind === "dlp";
+    if (sectool && (action === "remove" || action === "clear")) {
+        return fail("ENDPOINT_UNVERIFIED", "Malware, URL and DLP deletes duplicate create requests in the guide (pages 102-109, 113-119, 123-129); commissioning must establish the real requests");
+    }
+    if (sectool ? action !== "create" && action !== "update"
+        : kind !== "anomaly" && kind !== "click-time" || kind === "anomaly" && action !== "create" && action !== "remove") {
+        return fail("VALIDATION_ERROR", "Anomaly supports create/remove; click-time supports create/update/remove/remove-items/clear; malware/url/dlp support create/update");
+    }
+    if (flags.has("--specific") && (!sectool || action !== "create"))
+        return fail("VALIDATION_ERROR", "--specific is only valid for malware, url or dlp create");
+    if (sectool && id !== undefined)
+        return fail("VALIDATION_ERROR", "Malware, URL and DLP updates identify the exception in --input; omit the positional ID");
+    if (flags.has("--execute") && flags.has("--dry-run"))
+        return fail("VALIDATION_ERROR", "--execute cannot combine with --dry-run");
+    if (action === "clear")
+        return fail("ENDPOINT_UNVERIFIED", "Click-time clear requires a trustworthy pre-read count; the response schema is undocumented (guide pages 87-88, 96-97)");
+    if (action !== "remove-items" && flags.has("--ids"))
+        return fail("VALIDATION_ERROR", "--ids is only valid for click-time remove-items");
+    if (!sectool && (action === "update" || action === "remove") && !identifier.safeParse(id).success)
+        return fail("VALIDATION_ERROR", "Supply one exception ID containing letters, digits, underscores or hyphens");
+    let data;
+    if (action === "create" || action === "update") {
+        const path = flags.get("--input");
+        if (!path || !isAbsolute(path))
+            return fail("VALIDATION_ERROR", "--input requires an absolute private JSON file path");
+        let value;
+        try {
+            value = JSON.parse(readPrivateFile(path, true, true));
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            return fail("VALIDATION_ERROR", "Cannot read a valid private JSON input file");
+        }
+        const parsed = (sectool ? action === "update" ? sectoolUpdate : kind === "malware" ? malwareCreate : sectoolCreate
+            : kind === "anomaly" ? anomalyInput : action === "update" ? clickUpdate : clickInput).safeParse(value);
+        if (!parsed.success)
+            return fail("VALIDATION_ERROR", "Input must contain only the documented requestData fields for this operation");
+        data = parsed.data;
+        if (sectool && !exceptionFamilies[kind].types.includes(String(data.exception_type)))
+            return fail("VALIDATION_ERROR", "Input exception_type must be a documented type for the selected kind");
+        if (!sectool && action === "update" && data.listItemId !== id)
+            return fail("VALIDATION_ERROR", "Input listItemId must match the positional item ID");
+    }
+    const targets = action === "remove-items" ? flags.get("--ids")?.split(",") ?? [] : action === "create" || sectool
+        ? [`sha256:${createHash("sha256").update(JSON.stringify(sectool ? { specific: flags.has("--specific"), data } : data)).digest("hex")}`] : [id];
+    if (!targets.length || targets.length > 20 || new Set(targets).size !== targets.length
+        || action === "remove-items" && targets.some((target) => !identifier.safeParse(target).success)) {
+        return fail("VALIDATION_ERROR", "Supply --ids with 1-20 unique comma-separated item IDs");
+    }
+    if (action === "remove-items")
+        data = { listItemIds: targets };
+    if (kind === "anomaly" && action === "remove")
+        data = { ruleId: id };
+    const operation = `exception.${kind}.${action}`;
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const checkScope = () => {
+        if (store.readOnly() || !profile.writes.allowWrites)
+            fail("WRITES_DISABLED", "Writes are disabled for the selected profile");
+        if (!profile.writes.operations.includes(operation))
+            fail("OPERATION_NOT_WRITABLE", "Operation is outside the selected profile's exact write scope");
+        const fresh = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+        if (JSON.stringify(fresh) !== JSON.stringify(profile))
+            fail("CONFIG_CHANGED", "Profile changed during the write; nothing was sent");
+    };
+    checkScope();
+    const session = gateway(profile, store.credentials(profile, true), store.redactor, transport, true);
+    // No existence/no-op inference is safe without documented response identities.
+    // Both coordinator checks retain explicit uncertainty instead of inventing a list preflight.
+    return coordinateWrite({ operation, targets, flags, store, scope: { profile: profile.name, region: profile.region }, checkScope,
+        readState: async () => ({ noop: false, state: { targetState: "unverified", responseSchema: "unverified",
+                reason: "Existence and no-op detection require live response identity commissioning", ...(data ? { requested: data } : {}) } }),
+        send: async (authorization, checkScopeBeforeSend) => ({
+            response: await session.sectoolsWrite(authorization, kind, action, targets, checkScopeBeforeSend, data, flags.has("--specific")),
+            responseSchema: "unverified",
+            help: [`Run checkpoint-axi exception list ${kind}${sectool ? ` --type ${String(data.exception_type)}` : kind === "click-time" ? " --items" : ""} to inspect unverified JSON and reconcile; never replay automatically`],
+        }) });
+}

package/dist/src/writes.d.ts

@@ -0,0 +1,30 @@
+import { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+type Store = ReturnType<typeof credentialStore>;
+type Flags = Map<string, string>;
+export type WriteAuthorization = Readonly<{
+    operation: string;
+    targets: readonly string[];
+    profile: string;
+    region: string;
+}>;
+export declare function consumeWriteAuthorization(authorization: WriteAuthorization, operation: string, targets: readonly string[], profile: string, region: string): boolean;
+export declare function coordinateWrite(args: {
+    operation: string;
+    targets: readonly string[];
+    flags: Flags;
+    store: Store;
+    scope: {
+        profile: string;
+        region: string;
+    };
+    checkScope: () => void;
+    readState: () => Promise<{
+        noop: boolean;
+        state: unknown;
+    }>;
+    send: (authorization: WriteAuthorization, checkScopeBeforeSend: () => void) => Promise<Record<string, unknown>>;
+}): Promise<Record<string, unknown>>;
+export declare function eventWriteCommand(flags: Flags, store: Store, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;
+export declare function emailWriteCommand(name: "email quarantine" | "email restore", flags: Flags, store: Store, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;
+export {};