openttt 0.2.12 → 0.2.13

package/dist/integrity_client.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Integrity Client — replaces local integrity computation with server-side API call.
+ * Core pipeline source code stays in Helm private repo. Only API calls go through npm SDK.
+ *
+ * Drop-in replacement interface for local encode() and verify() operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrityClient = void 0;
+exports.getDefaultIntegrityClient = getDefaultIntegrityClient;
+exports.setDefaultIntegrityClient = setDefaultIntegrityClient;
+class IntegrityClient {
+    baseUrl;
+    timeoutMs;
+    apiKey;
+    constructor(baseUrl = "https://integrity.helmprotocol.com/api/v1", options) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.timeoutMs = options?.timeoutMs ?? 5000;
+        this.apiKey = options?.apiKey ?? (typeof process !== "undefined" ? process.env["INTEGRITY_API_KEY"] : undefined);
+    }
+    /**
+     * Forward pass: encode data through integrity pipeline (server-side).
+     *
+     * @returns Array of Uint8Array shards
+     */
+    async encode(data, chainId, poolAddress) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/encode`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(this.apiKey ? { "X-Integrity-Key": this.apiKey } : {}),
+                },
+                body: JSON.stringify({
+                    data: Buffer.from(data).toString("hex"),
+                    chainId: chainId,
+                    poolAddress,
+                }),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new Error(`Integrity API error: ${resp.status} ${resp.statusText}`);
+            }
+            const result = await resp.json();
+            return result.shards.map((hex) => Buffer.from(hex, "hex"));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Verify: check data integrity (server-side).
+     *
+     * @returns boolean — true if data matches the original shards
+     */
+    async verify(data, originalShards, chainId, poolAddress) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/verify`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(this.apiKey ? { "X-Integrity-Key": this.apiKey } : {}),
+                },
+                body: JSON.stringify({
+                    data: Buffer.from(data).toString("hex"),
+                    shards: originalShards.map((s) => Buffer.from(s).toString("hex")),
+                    chainId: chainId,
+                    poolAddress,
+                }),
+                signal: controller.signal,
+            });
+            if (!resp.ok) {
+                throw new Error(`Integrity API error: ${resp.status} ${resp.statusText}`);
+            }
+            const result = await resp.json();
+            return result.valid;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Health check — ping the integrity API server.
+     * Returns true if reachable within timeoutMs.
+     */
+    async isReachable() {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const resp = await fetch(`${this.baseUrl}/health`, {
+                method: "GET",
+                signal: controller.signal,
+            });
+            return resp.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.IntegrityClient = IntegrityClient;
+/**
+ * Singleton default client — uses production integrity API endpoint.
+ * Can be overridden via setDefaultIntegrityClient() for testing/staging.
+ */
+let _defaultClient = null;
+function getDefaultIntegrityClient() {
+    if (!_defaultClient) {
+        _defaultClient = new IntegrityClient();
+    }
+    return _defaultClient;
+}
+function setDefaultIntegrityClient(client) {
+    _defaultClient = client;
+}

package/dist/osnma_source.d.ts

@@ -0,0 +1,82 @@
+/**
+ * OSNMA (Galileo Open Service Navigation Message Authentication) Time Source
+ *
+ * Integrates Galileo OSNMA public key verification into the TTT SDK TimeSource interface.
+ * OSNMA provides satellite-grade time authentication via ECDSA P-256/SHA-256.
+ *
+ * Key data sourced from GSC Europa portal (gsc-europa.eu):
+ *   - PKID: 2, point: 02219204B5CA6C46B623EEED6CDD2CDDB1F7D6A7532767E5B8DA0DE1EBD695FC99
+ *   - Merkle Tree root: 7B944FA20915C7931D48DD016D94F9C6381FD37DC6C125D97015272FDDE41393
+ *   - Hash function: SHA-256, N=16
+ *   - Applicability: 2025-12-10T10:00:00Z
+ *
+ * SECURITY MODEL:
+ *   - Public key is hardcoded from GSC portal (authenticated via EUSPA PKI chain)
+ *   - Merkle tree root anchors the key — any key change requires new root proof
+ *   - Stratum is set to 1 (satellite direct, equivalent to GPS timing receiver)
+ *   - Uncertainty: 50ms base (conservative — actual Galileo timing is ±100ns,
+ *     but edge SDK without hardware PPS uses NTP-level cross-check)
+ */
+import { TimeReading } from './types';
+import { TimeSource } from './time_synthesis';
+export interface OsnmaKeyMaterial {
+    pkid: number;
+    publicKeyHex: string;
+    merkleRootHex: string;
+    hashFunction: string;
+    applicabilityMs: number;
+}
+export interface OsnmaVerificationResult {
+    valid: boolean;
+    pkid: number;
+    merkleRootHex: string;
+    keyFingerprint: string;
+    applicabilityMs: number;
+    checkedAt: number;
+}
+/**
+ * Verifies OSNMA key material integrity:
+ * 1. Public key point length (compressed P-256 = 33 bytes)
+ * 2. Merkle root length (SHA-256 = 32 bytes)
+ * 3. Applicability date is in the past (key is active)
+ * 4. Computes key fingerprint for audit trail
+ */
+export declare function verifyOsnmaKeyMaterial(key: OsnmaKeyMaterial): OsnmaVerificationResult;
+/**
+ * OsnmaTimeSource — implements TimeSource interface for TimeSynthesis integration.
+ *
+ * In a full hardware integration, this would parse OSNMA navigation messages
+ * from a Galileo receiver and verify the TESLA chain + ECDSA signature.
+ *
+ * In this edge SDK integration:
+ *   - Key material is verified against the hardcoded GSC anchor
+ *   - Time is sourced from system clock (same as HTTPS sources)
+ *   - Stratum is set to 1 to reflect satellite-grade authority
+ *   - This establishes the OSNMA trust anchor in the SDK trust chain,
+ *     ready for hardware receiver integration (UART/SPI/USB NMEA feed)
+ */
+export declare class OsnmaTimeSource implements TimeSource {
+    readonly name = "osnma";
+    private keyMaterial;
+    private verificationResult;
+    constructor(keyMaterial?: Partial<OsnmaKeyMaterial>);
+    /**
+     * Verifies key material and returns a TimeReading.
+     * Stratum 1 — satellite-grade authority.
+     * Uncertainty 50ms — conservative edge estimate without hardware PPS.
+     */
+    getTime(): Promise<TimeReading>;
+    /**
+     * Returns the verified key material for audit/logging.
+     */
+    getVerificationResult(): OsnmaVerificationResult | null;
+    /**
+     * Returns the raw key material (public key hex, merkle root, pkid).
+     */
+    getKeyMaterial(): Readonly<OsnmaKeyMaterial>;
+}
+/**
+ * Default OSNMA key material from GSC Europa portal.
+ * PKID=2, applicable from 2025-12-10T10:00:00Z.
+ */
+export declare const DEFAULT_OSNMA_KEY: OsnmaKeyMaterial;

package/dist/osnma_source.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * OSNMA (Galileo Open Service Navigation Message Authentication) Time Source
+ *
+ * Integrates Galileo OSNMA public key verification into the TTT SDK TimeSource interface.
+ * OSNMA provides satellite-grade time authentication via ECDSA P-256/SHA-256.
+ *
+ * Key data sourced from GSC Europa portal (gsc-europa.eu):
+ *   - PKID: 2, point: 02219204B5CA6C46B623EEED6CDD2CDDB1F7D6A7532767E5B8DA0DE1EBD695FC99
+ *   - Merkle Tree root: 7B944FA20915C7931D48DD016D94F9C6381FD37DC6C125D97015272FDDE41393
+ *   - Hash function: SHA-256, N=16
+ *   - Applicability: 2025-12-10T10:00:00Z
+ *
+ * SECURITY MODEL:
+ *   - Public key is hardcoded from GSC portal (authenticated via EUSPA PKI chain)
+ *   - Merkle tree root anchors the key — any key change requires new root proof
+ *   - Stratum is set to 1 (satellite direct, equivalent to GPS timing receiver)
+ *   - Uncertainty: 50ms base (conservative — actual Galileo timing is ±100ns,
+ *     but edge SDK without hardware PPS uses NTP-level cross-check)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OSNMA_KEY = exports.OsnmaTimeSource = void 0;
+exports.verifyOsnmaKeyMaterial = verifyOsnmaKeyMaterial;
+const crypto = __importStar(require("crypto"));
+const errors_1 = require("./errors");
+// OSNMA Public Key — ECDSA P-256, PKID=2
+// Sourced from GSC Europa OSNMA/PKI, applicability: 2025-12-10T10:00:00Z
+const OSNMA_PUBLIC_KEY_HEX = '02219204B5CA6C46B623EEED6CDD2CDDB1F7D6A7532767E5B8DA0DE1EBD695FC99';
+const OSNMA_MERKLE_ROOT_HEX = '7B944FA20915C7931D48DD016D94F9C6381FD37DC6C125D97015272FDDE41393';
+const OSNMA_PKID = 2;
+const OSNMA_HASH_FUNCTION = 'SHA-256';
+const OSNMA_APPLICABILITY = new Date('2025-12-10T10:00:00Z').getTime();
+/**
+ * Verifies OSNMA key material integrity:
+ * 1. Public key point length (compressed P-256 = 33 bytes)
+ * 2. Merkle root length (SHA-256 = 32 bytes)
+ * 3. Applicability date is in the past (key is active)
+ * 4. Computes key fingerprint for audit trail
+ */
+function verifyOsnmaKeyMaterial(key) {
+    const pubKeyBytes = Buffer.from(key.publicKeyHex, 'hex');
+    if (pubKeyBytes.length !== 33) {
+        throw new errors_1.TTTTimeSynthesisError('OSNMA_KEY_LENGTH_INVALID', `Public key must be 33 bytes (compressed P-256), got ${pubKeyBytes.length}`, 'Check OSNMA key format from GSC Europa portal');
+    }
+    // Compressed point prefix must be 02 or 03
+    if (pubKeyBytes[0] !== 0x02 && pubKeyBytes[0] !== 0x03) {
+        throw new errors_1.TTTTimeSynthesisError('OSNMA_KEY_PREFIX_INVALID', `Compressed P-256 point must start with 02 or 03, got ${pubKeyBytes[0].toString(16)}`, 'OSNMA public key is not a valid compressed EC point');
+    }
+    const merkleBytes = Buffer.from(key.merkleRootHex, 'hex');
+    if (merkleBytes.length !== 32) {
+        throw new errors_1.TTTTimeSynthesisError('OSNMA_MERKLE_LENGTH_INVALID', `Merkle root must be 32 bytes (SHA-256), got ${merkleBytes.length}`, 'Check OSNMA Merkle Tree XML from GSC Europa portal');
+    }
+    const now = Date.now();
+    if (now < key.applicabilityMs) {
+        throw new errors_1.TTTTimeSynthesisError('OSNMA_KEY_NOT_YET_APPLICABLE', `Key PKID=${key.pkid} not applicable until ${new Date(key.applicabilityMs).toISOString()}`, 'Use a key with an applicability date in the past');
+    }
+    // SHA-256 fingerprint of the raw public key bytes
+    const fingerprint = crypto.createHash('sha256').update(pubKeyBytes).digest('hex');
+    return {
+        valid: true,
+        pkid: key.pkid,
+        merkleRootHex: key.merkleRootHex,
+        keyFingerprint: fingerprint,
+        applicabilityMs: key.applicabilityMs,
+        checkedAt: now,
+    };
+}
+/**
+ * OsnmaTimeSource — implements TimeSource interface for TimeSynthesis integration.
+ *
+ * In a full hardware integration, this would parse OSNMA navigation messages
+ * from a Galileo receiver and verify the TESLA chain + ECDSA signature.
+ *
+ * In this edge SDK integration:
+ *   - Key material is verified against the hardcoded GSC anchor
+ *   - Time is sourced from system clock (same as HTTPS sources)
+ *   - Stratum is set to 1 to reflect satellite-grade authority
+ *   - This establishes the OSNMA trust anchor in the SDK trust chain,
+ *     ready for hardware receiver integration (UART/SPI/USB NMEA feed)
+ */
+class OsnmaTimeSource {
+    name = 'osnma';
+    keyMaterial;
+    verificationResult = null;
+    constructor(keyMaterial) {
+        this.keyMaterial = {
+            pkid: keyMaterial?.pkid ?? OSNMA_PKID,
+            publicKeyHex: keyMaterial?.publicKeyHex ?? OSNMA_PUBLIC_KEY_HEX,
+            merkleRootHex: keyMaterial?.merkleRootHex ?? OSNMA_MERKLE_ROOT_HEX,
+            hashFunction: keyMaterial?.hashFunction ?? OSNMA_HASH_FUNCTION,
+            applicabilityMs: keyMaterial?.applicabilityMs ?? OSNMA_APPLICABILITY,
+        };
+    }
+    /**
+     * Verifies key material and returns a TimeReading.
+     * Stratum 1 — satellite-grade authority.
+     * Uncertainty 50ms — conservative edge estimate without hardware PPS.
+     */
+    async getTime() {
+        // Verify key material on first call (or re-verify if not yet done)
+        if (!this.verificationResult) {
+            this.verificationResult = verifyOsnmaKeyMaterial(this.keyMaterial);
+        }
+        const timestamp = BigInt(Date.now()) * 1000000n; // ns
+        return {
+            timestamp,
+            uncertainty: 50, // 50ms conservative edge estimate
+            stratum: 1, // satellite-grade (equivalent to GPS timing)
+            source: 'osnma',
+        };
+    }
+    /**
+     * Returns the verified key material for audit/logging.
+     */
+    getVerificationResult() {
+        return this.verificationResult;
+    }
+    /**
+     * Returns the raw key material (public key hex, merkle root, pkid).
+     */
+    getKeyMaterial() {
+        return { ...this.keyMaterial };
+    }
+}
+exports.OsnmaTimeSource = OsnmaTimeSource;
+/**
+ * Default OSNMA key material from GSC Europa portal.
+ * PKID=2, applicable from 2025-12-10T10:00:00Z.
+ */
+exports.DEFAULT_OSNMA_KEY = {
+    pkid: OSNMA_PKID,
+    publicKeyHex: OSNMA_PUBLIC_KEY_HEX,
+    merkleRootHex: OSNMA_MERKLE_ROOT_HEX,
+    hashFunction: OSNMA_HASH_FUNCTION,
+    applicabilityMs: OSNMA_APPLICABILITY,
+};

package/dist/pot_frame.d.ts

@@ -0,0 +1,59 @@
+/**
+ * pot_frame.ts — TTTPS PoT Frame encoder/decoder
+ *
+ * Wire format per draft-helmprotocol-tttps-02 Section 7.1:
+ *
+ *   +----------------------------------+
+ *   |  binding_key  (32 bytes)         |  ← TLS Exporter output
+ *   +----------------------------------+
+ *   |  pot_record   (143 bytes)        |  ← Section 4.1
+ *   |    Version[1] Tier[1] Res[1]     |
+ *   |    Timestamp[8]                  |
+ *   |    Confidence[4]                 |
+ *   |    Nonce[32]                     |
+ *   |    GRGCommit[32]                 |
+ *   |    Ed25519Sig[64]                |
+ *   +----------------------------------+
+ *   Total: 175 bytes
+ *
+ * pot_record_without_sig = first 79 bytes of pot_record
+ * (used as TLS Exporter context)
+ */
+export declare const POT_RECORD_SIZE = 143;
+export declare const POT_WITHOUT_SIG_SIZE = 79;
+export declare const BINDING_KEY_SIZE = 32;
+export declare const POT_FRAME_SIZE = 175;
+export interface PotFrame {
+    bindingKey: Buffer;
+    potRecord: Buffer;
+    version: number;
+    tier: number;
+    reserved: number;
+    timestamp: bigint;
+    confidence: number;
+    nonce: Buffer;
+    grgCommit: Buffer;
+    ed25519Sig: Buffer;
+}
+export declare class PotFrameError extends Error {
+    constructor(message: string);
+}
+/**
+ * Encode a PoT frame (175 bytes) from components.
+ */
+export declare function encodePotFrame(bindingKey: Buffer, potRecord: Buffer): Buffer;
+/**
+ * Decode a PoT frame (175 bytes) into components.
+ */
+export declare function decodePotFrame(frame: Buffer): PotFrame;
+/**
+ * Extract the portion of pot_record EXCLUDING the signature.
+ * This is used as the TLS Exporter context (Section 7.1).
+ * = first 79 bytes of the 143-byte pot_record
+ */
+export declare function potRecordWithoutSig(potRecord: Buffer): Buffer;
+/**
+ * Validate basic frame structure without TLS verification.
+ * (Full verification requires a TLS socket — see tls_binding.ts)
+ */
+export declare function validatePotFrameStructure(frame: Buffer): void;

package/dist/pot_frame.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * pot_frame.ts — TTTPS PoT Frame encoder/decoder
+ *
+ * Wire format per draft-helmprotocol-tttps-02 Section 7.1:
+ *
+ *   +----------------------------------+
+ *   |  binding_key  (32 bytes)         |  ← TLS Exporter output
+ *   +----------------------------------+
+ *   |  pot_record   (143 bytes)        |  ← Section 4.1
+ *   |    Version[1] Tier[1] Res[1]     |
+ *   |    Timestamp[8]                  |
+ *   |    Confidence[4]                 |
+ *   |    Nonce[32]                     |
+ *   |    GRGCommit[32]                 |
+ *   |    Ed25519Sig[64]                |
+ *   +----------------------------------+
+ *   Total: 175 bytes
+ *
+ * pot_record_without_sig = first 79 bytes of pot_record
+ * (used as TLS Exporter context)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PotFrameError = exports.POT_FRAME_SIZE = exports.BINDING_KEY_SIZE = exports.POT_WITHOUT_SIG_SIZE = exports.POT_RECORD_SIZE = void 0;
+exports.encodePotFrame = encodePotFrame;
+exports.decodePotFrame = decodePotFrame;
+exports.potRecordWithoutSig = potRecordWithoutSig;
+exports.validatePotFrameStructure = validatePotFrameStructure;
+exports.POT_RECORD_SIZE = 143; // bytes
+exports.POT_WITHOUT_SIG_SIZE = 79; // bytes (143 - 64 sig)
+exports.BINDING_KEY_SIZE = 32; // bytes
+exports.POT_FRAME_SIZE = 175; // bytes (32 + 143)
+class PotFrameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PotFrameError";
+    }
+}
+exports.PotFrameError = PotFrameError;
+/**
+ * Encode a PoT frame (175 bytes) from components.
+ */
+function encodePotFrame(bindingKey, potRecord) {
+    if (bindingKey.length !== exports.BINDING_KEY_SIZE) {
+        throw new PotFrameError(`binding_key must be ${exports.BINDING_KEY_SIZE} bytes, got ${bindingKey.length}`);
+    }
+    if (potRecord.length !== exports.POT_RECORD_SIZE) {
+        throw new PotFrameError(`pot_record must be ${exports.POT_RECORD_SIZE} bytes, got ${potRecord.length}`);
+    }
+    const frame = Buffer.allocUnsafe(exports.POT_FRAME_SIZE);
+    bindingKey.copy(frame, 0);
+    potRecord.copy(frame, exports.BINDING_KEY_SIZE);
+    return frame;
+}
+/**
+ * Decode a PoT frame (175 bytes) into components.
+ */
+function decodePotFrame(frame) {
+    if (frame.length !== exports.POT_FRAME_SIZE) {
+        throw new PotFrameError(`PoT frame must be ${exports.POT_FRAME_SIZE} bytes, got ${frame.length}`);
+    }
+    const bindingKey = frame.subarray(0, exports.BINDING_KEY_SIZE);
+    const potRecord = frame.subarray(exports.BINDING_KEY_SIZE, exports.POT_FRAME_SIZE);
+    // Parse pot_record fields (big-endian per Section 4.1)
+    let offset = 0;
+    // Byte 0: Version[4 bits] | Tier[4 bits]
+    const versionTier = potRecord.readUInt8(offset++);
+    const version = (versionTier >> 4) & 0x0F;
+    const tier = versionTier & 0x0F;
+    // Byte 1: Source Count (ignored in frame, stored separately)
+    const _sourceCount = potRecord.readUInt8(offset++);
+    // Byte 2: Reserved
+    const reserved = potRecord.readUInt8(offset++);
+    // Bytes 3-10: Timestamp (64-bit BE, nanoseconds)
+    const timestamp = potRecord.readBigUInt64BE(offset);
+    offset += 8;
+    // Bytes 11-14: Confidence (32-bit BE, ppm)
+    const confidence = potRecord.readUInt32BE(offset);
+    offset += 4;
+    // Bytes 15-46: Nonce (32 bytes)
+    const nonce = Buffer.from(potRecord.subarray(offset, offset + 32));
+    offset += 32;
+    // Bytes 47-78: GRG Commitment (32 bytes)
+    const grgCommit = Buffer.from(potRecord.subarray(offset, offset + 32));
+    offset += 32;
+    // Bytes 79-142: Ed25519 Signature (64 bytes)
+    const ed25519Sig = Buffer.from(potRecord.subarray(offset, offset + 64));
+    return {
+        bindingKey: Buffer.from(bindingKey),
+        potRecord: Buffer.from(potRecord),
+        version,
+        tier,
+        reserved,
+        timestamp,
+        confidence,
+        nonce,
+        grgCommit,
+        ed25519Sig,
+    };
+}
+/**
+ * Extract the portion of pot_record EXCLUDING the signature.
+ * This is used as the TLS Exporter context (Section 7.1).
+ * = first 79 bytes of the 143-byte pot_record
+ */
+function potRecordWithoutSig(potRecord) {
+    if (potRecord.length !== exports.POT_RECORD_SIZE) {
+        throw new PotFrameError(`pot_record must be ${exports.POT_RECORD_SIZE} bytes`);
+    }
+    return Buffer.from(potRecord.subarray(0, exports.POT_WITHOUT_SIG_SIZE));
+}
+/**
+ * Validate basic frame structure without TLS verification.
+ * (Full verification requires a TLS socket — see tls_binding.ts)
+ */
+function validatePotFrameStructure(frame) {
+    if (frame.length !== exports.POT_FRAME_SIZE) {
+        throw new PotFrameError(`Expected ${exports.POT_FRAME_SIZE} bytes, got ${frame.length}`);
+    }
+    const parsed = decodePotFrame(frame);
+    if (parsed.version !== 1) {
+        throw new PotFrameError(`Unknown PoT version: ${parsed.version}. Expected 1.`);
+    }
+    if (parsed.tier > 3) {
+        throw new PotFrameError(`Invalid tier: ${parsed.tier}. Valid range 0-3.`);
+    }
+    if (parsed.reserved !== 0) {
+        throw new PotFrameError(`Reserved field must be 0x00, got 0x${parsed.reserved.toString(16)}`);
+    }
+}

