@knowttl/checkpoint-axi 0.0.0-stage → 0.1.0

package/dist/src/exceptions.js

@@ -0,0 +1,81 @@
+import { AxiError } from "axi-sdk-js";
+import { z } from "zod";
+import { gateway, READ_LIMITS } from "./transport.js";
+// Read routes and selectors: guide pages 49-60, 69-74, 83, 87-91, 100-102, 110-112 and 120-123.
+export const exceptionFamilies = {
+    "phishing-allow": { path: "/exceptions/whitelist", types: [] },
+    "phishing-block": { path: "/exceptions/blacklist", types: [] },
+    "spam-allow": { path: "/exceptions/spam_whitelist", types: [] },
+    anomaly: { path: "/sectools/anomaly/exceptions", types: [] },
+    "click-time": { path: "/sectools/click_time_protection/exceptions", types: [] },
+    malware: { path: "/sectool-exceptions/checkpoint2/exceptions", types: ["hash", "micro_hash", "file_type", "ppat_sender_name", "allow_file_type", "sender_email"] },
+    url: { path: "/sectool-exceptions/avanan_url/exceptions", types: ["allow-url", "allow-domain", "block-url", "block-domain"] },
+    dlp: { path: "/sectool-exceptions/avanan_dlp/exceptions", types: ["hash", "text_content", "sender_email", "recipient_email"] },
+};
+// Only these families have published response fields (pages 50, 56-60 and 70-74).
+const exception = z.object({ entityId: z.string().min(1), senderEmail: z.string().nullish(),
+    subject: z.string().nullish(), comment: z.string().nullish() }).passthrough();
+export async function exceptionCommand(name, kind, value, flags, store, transport) {
+    const invalid = (message) => { throw new AxiError(message, "VALIDATION_ERROR", [`Run checkpoint-axi ${name} --help`]); };
+    if (!kind || !Object.hasOwn(exceptionFamilies, kind))
+        invalid(`Choose an exception kind: ${Object.keys(exceptionFamilies).join(", ")}`);
+    const family = exceptionFamilies[kind];
+    const show = name === "exception show";
+    const documented = family.path.startsWith("/exceptions/");
+    const type = flags.get("--type");
+    if (family.types.length ? !type || !family.types.includes(type) : type !== undefined) {
+        invalid(family.types.length ? `--type must be one of: ${family.types.join(", ")}` : "--type is only valid for malware, url and dlp");
+    }
+    if (flags.has("--items") && kind !== "click-time")
+        invalid("--items is only valid for click-time");
+    if (show && (!value?.trim() || /[\u0000-\u001f\u007f]/.test(value) || value === "." || value === ".."))
+        invalid("show requires one nonempty exception ID or value");
+    if (show && documented && !/^[A-Za-z0-9_-]+$/.test(value))
+        invalid("Exception ID must contain 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");
+    if (show && kind === "anomaly")
+        throw new AxiError("Anomaly detail endpoint and response identity are undocumented (guide pages 83-84)", "ENDPOINT_UNVERIFIED", ["Use checkpoint-axi exception list anomaly; owner commissioning happens later through Artium"]);
+    let path = family.path;
+    if (type)
+        path += `/${type}`;
+    if (flags.has("--items"))
+        path += "/items";
+    if (show) {
+        try {
+            path += `/${encodeURIComponent(value)}`;
+        }
+        catch {
+            invalid("Exception value must be valid Unicode");
+        }
+    }
+    store.readOnly();
+    const profile = store.select(store.load(flags.get("--config"), true).config, flags.get("--profile"));
+    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
+    const page = await api.read({ path: path });
+    if (documented && !z.array(exception).safeParse(page.records).success)
+        throw new AxiError("Invalid exception response", "RESPONSE_INVALID", []);
+    const unverified = documented ? {} : { responseSchema: "unverified" };
+    if (show) {
+        if (!page.records.length)
+            throw new AxiError("Exception was not found", "NOT_FOUND", []);
+        if (documented && (page.records.length !== 1 || exception.parse(page.records[0]).entityId !== value)) {
+            throw new AxiError("Invalid exception detail response", "RESPONSE_INVALID", []);
+        }
+        return { exception: documented ? page.records[0] : page.records, ...unverified };
+    }
+    const limit = flags.has("--all") ? READ_LIMITS.rows : Number(limitText);
+    const rows = page.records.slice(0, limit);
+    const complete = rows.length === page.records.length && !page.scrollId && (page.total === undefined || page.total <= rows.length);
+    return { exceptions: documented ? rows.map((row) => {
+            const record = exception.parse(row);
+            return { id: record.entityId, sender: record.senderEmail ?? "", subject: record.subject ?? "", comment: record.comment ?? "" };
+        }) : rows, count: rows.length, ...(page.total === undefined ? {} : { total: page.total }), complete, ...unverified,
+        ...(!complete ? { reason: "No continuation request parameter is documented for this exception route" } : {}),
+        help: [rows.length ? kind === "anomaly" ? "Anomaly detail remains unavailable pending response identity commissioning"
+                : `Run checkpoint-axi exception show ${kind} <id-or-value>${type ? ` --type ${type}` : ""}${flags.has("--items") ? " --items" : ""} for details`
+                : `No ${kind} exceptions found`, ...(!complete && limit < READ_LIMITS.rows ? ["Repeat with --all for up to 1000 rows; server-side continuation remains undocumented"] : [])] };
+}

