halo-record 0.1.0

package/dist/record.js

@@ -0,0 +1,222 @@
+/* Build and append Halo Runtime Records (Schema v0.1).
+   Port of the Python implementation (record.py), including the symmetric
+   input/outcome redaction. Records written here verify with the Python
+   verifier and anchor to the same witness — the chain format is language-
+   independent. */
+import { randomUUID } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { GENESIS_PREV, computeHash, inputHash } from "./canon.js";
+import { redactText, scan, topSeverity } from "./redact.js";
+export const SCHEMA_VERSION = "0.1";
+export const ACTION_TYPES = new Set(["tool_call", "agent_message", "read", "write", "network"]);
+export const CATEGORIES = new Set(["security", "safety", "reliability", "privacy"]);
+/* Where a record came from — "captured" (Halo saw the call at the trust
+   boundary; strongest) vs "ingested" (built from telemetry the vendor already
+   emits; weaker). Same table as the Python package. */
+export const SOURCES = {
+    recorder: { adapter: "recorder", via: "Halo recorder (native)", capture: "captured" },
+    mcp: { adapter: "mcp", via: "MCP interceptor", capture: "captured" },
+    langchain: { adapter: "langchain", via: "LangChain / LangGraph", capture: "captured" },
+    openai_agents: { adapter: "openai_agents", via: "OpenAI Agents SDK", capture: "captured" },
+    vercel_ai: { adapter: "vercel_ai", via: "Vercel AI SDK", capture: "captured" },
+    claude_agent_sdk: { adapter: "claude_agent_sdk", via: "Claude Agent SDK", capture: "captured" },
+    otel: { adapter: "otel", via: "OpenTelemetry GenAI spans", capture: "ingested" },
+    litellm: { adapter: "litellm", via: "LiteLLM gateway", capture: "ingested" },
+    langfuse: { adapter: "langfuse", via: "Langfuse traces", capture: "ingested" },
+    gateway: { adapter: "gateway", via: "LLM gateway / proxy log", capture: "ingested" },
+};
+/* Unknown ids fall back to "ingested" — the conservative tier, so an
+   unrecognized origin is never overstated as boundary-captured. */
+export function normalizeSource(source) {
+    if (source == null)
+        return null;
+    if (typeof source === "string") {
+        return { ...(SOURCES[source] ?? { adapter: source, via: source, capture: "ingested" }) };
+    }
+    const src = { ...source };
+    src.capture ??= "ingested";
+    src.via ??= src.adapter ?? "unknown";
+    return src;
+}
+function now() {
+    return new Date().toISOString();
+}
+function normSubject(subject) {
+    if (subject == null)
+        return null;
+    if (typeof subject === "string")
+        return { id: subject };
+    return subject;
+}
+/* Construct a v0.1 record (without integrity.hash filled in). tool_input is
+   hashed and, by default, a redacted summary is stored; raw arguments never
+   enter the record. Outcome summaries are redacted and scanned symmetrically
+   with input. */
+export function build(actionType, category, opts = {}) {
+    const { tool, toolInput, sessionId = "local", agent, scope, decision = "allowed", approver, outcome: outcomeIn, ts, subject, source, summaries = true, } = opts;
+    let findings = opts.findings ?? null;
+    if (!ACTION_TYPES.has(actionType)) {
+        throw new RangeError("action.type must be one of " + [...ACTION_TYPES].sort().join(", "));
+    }
+    if (!CATEGORIES.has(category)) {
+        throw new RangeError("action.category must be one of " + [...CATEGORIES].sort().join(", "));
+    }
+    const action = { type: actionType, category };
+    if (tool !== undefined)
+        action["tool"] = tool;
+    if (scope !== undefined || decision !== undefined) {
+        const auth = { decision };
+        if (scope !== undefined)
+            auth["scope"] = scope;
+        if (approver !== undefined)
+            auth["approver"] = approver;
+        action["authorization"] = auth;
+    }
+    if (toolInput !== undefined) {
+        const inp = { hash: inputHash(toolInput) };
+        if (summaries)
+            inp["summary"] = redactText(stringify(toolInput)).slice(0, 200);
+        action["input"] = inp;
+    }
+    // Normalize the outcome up front so its summary is redacted before it is
+    // sealed/served and so it can be scanned for secrets alongside the input.
+    let outcome = null;
+    let outcomeSummaryRaw = null;
+    if (outcomeIn != null) {
+        outcome = { ...outcomeIn };
+        if ("summary" in outcome && outcome["summary"] != null) {
+            outcomeSummaryRaw = String(outcome["summary"]);
+        }
+        if (!summaries) {
+            delete outcome["summary"];
+        }
+        else if (outcomeSummaryRaw !== null) {
+            outcome["summary"] = redactText(outcomeSummaryRaw).slice(0, 200);
+        }
+    }
+    if (findings == null) {
+        findings = [];
+        if (toolInput !== undefined)
+            findings.push(...scan(stringify(toolInput)));
+        if (outcomeSummaryRaw !== null)
+            findings.push(...scan(outcomeSummaryRaw));
+    }
+    const record = {
+        schema_version: SCHEMA_VERSION,
+        record_id: randomUUID(),
+        session_id: sessionId,
+        ts: ts ?? now(),
+        agent: agent ?? { id: "unknown", name: "unknown" },
+        action,
+        severity: topSeverity(findings),
+        findings,
+        integrity: { alg: "sha-256", canon: "rfc8785", prev_hash: "", hash: "" },
+    };
+    const subj = normSubject(subject);
+    if (subj !== null)
+        record["subject"] = subj;
+    const src = normalizeSource(source);
+    if (src !== null)
+        record["source"] = src;
+    if (outcome !== null)
+        record["outcome"] = outcome;
+    return record;
+}
+function stringify(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function expandHome(p) {
+    return p.startsWith("~") ? join(homedir(), p.slice(1)) : p;
+}
+/* Append-only writer that maintains the hash chain in a JSONL file.
+
+   append() is fully synchronous, so within a Node process parallel tool calls
+   cannot interleave mid-append (the event loop runs the read-hash/write block
+   atomically). The chain head is cached after the first read so appending
+   stays O(1) per record instead of re-scanning the file. One Recorder
+   instance should own a given log file per process. */
+export class Recorder {
+    path;
+    #lastHash = null;
+    constructor(path) {
+        this.path = expandHome(path);
+    }
+    lastHash() {
+        if (this.#lastHash !== null)
+            return this.#lastHash;
+        if (!existsSync(this.path))
+            return GENESIS_PREV;
+        const lines = readFileSync(this.path, "utf8").split("\n").filter((l) => l.trim());
+        if (lines.length === 0)
+            return GENESIS_PREV;
+        try {
+            const rec = JSON.parse(lines[lines.length - 1]);
+            const integ = (rec["integrity"] ?? {});
+            return integ["hash"] || GENESIS_PREV;
+        }
+        catch {
+            return GENESIS_PREV;
+        }
+    }
+    append(record) {
+        const prev = this.lastHash();
+        const integ = (record["integrity"] ??= {});
+        integ["prev_hash"] = prev;
+        integ["hash"] = computeHash(record, prev);
+        appendFileSync(this.path, JSON.stringify(record) + "\n", "utf8");
+        this.#lastHash = integ["hash"];
+        return record;
+    }
+    /* Convenience: build + append in one call. */
+    record(actionType, category, opts = {}) {
+        return this.append(build(actionType, category, opts));
+    }
+}
+/* Routes each record to a per-subject log, each its own hash chain. */
+export class TenantRecorder {
+    directory;
+    default;
+    recorders = new Map();
+    constructor(directory, opts = {}) {
+        this.directory = expandHome(directory);
+        this.default = opts.default ?? "_local";
+    }
+    static safe(name) {
+        const cleaned = String(name)
+            .split("")
+            .map((c) => (/[a-zA-Z0-9\-_.]/.test(c) ? c : "_"))
+            .join("")
+            .replace(/^[._]+|[._]+$/g, "");
+        return cleaned || "tenant";
+    }
+    subjectId(record) {
+        const subj = record["subject"];
+        if (subj && typeof subj === "object" && subj["id"]) {
+            return String(subj["id"]);
+        }
+        return this.default;
+    }
+    pathFor(subjectId) {
+        return join(this.directory, TenantRecorder.safe(subjectId) + ".jsonl");
+    }
+    recorderFor(subjectId) {
+        let r = this.recorders.get(subjectId);
+        if (!r) {
+            r = new Recorder(this.pathFor(subjectId));
+            this.recorders.set(subjectId, r);
+        }
+        return r;
+    }
+    append(record) {
+        return this.recorderFor(this.subjectId(record)).append(record);
+    }
+}

package/dist/redact.d.ts

@@ -0,0 +1,11 @@
+export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW" | "INFO";
+export interface Finding {
+    type: string;
+    severity: Severity;
+    sample: string;
+}
+export declare const SEVERITY_RANK: Record<string, number>;
+export declare function redactSample(ftype: string, value: unknown): string;
+export declare function redactText(text: unknown): string;
+export declare function scan(text: unknown): Finding[];
+export declare function topSeverity(findings: Finding[]): Severity;

package/dist/redact.js

@@ -0,0 +1,75 @@
+/* Sensitive-pattern detection and redaction. Pattern-for-pattern port of the
+   Python implementation (redact.py) so both recorders flag and redact the
+   same content the same way. */
+const PATTERNS = [
+    ["api_key", "CRITICAL", /(?:sk-[a-zA-Z0-9]{20,}|AKIA[0-9A-Z]{16}|ghp_[a-zA-Z0-9]{36}|xox[baprs]-[a-zA-Z0-9-]{10,})/g],
+    ["private_key", "CRITICAL", /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g],
+    ["db_conn", "CRITICAL", /(?:postgres|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s"'<>]+/g],
+    ["credit_card", "HIGH", /\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13}|6(?:011|5[0-9]{2})[0-9]{12})\b/g],
+    ["ssn", "HIGH", /\b\d{3}-\d{2}-\d{4}\b/g],
+    ["email", "MEDIUM", /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g],
+    ["ip_internal", "MEDIUM", /\b(?:10\.\d{1,3}\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3})\b/g],
+    ["bearer_token", "HIGH", /Bearer\s+[a-zA-Z0-9\-_.]{20,}/g],
+];
+export const SEVERITY_RANK = {
+    CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0,
+};
+export function redactSample(ftype, value) {
+    const v = String(value);
+    if (ftype === "email") {
+        const m = v.match(/^([A-Za-z0-9._%+-])[A-Za-z0-9._%+-]*(@.+)$/);
+        return m ? m[1] + "****" + m[2] : "****";
+    }
+    if (ftype === "db_conn")
+        return v.replace(/:\/\/([^:/@]+):[^@]+@/, "://$1:****@");
+    if (ftype === "bearer_token")
+        return "Bearer ****";
+    if (ftype === "private_key")
+        return "-----BEGIN PRIVATE KEY----- ****";
+    if (ftype === "api_key")
+        return v.length > 4 ? v.slice(0, 4) + "****" : "****";
+    if (ftype === "credit_card") {
+        const digits = v.replace(/\D/g, "");
+        return digits.length >= 4 ? "****" + digits.slice(-4) : "****";
+    }
+    if (ftype === "ssn")
+        return v.length >= 4 ? "***-**-" + v.slice(-4) : "****";
+    if (ftype === "ip_internal") {
+        const parts = v.split(".");
+        return parts.length === 4 ? [parts[0], parts[1], "*", "*"].join(".") : "****";
+    }
+    return "****";
+}
+export function redactText(text) {
+    let out = String(text);
+    for (const [name, , pattern] of PATTERNS) {
+        out = out.replace(new RegExp(pattern.source, pattern.flags), (m) => redactSample(name, m));
+    }
+    return out;
+}
+/* Return a list of redacted findings for any sensitive patterns in `text`. */
+export function scan(text) {
+    const findings = [];
+    const s = String(text);
+    for (const [name, severity, pattern] of PATTERNS) {
+        const matches = s.match(new RegExp(pattern.source, pattern.flags));
+        if (matches && matches.length) {
+            findings.push({
+                type: name,
+                severity,
+                sample: redactSample(name, String(matches[0]).slice(0, 120)),
+            });
+        }
+    }
+    return findings;
+}
+export function topSeverity(findings) {
+    if (!findings || findings.length === 0)
+        return "INFO";
+    let best = findings[0];
+    for (const f of findings.slice(1)) {
+        if ((SEVERITY_RANK[f.severity] ?? 0) > (SEVERITY_RANK[best.severity] ?? 0))
+            best = f;
+    }
+    return best.severity;
+}

package/dist/verify.d.ts

@@ -0,0 +1,13 @@
+import type { HaloRecord } from "./record.ts";
+type Schema = Record<string, any>;
+export declare function loadSchema(): Schema;
+export declare function validateRecord(record: HaloRecord, schema?: Schema): string[];
+export interface VerifyResult {
+    ok: boolean;
+    count: number;
+    problems: string[];
+}
+export declare function verifyRecords(records: HaloRecord[], schema?: Schema): VerifyResult;
+export declare function readLog(path: string): HaloRecord[];
+export declare function verifyLog(path: string, schema?: Schema): VerifyResult;
+export {};

package/dist/verify.js

@@ -0,0 +1,103 @@
+/* Conformance verification: schema validation + hash-chain integrity.
+   Port of the Python verifier (verify.py); dependency-free. */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GENESIS_PREV, computeHash } from "./canon.js";
+const SCHEMA_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "halo-record.schema.json");
+export function loadSchema() {
+    return JSON.parse(readFileSync(SCHEMA_PATH, "utf8"));
+}
+function typeOk(node, t) {
+    switch (t) {
+        case "object": return node !== null && typeof node === "object" && !Array.isArray(node);
+        case "array": return Array.isArray(node);
+        case "string": return typeof node === "string";
+        case "number": return typeof node === "number" && typeof node !== "boolean";
+        case "integer": return typeof node === "number" && Number.isInteger(node);
+        case "boolean": return typeof node === "boolean";
+        case "null": return node === null;
+        default: return true;
+    }
+}
+function validate(node, schema, path, errors) {
+    if ("const" in schema && !deepEqual(node, schema["const"])) {
+        errors.push(`${path}: expected const ${JSON.stringify(schema["const"])}, got ${JSON.stringify(node)}`);
+    }
+    if ("enum" in schema && !schema["enum"].some((v) => deepEqual(node, v))) {
+        errors.push(`${path}: ${JSON.stringify(node)} not in enum ${JSON.stringify(schema["enum"])}`);
+    }
+    const t = schema["type"];
+    if (t) {
+        if ((t === "number" || t === "integer") && typeof node === "boolean") {
+            errors.push(`${path}: expected ${t}, got boolean`);
+        }
+        else if (!typeOk(node, t)) {
+            errors.push(`${path}: expected ${t}, got ${Array.isArray(node) ? "array" : node === null ? "null" : typeof node}`);
+            return;
+        }
+    }
+    if (node !== null && typeof node === "object" && !Array.isArray(node)) {
+        const obj = node;
+        for (const req of (schema["required"] ?? [])) {
+            if (!(req in obj))
+                errors.push(`${path}: missing required field ${JSON.stringify(req)}`);
+        }
+        const props = (schema["properties"] ?? {});
+        for (const [key, val] of Object.entries(obj)) {
+            if (key in props)
+                validate(val, props[key], `${path}.${key}`, errors);
+        }
+    }
+    if (Array.isArray(node) && "items" in schema) {
+        node.forEach((item, i) => validate(item, schema["items"], `${path}[${i}]`, errors));
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (typeof a !== "object")
+        return false;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+export function validateRecord(record, schema) {
+    const s = schema ?? loadSchema();
+    const errors = [];
+    validate(record, s, "record", errors);
+    return errors;
+}
+/* Verify a list of already-parsed records: schema + chain. */
+export function verifyRecords(records, schema) {
+    const s = schema ?? loadSchema();
+    const problems = [];
+    let prevHash = GENESIS_PREV;
+    records.forEach((record, idx) => {
+        const n = idx + 1;
+        for (const err of validateRecord(record, s))
+            problems.push(`record ${n}: schema: ${err}`);
+        const integ = (record["integrity"] ?? {});
+        const declaredPrev = integ["prev_hash"];
+        const declaredHash = integ["hash"];
+        if (declaredPrev !== prevHash) {
+            problems.push(`record ${n}: chain: prev_hash ${declaredPrev} does not match expected ${prevHash}`);
+        }
+        const recomputed = computeHash(record, prevHash);
+        if (declaredHash !== recomputed) {
+            problems.push(`record ${n}: chain: hash ${declaredHash} does not match recomputed ${recomputed}`);
+        }
+        prevHash = declaredHash || recomputed;
+    });
+    return { ok: problems.length === 0, count: records.length, problems };
+}
+export function readLog(path) {
+    return readFileSync(path, "utf8")
+        .split("\n")
+        .filter((ln) => ln.trim())
+        .map((ln) => JSON.parse(ln));
+}
+/* Verify a JSONL chain file. */
+export function verifyLog(path, schema) {
+    return verifyRecords(readLog(path), schema);
+}

package/dist/witness.d.ts

@@ -0,0 +1,8 @@
+import { type Checkpoint } from "./anchor.ts";
+import type { HaloRecord } from "./record.ts";
+export declare function anchorRemote(witnessUrl: string, key: string, records: HaloRecord[], opts?: {
+    timeoutMs?: number;
+}): Promise<Checkpoint>;
+export declare function fetchCheckpoints(witnessUrl: string, subject?: string | null, opts?: {
+    timeoutMs?: number;
+}): Promise<Checkpoint[]>;

package/dist/witness.js

@@ -0,0 +1,36 @@
+/* Client for the hosted Halo witness. The checkpoint is computed LOCALLY and
+   only {subject, count, head, chain_root} is sent — record contents never
+   leave the vendor. Same wire protocol as the Python client (witness.py). */
+import { checkpoint } from "./anchor.js";
+/* Anchor a chain's current head to a hosted Halo witness. Returns the
+   witness's receipt (the stored checkpoint with the server's timestamp). */
+export async function anchorRemote(witnessUrl, key, records, opts = {}) {
+    const cp = checkpoint(records);
+    const body = JSON.stringify({
+        subject: cp.subject,
+        count: cp.count,
+        head: cp.head,
+        chain_root: cp.chain_root,
+    });
+    const resp = await fetch(witnessUrl.replace(/\/+$/, "") + "/anchor", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: "Bearer " + key },
+        body,
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+    });
+    if (!resp.ok)
+        throw new Error(`witness anchor failed: HTTP ${resp.status}`);
+    const out = (await resp.json());
+    return out.receipt ?? out;
+}
+/* Fetch the witness's independently held checkpoints for a subject. */
+export async function fetchCheckpoints(witnessUrl, subject, opts = {}) {
+    let url = witnessUrl.replace(/\/+$/, "") + "/v1/checkpoints";
+    if (subject != null)
+        url += "?" + new URLSearchParams({ subject }).toString();
+    const resp = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000) });
+    if (!resp.ok)
+        throw new Error(`witness fetch failed: HTTP ${resp.status}`);
+    const out = (await resp.json());
+    return out.checkpoints ?? [];
+}

