@kyberonai/trailproof 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,202 @@
+/**
+ * Trailproof error hierarchy.
+ */
+/** Base error for all Trailproof operations. */
+declare class TrailproofError extends Error {
+    constructor(message: string);
+}
+/** Raised when event data is invalid (missing or empty required fields). */
+declare class ValidationError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when a storage operation fails (disk, permissions, corruption). */
+declare class StoreError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when the hash chain is broken. */
+declare class ChainError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when HMAC signature verification fails. */
+declare class SignatureError extends TrailproofError {
+    constructor(message: string);
+}
+
+/**
+ * Trailproof core data types.
+ */
+/** A single event in the audit trail.
+ *
+ * Contains the 10-field event envelope. Domain-specific data
+ * goes in the payload field, which Trailproof stores opaquely.
+ *
+ * Field names use snake_case to match the wire format.
+ */
+interface TrailEvent {
+    readonly event_id: string;
+    readonly event_type: string;
+    readonly timestamp: string;
+    readonly actor_id: string;
+    readonly tenant_id: string;
+    readonly payload: Record<string, unknown>;
+    readonly prev_hash: string;
+    readonly hash: string;
+    readonly trace_id?: string | null;
+    readonly session_id?: string | null;
+    readonly signature?: string | null;
+}
+/** Filters for querying events from a store.
+ *
+ * All fields are optional. No filters returns all events up to limit.
+ */
+interface QueryFilters {
+    readonly event_type?: string | null;
+    readonly actor_id?: string | null;
+    readonly tenant_id?: string | null;
+    readonly trace_id?: string | null;
+    readonly session_id?: string | null;
+    readonly from_time?: string | null;
+    readonly to_time?: string | null;
+    readonly limit?: number;
+    readonly cursor?: string | null;
+}
+/** Result of a query operation.
+ *
+ * Contains the matching events and an optional cursor for pagination.
+ */
+interface QueryResult {
+    readonly events: TrailEvent[];
+    readonly next_cursor: string | null;
+}
+/** Result of a chain verification operation.
+ *
+ * intact is true when the entire chain is valid.
+ * broken contains the indices of events with invalid hashes.
+ */
+interface VerifyResult {
+    readonly intact: boolean;
+    readonly total: number;
+    readonly broken: number[];
+}
+
+/**
+ * Abstract store interface for trail events.
+ */
+
+/**
+ * Append-only storage backend for trail events.
+ *
+ * All store implementations must implement these five methods.
+ * Stores are append-only — events cannot be modified or deleted.
+ */
+interface TrailStore {
+    /** Append a single event to the store. */
+    append(event: TrailEvent): void;
+    /** Return all events in insertion order. */
+    readAll(): TrailEvent[];
+    /** Query events with optional filters and pagination. */
+    query(filters: QueryFilters): QueryResult;
+    /** Return the hash of the most recent event, or genesis hash if empty. */
+    lastHash(): string;
+    /** Return the total number of stored events. */
+    count(): number;
+}
+
+/**
+ * Trailproof facade class — the main public API.
+ */
+
+/** Options for constructing a Trailproof instance. */
+interface TrailproofOptions {
+    /** Store type — "memory" (default) or "jsonl". */
+    store?: string;
+    /** File path for JSONL store. Required when store="jsonl". */
+    path?: string;
+    /** Optional HMAC-SHA256 key for event signing. */
+    signingKey?: string;
+    /** Default tenant_id used when emit() is called without one. */
+    defaultTenantId?: string;
+}
+/** Options for querying events. */
+interface QueryOptions {
+    /** Filter by exact event type match. */
+    eventType?: string;
+    /** Filter by exact actor ID match. */
+    actorId?: string;
+    /** Filter by exact tenant ID match. */
+    tenantId?: string;
+    /** Filter by exact trace ID match. */
+    traceId?: string;
+    /** Filter by exact session ID match. */
+    sessionId?: string;
+    /** Include events at or after this ISO-8601 timestamp. */
+    fromTime?: string;
+    /** Include events at or before this ISO-8601 timestamp. */
+    toTime?: string;
+    /** Maximum number of events to return (default 100). */
+    limit?: number;
+    /** Resume pagination from this event_id. */
+    cursor?: string;
+}
+/** Options for emitting a new event. */
+interface EmitOptions {
+    /** Namespaced event type (e.g., "memproof.memory.write"). */
+    eventType: string;
+    /** Who performed the action. */
+    actorId: string;
+    /** Domain-specific data (stored opaquely). */
+    payload: Record<string, unknown>;
+    /** Tenant/org isolation key. Falls back to defaultTenantId. */
+    tenantId?: string;
+    /** Optional cross-system correlation ID. */
+    traceId?: string;
+    /** Optional session grouping ID. */
+    sessionId?: string;
+}
+/**
+ * Tamper-evident audit trail using hash chains and optional HMAC signing.
+ *
+ * The main entry point for recording, querying, and verifying events.
+ */
+declare class Trailproof {
+    /** @internal */
+    readonly _store: TrailStore;
+    private readonly _signingKey;
+    private readonly defaultTenantId;
+    constructor(options?: TrailproofOptions);
+    /**
+     * Record a new event in the audit trail.
+     *
+     * Validates required fields, generates event_id and timestamp,
+     * computes the hash chain link, and appends to the store.
+     */
+    emit(options: EmitOptions): TrailEvent;
+    /**
+     * Query events with optional filters and cursor pagination.
+     *
+     * All filter parameters are optional. No filters returns all events
+     * up to the limit.
+     */
+    query(options?: QueryOptions): QueryResult;
+    /**
+     * Return all events with the given trace_id, ordered by timestamp.
+     */
+    getTrace(traceId: string): TrailEvent[];
+    /**
+     * Verify the integrity of the entire hash chain.
+     *
+     * Walks every event and recomputes its hash. If any event's hash
+     * does not match, that index and all subsequent indices are reported
+     * as broken (cascading breaks).
+     */
+    verify(): VerifyResult;
+    /**
+     * Flush any buffered data to the underlying store.
+     *
+     * For MemoryStore this is a no-op.
+     */
+    flush(): void;
+    private validateRequired;
+}
+
+export { ChainError, type EmitOptions, type QueryFilters, type QueryOptions, type QueryResult, SignatureError, StoreError, type TrailEvent, Trailproof, TrailproofError, type TrailproofOptions, ValidationError, type VerifyResult };

