/** * CLI Execution Observation Extension Schema * * Extension namespace: `org.peacprotocol/cli-execution` * Record type URI: `org.peacprotocol/cli-command-execution` * * Records observational evidence of a local command execution wrapped by * the `peac observe-command` / `peac record-command` subcommands. The * wrapper is an observer, not a sandbox / permission system / process * supervisor / job scheduler / shell orchestrator. Field-level variants * (exit_code, signal, timed_out, shell_mode, capture_policy, * termination_signal, exit_code_mode) live as fields on this single * record type, not as separate record types. * * Security defaults (hard): * - argv hashed by default (sha256 only) * - stdout/stderr default to length + sha256 + truncated only; * `sample_base64` is emitted only when raw capture is double-opted-in * - stdin defaults to none; raw stdin capture is not a supported mode * - env capture deny-by-default; values hashed unless raw env is double-opted-in * - cwd hashed-by-default; binary path hashed-by-default * - secret-scan ON by default; disabling under raw capture requires the * third unsafe flag (`--unsafe-disable-secret-scan`) * - shell-binary detected without `--shell-mode` is a hard fail * * Schema consistency invariants: * - command.program records the user-supplied basename only; absolute * paths are governed exclusively by --capture-binary-path and * surface only under binary.path_*. * - All byte-limited string fields use UTF-8 byte-length refinements, * not character counts. * - Env mode is discriminated; entries are required to be a subset of * capture_policy.env_allowlist. * - StreamRef enforces sample_base64 / sample_suppressed_reason mutual * exclusion; matched_pattern_category requires * sample_suppressed_reason and vice-versa; sample_base64 requires * capture_policy.raw_capture_unsafely_allowed; sample_base64 must * be valid base64 and decoded length must not exceed the matching * stream cap. * - Cross-field unsafe consistency: argv_mode=raw requires the raw * capture flag; env.mode=raw requires the raw env flag; * secret_scan=false under raw capture requires * secret_scan_disabled_unsafely. * - approval_ref uses the canonical opaque-ref grammar; binary.shell_ref * uses the canonical sha256 digest schema; shell_mode is biconditional * with the presence of binary.shell_ref. * * Validation returns the structured error contract: * `{ ok: true, value }` or `{ ok: false, errors: [{ code, path?, message }] }`. */ import { z } from 'zod'; export declare const CLI_EXECUTION_EXTENSION_KEY: "org.peacprotocol/cli-execution"; export declare const CLI_COMMAND_EXECUTION_TYPE: "org.peacprotocol/cli-command-execution"; /** Stable error codes for `validateCliExecution`. */ export declare const CLI_EXECUTION_ERROR_CODES: { readonly shellModeRequired: "cli.shell_mode_required"; readonly captureModeInvalid: "cli.capture_mode_invalid"; readonly cwdModeInvalid: "cli.cwd_mode_invalid"; readonly binaryPathModeInvalid: "cli.binary_path_mode_invalid"; readonly envNotInAllowlist: "cli.env_not_in_allowlist"; readonly envModeInconsistent: "cli.env_mode_inconsistent"; readonly unsafeFlagRequired: "cli.unsafe_flag_required"; readonly secretScanDisableRequiresUnsafeFlag: "cli.secret_scan_disable_requires_unsafe_flag"; readonly timeoutMsOutOfRange: "cli.timeout_ms_out_of_range"; readonly killGraceMsOutOfRange: "cli.kill_grace_ms_out_of_range"; readonly exitCodeModeInvalid: "cli.exit_code_mode_invalid"; readonly argvTokenTooLong: "cli.argv_token_too_long"; readonly streamRefInconsistent: "cli.stream_ref_inconsistent"; readonly schemaRejection: "cli.schema_rejection"; readonly unknownField: "cli.unknown_field"; }; /** * Numeric ranges (mirrored as constants from `packages/cli/src/lib/cli-limits.ts`; * a parity test enforces the two sides stay in sync). */ export declare const CLI_SCHEMA_LIMITS: { readonly TIMEOUT_MS_MIN: 1; readonly TIMEOUT_MS_MAX: 86400000; readonly KILL_GRACE_MS_MIN: 0; readonly KILL_GRACE_MS_MAX: 60000; readonly ARGV_BYTES_MIN: 0; readonly ARGV_BYTES_MAX: 16384; readonly STDOUT_BYTES_MAX: 65536; readonly STDERR_BYTES_MAX: 65536; readonly ENV_ENTRIES_MAX: 32; readonly PROGRAM_TOKEN_BYTES_MAX: 256; readonly CWD_BASENAME_BYTES_MAX: 128; readonly CWD_ABSOLUTE_BYTES_MAX: 1024; readonly BINARY_PATH_ABSOLUTE_BYTES_MAX: 1024; readonly BINARY_VERSION_BYTES_MAX: 64; readonly ENV_KEY_BYTES_MAX: 256; readonly ENV_VALUE_BYTES_MAX: 8192; readonly SIGNAL_NAME_BYTES_MAX: 32; readonly PLATFORM_FIELD_BYTES_MAX: 64; readonly APPROVAL_REF_BYTES_MAX: 256; }; /** * The full CLI execution observation record. * * Top-level superRefine enforces the cross-field invariants: * - sample_base64 on stdout/stderr requires * capture_policy.raw_capture_unsafely_allowed = true * - decoded sample length must not exceed the matching stream cap * - command.argv_mode = raw requires * capture_policy.raw_capture_unsafely_allowed = true * - env.mode = raw requires * capture_policy.raw_env_unsafely_allowed = true * - capture_policy.secret_scan = false combined with * capture_policy.raw_capture_unsafely_allowed = true requires * capture_policy.secret_scan_disabled_unsafely = true * - env.entries keys must be a subset of * capture_policy.env_allowlist * - shell_mode = true requires binary.shell_ref present and * binary.path_mode != 'none'; shell_mode = false requires * binary.shell_ref absent. Under binary.path_mode = 'hashed', * binary.shell_ref must equal binary.path_sha256 so the shell * reference is a single canonical digest with a well-defined input. */ export declare const CliExecutionSchema: z.ZodObject<{ type: z.ZodLiteral<"org.peacprotocol/cli-command-execution">; surface: z.ZodObject<{ kind: z.ZodLiteral<"cli">; }, z.core.$strict>; command: z.ZodDiscriminatedUnion<[z.ZodObject<{ program: z.ZodString; argv_mode: z.ZodLiteral<"hashed">; argv_sha256: z.ZodString; argv_token_count: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ program: z.ZodString; argv_mode: z.ZodLiteral<"redacted">; argv: z.ZodArray; argv_token_count: z.ZodOptional; }, z.core.$strict>, z.ZodObject<{ program: z.ZodString; argv_mode: z.ZodLiteral<"raw">; argv: z.ZodArray; argv_token_count: z.ZodOptional; }, z.core.$strict>], "argv_mode">; cwd: z.ZodDiscriminatedUnion<[z.ZodObject<{ cwd_mode: z.ZodLiteral<"none">; }, z.core.$strict>, z.ZodObject<{ cwd_mode: z.ZodLiteral<"hashed">; cwd_sha256: z.ZodString; }, z.core.$strict>, z.ZodObject<{ cwd_mode: z.ZodLiteral<"basename">; cwd_basename: z.ZodString; }, z.core.$strict>, z.ZodObject<{ cwd_mode: z.ZodLiteral<"absolute">; cwd_absolute: z.ZodString; }, z.core.$strict>], "cwd_mode">; binary: z.ZodIntersection; }, z.core.$strict>, z.ZodObject<{ path_mode: z.ZodLiteral<"hashed">; path_sha256: z.ZodString; }, z.core.$strict>, z.ZodObject<{ path_mode: z.ZodLiteral<"absolute">; path_absolute: z.ZodString; }, z.core.$strict>], "path_mode">, z.ZodObject<{ size_bytes: z.ZodOptional; mode_octal: z.ZodOptional; sha256: z.ZodOptional; version: z.ZodOptional; shell_ref: z.ZodOptional; }, z.core.$strict>>; stdin_ref: z.ZodDiscriminatedUnion<[z.ZodObject<{ mode: z.ZodLiteral<"none">; }, z.core.$strict>, z.ZodObject<{ mode: z.ZodLiteral<"length-only">; length: z.ZodNumber; truncated: z.ZodBoolean; }, z.core.$strict>, z.ZodObject<{ mode: z.ZodLiteral<"hashed">; length: z.ZodNumber; sha256: z.ZodString; truncated: z.ZodBoolean; }, z.core.$strict>], "mode">; stdout_ref: z.ZodObject<{ length: z.ZodNumber; sha256: z.ZodString; truncated: z.ZodBoolean; sample_base64: z.ZodOptional; sample_suppressed_reason: z.ZodOptional>; matched_pattern_category: z.ZodOptional>; }, z.core.$strict>; stderr_ref: z.ZodObject<{ length: z.ZodNumber; sha256: z.ZodString; truncated: z.ZodBoolean; sample_base64: z.ZodOptional; sample_suppressed_reason: z.ZodOptional>; matched_pattern_category: z.ZodOptional>; }, z.core.$strict>; env: z.ZodObject<{ mode: z.ZodEnum<{ hashed: "hashed"; raw: "raw"; }>; entries: z.ZodRecord; value: z.ZodOptional; }, z.core.$strict>>; }, z.core.$strict>; started_at: z.ZodString; finished_at: z.ZodString; duration_ms: z.ZodNumber; exit_code: z.ZodNumber; signal: z.ZodOptional; timed_out: z.ZodBoolean; timeout_ms: z.ZodNumber; kill_grace_ms: z.ZodNumber; termination_signal: z.ZodOptional; exit_code_mode: z.ZodEnum<{ record: "record"; child: "child"; }>; shell_mode: z.ZodBoolean; execution_mode: z.ZodEnum<{ deterministic_script: "deterministic_script"; templated_flow: "templated_flow"; agent_loop: "agent_loop"; human_step: "human_step"; hybrid: "hybrid"; }>; capture_policy: z.ZodObject<{ stdout_max_bytes: z.ZodNumber; stderr_max_bytes: z.ZodNumber; argv_max_bytes: z.ZodNumber; env_allowlist: z.ZodArray; stdin_mode: z.ZodEnum<{ none: "none"; hashed: "hashed"; "length-only": "length-only"; }>; cwd_mode: z.ZodEnum<{ none: "none"; hashed: "hashed"; basename: "basename"; absolute: "absolute"; }>; binary_path_mode: z.ZodEnum<{ none: "none"; hashed: "hashed"; absolute: "absolute"; }>; secret_scan: z.ZodBoolean; raw_capture_unsafely_allowed: z.ZodBoolean; raw_env_unsafely_allowed: z.ZodBoolean; secret_scan_disabled_unsafely: z.ZodBoolean; timeout_ms: z.ZodNumber; kill_grace_ms: z.ZodNumber; exit_code_mode: z.ZodEnum<{ record: "record"; child: "child"; }>; }, z.core.$strict>; platform: z.ZodObject<{ os: z.ZodString; arch: z.ZodString; peac_cli_version: z.ZodString; }, z.core.$strict>; policy_digest: z.ZodOptional; config_digest: z.ZodOptional; approval_ref: z.ZodOptional; }, z.core.$strict>; export type CliExecutionObservation = z.infer; export interface CliValidationError { code: string; path?: string; message: string; } export type CliValidationResult = { ok: true; value: CliExecutionObservation; } | { ok: false; errors: CliValidationError[]; }; /** * Validate a CLI execution observation payload. * * Returns a structured result with stable error codes for downstream * conformance vector assertions. Mirrors the `validateA2AHandoff` shape. */ export declare function validateCliExecution(data: unknown): CliValidationResult; //# sourceMappingURL=cli-execution.d.ts.map