@predicatesystems/authority 0.3.1 → 0.3.3

package/dist/canonicalization/desktop.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Desktop accessibility tree canonicalization for reproducible state hashes.
+ *
+ * This module provides canonical normalization for desktop accessibility snapshots,
+ * ensuring that equivalent UI states produce identical hashes regardless of
+ * superficial differences (whitespace, element order, transient attributes).
+ */
+import { type Platform } from "./utils.js";
+/**
+ * Raw accessibility tree node from the runtime environment.
+ */
+export interface AccessibilityNode {
+    role?: string;
+    name?: string;
+    children?: AccessibilityNode[];
+    pid?: number;
+    position?: {
+        x: number;
+        y: number;
+    };
+    focused?: boolean;
+    selected?: boolean;
+}
+/**
+ * Raw desktop accessibility snapshot from the runtime environment.
+ */
+export interface DesktopAccessibilitySnapshot {
+    app_name?: string;
+    window_title?: string;
+    focused_role?: string;
+    focused_name?: string;
+    ui_tree?: AccessibilityNode;
+    ui_tree_text?: string;
+    platform?: Platform;
+    observed_at?: string;
+    confidence?: number;
+}
+/**
+ * Canonical accessibility node with normalized fields.
+ */
+export interface CanonicalAccessibilityNode {
+    role: string;
+    name_norm: string;
+    children: CanonicalAccessibilityNode[];
+}
+/**
+ * Canonical desktop snapshot with normalized fields.
+ *
+ * This is the deterministic representation used for hashing.
+ */
+export interface CanonicalDesktopSnapshot {
+    app_name_norm: string;
+    window_title_norm: string;
+    focused_path: string;
+    tree_hash: string;
+    platform: Platform;
+}
+/**
+ * Canonicalize an accessibility tree node.
+ *
+ * Normalizes:
+ * - `role`: Lowercase, trimmed
+ * - `name`: Text normalization (whitespace, case, length)
+ * - `children`: Recursively canonicalized, sorted by (role, name)
+ *
+ * Ignores transient attributes: pid, position, focused, selected.
+ *
+ * @param node - Raw accessibility node
+ * @param depth - Current depth (for truncation)
+ * @returns Canonical node
+ */
+export declare function canonicalizeAccessibilityNode(node: AccessibilityNode | null | undefined, depth?: number): CanonicalAccessibilityNode;
+/**
+ * Build a focused element path string.
+ *
+ * Creates a path like "window/toolbar/button[Save]" representing
+ * the path to the focused element in the accessibility tree.
+ *
+ * @param focusedRole - Role of the focused element
+ * @param focusedName - Name of the focused element
+ * @returns Path string
+ */
+export declare function buildFocusedPath(focusedRole?: string, focusedName?: string): string;
+/**
+ * Canonicalize a desktop accessibility snapshot.
+ *
+ * Normalizes all fields to produce a deterministic representation:
+ * - `app_name`: Lowercase, trimmed
+ * - `window_title`: Text normalization (capped at 100 chars)
+ * - `focused_path`: Built from focused element info
+ * - `tree_hash`: SHA-256 of canonical tree JSON
+ *
+ * @param snapshot - Raw desktop accessibility snapshot
+ * @returns Canonical snapshot for hashing
+ */
+export declare function canonicalizeDesktopSnapshot(snapshot: DesktopAccessibilitySnapshot): CanonicalDesktopSnapshot;
+/**
+ * Compute state hash for a desktop accessibility snapshot.
+ *
+ * The hash includes all canonical fields in a deterministic order.
+ * Platform is included because different platforms have different
+ * accessibility APIs and security contexts.
+ *
+ * @param snapshot - Raw or canonical desktop snapshot
+ * @returns SHA-256 hash prefixed with "sha256:"
+ */
+export declare function computeDesktopStateHash(snapshot: DesktopAccessibilitySnapshot | CanonicalDesktopSnapshot): string;
+/**
+ * Current schema version for desktop canonicalization.
+ *
+ * Increment major version for breaking changes to canonical format.
+ * Increment minor version for additions that don't change existing hashes.
+ */
+export declare const DESKTOP_SCHEMA_VERSION = "desktop:v1.0";
+//# sourceMappingURL=desktop.d.ts.map