package/dist/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Trailproof error hierarchy.
+ */
+/** Base error for all Trailproof operations. */
+declare class TrailproofError extends Error {
+    constructor(message: string);
+}
+/** Raised when event data is invalid (missing or empty required fields). */
+declare class ValidationError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when a storage operation fails (disk, permissions, corruption). */
+declare class StoreError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when the hash chain is broken. */
+declare class ChainError extends TrailproofError {
+    constructor(message: string);
+}
+/** Raised when HMAC signature verification fails. */
+declare class SignatureError extends TrailproofError {
+    constructor(message: string);
+}
+
+/**
+ * Trailproof core data types.
+ */
+/** A single event in the audit trail.
+ *
+ * Contains the 10-field event envelope. Domain-specific data
+ * goes in the payload field, which Trailproof stores opaquely.
+ *
+ * Field names use snake_case to match the wire format.
+ */
+interface TrailEvent {
+    readonly event_id: string;
+    readonly event_type: string;
+    readonly timestamp: string;
+    readonly actor_id: string;
+    readonly tenant_id: string;
+    readonly payload: Record<string, unknown>;
+    readonly prev_hash: string;
+    readonly hash: string;
+    readonly trace_id?: string | null;
+    readonly session_id?: string | null;
+    readonly signature?: string | null;
+}
+/** Filters for querying events from a store.
+ *
+ * All fields are optional. No filters returns all events up to limit.
+ */
+interface QueryFilters {
+    readonly event_type?: string | null;
+    readonly actor_id?: string | null;
+    readonly tenant_id?: string | null;
+    readonly trace_id?: string | null;
+    readonly session_id?: string | null;
+    readonly from_time?: string | null;
+    readonly to_time?: string | null;
+    readonly limit?: number;
+    readonly cursor?: string | null;
+}
+/** Result of a query operation.
+ *
+ * Contains the matching events and an optional cursor for pagination.
+ */
+interface QueryResult {
+    readonly events: TrailEvent[];
+    readonly next_cursor: string | null;
+}
+/** Result of a chain verification operation.
+ *
+ * intact is true when the entire chain is valid.
+ * broken contains the indices of events with invalid hashes.
+ */
+interface VerifyResult {
+    readonly intact: boolean;
+    readonly total: number;
+    readonly broken: number[];
+}
+
+/**
+ * Abstract store interface for trail events.
+ */
+
+/**
+ * Append-only storage backend for trail events.
+ *
+ * All store implementations must implement these five methods.
+ * Stores are append-only — events cannot be modified or deleted.
+ */
+interface TrailStore {
+    /** Append a single event to the store. */
+    append(event: TrailEvent): void;
+    /** Return all events in insertion order. */
+    readAll(): TrailEvent[];
+    /** Query events with optional filters and pagination. */
+    query(filters: QueryFilters): QueryResult;
+    /** Return the hash of the most recent event, or genesis hash if empty. */
+    lastHash(): string;
+    /** Return the total number of stored events. */
+    count(): number;
+}
+
+/**
+ * Trailproof facade class — the main public API.
+ */
+
+/** Options for constructing a Trailproof instance. */
+interface TrailproofOptions {
+    /** Store type — "memory" (default) or "jsonl". */
+    store?: string;
+    /** File path for JSONL store. Required when store="jsonl". */
+    path?: string;
+    /** Optional HMAC-SHA256 key for event signing. */
+    signingKey?: string;
+    /** Default tenant_id used when emit() is called without one. */
+    defaultTenantId?: string;
+}
+/** Options for querying events. */
+interface QueryOptions {
+    /** Filter by exact event type match. */
+    eventType?: string;
+    /** Filter by exact actor ID match. */
+    actorId?: string;
+    /** Filter by exact tenant ID match. */
+    tenantId?: string;
+    /** Filter by exact trace ID match. */
+    traceId?: string;
+    /** Filter by exact session ID match. */
+    sessionId?: string;
+    /** Include events at or after this ISO-8601 timestamp. */
+    fromTime?: string;
+    /** Include events at or before this ISO-8601 timestamp. */
+    toTime?: string;
+    /** Maximum number of events to return (default 100). */
+    limit?: number;
+    /** Resume pagination from this event_id. */
+    cursor?: string;
+}
+/** Options for emitting a new event. */
+interface EmitOptions {
+    /** Namespaced event type (e.g., "memproof.memory.write"). */
+    eventType: string;
+    /** Who performed the action. */
+    actorId: string;
+    /** Domain-specific data (stored opaquely). */
+    payload: Record<string, unknown>;
+    /** Tenant/org isolation key. Falls back to defaultTenantId. */
+    tenantId?: string;
+    /** Optional cross-system correlation ID. */
+    traceId?: string;
+    /** Optional session grouping ID. */
+    sessionId?: string;
+}
+/**
+ * Tamper-evident audit trail using hash chains and optional HMAC signing.
+ *
+ * The main entry point for recording, querying, and verifying events.
+ */
+declare class Trailproof {
+    /** @internal */
+    readonly _store: TrailStore;
+    private readonly _signingKey;
+    private readonly defaultTenantId;
+    constructor(options?: TrailproofOptions);
+    /**
+     * Record a new event in the audit trail.
+     *
+     * Validates required fields, generates event_id and timestamp,
+     * computes the hash chain link, and appends to the store.
+     */
+    emit(options: EmitOptions): TrailEvent;
+    /**
+     * Query events with optional filters and cursor pagination.
+     *
+     * All filter parameters are optional. No filters returns all events
+     * up to the limit.
+     */
+    query(options?: QueryOptions): QueryResult;
+    /**
+     * Return all events with the given trace_id, ordered by timestamp.
+     */
+    getTrace(traceId: string): TrailEvent[];
+    /**
+     * Verify the integrity of the entire hash chain.
+     *
+     * Walks every event and recomputes its hash. If any event's hash
+     * does not match, that index and all subsequent indices are reported
+     * as broken (cascading breaks).
+     */
+    verify(): VerifyResult;
+    /**
+     * Flush any buffered data to the underlying store.
+     *
+     * For MemoryStore this is a no-op.
+     */
+    flush(): void;
+    private validateRequired;
+}
+
+export { ChainError, type EmitOptions, type QueryFilters, type QueryOptions, type QueryResult, SignatureError, StoreError, type TrailEvent, Trailproof, TrailproofError, type TrailproofOptions, ValidationError, type VerifyResult };