@knowttl/checkpoint-axi 0.0.0 → 0.1.1

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"] };
+        } });
+}

package/docs/agent-guide.md

@@ -0,0 +1,108 @@
+<!-- Generated by scripts/generate-docs.mjs from src/catalogue.ts. Do not hand-edit. -->
+
+# Investigation agent guide
+
+Start with these reads; use command help only to recover from a failed command or inspect an unfamiliar selector.
+Examples assume an installed checkpoint-axi and an operator-provisioned read-only profile (the repository tests use synthetic credentials and a fake gateway).
+Without a global install, replace checkpoint-axi with npx -y @knowttl/checkpoint-axi.
+Never pass credentials in argv; use environment/file SecretRefs as described in [configuration](configuration.md).
+Force read-only with CHECKPOINT_AXI_READ_ONLY=1; this overrides profile write permissions.
+Live API contracts remain uncommissioned; fixture success does not establish live compatibility.
+
+## Read commands and examples
+
+Local readiness checks make no API calls:
+
+```sh
+checkpoint-axi
+checkpoint-axi config path
+checkpoint-axi profile list
+checkpoint-axi auth status
+```
+
+The home view shows local profile context, config path shows effective paths, profile list lists file profiles, and auth status validates the selected secret source locally.
+Add --profile <name> or --config <absolute-path> to select provisioned configuration; profile list ignores --profile.
+Doctor authenticates and checks one search page without printing email data:
+
+```sh
+checkpoint-axi doctor
+```
+
+Search emails, then inspect a returned entity ID for payload, verdicts, actions taken and available actions:
+
+```sh
+checkpoint-axi email search --limit 5 --fields emails,count,total,complete,reason,cursor
+checkpoint-axi email show synthetic-email-1 --fields email
+```
+
+Search flags: --saas (default profile SaaS or office365_emails), --saas-entity, and --filter (JSON array of {saasAttrName, saasAttrOp, saasAttrValue}).
+Event selectors include --event-types, --event-states, --severities, --event-ids (comma-separated), --confidence-indicator and --description; --saas accepts comma-separated SaaS values here.
+Event detail includes available actions; task detail reads status and per-action results once, without waiting or polling:
+
+```sh
+checkpoint-axi event list --all --event-types phishing --fields events,count,total,complete,reason,cursor
+checkpoint-axi event show synthetic-event-1 --fields event
+checkpoint-axi task show synthetic-task-1 --fields task
+```
+
+Inspect exception rules with exception list <kind> or exception show <kind> <id-or-value>:
+
+```sh
+checkpoint-axi exception list phishing-block --limit 5 --fields exceptions,count,total,complete,reason
+checkpoint-axi exception show phishing-block synthetic-exception-1 --fields exception
+```
+
+Kinds: phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url, dlp.
+For malware, --type is required: hash, micro_hash, file_type, ppat_sender_name, allow_file_type or sender_email.
+For url, --type is allow-url, allow-domain, block-url or block-domain; for dlp, hash, text_content, sender_email or recipient_email.
+Click-time --items selects item routes instead of list routes.
+Anomaly show is refused with ENDPOINT_UNVERIFIED; use anomaly list.
+Undocumented response shapes carry responseSchema: unverified; do not infer identities from them.
+
+## One-call forms and output bounds
+
+Email search and event list --all follow scroll pages in one invocation, capped at 1000 rows, 10 HTTP requests, 60 seconds and 8 MiB of JSON, including authentication and read retries.
+Both default to 50 rows over the past 24 hours; --limit accepts 1-1000 and cannot combine with --all.
+Use --start-date and --end-date with ISO timestamps including timezones; the positive window cannot exceed 31 days.
+Inspect complete, reason and cursor even on exit 0; limits and page replay can leave results incomplete.
+Resume with --cursor <returned-cursor> and the original selectors/profile; see [continuation limitations](reads.md#email-reads).
+Exception --all bounds returned rows at 1000 but cannot fetch additional pages: no continuation parameter is documented.
+Email/event detail already includes available actions, avoiding a separate action lookup.
+There is no bulk detail expansion, cross-resource pivot or task wait flag; use returned IDs for individual reads and never replay an action to obtain its status.
+
+--fields selects top-level output keys, not nested row columns: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+Email rows contain id,subject,state,verdict; event rows contain id,type,state,severity; documented exception rows contain id,sender,subject,comment.
+TOON strings preview at 500 characters; --full expands strings after redaction, while cursors are never truncated.
+
+## Help and safety
+
+Top-level --help returns the full command catalogue, common flags, version flags and home examples.
+Group --help (such as email --help) is unsupported and returns VALIDATION_ERROR with the valid command list; select a leaf command directly.
+Leaf command --help returns its description, accepted flags with defaults, and examples; positional arguments appear in those examples.
+Use the failing leaf's help to correct syntax; do not run a help sweep before investigating.
+
+Reviewed read allowlist: home (also no arguments), config path, profile list, auth status, doctor, email search, email show, event list, event show, task show, exception list, exception show (except unsupported anomaly detail).
+These commands never mutate remote state or save downloaded files; API authentication exchanges tokens held only in memory.
+Exclude email quarantine/restore, event action and every exception create/update/remove/remove-items/clear command, including previews and --specific creates, from an investigation read allowlist.
+Writes require exact profile operation scope, preview, --execute, exact --confirm and durable redacted intent; forced read-only always wins.
+Email download and attachment download/download-all write local files and require separate download opt-in; they are outside the read allowlist.
+See [write safety](writes.md) and [download safety](downloads.md) before requesting them.
+
+## Failure recovery
+
+Exit 0 means success, preview or no-op; 2 means invalid syntax (VALIDATION_ERROR); 1 means configuration, authentication, transport or operation failure.
+Structured errors and suggestions are on stdout; follow the code and suggestion instead of retrying blindly.
+
+| Code | Meaning and next action |
+|---|---|
+| VALIDATION_ERROR | Invalid flags, IDs, date window or mismatched cursor selectors; correct the failed command. |
+| PROFILE_REQUIRED / CONFIG_INVALID | Missing or invalid configuration; select a complete provisioned profile. |
+| CONFIG_INSECURE | Fix private-file permissions using the configuration guide. |
+| AUTH_FAILED | Check region and secret source; the CLI already attempts one token re-exchange after API rejection. |
+| AUTH_SHAPE_UNVERIFIED / ENDPOINT_UNVERIFIED | Contract is undocumented; request owner commissioning, never guess a route or token shape. |
+| NOT_FOUND | No matching detail record; verify the ID and profile using a list read. |
+| RESPONSE_INVALID / API_ERROR / HTTP_ERROR | Unexpected response or upstream failure; inspect the redacted error and verify service/profile before retrying. |
+| RATE_LIMITED | Two read retries exhausted; defer work instead of immediate repeated calls. |
+| REQUEST_BUDGET / TIME_BUDGET / RESPONSE_TOO_LARGE | Reduce date window or limit; inspect incomplete results and continuation before another bounded read. |
+| WRITES_DISABLED / DOWNLOADS_DISABLED | Operation is outside profile permissions; do not loosen permissions during investigation. |
+| OUTCOME_UNKNOWN | A mutation may have happened; reconcile with reads and the journal, never replay automatically. |