package/dist/canonicalization/desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.d.ts","sourceRoot":"","sources":["../../src/canonicalization/desktop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAMlE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAE/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,0BAA0B,EAAE,CAAC;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAmBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,EAC1C,KAAK,SAAI,GACR,0BAA0B,CAyC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,CAAC,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAaR;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,4BAA4B,GACrC,wBAAwB,CAsB1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,4BAA4B,GAAG,wBAAwB,GAChE,MAAM,CAgBR;AAoCD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,iBAAiB,CAAC"}

package/dist/canonicalization/desktop.js

@@ -0,0 +1,187 @@
+/**
+ * Desktop accessibility tree canonicalization for reproducible state hashes.
+ *
+ * This module provides canonical normalization for desktop accessibility snapshots,
+ * ensuring that equivalent UI states produce identical hashes regardless of
+ * superficial differences (whitespace, element order, transient attributes).
+ */
+import { normalizeText, sha256 } from "./utils.js";
+// =============================================================================
+// Constants
+// =============================================================================
+/** Maximum depth for UI tree canonicalization */
+const MAX_TREE_DEPTH = 10;
+/** Maximum children per node */
+const MAX_CHILDREN_PER_NODE = 50;
+/** Maximum length for window title */
+const MAX_WINDOW_TITLE_LENGTH = 100;
+// =============================================================================
+// Accessibility Node Canonicalization
+// =============================================================================
+/**
+ * Canonicalize an accessibility tree node.
+ *
+ * Normalizes:
+ * - `role`: Lowercase, trimmed
+ * - `name`: Text normalization (whitespace, case, length)
+ * - `children`: Recursively canonicalized, sorted by (role, name)
+ *
+ * Ignores transient attributes: pid, position, focused, selected.
+ *
+ * @param node - Raw accessibility node
+ * @param depth - Current depth (for truncation)
+ * @returns Canonical node
+ */
+export function canonicalizeAccessibilityNode(node, depth = 0) {
+    if (!node) {
+        return { role: "", name_norm: "", children: [] };
+    }
+    const role = (node.role ?? "").toLowerCase().trim();
+    const nameNorm = normalizeText(node.name);
+    // Truncate at max depth
+    if (depth >= MAX_TREE_DEPTH) {
+        return {
+            role,
+            name_norm: nameNorm,
+            children: [], // Truncated
+        };
+    }
+    // Canonicalize children
+    let children = [];
+    if (node.children && Array.isArray(node.children)) {
+        // Limit children count
+        const limitedChildren = node.children.slice(0, MAX_CHILDREN_PER_NODE);
+        // Canonicalize each child
+        children = limitedChildren.map((child) => canonicalizeAccessibilityNode(child, depth + 1));
+        // Sort children by (role, name_norm) for determinism
+        children.sort((a, b) => {
+            const roleCompare = a.role.localeCompare(b.role);
+            if (roleCompare !== 0)
+                return roleCompare;
+            return a.name_norm.localeCompare(b.name_norm);
+        });
+    }
+    return {
+        role,
+        name_norm: nameNorm,
+        children,
+    };
+}
+/**
+ * Build a focused element path string.
+ *
+ * Creates a path like "window/toolbar/button[Save]" representing
+ * the path to the focused element in the accessibility tree.
+ *
+ * @param focusedRole - Role of the focused element
+ * @param focusedName - Name of the focused element
+ * @returns Path string
+ */
+export function buildFocusedPath(focusedRole, focusedName) {
+    const role = (focusedRole ?? "").toLowerCase().trim();
+    const name = normalizeText(focusedName);
+    if (!role && !name) {
+        return "";
+    }
+    if (!name) {
+        return role;
+    }
+    return `${role}[${name}]`;
+}
+// =============================================================================
+// Desktop Snapshot Canonicalization
+// =============================================================================
+/**
+ * Canonicalize a desktop accessibility snapshot.
+ *
+ * Normalizes all fields to produce a deterministic representation:
+ * - `app_name`: Lowercase, trimmed
+ * - `window_title`: Text normalization (capped at 100 chars)
+ * - `focused_path`: Built from focused element info
+ * - `tree_hash`: SHA-256 of canonical tree JSON
+ *
+ * @param snapshot - Raw desktop accessibility snapshot
+ * @returns Canonical snapshot for hashing
+ */
+export function canonicalizeDesktopSnapshot(snapshot) {
+    const platform = snapshot.platform ?? detectPlatform();
+    // Canonicalize the UI tree if present
+    let treeHash;
+    if (snapshot.ui_tree) {
+        const canonicalTree = canonicalizeAccessibilityNode(snapshot.ui_tree);
+        treeHash = sha256(JSON.stringify(canonicalTree));
+    }
+    else if (snapshot.ui_tree_text) {
+        // Fallback: hash the raw text if no structured tree
+        treeHash = sha256(normalizeText(snapshot.ui_tree_text, 10000));
+    }
+    else {
+        treeHash = sha256("");
+    }
+    return {
+        app_name_norm: normalizeText(snapshot.app_name),
+        window_title_norm: normalizeText(snapshot.window_title, MAX_WINDOW_TITLE_LENGTH),
+        focused_path: buildFocusedPath(snapshot.focused_role, snapshot.focused_name),
+        tree_hash: treeHash,
+        platform,
+    };
+}
+/**
+ * Compute state hash for a desktop accessibility snapshot.
+ *
+ * The hash includes all canonical fields in a deterministic order.
+ * Platform is included because different platforms have different
+ * accessibility APIs and security contexts.
+ *
+ * @param snapshot - Raw or canonical desktop snapshot
+ * @returns SHA-256 hash prefixed with "sha256:"
+ */
+export function computeDesktopStateHash(snapshot) {
+    // Canonicalize if not already canonical
+    const canonical = isCanonicalDesktopSnapshot(snapshot)
+        ? snapshot
+        : canonicalizeDesktopSnapshot(snapshot);
+    // Build deterministic JSON (sorted keys)
+    const hashInput = JSON.stringify({
+        app_name_norm: canonical.app_name_norm,
+        focused_path: canonical.focused_path,
+        platform: canonical.platform,
+        tree_hash: canonical.tree_hash,
+        window_title_norm: canonical.window_title_norm,
+    });
+    return `sha256:${sha256(hashInput)}`;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Detect the current platform.
+ */
+function detectPlatform() {
+    const p = process.platform;
+    if (p === "darwin" || p === "linux" || p === "win32") {
+        return p;
+    }
+    // Default to linux for unknown Unix-like platforms
+    return "linux";
+}
+/**
+ * Type guard to check if a snapshot is already canonical.
+ */
+function isCanonicalDesktopSnapshot(snapshot) {
+    return ("app_name_norm" in snapshot &&
+        "window_title_norm" in snapshot &&
+        "focused_path" in snapshot &&
+        "tree_hash" in snapshot);
+}
+// =============================================================================
+// Schema Version
+// =============================================================================
+/**
+ * Current schema version for desktop canonicalization.
+ *
+ * Increment major version for breaking changes to canonical format.
+ * Increment minor version for additions that don't change existing hashes.
+ */
+export const DESKTOP_SCHEMA_VERSION = "desktop:v1.0";
+//# sourceMappingURL=desktop.js.map

package/dist/canonicalization/desktop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop.js","sourceRoot":"","sources":["../../src/canonicalization/desktop.ts"],"names":[],"mappings":"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"}

package/dist/canonicalization/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Canonicalization module for non-web state evidence.
+ *
+ * This module provides consistent normalization for terminal and desktop
+ * accessibility snapshots, ensuring reproducible state hashes across
+ * different runs, platforms, and environments.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   canonicalizeTerminalSnapshot,
+ *   computeTerminalStateHash,
+ *   canonicalizeDesktopSnapshot,
+ *   computeDesktopStateHash,
+ * } from "@predicatesystems/authority/canonicalization";
+ *
+ * // Terminal session
+ * const terminalHash = computeTerminalStateHash({
+ *   session_id: "sess-123",
+ *   cwd: "~/projects/myapp",
+ *   command: "npm  test",  // Extra whitespace normalized
+ *   transcript: "\x1b[32mPASS\x1b[0m all tests",  // ANSI stripped
+ * });
+ *
+ * // Desktop accessibility
+ * const desktopHash = computeDesktopStateHash({
+ *   app_name: "Firefox",
+ *   window_title: "  GitHub - My Repo  ",  // Whitespace normalized
+ *   focused_role: "button",
+ *   focused_name: "Submit",
+ * });
+ * ```
+ *
+ * @module canonicalization
+ */
+export { type Platform, normalizeText, normalizeCommand, stripAnsi, normalizeTimestamps, normalizeTranscript, normalizePath, isSecretKey, hashEnvironment, sha256, } from "./utils.js";
+export { type TerminalSessionSnapshot, type CanonicalTerminalSnapshot, canonicalizeTerminalSnapshot, computeTerminalStateHash, TERMINAL_SCHEMA_VERSION, } from "./terminal.js";
+export { type AccessibilityNode, type DesktopAccessibilitySnapshot, type CanonicalAccessibilityNode, type CanonicalDesktopSnapshot, canonicalizeAccessibilityNode, buildFocusedPath, canonicalizeDesktopSnapshot, computeDesktopStateHash, DESKTOP_SCHEMA_VERSION, } from "./desktop.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/canonicalization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/canonicalization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAMH,OAAO,EAEL,KAAK,QAAQ,EAEb,aAAa,EACb,gBAAgB,EAEhB,SAAS,EACT,mBAAmB,EAEnB,mBAAmB,EAEnB,aAAa,EAEb,WAAW,EACX,eAAe,EAEf,MAAM,GACP,MAAM,YAAY,CAAC;AAMpB,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAE9B,4BAA4B,EAC5B,wBAAwB,EAExB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAMvB,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAE7B,6BAA6B,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB,EAEvB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

package/dist/canonicalization/index.js

@@ -0,0 +1,68 @@
+/**
+ * Canonicalization module for non-web state evidence.
+ *
+ * This module provides consistent normalization for terminal and desktop
+ * accessibility snapshots, ensuring reproducible state hashes across
+ * different runs, platforms, and environments.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   canonicalizeTerminalSnapshot,
+ *   computeTerminalStateHash,
+ *   canonicalizeDesktopSnapshot,
+ *   computeDesktopStateHash,
+ * } from "@predicatesystems/authority/canonicalization";
+ *
+ * // Terminal session
+ * const terminalHash = computeTerminalStateHash({
+ *   session_id: "sess-123",
+ *   cwd: "~/projects/myapp",
+ *   command: "npm  test",  // Extra whitespace normalized
+ *   transcript: "\x1b[32mPASS\x1b[0m all tests",  // ANSI stripped
+ * });
+ *
+ * // Desktop accessibility
+ * const desktopHash = computeDesktopStateHash({
+ *   app_name: "Firefox",
+ *   window_title: "  GitHub - My Repo  ",  // Whitespace normalized
+ *   focused_role: "button",
+ *   focused_name: "Submit",
+ * });
+ * ```
+ *
+ * @module canonicalization
+ */
+// =============================================================================
+// Re-exports: Utilities
+// =============================================================================
+export { 
+// Text normalization
+normalizeText, normalizeCommand, 
+// ANSI and timestamp handling
+stripAnsi, normalizeTimestamps, 
+// Transcript normalization
+normalizeTranscript, 
+// Path normalization
+normalizePath, 
+// Environment hashing
+isSecretKey, hashEnvironment, 
+// Core hashing
+sha256, } from "./utils.js";
+// =============================================================================
+// Re-exports: Terminal Canonicalization
+// =============================================================================
+export { 
+// Functions
+canonicalizeTerminalSnapshot, computeTerminalStateHash, 
+// Schema version
+TERMINAL_SCHEMA_VERSION, } from "./terminal.js";
+// =============================================================================
+// Re-exports: Desktop Canonicalization
+// =============================================================================
+export { 
+// Functions
+canonicalizeAccessibilityNode, buildFocusedPath, canonicalizeDesktopSnapshot, computeDesktopStateHash, 
+// Schema version
+DESKTOP_SCHEMA_VERSION, } from "./desktop.js";
+//# sourceMappingURL=index.js.map

