@reclaimprotocol/attestor-core 5.0.1-beta.1 → 5.0.1-beta.2

package/lib/server/utils/tee-transcript-reconstruction.js

@@ -0,0 +1,140 @@
+import { AttestorError } from "../../utils/error.js";
+import { REDACTION_CHAR_CODE } from "../../utils/index.js";
+async function reconstructTlsTranscript(bundleData, logger, oprfResults) {
+  try {
+    const revealedRequest = reconstructRequest(bundleData, logger);
+    const reconstructedResponse = await reconstructConsolidatedResponse(bundleData, logger, oprfResults);
+    const certificateInfo = bundleData.kOutputPayload.certificateInfo;
+    logger.info("TLS transcript reconstruction completed successfully", {
+      requestSize: revealedRequest.length,
+      responseSize: reconstructedResponse.length,
+      hasCertificateInfo: !!certificateInfo
+    });
+    return {
+      revealedRequest,
+      reconstructedResponse,
+      certificateInfo
+    };
+  } catch (error) {
+    logger.error({ error }, "TLS transcript reconstruction failed");
+    throw new AttestorError("ERROR_INVALID_CLAIM", `Transcript reconstruction failed: ${error.message}`);
+  }
+}
+function reconstructRequest(bundleData, logger) {
+  const { kOutputPayload } = bundleData;
+  if (!kOutputPayload.requestRedactionRanges || kOutputPayload.requestRedactionRanges.length === 0) {
+    logger.warn("No request redaction ranges - using redacted request as-is");
+    return kOutputPayload.redactedRequest;
+  }
+  const revealedRequest = new Uint8Array(kOutputPayload.redactedRequest);
+  const prettyRequest = new Uint8Array(revealedRequest);
+  for (const range of kOutputPayload.requestRedactionRanges) {
+    if (!range.type.includes("proof")) {
+      const start = range.start;
+      const length = range.length;
+      for (let i = 0; i < length && start + i < prettyRequest.length; i++) {
+        prettyRequest[start + i] = REDACTION_CHAR_CODE;
+      }
+    }
+  }
+  return prettyRequest;
+}
+async function reconstructConsolidatedResponse(bundleData, logger, oprfResults) {
+  const { kOutputPayload, tOutputPayload } = bundleData;
+  const consolidatedKeystream = kOutputPayload.consolidatedResponseKeystream;
+  const consolidatedCiphertext = tOutputPayload.consolidatedResponseCiphertext;
+  if (!consolidatedKeystream || consolidatedKeystream.length === 0) {
+    throw new AttestorError("ERROR_INVALID_CLAIM", "No consolidated response keystream available");
+  }
+  if (!consolidatedCiphertext || consolidatedCiphertext.length === 0) {
+    throw new AttestorError("ERROR_INVALID_CLAIM", "No consolidated response ciphertext available");
+  }
+  if (consolidatedKeystream.length !== consolidatedCiphertext.length) {
+    logger.warn("Keystream and ciphertext length mismatch", {
+      keystreamLength: consolidatedKeystream.length,
+      ciphertextLength: consolidatedCiphertext.length
+    });
+  }
+  const minLength = Math.min(consolidatedKeystream.length, consolidatedCiphertext.length);
+  const reconstructedResponse = new Uint8Array(minLength);
+  for (let i = 0; i < minLength; i++) {
+    reconstructedResponse[i] = consolidatedKeystream[i] ^ consolidatedCiphertext[i];
+  }
+  logger.info(`Reconstructed response: ${reconstructedResponse.length} bytes, ${kOutputPayload.responseRedactionRanges?.length || 0} redaction ranges`);
+  let processedResponse = applyResponseRedactionRanges(reconstructedResponse, kOutputPayload.responseRedactionRanges, logger);
+  if (oprfResults && oprfResults.length > 0) {
+    logger.info(`Applying ${oprfResults.length} OPRF replacements before trimming`);
+    const { replaceOprfRanges } = await import("../../server/utils/tee-oprf-verification.js");
+    processedResponse = replaceOprfRanges(processedResponse, oprfResults, logger);
+  }
+  let leadingAsterisks = 0;
+  for (const element of processedResponse) {
+    if (element === REDACTION_CHAR_CODE) {
+      leadingAsterisks++;
+    } else {
+      break;
+    }
+  }
+  let trailingAsterisks = 0;
+  for (let i = processedResponse.length - 1; i >= leadingAsterisks; i--) {
+    if (processedResponse[i] === REDACTION_CHAR_CODE) {
+      trailingAsterisks++;
+    } else {
+      break;
+    }
+  }
+  const finalLength = processedResponse.length - leadingAsterisks - trailingAsterisks;
+  logger.info(`After processing: ${processedResponse.length} bytes, ${leadingAsterisks} leading and ${trailingAsterisks} trailing asterisks trimmed, final: ${finalLength} bytes`);
+  return processedResponse.slice(leadingAsterisks, processedResponse.length - trailingAsterisks);
+}
+function applyResponseRedactionRanges(response, redactionRanges, logger) {
+  if (!redactionRanges || redactionRanges.length === 0) {
+    return response;
+  }
+  const result = new Uint8Array(response);
+  const consolidatedRanges = consolidateRedactionRanges(redactionRanges);
+  if (logger) {
+    logger.info(`Applying ${consolidatedRanges.length} redaction ranges to ${response.length} byte response`);
+  }
+  for (const [idx, range] of consolidatedRanges.entries()) {
+    const rangeStart = range.start;
+    const rangeEnd = range.start + range.length;
+    if (rangeStart < 0 || rangeEnd > result.length) {
+      if (logger) {
+        logger.warn(`Redaction range #${idx} out of bounds: [${rangeStart}-${rangeEnd}] vs ${result.length}`);
+      }
+      continue;
+    }
+    if (logger && idx < 3) {
+      logger.info(`Redaction range #${idx}: [${rangeStart}-${rangeEnd}]`);
+    }
+    for (let i = rangeStart; i < rangeEnd; i++) {
+      result[i] = REDACTION_CHAR_CODE;
+    }
+  }
+  return result;
+}
+function consolidateRedactionRanges(ranges) {
+  if (ranges.length === 0) {
+    return [];
+  }
+  const sortedRanges = [...ranges].sort((a, b) => a.start - b.start);
+  const consolidated = [];
+  let current = { ...sortedRanges[0] };
+  for (let i = 1; i < sortedRanges.length; i++) {
+    const next = sortedRanges[i];
+    if (next.start <= current.start + current.length) {
+      const endCurrent = current.start + current.length;
+      const endNext = next.start + next.length;
+      current.length = Math.max(endCurrent, endNext) - current.start;
+    } else {
+      consolidated.push(current);
+      current = { ...next };
+    }
+  }
+  consolidated.push(current);
+  return consolidated;
+}
+export {
+  reconstructTlsTranscript
+};