package/halo-record.schema.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://halo.dev/spec/v0.1/halo-record.schema.json",
+  "title": "Halo Runtime Record",
+  "description": "An append-only, tamper-evident record of a single AI-agent action. Schema v0.1.",
+  "type": "object",
+  "required": ["schema_version", "record_id", "session_id", "ts", "action", "integrity"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "0.1" },
+    "record_id": { "type": "string", "description": "Unique identifier for this record (UUID recommended)." },
+    "session_id": { "type": "string", "description": "Links the record to the triggering session/conversation." },
+    "parent_id": { "type": "string", "description": "The record this one was caused by, for provenance/chaining." },
+    "ts": { "type": "string", "description": "RFC 3339 UTC timestamp." },
+    "subject": {
+      "type": "object",
+      "description": "The tenant/customer context this action belongs to — the segmentation key. Distinct from principal (who operated): subject is whose engagement the action serves. Used to keep each customer's records in their own chain and report, so one is never exposed to another.",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" }
+      }
+    },
+    "principal": {
+      "type": "object",
+      "description": "Identities on whose behalf the action ran (up to four layers).",
+      "properties": {
+        "human_id": { "type": "string" },
+        "creator_id": { "type": "string" },
+        "service_account": { "type": "string" },
+        "role_scope": { "type": "string" }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "model": { "type": "string" },
+        "model_version": { "type": "string" }
+      }
+    },
+    "mcp": {
+      "type": "object",
+      "properties": {
+        "host": { "type": "string" },
+        "client": { "type": "string" },
+        "server": { "type": "string" },
+        "server_version": { "type": "string" }
+      }
+    },
+    "action": {
+      "type": "object",
+      "required": ["type", "category"],
+      "properties": {
+        "type": { "type": "string", "enum": ["tool_call", "agent_message", "read", "write", "network"] },
+        "category": { "type": "string", "enum": ["security", "safety", "reliability", "privacy"] },
+        "tool": { "type": "string" },
+        "authorization": {
+          "type": "object",
+          "properties": {
+            "decision": { "type": "string", "enum": ["allowed", "denied", "human_approved"] },
+            "scope": { "type": "string" },
+            "approver": { "type": "string" }
+          }
+        },
+        "input": {
+          "type": "object",
+          "description": "Redacted summary plus a hash of the full canonical arguments. Raw arguments MUST NOT appear.",
+          "properties": {
+            "summary": { "type": "string" },
+            "hash": { "type": "string" }
+          }
+        }
+      }
+    },
+    "outcome": {
+      "type": "object",
+      "properties": {
+        "status": { "type": "string", "enum": ["ok", "error", "denied"] },
+        "summary": { "type": "string" },
+        "hash": { "type": "string" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type", "severity"],
+        "properties": {
+          "type": { "type": "string", "description": "e.g. api_key, private_key, db_conn, credit_card, ssn, email, ip_internal, bearer_token" },
+          "severity": { "type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"] },
+          "sample": { "type": "string", "description": "Redacted excerpt. Unredacted value MUST NOT appear." }
+        }
+      }
+    },
+    "severity": { "type": "string", "enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"] },
+    "threats": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["type"],
+        "properties": {
+          "type": { "type": "string", "description": "e.g. prompt_injection_direct, prompt_injection_indirect, policy_violation, tool_misuse" },
+          "ref": { "type": "string" }
+        }
+      }
+    },
+    "data": {
+      "type": "object",
+      "properties": {
+        "region": { "type": "string" },
+        "cross_region": { "type": "number" },
+        "purpose": { "type": "string" },
+        "pii_types": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "retention": {
+      "type": "object",
+      "properties": {
+        "policy": { "type": "string" },
+        "expires": { "type": "string" }
+      }
+    },
+    "jurisdiction": { "type": "string" },
+    "framework_tags": { "type": "array", "items": { "type": "string" } },
+    "integrity": {
+      "type": "object",
+      "required": ["alg", "canon", "prev_hash", "hash"],
+      "properties": {
+        "alg": { "type": "string", "enum": ["sha-256"] },
+        "canon": { "type": "string", "enum": ["rfc8785"] },
+        "prev_hash": { "type": "string", "description": "Hex SHA-256 of the previous record; 64 zeros for the first record." },
+        "hash": { "type": "string", "description": "Hex SHA-256 of this record (excluding integrity.hash), canonicalized per RFC 8785." }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "required": ["alg", "sig"],
+      "properties": {
+        "alg": { "type": "string", "enum": ["ecdsa-p256", "ed25519"] },
+        "sig": { "type": "string" },
+        "key_id": { "type": "string" }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "halo-record",
+  "version": "0.1.0",
+  "description": "Tamper-evident, hash-chained Runtime Records for AI agents: the TypeScript recorder. Chain-format compatible with the Python halo-record package.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "halo-record.schema.json"
+  ],
+  "scripts": {
+    "test": "node --test test/core.test.ts test/integrations.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^24.13.1",
+    "typescript": "^5.8.3"
+  }
+}