@moonglade/provenance 0.0.0-stage → 2.6.0

package/dist/timestamp.d.ts

@@ -0,0 +1,274 @@
+/** RFC 3161 signature/imprint checks and optional caller-anchored chain validation.
+ * Acquisition probe tiers describe routing; only verified tokens supply timestamp evidence.
+ * Revocation checking is outside this implementation.
+ */
+export interface TSAProbeResult {
+    tier: 'L1_CRYPTO_PRIMARY' | 'L2_CRYPTO_FALLBACK' | 'L3_NETWORK_CONSENSUS' | 'L4_HOST_UNAUTHENTICATED';
+    method: 'RFC3161' | 'HTTP_DATE' | 'KERNEL_UTC';
+    server: string;
+    status: 'SUCCESS' | 'ERROR' | 'TIMEOUT';
+    timestamp_iso?: string;
+    token_b64?: string;
+    token_bytes?: Buffer;
+    error?: string;
+}
+export interface DTAResult {
+    tier: 'INTEGRITY_ONLY' | 'L3_NETWORK_CONSENSUS' | 'L4_HOST_UNAUTHENTICATED';
+    tsa?: string;
+    tsa_time: string;
+    token_b64?: string;
+    token_bytes?: Buffer;
+    probes: TSAProbeResult[];
+}
+export interface DTAOptions {
+    /** If specified, bypasses multi-tier fanout and queries only this specific TSA server URL or network host */
+    specifiedServer?: string;
+    /** If specified, restricts queries to this tier only */
+    specifiedTier?: 'L1_CRYPTO_PRIMARY' | 'L2_CRYPTO_FALLBACK' | 'L3_NETWORK_CONSENSUS' | 'L4_HOST_UNAUTHENTICATED';
+    /**
+     * Number of probes to simultaneously seek from each tier (default: 1 for the TSA tiers,
+     * min(3, distinct hosts) for the L3 network tier, because one probe can never reach quorum)
+     */
+    probesPerTier?: number;
+    /** Whether to rotate through available endpoints (default: true) */
+    rotate?: boolean;
+    primaryEndpoints?: string[];
+    fallbackEndpoints?: string[];
+    networkEndpoints?: string[];
+    timeoutMs?: number;
+    certReq?: boolean;
+    nonce?: Buffer | bigint;
+    circuitBreaker?: EndpointCircuitBreaker;
+    maxParallelProbes?: number;
+    /**
+     * Distinct agreeing network hosts needed for L3_NETWORK_CONSENSUS (default 2). A single host
+     * is never L3 unless this is explicitly set to 1.
+     */
+    quorumThreshold?: number;
+    /** Maximum spread between the earliest and latest L3 probe, in milliseconds (default 3000). */
+    maxDriftMs?: number;
+}
+export interface TierEndpointConfig {
+    default: string;
+    fallbacks: string[];
+}
+export declare const TIER_CONFIGS: {
+    L1: TierEndpointConfig;
+    L2: TierEndpointConfig;
+    L3: TierEndpointConfig;
+};
+export declare const DEFAULT_PRIMARY_TSAS: string[];
+export declare const DEFAULT_FALLBACK_TSAS: string[];
+export declare const DEFAULT_NETWORK_HOSTS: string[];
+export interface ServerPolicy {
+    url: string;
+    name: string;
+    tier: 'L1_CRYPTO_PRIMARY' | 'L2_CRYPTO_FALLBACK' | 'L3_NETWORK_CONSENSUS';
+    /** Minimum interval in ms between consecutive requests to this endpoint (rate-limit compliance) */
+    minIntervalMs: number;
+}
+export declare const DEFAULT_SERVER_POLICIES: ServerPolicy[];
+export interface EndpointHealth {
+    url?: string;
+    name?: string;
+    consecutiveFailures: number;
+    nextAvailableTime: number;
+    lastRequestTime?: number;
+    lastSuccessTime?: number;
+    lastError?: string;
+}
+export interface ServerStatusSnapshot {
+    url: string;
+    name?: string;
+    status: 'READY' | 'COOLDOWN' | 'BACKOFF';
+    consecutiveFailures: number;
+    remainingCooldownMs: number;
+    lastError?: string;
+}
+/**
+ * Circuit breaker & Server Pool Manager.
+ * Manages:
+ * 1. Endpoint health and consecutive failure tracking
+ * 2. Exponential backoff for failing/down servers
+ * 3. Individual server policies (e.g. FreeTSA 15s rate-limit cooldown)
+ * 4. Fair round-robin rotation queue ("who's next")
+ * 5. Telemetry for ready vs disabled/cooldown servers
+ */
+export declare class EndpointCircuitBreaker {
+    private health;
+    private policies;
+    private queuePointers;
+    readonly baseBackoffMs: number;
+    readonly maxBackoffMs: number;
+    constructor(options?: {
+        baseBackoffMs?: number;
+        maxBackoffMs?: number;
+        policies?: ServerPolicy[];
+    });
+    getPolicy(url: string): ServerPolicy;
+    setPolicy(policy: ServerPolicy): void;
+    isAvailable(url: string, now?: number): boolean;
+    getServerStatus(url: string, now?: number): 'READY' | 'COOLDOWN' | 'BACKOFF';
+    recordRequest(url: string, now?: number): void;
+    recordSuccess(url: string, now?: number): void;
+    recordFailure(url: string, error: string, now?: number): number;
+    getHealth(url: string): EndpointHealth | undefined;
+    reset(): void;
+    /**
+     * Return ordered candidate queue starting with "who's next".
+     */
+    getQueue(urls: string[], queueKey?: string): string[];
+    /**
+     * Return servers currently on cooldown or in failure backoff.
+     */
+    getDisabledEndpoints(urls: string[], now?: number): ServerStatusSnapshot[];
+    /**
+     * Return servers currently READY to serve requests immediately.
+     */
+    getReadyEndpoints(urls: string[], now?: number): ServerStatusSnapshot[];
+    /**
+     * Fair rotating endpoint selection.
+     * Cycles through the array in round-robin order, picking healthy/available endpoints,
+     * skipping those in failure backoff or policy cooldown, and advancing the queue pointer.
+     */
+    selectRotatingEndpoints(urls: string[], count?: number, queueKey?: string, now?: number): string[];
+    /**
+     * Prioritized selection (used for targeted or non-rotating requests).
+     */
+    selectEndpoints(urls: string[], maxCount?: number, now?: number): string[];
+}
+export declare const globalCircuitBreaker: EndpointCircuitBreaker;
+/**
+ * Helper to encode ASN.1 DER length octets.
+ */
+export declare function encodeDerLength(len: number): Buffer;
+/**
+ * Helper to wrap elements in an ASN.1 DER SEQUENCE (tag 0x30).
+ */
+export declare function encodeDerSequence(items: Buffer[]): Buffer;
+/**
+ * Helper to decode ASN.1 DER length octets from a buffer at a given offset.
+ * Returns the parsed length and the number of octets consumed by the length header.
+ */
+export declare function decodeDerLength(buf: Buffer, offset: number): {
+    length: number;
+    headerLength: number;
+};
+export declare const PKI_STATUS_TEXT: Record<number, string>;
+export interface ValidateTimeStampRespOptions {
+    expectedDigest?: Buffer;
+    expectedNonce?: Buffer | bigint;
+}
+export interface ValidationResultRFC3161 {
+    valid: boolean;
+    status: number;
+    statusText: string;
+    error?: string;
+    genTime?: string;
+}
+/**
+ * Parse the RFC 3161 PKIStatusInfo integer code from TimeStampResp.
+ * RFC 3161 §2.4.2:
+ *   TimeStampResp ::= SEQUENCE {
+ *      status            PKIStatusInfo,
+ *      timeStampToken    TimeStampToken     OPTIONAL
+ *   }
+ *   PKIStatusInfo ::= SEQUENCE {
+ *      status        PKIStatus,
+ *      statusString  PKIFreeText     OPTIONAL,
+ *      failInfo      PKIFailureInfo  OPTIONAL
+ *   }
+ */
+export declare function parsePkiStatus(respBuffer: Buffer): {
+    status: number;
+    statusText: string;
+};
+/**
+ * In-band RFC 3161 TimeStampResp validator.
+ * Enforces:
+ * 1. PKIStatusInfo is granted (0) or grantedWithMods (1)
+ * 2. TimeStampToken presence
+ * 3. MessageImprint digest equality (asserts TSA stamped the exact requested file hash)
+ * 4. Cryptographic nonce echo match (asserts replay attack protection)
+ */
+export declare function validateTimeStampResp(respBuffer: Buffer, options?: ValidateTimeStampRespOptions): ValidationResultRFC3161;
+export interface TimestampTokenVerificationResult {
+    verified: boolean;
+    signerVerified?: boolean;
+    trusted?: boolean;
+    trust?: 'ANCHORED' | 'INTEGRITY_ONLY';
+    signerSubject?: string;
+    genTime?: string;
+    error?: string;
+}
+/**
+ * Cryptographically verifies an RFC 3161 TimeStampToken or TimeStampResp buffer using PKI.js.
+ * Validates CMS SignedData signature over signedAttrs (including 0x31 SET OF re-encoding),
+ * confirms message-digest matches the encapsulated TSTInfo, and asserts the stamped
+ * document digest matches documentBytes.
+ */
+export declare function verifyTimeStampToken(tsrBuffer: Buffer, documentBytes: Buffer, options?: {
+    trustAnchors?: string[];
+    expectedDigest?: Buffer;
+}): Promise<TimestampTokenVerificationResult>;
+/**
+ * Build an RFC 3161 TimeStampReq ASN.1 DER structure.
+ * RFC 3161 §2.4.1:
+ *   TimeStampReq ::= SEQUENCE {
+ *      version          INTEGER { v1(1) },
+ *      messageImprint   MessageImprint,
+ *      nonce            INTEGER OPTIONAL,
+ *      certReq          BOOLEAN DEFAULT FALSE
+ *   }
+ */
+export declare function buildTimeStampReq(sha256Digest: Buffer, options?: {
+    certReq?: boolean;
+    nonce?: Buffer | bigint;
+}): Buffer;
+/**
+ * Extract GeneralizedTime (tag 0x18) from ASN.1 DER TimeStampResp buffer.
+ * Returns ISO 8601 formatted string or null if not found.
+ */
+export declare function extractGenTime(tsrBuffer: Buffer): string | null;
+/**
+ * Execute HTTP POST query to an RFC 3161 TSA endpoint.
+ */
+export declare function queryTsa(tsaUrl: string, tsqBuffer: Buffer, timeoutMs?: number): Promise<Buffer>;
+/**
+ * Probe a single TSA server and return a structured telemetry record.
+ * Automatically performs in-band RFC 3161 verification on successful responses:
+ * - Checks PKIStatus is granted (0) or grantedWithMods (1)
+ * - Verifies TimeStampToken exists
+ * - Asserts messageImprint digest matches expectedDigest (if provided)
+ * - Asserts returned nonce matches expectedNonce (if provided)
+ */
+export declare function probeTsa(tsaUrl: string, tsqBuffer: Buffer, tier: 'L1_CRYPTO_PRIMARY' | 'L2_CRYPTO_FALLBACK', timeoutMs?: number, expectedDigest?: Buffer, expectedNonce?: Buffer | bigint, circuitBreaker?: EndpointCircuitBreaker): Promise<TSAProbeResult>;
+/**
+ * Parse an RFC 7231 section 7.1.1.1 HTTP-date: IMF-fixdate, or the obsolete RFC 850 and asctime
+ * forms a recipient must still accept. The grammar is case-sensitive, the day name must agree
+ * with the date, and the date must exist (no 31 February, no 24:00:00, no leap second).
+ * Returns epoch milliseconds, or null for anything else - including ISO-8601 and bare numbers
+ * that `new Date(...)` would happily accept.
+ */
+export declare function parseHttpDate(value: string, now?: number): number | null;
+/**
+ * Probe network time via HTTP Date header. The header must be an RFC 7231 HTTP-date.
+ */
+export declare function probeNetworkTime(host: string, timeoutMs?: number): Promise<TSAProbeResult>;
+/**
+ * Evaluates whether successful L3 network probes form a Byzantine-tolerant quorum.
+ * Requirements:
+ * 1. At least 2 successful HTTP Date probes (or >= quorumThreshold).
+ * 2. Absolute time drift between min and max probe timestamps is within maxDriftMs (default: 3000ms).
+ * Returns the median timestamp and participating servers if quorum is reached, otherwise null.
+ */
+export declare function resolveNetworkConsensus(probes: TSAProbeResult[], quorumThreshold?: number, maxDriftMs?: number): {
+    consensusTime: string;
+    server: string;
+} | null;
+/**
+ * Execute Concurrent Multi-Source Degrading Timestamping Architecture (DTA) fan-out.
+ * Default pattern: simultaneously seeks 1 probe from each tier (L1, L2, L3, L4).
+ * If specifiedServer or specifiedTier is requested, executes targeted query instead.
+ */
+export declare function concurrentDegradingTimestamp(sha256Digest: Buffer, options?: DTAOptions): Promise<DTAResult>;