package/lib/server/utils/tee-verification.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TEE Bundle verification utilities
+ * Handles validation of TEE verification bundles including attestations and signatures
+ */
+import type { SignedMessage } from '#src/proto/tee-bundle.ts';
+import { KOutputPayload, TOutputPayload } from '#src/proto/tee-bundle.ts';
+import type { Logger } from '#src/types/general.ts';
+export interface TeeBundleData {
+    teekSigned: SignedMessage;
+    teetSigned: SignedMessage;
+    kOutputPayload: KOutputPayload;
+    tOutputPayload: TOutputPayload;
+    teekPcr0: string;
+    teetPcr0: string;
+    teeSessionId: string;
+}
+export interface TeeSignatureVerificationResult {
+    isValid: boolean;
+    errors: string[];
+    address?: string;
+}
+/**
+ * Verifies a complete TEE verification bundle
+ * @param bundleBytes - Raw protobuf-encoded verification bundle
+ * @param logger - Logger instance
+ * @returns Validated TEE bundle data
+ */
+export declare function verifyTeeBundle(bundleBytes: Uint8Array, logger: Logger): Promise<TeeBundleData>;

package/lib/server/utils/tee-verification.js

@@ -0,0 +1,358 @@
+import { ServiceSignatureType } from "../../proto/api.js";
+import { BodyType, KOutputPayload, TOutputPayload, VerificationBundle } from "../../proto/tee-bundle.js";
+import { validateGcpAttestationAndExtractKey } from "../../server/utils/gcp-attestation.js";
+import { validateNitroAttestationAndExtractKey } from "../../server/utils/nitro-attestation.js";
+import { AttestorError } from "../../utils/error.js";
+import { SIGNATURES } from "../../utils/signatures/index.js";
+async function verifyTeeBundle(bundleBytes, logger) {
+  const bundle = parseVerificationBundle(bundleBytes);
+  validateBundleCompleteness(bundle);
+  const { teekKeyResult, teetKeyResult } = await extractPublicKeys(bundle, logger);
+  await verifyTeeSignatures(bundle, teekKeyResult, teetKeyResult, logger);
+  if (!bundle.teekSigned || !bundle.teetSigned) {
+    throw new AttestorError("ERROR_INVALID_CLAIM", "Missing TEE signed messages");
+  }
+  const kOutputPayload = parseKOutputPayload(bundle.teekSigned);
+  const tOutputPayload = parseTOutputPayload(bundle.teetSigned);
+  validateTimestamps(kOutputPayload, tOutputPayload, logger);
+  const teeSessionId = validateSessionIds(kOutputPayload, tOutputPayload, logger);
+  logger.info("TEE bundle verification successful");
+  return {
+    teekSigned: bundle.teekSigned,
+    teetSigned: bundle.teetSigned,
+    kOutputPayload,
+    tOutputPayload,
+    teekPcr0: teekKeyResult.pcr0,
+    teetPcr0: teetKeyResult.pcr0,
+    teeSessionId
+  };
+}
+function parseVerificationBundle(bundleBytes) {
+  try {
+    return VerificationBundle.decode(bundleBytes);
+  } catch (error) {
+    throw new Error(`Failed to parse verification bundle: ${error.message}`);
+  }
+}
+function validateBundleCompleteness(bundle) {
+  if (!bundle.teekSigned) {
+    throw new Error("SECURITY ERROR: missing TEE_K signed message - verification bundle incomplete");
+  }
+  if (!bundle.teetSigned) {
+    throw new Error("SECURITY ERROR: missing TEE_T signed message - verification bundle incomplete");
+  }
+  const hasAttestations = bundle.teekSigned.attestationReport?.report && bundle.teekSigned.attestationReport.report.length > 0 || bundle.teetSigned.attestationReport?.report && bundle.teetSigned.attestationReport.report.length > 0;
+  const hasPublicKeys = bundle.teekSigned.ethAddress && bundle.teekSigned.ethAddress.length > 0 || bundle.teetSigned.ethAddress && bundle.teetSigned.ethAddress.length > 0;
+  if (!hasAttestations && !hasPublicKeys) {
+    throw new Error("SECURITY ERROR: bundle must have either Nitro attestations (production) or embedded public keys (development)");
+  }
+  if (bundle.teekSigned.bodyType !== BodyType.BODY_TYPE_K_OUTPUT) {
+    throw new Error("Invalid TEE_K signed message: wrong body type");
+  }
+  if (bundle.teetSigned.bodyType !== BodyType.BODY_TYPE_T_OUTPUT) {
+    throw new Error("Invalid TEE_T signed message: wrong body type");
+  }
+  if (!bundle.teekSigned.body || bundle.teekSigned.body.length === 0) {
+    throw new Error("Invalid TEE_K signed message: empty body");
+  }
+  if (!bundle.teetSigned.body || bundle.teetSigned.body.length === 0) {
+    throw new Error("Invalid TEE_T signed message: empty body");
+  }
+  if (!bundle.teekSigned.signature || bundle.teekSigned.signature.length === 0) {
+    throw new Error("Invalid TEE_K signed message: missing signature");
+  }
+  if (!bundle.teetSigned.signature || bundle.teetSigned.signature.length === 0) {
+    throw new Error("Invalid TEE_T signed message: missing signature");
+  }
+}
+async function extractPublicKeys(bundle, logger) {
+  const hasEmbeddedAttestations = bundle.teekSigned.attestationReport?.report && bundle.teekSigned.attestationReport.report.length > 0 && (bundle.teetSigned.attestationReport?.report && bundle.teetSigned.attestationReport.report.length > 0);
+  let teekKeyResult;
+  let teetKeyResult;
+  if (hasEmbeddedAttestations) {
+    logger.info("Using production mode: extracting keys from attestations");
+    if (!bundle.teekSigned?.attestationReport?.report) {
+      throw new Error("TEE_K embedded attestation report missing");
+    }
+    if (!bundle.teetSigned?.attestationReport?.report) {
+      throw new Error("TEE_T embedded attestation report missing");
+    }
+    const teekAttestationType = bundle.teekSigned.attestationReport.type || "nitro";
+    const teetAttestationType = bundle.teetSigned.attestationReport.type || "nitro";
+    logger.info(`TEE_K attestation type: ${teekAttestationType}`);
+    logger.info(`TEE_T attestation type: ${teetAttestationType}`);
+    const teekAttestationBytes = bundle.teekSigned.attestationReport.report;
+    const teetAttestationBytes = bundle.teetSigned.attestationReport.report;
+    if (teekAttestationType === "gcp") {
+      const gcpResult = await validateGcpAttestationAndExtractKey(teekAttestationBytes, logger);
+      if (!gcpResult.isValid) {
+        throw new Error(`TEE_K GCP attestation validation failed: ${gcpResult.errors.join(", ")}`);
+      }
+      if (!gcpResult.ethAddress) {
+        throw new Error("TEE_K GCP attestation validation failed: no address");
+      }
+      if (gcpResult.userDataType !== "tee_k") {
+        throw new Error(`TEE_K GCP attestation validation failed: wrong TEE type, expected tee_k, got ${gcpResult.userDataType}`);
+      }
+      teekKeyResult = {
+        teeType: gcpResult.userDataType,
+        ethAddress: "0x" + Buffer.from(gcpResult.ethAddress).toString("hex"),
+        pcr0: gcpResult.pcr0 || "gcp-no-digest"
+      };
+    } else {
+      const nitroResult = await validateNitroAttestationAndExtractKey(teekAttestationBytes);
+      if (!nitroResult.isValid) {
+        throw new Error(`TEE_K Nitro attestation validation failed: ${nitroResult.errors.join(", ")}`);
+      }
+      if (!nitroResult.ethAddress) {
+        throw new Error("TEE_K Nitro attestation validation failed: no address");
+      }
+      if (nitroResult.userDataType !== "tee_k") {
+        throw new Error(`TEE_K Nitro attestation validation failed: wrong TEE type, expected tee_k, got ${nitroResult.userDataType}`);
+      }
+      teekKeyResult = {
+        teeType: nitroResult.userDataType,
+        ethAddress: nitroResult.ethAddress,
+        pcr0: nitroResult.pcr0
+      };
+    }
+    if (teetAttestationType === "gcp") {
+      const gcpResult = await validateGcpAttestationAndExtractKey(teetAttestationBytes, logger);
+      if (!gcpResult.isValid) {
+        throw new Error(`TEE_T GCP attestation validation failed: ${gcpResult.errors.join(", ")}`);
+      }
+      if (!gcpResult.ethAddress) {
+        throw new Error("TEE_T GCP attestation validation failed: no address");
+      }
+      if (gcpResult.userDataType !== "tee_t") {
+        throw new Error(`TEE_T GCP attestation validation failed: wrong TEE type, expected tee_t, got ${gcpResult.userDataType}`);
+      }
+      teetKeyResult = {
+        teeType: gcpResult.userDataType,
+        ethAddress: "0x" + Buffer.from(gcpResult.ethAddress).toString("hex"),
+        pcr0: gcpResult.pcr0 || "gcp-no-digest"
+      };
+      if (!gcpResult.envVars?.EXPECTED_TEEK_PCR0) {
+        throw new Error("TEE_T GCP attestation missing required EXPECTED_TEEK_PCR0 environment variable");
+      }
+      const expectedPcr0 = gcpResult.envVars.EXPECTED_TEEK_PCR0;
+      const actualPcr0 = teekKeyResult.pcr0;
+      logger.info(`Cross-validating TEE_K PCR0: expected=${expectedPcr0}, actual=${actualPcr0}`);
+      if (expectedPcr0 !== actualPcr0) {
+        throw new Error(`TEE cross-validation failed: TEE_T expects TEE_K PCR0 "${expectedPcr0}" but got "${actualPcr0}"`);
+      }
+      logger.info("TEE cross-validation successful: TEE_K PCR0 matches TEE_T expectation");
+    } else {
+      const nitroResult = await validateNitroAttestationAndExtractKey(teetAttestationBytes);
+      if (!nitroResult.isValid) {
+        throw new Error(`TEE_T Nitro attestation validation failed: ${nitroResult.errors.join(", ")}`);
+      }
+      if (!nitroResult.ethAddress) {
+        throw new Error("TEE_T Nitro attestation validation failed: no address");
+      }
+      if (nitroResult.userDataType !== "tee_t") {
+        throw new Error(`TEE_T Nitro attestation validation failed: wrong TEE type, expected tee_t, got ${nitroResult.userDataType}`);
+      }
+      teetKeyResult = {
+        teeType: nitroResult.userDataType,
+        ethAddress: nitroResult.ethAddress,
+        pcr0: nitroResult.pcr0
+      };
+    }
+    logger.info("Attestations validated successfully");
+  } else {
+    const standaloneEnabled = process.env.TEE_STANDALONE === "true" || process.env.TEE_STANDALONE === "1";
+    if (!standaloneEnabled) {
+      throw new Error("Missing attestation reports and standalone mode is not enabled (set TEE_STANDALONE=true to enable)");
+    }
+    const hasEmbeddedKeys = bundle.teekSigned.ethAddress && bundle.teekSigned.ethAddress.length > 0 && (bundle.teetSigned.ethAddress && bundle.teetSigned.ethAddress.length > 0);
+    if (!hasEmbeddedKeys) {
+      throw new Error("Missing attestation and no embedded ETH addresses for standalone mode");
+    }
+    logger.warn("STANDALONE MODE ENABLED: Using embedded ETH addresses without attestation verification");
+    const teekAddress = Buffer.from(bundle.teekSigned.ethAddress).toString("utf8");
+    teekKeyResult = {
+      teeType: "tee_k",
+      ethAddress: teekAddress,
+      pcr0: "standalone-mode"
+      // No PCR0 in standalone mode
+    };
+    logger.info(`TEE_K standalone address: ${teekAddress}`);
+    const teetAddress = Buffer.from(bundle.teetSigned.ethAddress).toString("utf8");
+    teetKeyResult = {
+      teeType: "tee_t",
+      ethAddress: teetAddress,
+      pcr0: "standalone-mode"
+      // No PCR0 in standalone mode
+    };
+    logger.info(`TEE_T standalone address: ${teetAddress}`);
+    logger.info("Standalone mode key extraction successful");
+  }
+  return {
+    teekKeyResult,
+    teetKeyResult
+  };
+}
+async function verifyTeeSignatures(bundle, teekKeyResult, teetKeyResult, logger) {
+  if (!bundle.teekSigned) {
+    throw new Error("TEE_K signed message is missing");
+  }
+  const teekResult = await verifyTeeSignature(
+    bundle.teekSigned,
+    teekKeyResult,
+    "TEE_K",
+    logger
+  );
+  if (!teekResult.isValid) {
+    throw new Error(`TEE_K signature verification failed: ${teekResult.errors.join(", ")}`);
+  }
+  if (!bundle.teetSigned) {
+    throw new Error("TEE_T signed message is missing");
+  }
+  const teetResult = await verifyTeeSignature(
+    bundle.teetSigned,
+    teetKeyResult,
+    "TEE_T",
+    logger
+  );
+  if (!teetResult.isValid) {
+    throw new Error(`TEE_T signature verification failed: ${teetResult.errors.join(", ")}`);
+  }
+  logger.info("TEE signatures verified successfully");
+}
+async function verifyTeeSignature(signedMessage, extractedKey, teeType, logger) {
+  const errors = [];
+  if (!signedMessage) {
+    return {
+      isValid: false,
+      errors: ["Signed message is null or undefined"]
+    };
+  }
+  try {
+    let ethAddress;
+    if (extractedKey.ethAddress) {
+      ethAddress = extractedKey.ethAddress;
+      logger.debug(`${teeType} using ETH address from attestation: ${ethAddress}`);
+    } else {
+      return {
+        isValid: false,
+        errors: ["eth address is null"]
+      };
+    }
+    const { verify: verifySig } = SIGNATURES[ServiceSignatureType.SERVICE_SIGNATURE_TYPE_ETH];
+    const isValid = await verifySig(
+      signedMessage.body,
+      signedMessage.signature,
+      ethAddress
+    );
+    if (!isValid) {
+      errors.push(`${teeType} signature verification failed for address ${ethAddress}`);
+    }
+    logger.debug(`${teeType} signature verification result: ${isValid} for address ${ethAddress}`);
+    return {
+      isValid: errors.length === 0,
+      errors,
+      address: extractedKey.ethAddress
+    };
+  } catch (error) {
+    errors.push(`${teeType} signature verification error: ${error.message}`);
+    return {
+      isValid: false,
+      errors
+    };
+  }
+}
+function parseKOutputPayload(signedMessage) {
+  const payload = KOutputPayload.decode(signedMessage.body);
+  if (!payload.redactedRequest) {
+    throw new Error("Missing redacted request in TEE_K payload");
+  }
+  if (!payload.consolidatedResponseKeystream || payload.consolidatedResponseKeystream.length === 0) {
+    throw new Error("Missing consolidated response keystream in TEE_K payload");
+  }
+  if (!payload.certificateInfo) {
+    throw new Error("Missing certificate info in TEE_K payload");
+  }
+  return payload;
+}
+function parseTOutputPayload(signedMessage) {
+  const payload = TOutputPayload.decode(signedMessage.body);
+  if (!payload.consolidatedResponseCiphertext || payload.consolidatedResponseCiphertext.length === 0) {
+    throw new Error("Missing consolidated response ciphertext in TEE_T payload");
+  }
+  return payload;
+}
+function validateTimestamps(kPayload, tPayload, logger) {
+  const now = Date.now();
+  const kTimestamp = kPayload.timestampMs;
+  const tTimestamp = tPayload.timestampMs;
+  const kTimestampS = Math.floor(kTimestamp / 1e3);
+  const tTimestampS = Math.floor(tTimestamp / 1e3);
+  const nowS = Math.floor(now / 1e3);
+  logger.info("Validating TEE timestamps", {
+    kTimestampMs: kTimestamp,
+    tTimestampMs: tTimestamp,
+    kTimestampS,
+    tTimestampS,
+    nowS
+  });
+  const maxAgeMs = 10 * 60 * 1e3;
+  const oldestAllowed = now - maxAgeMs;
+  if (kTimestamp < oldestAllowed) {
+    throw new Error(`TEE_K timestamp ${kTimestamp} is too old. Must be within 10 minutes of current time ${now}`);
+  }
+  if (tTimestamp < oldestAllowed) {
+    throw new Error(`TEE_T timestamp ${tTimestamp} is too old. Must be within 10 minutes of current time ${now}`);
+  }
+  const maxFutureMs = 60 * 1e3;
+  const maxAllowed = now + maxFutureMs;
+  if (kTimestamp > maxAllowed) {
+    throw new Error(`TEE_K timestamp ${kTimestamp} is in the future. Current time is ${now}`);
+  }
+  if (tTimestamp > maxAllowed) {
+    throw new Error(`TEE_T timestamp ${tTimestamp} is in the future. Current time is ${now}`);
+  }
+  const timestampDiffMs = Math.abs(kTimestamp - tTimestamp);
+  const maxDiffMs = 60 * 1e3;
+  if (timestampDiffMs > maxDiffMs) {
+    throw new Error(`TEE timestamps differ by ${timestampDiffMs}ms, which exceeds maximum allowed difference of ${maxDiffMs}ms (1 minute)`);
+  }
+  logger.info("TEE timestamp validation successful", {
+    timestampDiffMs,
+    ageKMs: now - kTimestamp,
+    ageTMs: now - tTimestamp
+  });
+}
+function validateSessionIds(kPayload, tPayload, logger) {
+  const kSessionId = kPayload.sessionId;
+  const tSessionId = tPayload.sessionId;
+  logger.info("Validating TEE session IDs", {
+    kSessionId,
+    tSessionId
+  });
+  if (!kSessionId || kSessionId.length === 0) {
+    throw new AttestorError(
+      "ERROR_INVALID_CLAIM",
+      "Missing session_id in TEE_K payload - required for cross-TEE binding"
+    );
+  }
+  if (!tSessionId || tSessionId.length === 0) {
+    throw new AttestorError(
+      "ERROR_INVALID_CLAIM",
+      "Missing session_id in TEE_T payload - required for cross-TEE binding"
+    );
+  }
+  if (kSessionId !== tSessionId) {
+    throw new AttestorError(
+      "ERROR_INVALID_CLAIM",
+      `Session ID mismatch: TEE_K session_id "${kSessionId}" does not match TEE_T session_id "${tSessionId}".`
+    );
+  }
+  logger.info("TEE session ID validation successful", {
+    sessionId: kSessionId
+  });
+  return kSessionId;
+}
+export {
+  verifyTeeBundle
+};