package/dist/canonicalization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/canonicalization/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,gFAAgF;AAChF,wBAAwB;AACxB,gFAAgF;AAEhF,OAAO;AAGL,qBAAqB;AACrB,aAAa,EACb,gBAAgB;AAChB,8BAA8B;AAC9B,SAAS,EACT,mBAAmB;AACnB,2BAA2B;AAC3B,mBAAmB;AACnB,qBAAqB;AACrB,aAAa;AACb,sBAAsB;AACtB,WAAW,EACX,eAAe;AACf,eAAe;AACf,MAAM,GACP,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,wCAAwC;AACxC,gFAAgF;AAEhF,OAAO;AAIL,YAAY;AACZ,4BAA4B,EAC5B,wBAAwB;AACxB,iBAAiB;AACjB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AAEvB,gFAAgF;AAChF,uCAAuC;AACvC,gFAAgF;AAEhF,OAAO;AAML,YAAY;AACZ,6BAA6B,EAC7B,gBAAgB,EAChB,2BAA2B,EAC3B,uBAAuB;AACvB,iBAAiB;AACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}

package/dist/canonicalization/terminal.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Terminal session canonicalization for reproducible state hashes.
+ *
+ * This module provides canonical normalization for terminal sessions,
+ * ensuring that equivalent terminal states produce identical hashes
+ * regardless of superficial differences (whitespace, ANSI codes, timestamps).
+ */
+import { type Platform } from "./utils.js";
+/**
+ * Raw terminal session snapshot from the runtime environment.
+ */
+export interface TerminalSessionSnapshot {
+    session_id: string;
+    terminal_id?: string;
+    cwd?: string;
+    command?: string;
+    transcript?: string;
+    exit_code?: number | null;
+    env?: Record<string, string>;
+    platform?: Platform;
+    observed_at?: string;
+}
+/**
+ * Canonical terminal snapshot with normalized fields.
+ *
+ * This is the deterministic representation used for hashing.
+ */
+export interface CanonicalTerminalSnapshot {
+    session_id: string;
+    terminal_id: string;
+    cwd_normalized: string;
+    command_normalized: string;
+    transcript_normalized: string;
+    exit_code: number | null;
+    env_hash: string;
+    platform: Platform;
+}
+/**
+ * Canonicalize a terminal session snapshot.
+ *
+ * Normalizes all fields to produce a deterministic representation:
+ * - `cwd`: Resolved to absolute path
+ * - `command`: Trimmed and whitespace-collapsed (case preserved)
+ * - `transcript`: ANSI stripped, timestamps normalized, whitespace collapsed
+ * - `env`: Sorted, secrets redacted, then hashed
+ *
+ * @param snapshot - Raw terminal session snapshot
+ * @returns Canonical snapshot for hashing
+ */
+export declare function canonicalizeTerminalSnapshot(snapshot: TerminalSessionSnapshot): CanonicalTerminalSnapshot;
+/**
+ * Compute state hash for a terminal session snapshot.
+ *
+ * The hash includes all canonical fields in a deterministic order.
+ * Platform is included because different platforms have different
+ * security contexts (e.g., Unix vs Windows permissions).
+ *
+ * @param snapshot - Raw or canonical terminal snapshot
+ * @returns SHA-256 hash prefixed with "sha256:"
+ */
+export declare function computeTerminalStateHash(snapshot: TerminalSessionSnapshot | CanonicalTerminalSnapshot): string;
+/**
+ * Current schema version for terminal canonicalization.
+ *
+ * Increment major version for breaking changes to canonical format.
+ * Increment minor version for additions that don't change existing hashes.
+ */
+export declare const TERMINAL_SCHEMA_VERSION = "terminal:v1.0";
+//# sourceMappingURL=terminal.d.ts.map

