@knowttl/checkpoint-axi 0.0.0 → 0.1.0

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

package/dist/src/writes.js

@@ -0,0 +1,295 @@
+import { AxiError } from "axi-sdk-js";
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { gateway } from "./transport.js";
+import { protectWindowsFile, windowsAcl } from "./private-file.js";
+const fail = (code, message, help = []) => { throw new AxiError(message, code, help); };
+const authorizations = new WeakSet();
+export function consumeWriteAuthorization(authorization, operation, targets, profile, region) {
+    if (!authorizations.delete(authorization))
+        return false;
+    return authorization.operation === operation && authorization.profile === profile && authorization.region === region
+        && targets.length > 0 && targets.length <= 20 && new Set(targets).size === targets.length
+        && targets.every((target) => authorization.targets.includes(target));
+}
+// Metadata only, never message payloads, headers, credentials or API bodies.
+function journal(store) {
+    const path = store.writeLogPath();
+    function append(record) {
+        let lock;
+        let fd;
+        try {
+            const directory = dirname(path);
+            const created = mkdirSync(directory, { recursive: true, mode: 0o700 });
+            if (process.platform === "win32" && created !== undefined)
+                protectWindowsFile(directory);
+            const parent = lstatSync(directory);
+            if (!parent.isDirectory() || parent.isSymbolicLink() || process.platform !== "win32"
+                && (parent.uid !== process.getuid() || (parent.mode & 0o077) !== 0))
+                throw new Error("Insecure journal directory");
+            if (process.platform === "win32")
+                windowsAcl(directory, true);
+            lock = openSync(`${path}.lock`, "wx", 0o600);
+            if (process.platform === "win32")
+                protectWindowsFile(`${path}.lock`);
+            try {
+                fd = openSync(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_EXCL, 0o600);
+                if (process.platform === "win32")
+                    protectWindowsFile(path);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const existing = lstatSync(path);
+                if (!existing.isFile() || existing.isSymbolicLink() || existing.nlink !== 1 || process.platform !== "win32"
+                    && (existing.uid !== process.getuid() || (existing.mode & 0o077) !== 0))
+                    throw new Error("Insecure journal file");
+                if (process.platform === "win32")
+                    windowsAcl(path, true);
+                fd = openSync(path, constants.O_RDWR | constants.O_APPEND | (process.platform === "win32" ? 0 : constants.O_NOFOLLOW));
+            }
+            const stat = fstatSync(fd);
+            if (!stat.isFile() || stat.nlink !== 1 || process.platform !== "win32"
+                && (stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0))
+                throw new Error("Insecure journal file");
+            if (process.platform === "win32")
+                windowsAcl(path, true);
+            const contents = readFileSync(fd, "utf8");
+            if (contents && !contents.endsWith("\n"))
+                throw new Error("Incomplete journal");
+            for (const line of contents.split("\n").filter(Boolean)) {
+                const entry = JSON.parse(line);
+                if (!entry || !["intent", "outcome"].includes(String(entry.kind)) || typeof entry.auditId !== "string")
+                    throw new Error("Invalid journal");
+                if (record.kind === "intent" && entry.kind === "intent" && entry.auditId === record.auditId)
+                    throw new Error("Duplicate intent");
+            }
+            const line = Buffer.from(JSON.stringify(store.redactor.value({ ...record, time: new Date().toISOString() })) + "\n");
+            let offset = 0;
+            while (offset < line.length) {
+                const written = writeSync(fd, line, offset, line.length - offset);
+                if (!written)
+                    throw new Error("Incomplete journal write");
+                offset += written;
+            }
+            fsyncSync(fd);
+            // The directory entry must survive a crash too, before sending anything.
+            if (process.platform !== "win32") {
+                const stop = created === undefined ? directory : dirname(created);
+                let current = directory;
+                for (;;) {
+                    const directoryFd = openSync(current, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                    try {
+                        fsyncSync(directoryFd);
+                    }
+                    finally {
+                        closeSync(directoryFd);
+                    }
+                    if (current === stop)
+                        break;
+                    current = dirname(current);
+                }
+            }
+        }
+        catch {
+            fail(record.kind === "intent" ? "INTENT_NOT_RECORDED" : "OUTCOME_NOT_RECORDED", record.kind === "intent" ? "Durable write intent could not be recorded; nothing was sent" : "Write outcome could not be recorded; reconcile before any further action", [`Audit ID: ${String(record.auditId)}`, "Check CHECKPOINT_AXI_WRITE_LOG and its private directory permissions; never replay an ambiguous action"]);
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            if (lock !== undefined) {
+                closeSync(lock);
+                unlinkSync(`${path}.lock`);
+            }
+        }
+    }
+    return append;
+}
+// Domain callers bind the operation and single send; flags cannot supply routes.
+export async function coordinateWrite(args) {
+    const { operation, targets, flags, store, checkScope, readState, send } = args;
+    if (!targets.length || targets.length > 20 || new Set(targets).size !== targets.length)
+        fail("VALIDATION_ERROR", "Supply 1-20 unique targets");
+    if (flags.has("--execute") && flags.has("--dry-run"))
+        fail("VALIDATION_ERROR", "--execute cannot combine with --dry-run");
+    checkScope();
+    const current = await readState();
+    const confirmation = `${operation} ${targets.join(",")}`;
+    const preview = { operation, effect: "disruptive", targets, noop: current.noop, currentState: current.state, confirm: confirmation };
+    if (!flags.has("--execute"))
+        return { outcome: "preview", preview };
+    if (current.noop)
+        return { outcome: "noop", preview };
+    if (!flags.has("--confirm"))
+        fail("CONFIRM_REQUIRED", "Exact target confirmation is required", [`Repeat with --confirm '${confirmation}'`]);
+    if (flags.get("--confirm") !== confirmation)
+        fail("CONFIRM_MISMATCH", "Confirmation does not exactly match the operation and every target", [`Repeat with --confirm '${confirmation}'`]);
+    checkScope();
+    const auditId = randomUUID();
+    const record = journal(store);
+    const meta = { auditId, ...args.scope, operation, targets, effect: "disruptive" };
+    record({ ...meta, kind: "intent" });
+    let fresh;
+    try {
+        fresh = await readState();
+        checkScope();
+    }
+    catch (error) {
+        record({ ...meta, kind: "outcome", outcome: "NOT_SENT" });
+        throw error;
+    }
+    if (fresh.noop) {
+        record({ ...meta, kind: "outcome", outcome: "NOT_SENT" });
+        return { outcome: "noop", preview, auditId };
+    }
+    const authorization = Object.freeze({ operation, targets: Object.freeze([...targets]), ...args.scope });
+    authorizations.add(authorization);
+    let result;
+    let scopeRevoked = false;
+    try {
+        result = await send(authorization, () => {
+            try {
+                checkScope();
+            }
+            catch (error) {
+                scopeRevoked = true;
+                throw error;
+            }
+        });
+    }
+    catch (error) {
+        if (scopeRevoked) {
+            record({ ...meta, kind: "outcome", outcome: "NOT_SENT" });
+            throw error;
+        }
+        record({ ...meta, kind: "outcome", outcome: "OUTCOME_UNKNOWN" });
+        return fail("OUTCOME_UNKNOWN", "Action outcome is unknown; never replay automatically", [
+            `Audit ID: ${auditId}`, "Inspect the write journal and read back every target before deciding what to do next",
+        ]);
+    }
+    finally {
+        authorizations.delete(authorization);
+    }
+    record({ ...meta, kind: "outcome", outcome: "accepted" });
+    return { outcome: "accepted", auditId, ...result };
+}
+const entity = z.object({ entityInfo: z.object({ entityId: z.string(), saasEntityType: z.string() }),
+    entityPayload: z.object({ isQuarantined: z.boolean().optional(), isRestored: z.boolean().optional() }),
+    entityAvailableActions: z.array(z.object({ entityActionName: z.string() })) });
+const task = z.object({ entityId: z.string(), taskId: z.union([z.string().regex(/^[A-Za-z0-9_-]+$/), z.number().int().nonnegative()]) });
+const event = z.object({ eventId: z.string(), entityId: z.string(), state: z.string(),
+    availableEventActions: z.array(z.object({ actionName: z.string(), actionParameter: z.record(z.string(), z.unknown()) })) });
+const eventTask = task.extend({ eventId: z.string() });
+export async function eventWriteCommand(flags, store, transport) {
+    const targets = flags.get("--ids")?.split(",") ?? [];
+    const action = flags.get("--name");
+    if (!targets.length || targets.length > 20 || new Set(targets).size !== targets.length
+        || targets.some((id) => !/^[A-Za-z0-9][A-Za-z0-9_-]{0,255}$/.test(id))
+        || !action || !/^[a-z][A-Za-z0-9_-]{0,127}$/.test(action)) {
+        return fail("VALIDATION_ERROR", "Supply --name <action> and --ids with 1-20 unique comma-separated event IDs");
+    }
+    if (flags.has("--execute") && flags.has("--dry-run"))
+        return fail("VALIDATION_ERROR", "--execute cannot combine with --dry-run");
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const operation = `event.action.${action}`;
+    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 entities = new Map();
+    const readState = async () => {
+        const states = [];
+        for (const id of targets) {
+            const page = await session.read({ path: `/event/${encodeURIComponent(id)}` });
+            const parsed = event.safeParse(page.records[0]);
+            if (page.records.length !== 1 || !parsed.success || parsed.data.eventId !== id) {
+                return fail("RESPONSE_INVALID", "Event preflight returned a missing, mismatched or malformed event");
+            }
+            const value = parsed.data;
+            const offered = value.availableEventActions.filter((item) => item.actionName === action);
+            if (!offered.length)
+                fail("ACTION_UNAVAILABLE", "Requested action is unavailable for an event target");
+            // Guide pp.36-37 uses objects, but p.43 requires strings; never guess serialization.
+            if (offered.length !== 1 || Object.keys(offered[0].actionParameter).length) {
+                fail("ENDPOINT_UNVERIFIED", "Parameterized event actions require live commissioning through Artium", ["Run checkpoint-axi event show <id> to inspect available actions; parameter serialization is unverified (guide pages 36-37, 43)"]);
+            }
+            entities.set(id, value.entityId);
+            states.push({ id, state: value.state, action });
+        }
+        return { noop: false, state: states };
+    };
+    return coordinateWrite({ operation, targets, flags, store, scope: { profile: profile.name, region: profile.region }, checkScope, readState, send: async (authorization) => {
+            const page = await session.eventAction(authorization, action, targets);
+            const parsed = z.array(eventTask).safeParse(page.records);
+            if (!parsed.success || parsed.data.length !== targets.length || new Set(parsed.data.map((item) => item.eventId)).size !== targets.length
+                || parsed.data.some((item) => !targets.includes(item.eventId) || entities.get(item.eventId) !== item.entityId
+                    || store.redactor.text(String(item.taskId)) !== String(item.taskId))) {
+                return fail("OUTCOME_UNKNOWN", "Action response did not identify a task for every event target");
+            }
+            return { tasks: parsed.data.map((item) => ({ ...item, outcome: "accepted" })), help: ["Run checkpoint-axi task show <taskId> to inspect asynchronous execution; accepted does not mean completed"] };
+        } });
+}
+export async function emailWriteCommand(name, flags, store, transport) {
+    const targets = flags.get("--ids")?.split(",") ?? [];
+    if (!targets.length || targets.length > 20 || new Set(targets).size !== targets.length
+        || targets.some((id) => !/^[A-Za-z0-9][A-Za-z0-9_-]{0,255}$/.test(id))) {
+        return fail("VALIDATION_ERROR", "--ids must name 1-20 unique comma-separated entity IDs");
+    }
+    if (flags.has("--execute") && flags.has("--dry-run"))
+        return fail("VALIDATION_ERROR", "--execute cannot combine with --dry-run");
+    store.readOnly();
+    const loaded = store.load(flags.get("--config"), true);
+    const profile = store.select(loaded.config, flags.get("--profile"));
+    const operation = name.replace(" ", ".");
+    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 action = name === "email quarantine" ? "quarantine" : "restore";
+    let pending = targets;
+    const readState = async () => {
+        const states = [];
+        for (const id of targets) {
+            const page = await session.read({ path: `/search/entity/${encodeURIComponent(id)}` });
+            const parsed = entity.safeParse(page.records[0]);
+            if (page.records.length !== 1 || !parsed.success || parsed.data.entityInfo.entityId !== id
+                || !["office365_emails_email", "google_mail_email"].includes(parsed.data.entityInfo.saasEntityType)) {
+                return fail("RESPONSE_INVALID", "Email preflight returned a missing, mismatched or malformed entity");
+            }
+            const value = parsed.data;
+            const noop = action === "quarantine" ? value.entityPayload.isQuarantined === true
+                : value.entityPayload.isRestored === true && value.entityPayload.isQuarantined === false;
+            if (!noop && !value.entityAvailableActions.some((item) => item.entityActionName === action))
+                fail("ACTION_UNAVAILABLE", "Requested action is unavailable for an email target");
+            states.push({ id, noop, isQuarantined: value.entityPayload.isQuarantined, isRestored: value.entityPayload.isRestored });
+        }
+        pending = states.filter((state) => !state.noop).map((state) => state.id);
+        return { noop: pending.length === 0, state: states };
+    };
+    return coordinateWrite({ operation, targets, flags, store, scope: { profile: profile.name, region: profile.region }, checkScope, readState, send: async (authorization) => {
+            const page = await session.emailAction(authorization, action, pending);
+            const parsed = z.array(task).safeParse(page.records);
+            if (!parsed.success || parsed.data.length !== pending.length || new Set(parsed.data.map((item) => item.entityId)).size !== pending.length
+                || parsed.data.some((item) => !pending.includes(item.entityId) || store.redactor.text(String(item.taskId)) !== String(item.taskId))) {
+                return fail("OUTCOME_UNKNOWN", "Action response did not identify a task for every target");
+            }
+            return { tasks: parsed.data.map((item) => ({ ...item, outcome: "accepted" })), help: ["Run checkpoint-axi task show <taskId> to inspect asynchronous execution; accepted does not mean completed"] };
+        } });
+}