package/dist/pot_verifier.d.ts

@@ -0,0 +1,56 @@
+/**
+ * pot_verifier.ts — Complete TTTPS PoT frame verification
+ *
+ * Implements the normative verification sequence from
+ * draft-helmprotocol-tttps-02 Section 4.5 + Section 7.1:
+ *
+ *   1. Version check
+ *   2. TLS binding_key check  ← NEW in -02 (Ekr fix)
+ *   3. HMAC context gate      (~6 μs)
+ *   4. Ed25519 signature      (~100 μs)
+ *   5. Recency check
+ *   6. Nonce freshness
+ *
+ * Step 2 is checked FIRST because it's O(1) constant-time
+ * and prevents cross-session replay before any crypto.
+ */
+import * as tls from "tls";
+import { PotFrame } from "./pot_frame";
+export type VerifyError = "UNKNOWN_VERSION" | "BINDING_KEY_MISMATCH" | "HMAC_CONTEXT_FAILURE" | "SIGNATURE_INVALID" | "SUBMISSION_OUTSIDE_TOLERANCE" | "NONCE_REPLAY" | "FRAME_MALFORMED";
+export interface VerifyResult {
+    valid: boolean;
+    error?: VerifyError;
+    frame?: PotFrame;
+    latencyMs?: number;
+}
+export interface VerifierConfig {
+    /** Ed25519 public key of the trusted PoT Issuer (hex or Buffer) */
+    issuerPublicKey: Buffer | string;
+    /** Non-recoverable nonce cache (implement as LRU or Set with TTL) */
+    nonceCache: {
+        has(nonce: string): boolean;
+        add(nonce: string): void;
+    };
+}
+export declare class PotVerifier {
+    private issuerPubKey;
+    private nonceCache;
+    constructor(config: VerifierConfig);
+    /**
+     * Verify a 175-byte PoT frame over an active TLS socket.
+     *
+     * @param socket   - The TLS socket on which the frame was received
+     * @param frame    - 175-byte PoT frame (binding_key[32] + pot_record[143])
+     * @param nowMs    - Current time in milliseconds (injectable for testing)
+     */
+    verify(socket: tls.TLSSocket, frame: Buffer, nowMs?: number): VerifyResult;
+    private verifyEd25519;
+}
+export declare class MemoryNonceCache {
+    private cache;
+    private ttlMs;
+    constructor(ttlMs?: number);
+    has(nonce: string): boolean;
+    add(nonce: string): void;
+    private sweep;
+}