package/dist/src/local-commands.d.ts

@@ -0,0 +1,3 @@
+import { credentialStore } from "./profiles.js";
+import type { gateway } from "./transport.js";
+export declare function localCommand(argv: string[], store: ReturnType<typeof credentialStore>, transport?: Parameters<typeof gateway>[3]): Promise<Record<string, unknown>>;

package/dist/src/local-commands.js

@@ -0,0 +1,123 @@
+import { AxiError } from "axi-sdk-js";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { catalogue, DESCRIPTION, help, SETUP_GUIDANCE } from "./catalogue.js";
+import { doctor } from "./doctor.js";
+import { readCommand } from "./reads.js";
+import { exceptionCommand } from "./exceptions.js";
+import { emailWriteCommand, eventWriteCommand } from "./writes.js";
+import { exceptionWriteCommand } from "./write-exceptions.js";
+import { downloadCommand } from "./downloads.js";
+export async function localCommand(argv, store, transport) {
+    if (argv.length === 1 && argv[0] === "--help")
+        return help();
+    const name = !argv.length || argv[0]?.startsWith("--") ? "home" : argv[0] === "home" || argv[0] === "doctor" ? argv[0] : argv.slice(0, 2).join(" ");
+    const entry = Object.hasOwn(catalogue, name) ? catalogue[name] : undefined;
+    const usage = (message = "Unknown command, argument, duplicate or invalid flag") => {
+        throw new AxiError(message, "VALIDATION_ERROR", [
+            `Valid commands: ${Object.keys(catalogue).join(", ")}; valid flags: ${entry ? Object.keys(entry.flags).map((flag) => `--${flag}`).join(", ") : "run checkpoint-axi --help"}`,
+        ]);
+    };
+    if (!entry)
+        return usage();
+    const flags = new Map();
+    const isExceptionWrite = name === "exception create" || name === "exception update" || name === "exception remove" || name === "exception remove-items" || name === "exception clear";
+    const isException = name === "exception list" || name === "exception show" || isExceptionWrite;
+    const isDownload = name === "email download" || name === "attachment download" || name === "attachment download-all";
+    const kind = isException && !argv[2]?.startsWith("--") ? argv[2] : undefined;
+    const idIndex = isException ? 3 : 2;
+    const entityId = (isDownload || name.endsWith(" show") || name === "exception update" || name === "exception remove") && !argv[idIndex]?.startsWith("--") ? argv[idIndex] : undefined;
+    const attachmentId = name === "attachment download" && entityId !== undefined && !argv[3]?.startsWith("--") ? argv[3] : undefined;
+    const start = name === "home" ? (argv[0] === "home" ? 1 : 0) : name === "doctor" ? 1
+        : isException ? 2 + Number(kind !== undefined) + Number(entityId !== undefined) : entityId === undefined ? 2 : 3 + Number(attachmentId !== undefined);
+    for (let index = start; index < argv.length; index++) {
+        const flag = argv[index];
+        if (!flag.startsWith("--"))
+            usage();
+        if (!Object.hasOwn(entry.flags, flag.slice(2)) || flags.has(flag)) {
+            const label = flag.split("=")[0];
+            usage(/^--[A-Za-z][A-Za-z0-9-]*$/.test(label) ? `Unknown or duplicate flag ${label}` : undefined);
+        }
+        if (["--help", "--full", "--all", "--items", "--specific", "--original", "--execute", "--dry-run"].includes(flag))
+            flags.set(flag, "true");
+        else {
+            const value = argv[++index];
+            if (!value || value.startsWith("--"))
+                usage();
+            flags.set(flag, value);
+        }
+    }
+    if (flags.has("--help"))
+        return { command: name, ...entry };
+    const available = isException ? name === "exception list" ? ["exceptions", "count", "total", "complete", "reason", "responseSchema", "help"] : ["exception", "responseSchema"]
+        : name === "email search" || name === "event list" ? [name === "event list" ? "events" : "emails", "count", "total", "complete", "reason", "cursor", "help"] : name.endsWith(" show") ? [name.split(" ")[0]]
+            : name === "doctor" ? ["region", "saas", "checks", "pass", "help"] : name === "auth status" ? ["profile", "source", "region", "origin", "saas", "clientSecret", "readOnly"]
+                : name === "profile list" ? ["profiles", "count", "config"] : name === "config path" ? ["config", "state"]
+                    : ["bin", "description", "status", "profiles", "count", "help"];
+    const isWrite = name === "email quarantine" || name === "email restore" || name === "event action" || isExceptionWrite;
+    if (isWrite)
+        available.splice(0, available.length, "outcome", "preview", "auditId", "tasks", "response", "responseSchema", "help");
+    if (isDownload)
+        available.splice(0, available.length, "path", "size", "sha256");
+    const fields = flags.get("--fields")?.split(",") ?? available;
+    if (fields.some((field) => !available.includes(field)) || new Set(fields).size !== fields.length)
+        usage();
+    const config = flags.get("--config");
+    let result;
+    if (isDownload)
+        result = await downloadCommand(name, entityId, attachmentId, flags, store, transport);
+    else if (name === "exception create" || name === "exception update" || name === "exception remove" || name === "exception remove-items" || name === "exception clear")
+        result = await exceptionWriteCommand(name, kind, entityId, flags, store, transport);
+    else if (name === "event action")
+        result = await eventWriteCommand(flags, store, transport);
+    else if (name === "email quarantine" || name === "email restore")
+        result = await emailWriteCommand(name, flags, store, transport);
+    else if (name === "exception list" || name === "exception show")
+        result = await exceptionCommand(name, kind, entityId, flags, store, transport);
+    else if (name === "email search" || name === "email show" || name === "event list" || name === "event show" || name === "task show")
+        result = await readCommand(name, entityId, flags, store, transport);
+    else if (name === "doctor")
+        result = await doctor(store, config, flags.get("--profile"), flags.get("--saas"), transport);
+    else if (name === "auth status")
+        result = store.status(config, flags.get("--profile"));
+    else if (name === "profile list")
+        result = store.list(config);
+    else if (name === "config path")
+        result = { config: store.configPath(config), state: store.statePath() };
+    else {
+        const listed = store.list(config);
+        // Selection errors matter when context exists, but a new installation has a useful empty home.
+        const loaded = store.load(config);
+        let status = "not configured";
+        try {
+            const selected = store.select(loaded.config, flags.get("--profile"));
+            status = `configured: ${selected.name} (${selected.region}); not verified with the API`;
+        }
+        catch (error) {
+            if (!(error instanceof AxiError) || error.code !== "PROFILE_REQUIRED")
+                throw error;
+        }
+        const executable = resolve(process.argv[1] ?? "bin/checkpoint-axi.js");
+        const home = homedir();
+        result = { bin: executable.startsWith(`${home}/`) ? `~${executable.slice(home.length)}` : executable,
+            description: DESCRIPTION, status, profiles: listed.profiles, count: listed.count,
+            help: [SETUP_GUIDANCE, "Run checkpoint-axi auth status to validate local credentials", "Run checkpoint-axi profile list to inspect configured profiles"] };
+    }
+    let truncated = false;
+    const preview = (value) => {
+        if (typeof value === "string" && value.length > 500 && !flags.has("--full")) {
+            truncated = true;
+            return `${value.slice(0, 500)}... (truncated, ${value.length} chars total)`;
+        }
+        if (Array.isArray(value))
+            return value.map(preview);
+        if (value && typeof value === "object")
+            return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, preview(child)]));
+        return value;
+    };
+    const projected = Object.fromEntries(fields.filter((field) => result[field] !== undefined).map((field) => [field,
+        field === "cursor" || isDownload ? store.redactor.value(result[field]) : preview(store.redactor.value(result[field]))]));
+    if (truncated && !isWrite)
+        projected.help = [...(Array.isArray(projected.help) ? projected.help : []), "Repeat the command with --full to see complete strings"];
+    return projected;
+}

