@knowttl/checkpoint-axi 0.0.0 → 0.1.1

package/dist/src/profiles.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import { type PrivateFileOptions } from "./private-file.js";
+import { SecretRedactor } from "./redact.js";
+export type CredentialContext = PrivateFileOptions & {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+};
+declare function schema(platform: NodeJS.Platform): z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    defaultProfile: z.ZodOptional<z.ZodString>;
+    profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        region: z.ZodEnum<{
+            us: "us";
+            eu: "eu";
+            ca: "ca";
+            au: "au";
+            uk: "uk";
+            uae: "uae";
+            in: "in";
+        }>;
+        clientId: z.ZodString;
+        clientSecret: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+            env: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            file: z.ZodString;
+        }, z.core.$strict>]>>;
+        saas: z.ZodDefault<z.ZodString>;
+        scope: z.ZodOptional<z.ZodString>;
+        downloads: z.ZodDefault<z.ZodObject<{
+            allow: z.ZodBoolean;
+        }, z.core.$strict>>;
+        writes: z.ZodDefault<z.ZodObject<{
+            allowWrites: z.ZodBoolean;
+            operations: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Profile = z.infer<ReturnType<typeof schema>>["profiles"][string];
+export type SelectedProfile = Profile & {
+    name: string;
+    source: "flag" | "env" | "env-profile" | "config-default" | "sole";
+};
+export declare function credentialStore(options?: CredentialContext, redactor?: SecretRedactor): {
+    configPath: (explicit?: string) => string;
+    statePath: () => string;
+    writeLogPath: () => string;
+    readOnly: () => boolean;
+    load: (explicit?: string, verifyAcl?: boolean) => {
+        path: string;
+        config: {
+            version: 1;
+            profiles: Record<string, {
+                region: "us" | "eu" | "ca" | "au" | "uk" | "uae" | "in";
+                clientId: string;
+                clientSecret: {
+                    env: string;
+                } | {
+                    file: string;
+                };
+                saas: string;
+                downloads: {
+                    allow: boolean;
+                };
+                writes: {
+                    allowWrites: boolean;
+                    operations: string[];
+                };
+                scope?: string | undefined;
+            }>;
+            defaultProfile?: string | undefined;
+        };
+    };
+    select: (config: ReturnType<(explicit?: string, verifyAcl?: boolean) => {
+        path: string;
+        config: {
+            version: 1;
+            profiles: Record<string, {
+                region: "us" | "eu" | "ca" | "au" | "uk" | "uae" | "in";
+                clientId: string;
+                clientSecret: {
+                    env: string;
+                } | {
+                    file: string;
+                };
+                saas: string;
+                downloads: {
+                    allow: boolean;
+                };
+                writes: {
+                    allowWrites: boolean;
+                    operations: string[];
+                };
+                scope?: string | undefined;
+            }>;
+            defaultProfile?: string | undefined;
+        };
+    }>["config"], flag?: string) => SelectedProfile;
+    credentials: (profile: SelectedProfile, verifyAcl?: boolean) => {
+        clientId: string;
+        clientSecret: string;
+    };
+    status: (explicit?: string, flag?: string) => {
+        profile: string;
+        source: "env" | "flag" | "env-profile" | "config-default" | "sole";
+        region: "us" | "eu" | "ca" | "au" | "uk" | "uae" | "in";
+        origin: "https://cloudinfra-gw-us.portal.checkpoint.com" | "https://cloudinfra-gw.portal.checkpoint.com" | "https://cloudinfra-gw.ca.portal.checkpoint.com" | "https://cloudinfra-gw.ap.portal.checkpoint.com" | "https://cloudinfra-gw.uk.portal.checkpoint.com" | "https://cloudinfra-gw.me.portal.checkpoint.com" | "https://cloudinfra-gw.in.portal.checkpoint.com";
+        saas: string;
+        clientSecret: string;
+        readOnly: boolean;
+    };
+    list: (explicit?: string) => {
+        profiles: {
+            name: string;
+            region: "us" | "eu" | "ca" | "au" | "uk" | "uae" | "in";
+            default: boolean;
+        }[];
+        count: number;
+        config: string;
+    };
+    redactor: SecretRedactor;
+};
+export {};

package/dist/src/profiles.js

@@ -0,0 +1,137 @@
+import { AxiError } from "axi-sdk-js";
+import { z } from "zod";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve, win32 } from "node:path";
+import { readPrivateFile, toolDirectory } from "./private-file.js";
+import { REGIONS } from "./regions.js";
+import { SecretRedactor } from "./redact.js";
+const profileName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/);
+const region = z.enum(Object.keys(REGIONS));
+const nonempty = z.string().trim().min(1);
+function schema(platform) {
+    const secretRef = z.union([
+        z.strictObject({ env: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/) }),
+        z.strictObject({ file: z.string().refine((path) => platform === "win32" ? /^[A-Za-z]:[\\/]/.test(path) : isAbsolute(path)) }),
+    ]);
+    const profile = z.strictObject({
+        region,
+        clientId: nonempty,
+        clientSecret: secretRef.default({ env: "CHECKPOINT_AXI_CLIENT_SECRET" }),
+        saas: nonempty.default("office365_emails"),
+        scope: nonempty.optional(),
+        downloads: z.strictObject({ allow: z.boolean() }).default({ allow: false }),
+        writes: z.strictObject({ allowWrites: z.boolean(), operations: z.array(z.string().regex(/^[a-z][A-Za-z0-9_.-]*$/)) })
+            .default({ allowWrites: false, operations: [] }),
+    });
+    return z.strictObject({ version: z.literal(1), defaultProfile: profileName.optional(), profiles: z.record(profileName, profile) })
+        .refine((config) => config.defaultProfile === undefined || Object.hasOwn(config.profiles, config.defaultProfile));
+}
+export function credentialStore(options = {}, redactor = new SecretRedactor()) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const home = options.home ?? homedir();
+    const invalid = (message) => {
+        throw new AxiError(message, "CONFIG_INVALID", [
+            "Use version: 1, named profiles, a supported region, clientId and a clientSecret env/file SecretRef; run checkpoint-axi auth status --help",
+        ]);
+    };
+    redactor.add(env.CHECKPOINT_AXI_CLIENT_SECRET);
+    function configPath(explicit) {
+        const selected = explicit ?? env.CHECKPOINT_AXI_CONFIG;
+        if (selected !== undefined && !selected.trim())
+            invalid("Config path must not be blank");
+        return selected !== undefined ? resolve(selected) : (platform === "win32" ? win32.join : join)(toolDirectory("config", env, platform, home), "config.json");
+    }
+    function readOnly() {
+        const value = env.CHECKPOINT_AXI_READ_ONLY?.toLowerCase();
+        if (value === undefined || value === "0" || value === "false")
+            return false;
+        if (value === "1" || value === "true")
+            return true;
+        return invalid("Read-only override must be 1, true, 0 or false");
+    }
+    function load(explicit, verifyAcl = false) {
+        const path = configPath(explicit);
+        let raw;
+        try {
+            raw = JSON.parse(readPrivateFile(path, false, verifyAcl, options));
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            if (explicit === undefined && env.CHECKPOINT_AXI_CONFIG === undefined && error.code === "ENOENT") {
+                return { path, config: { version: 1, profiles: {}, defaultProfile: undefined } };
+            }
+            return invalid("Cannot read profile configuration as JSON; check its path and syntax");
+        }
+        // Register malformed inline secrets too, before any validation result is rendered.
+        if (raw && typeof raw === "object" && "profiles" in raw && raw.profiles && typeof raw.profiles === "object") {
+            for (const profile of Object.values(raw.profiles)) {
+                if (!profile || typeof profile !== "object" || !("clientSecret" in profile))
+                    continue;
+                const ref = profile.clientSecret;
+                if (typeof ref === "string")
+                    redactor.add(ref);
+                if (ref && typeof ref === "object" && "env" in ref && typeof ref.env === "string")
+                    redactor.add(env[ref.env]);
+            }
+        }
+        const parsed = schema(platform).safeParse(raw);
+        if (!parsed.success)
+            return invalid("Invalid configuration: check profile names, region, defaultProfile, unknown fields and clientSecret SecretRef");
+        return { path, config: parsed.data };
+    }
+    function select(config, flag) {
+        const selected = flag ?? env.CHECKPOINT_AXI_PROFILE;
+        if (selected !== undefined && !profileName.safeParse(selected).success)
+            invalid("Invalid selected profile name");
+        const envFields = ["REGION", "CLIENT_ID", "SAAS", "SCOPE"];
+        if (selected === undefined && envFields.some((field) => env[`CHECKPOINT_AXI_${field}`] !== undefined)) {
+            if (!region.safeParse(env.CHECKPOINT_AXI_REGION).success || !env.CHECKPOINT_AXI_CLIENT_ID?.trim() || !env.CHECKPOINT_AXI_CLIENT_SECRET?.trim()
+                || (env.CHECKPOINT_AXI_SAAS !== undefined && !env.CHECKPOINT_AXI_SAAS.trim()) || (env.CHECKPOINT_AXI_SCOPE !== undefined && !env.CHECKPOINT_AXI_SCOPE.trim())) {
+                return invalid("Incomplete or invalid env profile; set REGION, CLIENT_ID and CLIENT_SECRET together");
+            }
+            return { region: env.CHECKPOINT_AXI_REGION, clientId: env.CHECKPOINT_AXI_CLIENT_ID.trim(),
+                clientSecret: { env: "CHECKPOINT_AXI_CLIENT_SECRET" }, saas: env.CHECKPOINT_AXI_SAAS?.trim() ?? "office365_emails", scope: env.CHECKPOINT_AXI_SCOPE?.trim(),
+                downloads: { allow: false }, writes: { allowWrites: false, operations: [] }, name: "env", source: "env-profile" };
+        }
+        const names = Object.keys(config.profiles);
+        const name = selected ?? config.defaultProfile ?? (names.length === 1 ? names[0] : undefined);
+        if (name === undefined)
+            throw new AxiError(names.length ? "Select one of the configured profiles" : "No profiles are configured", names.length ? "PROFILE_AMBIGUOUS" : "PROFILE_REQUIRED", ["Pass --profile <name> or configure defaultProfile; run checkpoint-axi config path"]);
+        if (!Object.hasOwn(config.profiles, name))
+            throw new AxiError("Selected profile is not configured", "PROFILE_NOT_FOUND", ["Run checkpoint-axi profile list"]);
+        return { ...config.profiles[name], name, source: flag !== undefined ? "flag" : env.CHECKPOINT_AXI_PROFILE !== undefined ? "env" : config.defaultProfile !== undefined ? "config-default" : "sole" };
+    }
+    function credentials(profile, verifyAcl = false) {
+        const ref = profile.clientSecret;
+        let value;
+        try {
+            value = "env" in ref ? env[ref.env] : readPrivateFile(ref.file, true, verifyAcl, options).replace(/^\uFEFF/, "").trimEnd();
+        }
+        catch (error) {
+            if (error instanceof AxiError)
+                throw error;
+            throw new AxiError("Cannot read clientSecret SecretRef file", "AUTH_REQUIRED", ["Check the SecretRef file exists and is readable"]);
+        }
+        redactor.add(value);
+        if (!value?.trim())
+            throw new AxiError("clientSecret is required", "AUTH_REQUIRED", ["Set the selected clientSecret SecretRef source; run checkpoint-axi auth status --help"]);
+        return { clientId: profile.clientId, clientSecret: value };
+    }
+    function status(explicit, flag) {
+        const forced = readOnly();
+        const loaded = load(explicit, true);
+        const profile = select(loaded.config, flag);
+        credentials(profile, true);
+        return { profile: profile.name, source: profile.source, region: profile.region, origin: REGIONS[profile.region], saas: profile.saas,
+            clientSecret: "env" in profile.clientSecret ? "env" : "file", readOnly: forced || !profile.writes.allowWrites || profile.writes.operations.length === 0 };
+    }
+    function list(explicit) {
+        readOnly();
+        const loaded = load(explicit);
+        return { profiles: Object.entries(loaded.config.profiles).map(([name, profile]) => ({ name, region: profile.region, default: name === loaded.config.defaultProfile })),
+            count: Object.keys(loaded.config.profiles).length, config: loaded.path };
+    }
+    return { configPath, statePath: () => toolDirectory("state", env, platform, home), writeLogPath: () => env.CHECKPOINT_AXI_WRITE_LOG?.trim() || join(toolDirectory("state", env, platform, home), "writes.log"), readOnly, load, select, credentials, status, list, redactor };
+}

package/dist/src/reads.d.ts

@@ -0,0 +1,3 @@
+import type { credentialStore } from "./profiles.js";
+import { gateway } from "./transport.js";
+export declare function readCommand(name: "email search" | "email show" | "event list" | "event show" | "task show", id: string | undefined, flags: Map<string, string>, store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/reads.js

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

package/dist/src/redact.d.ts

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

package/dist/src/redact.js

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

package/dist/src/regions.d.ts

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

package/dist/src/regions.js

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

package/dist/src/transport.d.ts

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