package/dist/canonicalization/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/canonicalization/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,KAAK,QAAQ,EAMd,MAAM,YAAY,CAAC;AAMpB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,uBAAuB,GAChC,yBAAyB,CAa3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,uBAAuB,GAAG,yBAAyB,GAC5D,MAAM,CAmBR;AAoCD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,kBAAkB,CAAC"}

package/dist/canonicalization/terminal.js

@@ -0,0 +1,98 @@
+/**
+ * Terminal session canonicalization for reproducible state hashes.
+ *
+ * This module provides canonical normalization for terminal sessions,
+ * ensuring that equivalent terminal states produce identical hashes
+ * regardless of superficial differences (whitespace, ANSI codes, timestamps).
+ */
+import { hashEnvironment, normalizeCommand, normalizePath, normalizeTranscript, sha256, } from "./utils.js";
+// =============================================================================
+// Canonicalization
+// =============================================================================
+/**
+ * Canonicalize a terminal session snapshot.
+ *
+ * Normalizes all fields to produce a deterministic representation:
+ * - `cwd`: Resolved to absolute path
+ * - `command`: Trimmed and whitespace-collapsed (case preserved)
+ * - `transcript`: ANSI stripped, timestamps normalized, whitespace collapsed
+ * - `env`: Sorted, secrets redacted, then hashed
+ *
+ * @param snapshot - Raw terminal session snapshot
+ * @returns Canonical snapshot for hashing
+ */
+export function canonicalizeTerminalSnapshot(snapshot) {
+    const platform = snapshot.platform ?? detectPlatform();
+    return {
+        session_id: snapshot.session_id,
+        terminal_id: snapshot.terminal_id ?? "",
+        cwd_normalized: normalizePath(snapshot.cwd),
+        command_normalized: normalizeCommand(snapshot.command),
+        transcript_normalized: normalizeTranscript(snapshot.transcript),
+        exit_code: snapshot.exit_code ?? null,
+        env_hash: hashEnvironment(snapshot.env),
+        platform,
+    };
+}
+/**
+ * Compute state hash for a terminal session snapshot.
+ *
+ * The hash includes all canonical fields in a deterministic order.
+ * Platform is included because different platforms have different
+ * security contexts (e.g., Unix vs Windows permissions).
+ *
+ * @param snapshot - Raw or canonical terminal snapshot
+ * @returns SHA-256 hash prefixed with "sha256:"
+ */
+export function computeTerminalStateHash(snapshot) {
+    // Canonicalize if not already canonical
+    const canonical = isCanonicalTerminalSnapshot(snapshot)
+        ? snapshot
+        : canonicalizeTerminalSnapshot(snapshot);
+    // Build deterministic JSON (sorted keys)
+    const hashInput = JSON.stringify({
+        command_normalized: canonical.command_normalized,
+        cwd_normalized: canonical.cwd_normalized,
+        env_hash: canonical.env_hash,
+        exit_code: canonical.exit_code,
+        platform: canonical.platform,
+        session_id: canonical.session_id,
+        terminal_id: canonical.terminal_id,
+        transcript_normalized: canonical.transcript_normalized,
+    });
+    return `sha256:${sha256(hashInput)}`;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Detect the current platform.
+ */
+function detectPlatform() {
+    const p = process.platform;
+    if (p === "darwin" || p === "linux" || p === "win32") {
+        return p;
+    }
+    // Default to linux for unknown Unix-like platforms
+    return "linux";
+}
+/**
+ * Type guard to check if a snapshot is already canonical.
+ */
+function isCanonicalTerminalSnapshot(snapshot) {
+    return ("cwd_normalized" in snapshot &&
+        "command_normalized" in snapshot &&
+        "transcript_normalized" in snapshot &&
+        "env_hash" in snapshot);
+}
+// =============================================================================
+// Schema Version
+// =============================================================================
+/**
+ * Current schema version for terminal canonicalization.
+ *
+ * Increment major version for breaking changes to canonical format.
+ * Increment minor version for additions that don't change existing hashes.
+ */
+export const TERMINAL_SCHEMA_VERSION = "terminal:v1.0";
+//# sourceMappingURL=terminal.js.map

package/dist/canonicalization/terminal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.js","sourceRoot":"","sources":["../../src/canonicalization/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,MAAM,GACP,MAAM,YAAY,CAAC;AAqCpB,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAiC;IAEjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAC;IAEvD,OAAO;QACL,UAAU,EAAE,QAAQ,CAAC,UAAU;QAC/B,WAAW,EAAE,QAAQ,CAAC,WAAW,IAAI,EAAE;QACvC,cAAc,EAAE,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC3C,kBAAkB,EAAE,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC;QACtD,qBAAqB,EAAE,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC;QAC/D,SAAS,EAAE,QAAQ,CAAC,SAAS,IAAI,IAAI;QACrC,QAAQ,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC;QACvC,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA6D;IAE7D,wCAAwC;IACxC,MAAM,SAAS,GAAG,2BAA2B,CAAC,QAAQ,CAAC;QACrD,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,4BAA4B,CAAC,QAAQ,CAAC,CAAC;IAE3C,yCAAyC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,kBAAkB,EAAE,SAAS,CAAC,kBAAkB;QAChD,cAAc,EAAE,SAAS,CAAC,cAAc;QACxC,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,qBAAqB,EAAE,SAAS,CAAC,qBAAqB;KACvD,CAAC,CAAC;IAEH,OAAO,UAAU,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,UAAU;AACV,gFAAgF;AAEhF;;GAEG;AACH,SAAS,cAAc;IACrB,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC3B,IAAI,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,mDAAmD;IACnD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAS,2BAA2B,CAClC,QAA6D;IAE7D,OAAO,CACL,gBAAgB,IAAI,QAAQ;QAC5B,oBAAoB,IAAI,QAAQ;QAChC,uBAAuB,IAAI,QAAQ;QACnC,UAAU,IAAI,QAAQ,CACvB,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC"}