package/dist/src/private-file.d.ts

@@ -0,0 +1,10 @@
+export type WindowsAcl = (path: string, verify: boolean) => void;
+export declare const windowsAcl: WindowsAcl;
+export declare function protectWindowsFile(path: string): void;
+export declare function toolDirectory(kind: "config" | "state", env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+export type PrivateFileOptions = {
+    platform?: NodeJS.Platform;
+    acl?: WindowsAcl;
+    uid?: number;
+};
+export declare function readPrivateFile(path: string, secret: boolean, verifyAcl: boolean, options?: PrivateFileOptions): string;

package/dist/src/private-file.js

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, join, win32 } from "node:path";
+import { AxiError } from "axi-sdk-js";
+export const windowsAcl = (path, verify) => {
+    const quoted = `'${path.replaceAll("'", "''")}'`;
+    const script = `$ErrorActionPreference='Stop'; $p=${quoted}; $item=Get-Item -LiteralPath $p -Force; `
+        + `if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Reparse point' }; `
+        + (verify ? `$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User; $allowed=@($sid.Value,'S-1-5-18','S-1-5-32-544'); `
+            + `$acl=Get-Acl -LiteralPath $p; if (!$acl.AreAccessRulesProtected -or ($acl.Owner -ne $sid.Translate([Security.Principal.NTAccount]).Value -and $acl.Owner -ne $sid.Value)) { throw 'Unprotected ACL' }; `
+            + `$seen=@(); foreach ($r in $acl.Access) { $s=$r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value; if ($s -notin $allowed -or $r.IsInherited -or $r.AccessControlType -ne 'Allow' -or $r.FileSystemRights -ne [Security.AccessControl.FileSystemRights]::FullControl) { throw 'Unexpected ACL' }; $seen+=$s }; foreach ($s in $allowed) { if ($s -notin $seen) { throw 'Missing ACL' } }` : "");
+    execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { stdio: "pipe" });
+};
+export function protectWindowsFile(path) {
+    const quoted = `'${path.replaceAll("'", "''")}'`;
+    const script = `$ErrorActionPreference='Stop'; $p=${quoted}; $item=Get-Item -LiteralPath $p -Force; `
+        + `if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Reparse point' }; `
+        + `$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User; $acl=Get-Acl -LiteralPath $p; `
+        + `$acl.SetAccessRuleProtection($true,$false); foreach ($r in @($acl.Access)) { [void]$acl.RemoveAccessRuleSpecific($r) }; $acl.SetOwner($sid); `
+        + `foreach ($s in @($sid.Value,'S-1-5-18','S-1-5-32-544')) { $id=New-Object Security.Principal.SecurityIdentifier($s); `
+        + `$rule=New-Object Security.AccessControl.FileSystemAccessRule($id,'FullControl','Allow'); $acl.AddAccessRule($rule) }; Set-Acl -LiteralPath $p -AclObject $acl`;
+    execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], { stdio: "pipe" });
+    windowsAcl(path, true);
+}
+export function toolDirectory(kind, env = process.env, platform = process.platform, home = homedir()) {
+    if (platform === "win32") {
+        const base = env[kind === "config" ? "APPDATA" : "LOCALAPPDATA"];
+        return win32.join(base && win32.isAbsolute(base) ? base : win32.join(home, "AppData", kind === "config" ? "Roaming" : "Local"), "checkpoint-axi");
+    }
+    const xdg = env[kind === "config" ? "XDG_CONFIG_HOME" : "XDG_STATE_HOME"];
+    return join(xdg && isAbsolute(xdg) ? xdg : join(home, kind === "config" ? ".config" : ".local/state"), "checkpoint-axi");
+}
+export function readPrivateFile(path, secret, verifyAcl, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const insecure = () => {
+        throw new AxiError("Insecure private file", "CONFIG_INSECURE", [
+            platform === "win32" ? "Apply a protected DACL granting FullControl only to the current user, SYSTEM and Administrators"
+                : "Ensure the file is regular, owned by the current user and has mode 600",
+        ]);
+    };
+    function validate(stat) {
+        if (!stat.isFile() || stat.isSymbolicLink())
+            insecure();
+        if (platform !== "win32" && (stat.uid !== (options.uid ?? process.getuid()) || (stat.mode & (secret ? 0o077 : 0o022)) !== 0))
+            insecure();
+    }
+    validate(lstatSync(path));
+    if (platform === "win32") {
+        try {
+            (options.acl ?? windowsAcl)(path, verifyAcl);
+        }
+        catch {
+            insecure();
+        }
+    }
+    const fd = openSync(path, constants.O_RDONLY | (platform === "win32" ? 0 : constants.O_NOFOLLOW));
+    try {
+        validate(fstatSync(fd));
+        return readFileSync(fd, "utf8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}

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