package/lib/server/utils/validation.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderName, ProviderParams } from '#src/types/index.ts';
+export declare function assertValidateProviderParams<T extends ProviderName>(name: T, params: unknown): asserts params is ProviderParams<T>;

package/lib/server/utils/validation.js

@@ -0,0 +1,45 @@
+import { Ajv } from "ajv";
+import { PROVIDER_SCHEMAS } from "../../types/providers.gen.js";
+import { AttestorError } from "../../utils/error.js";
+const PROVIDER_VALIDATOR_MAP = {};
+const AJV = new Ajv({
+  allErrors: true,
+  strict: true,
+  strictRequired: false,
+  formats: {
+    binary(data) {
+      return data instanceof Uint8Array || typeof Buffer !== "undefined" && Buffer.isBuffer(data);
+    },
+    url(data) {
+      try {
+        new URL(data);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+});
+function assertValidateProviderParams(name, params) {
+  let validate = PROVIDER_VALIDATOR_MAP[name];
+  if (!validate) {
+    const schema = PROVIDER_SCHEMAS[name]?.parameters;
+    if (!schema) {
+      throw new AttestorError(
+        "ERROR_BAD_REQUEST",
+        `Invalid provider name "${String(name)}"`
+      );
+    }
+    validate = AJV.compile(schema);
+  }
+  if (!validate?.(params)) {
+    throw new AttestorError(
+      "ERROR_BAD_REQUEST",
+      "Params validation failed",
+      { errors: JSON.stringify(validate.errors) }
+    );
+  }
+}
+export {
+  assertValidateProviderParams
+};

package/lib/types/bgp.d.ts

@@ -0,0 +1,11 @@
+export type BGPAnnouncementOverlapData = {
+    prefix: string;
+};
+export type BGPListener = {
+    /**
+     * Add an IP to listen for overlap,
+     * @returns a function to remove the IP from the listener
+     */
+    onOverlap(ips: string[], callback: (event: BGPAnnouncementOverlapData) => void): (() => void);
+    close(): void;
+};

package/lib/types/claims.d.ts

@@ -0,0 +1,70 @@
+import type { ProviderClaimData } from '#src/proto/api.ts';
+import type { IAttestorClient, IAttestorClientInitParams } from '#src/types/client.ts';
+import type { CompleteTLSPacket, Logger } from '#src/types/general.ts';
+import type { ProofGenerationStep, ProviderName, ProviderParams, ProviderSecretParams } from '#src/types/providers.ts';
+import type { Transcript } from '#src/types/tunnel.ts';
+import type { PrepareZKProofsBaseOpts } from '#src/types/zk.ts';
+/**
+ * Uniquely identifies a claim.
+ * Hash of claim info.
+ * Utilise `getIdentifierFromClaimInfo` to obtain this.
+ */
+export type ClaimID = ProviderClaimData['identifier'];
+export type ClaimInfo = Pick<ProviderClaimData, 'context' | 'provider' | 'parameters'>;
+export type CompleteClaimData = Pick<ProviderClaimData, 'owner' | 'timestampS' | 'epoch'> & ClaimInfo;
+export type CreateClaimOnAttestorOpts<N extends ProviderName> = {
+    /** name of the provider to generate signed receipt for */
+    name: N;
+    /**
+     * secrets that are used to make the API request;
+     * not included in the receipt & cannot be viewed by anyone
+     * outside this client
+     */
+    secretParams: ProviderSecretParams<N>;
+    params: ProviderParams<N>;
+    /**
+     * Some metadata context to be included in the claim
+     */
+    context?: {
+        [key: string]: any;
+    };
+    onStep?(step: ProofGenerationStep): void;
+    /**
+     * Private key in hex format,
+     * prefixed with '0x'
+     */
+    ownerPrivateKey: string;
+    /**
+     * Provide either the client or the URL
+     * to the server -- so a client can be created internally.
+     *
+     * The created client will go into the global client pool.
+     */
+    client: IAttestorClient | IAttestorClientInitParams;
+    /**
+     * Optionally set the timestamp of the claim
+     * in unix seconds. If not provided, the current
+     * time will be used.
+     */
+    timestampS?: number;
+    logger?: Logger;
+    /**
+     * Maximum number of retries to attempt
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Optionally update the provider parameters
+     * based on the transcript
+     */
+    updateProviderParams?(transcript: Transcript<CompleteTLSPacket>, tlsVersion: string): Promise<{
+        params: Partial<ProviderParams<N>>;
+        secretParams: Partial<ProviderSecretParams<N>>;
+    }>;
+    /**
+     * Replaces paramValue with corresponding OPRF hash before proof is made
+     * Only if there's matching redaction exists
+     * For example: "domain.com" -> "dv4Nrgtr"
+     */
+    updateParametersFromOprfData?: boolean;
+} & PrepareZKProofsBaseOpts;