@reclaimprotocol/attestor-core 4.0.3 → 5.0.1-beta.10

package/lib/browser/client/create-claim.js

@@ -0,0 +1,461 @@
+import { makeRpcTlsTunnel } from "../client/tunnels/make-rpc-tls-tunnel.js";
+import { getAttestorClientFromPool } from "../client/utils/attestor-pool.js";
+import { DEFAULT_HTTPS_PORT, PROVIDER_CTX, TOPRF_DOMAIN_SEPARATOR } from "../config/index.js";
+import { ClaimTunnelRequest } from "../proto/api.js";
+import { providers } from "../providers/index.js";
+import {
+  asciiToUint8Array,
+  AttestorError,
+  binaryHashToStr,
+  canonicalStringify,
+  generateTunnelId,
+  getBlocksToReveal,
+  getEngineProto,
+  getProviderValue,
+  isApplicationData,
+  logger as LOGGER,
+  makeDefaultOPRFOperator,
+  makeHttpResponseParser,
+  preparePacketsForReveal,
+  redactSlices,
+  uint8ArrayToStr,
+  unixTimestampSeconds
+} from "../utils/index.js";
+import { executeWithRetries } from "../utils/retries.js";
+import { SIGNATURES } from "../utils/signatures/index.js";
+import { getDefaultTlsOptions } from "../utils/tls.js";
+function createClaimOnAttestor({
+  logger: _logger,
+  maxRetries = 3,
+  ...opts
+}) {
+  const logger = _logger || ("logger" in opts.client ? opts.client.logger : LOGGER);
+  return executeWithRetries(
+    (attempt) => _createClaimOnAttestor({
+      ...opts,
+      logger: attempt ? logger.child({ attempt }) : logger
+    }),
+    { maxRetries, logger, shouldRetry }
+  );
+}
+function shouldRetry(err) {
+  if (err instanceof TypeError) {
+    return false;
+  }
+  if (err?.message?.includes("stream ended before")) {
+    return true;
+  }
+  return err instanceof AttestorError && err.code !== "ERROR_INVALID_CLAIM" && err.code !== "ERROR_BAD_REQUEST" && err.code !== "ERROR_AUTHENTICATION_FAILED" && err.code !== "ERROR_TOPRF_OUT_OF_BOUNDS";
+}
+async function _createClaimOnAttestor({
+  name,
+  params,
+  secretParams,
+  context,
+  onStep,
+  ownerPrivateKey,
+  client: clientInit,
+  logger = LOGGER,
+  timestampS,
+  updateProviderParams,
+  updateParametersFromOprfData = true,
+  ...zkOpts
+}) {
+  const provider = providers[name];
+  const hostPort = getProviderValue(params, provider.hostPort, secretParams);
+  const geoLocation = getProviderValue(params, provider.geoLocation, secretParams);
+  const proxySessionId = getProviderValue(params, provider.proxySessionId, secretParams);
+  const providerTlsOpts = getProviderValue(
+    params,
+    provider.additionalClientOptions
+  );
+  const tlsOpts = {
+    ...getDefaultTlsOptions(),
+    fetchCertificateBytes: fetchCertificateBytesFromAttestor,
+    ...providerTlsOpts
+  };
+  const { zkEngine = "snarkjs" } = zkOpts;
+  let redactionMode = getProviderValue(params, provider.writeRedactionMode);
+  const [host, port] = hostPort.split(":");
+  const resParser = makeHttpResponseParser();
+  let client;
+  let lastMsgRevealed = false;
+  const revealMap = /* @__PURE__ */ new Map();
+  onStep?.({ name: "connecting" });
+  let endedHttpRequest;
+  const createTunnelReq = {
+    host,
+    port: port ? +port : DEFAULT_HTTPS_PORT,
+    geoLocation,
+    proxySessionId,
+    id: generateTunnelId()
+  };
+  logger = logger.child({ tunnelId: createTunnelReq.id });
+  const authRequest = "authRequest" in clientInit ? typeof clientInit.authRequest === "function" ? await clientInit.authRequest() : clientInit.authRequest : void 0;
+  const tunnel = await makeRpcTlsTunnel({
+    tlsOpts,
+    connect: (connectMsgs) => {
+      let created = false;
+      if ("metadata" in clientInit) {
+        client = clientInit;
+      } else {
+        client = getAttestorClientFromPool(
+          clientInit.url,
+          () => {
+            created = true;
+            return {
+              authRequest,
+              initMessages: connectMsgs,
+              logger
+            };
+          }
+        );
+      }
+      if (!created) {
+        client.waitForInit().then(() => client.sendMessage(...connectMsgs)).catch((err) => {
+          logger.error(
+            { err },
+            "error in sending init msgs"
+          );
+        });
+      }
+      return client;
+    },
+    logger,
+    request: createTunnelReq,
+    onMessage(data) {
+      logger.debug({ bytes: data.length }, "recv data from server");
+      resParser.onChunk(data);
+      if (resParser.res.complete) {
+        logger?.debug("got complete HTTP response from server");
+        setTimeout(() => {
+          endedHttpRequest?.();
+        }, 100);
+      }
+    },
+    onClose(err) {
+      const level = err ? "error" : "debug";
+      logger?.[level]({ err }, "tls session ended");
+      endedHttpRequest?.(err);
+      try {
+        resParser.streamEnded();
+      } catch {
+      }
+    }
+  });
+  const {
+    version: tlsVersion,
+    cipherSuite
+  } = tunnel.tls.getMetadata();
+  if (tlsVersion === "TLS1_2" && redactionMode !== "zk") {
+    redactionMode = "zk";
+    logger.info("TLS1.2 detected, defaulting to zk redaction mode");
+  }
+  const {
+    redactions,
+    data: requestStr
+  } = provider.createRequest(
+    // @ts-ignore
+    secretParams,
+    params,
+    logger
+  );
+  const requestData = typeof requestStr === "string" ? asciiToUint8Array(requestStr) : requestStr;
+  logger.debug(
+    { redactions: redactions.length },
+    "generated request"
+  );
+  const waitForAllData = new Promise(
+    (resolve, reject) => {
+      endedHttpRequest = (err) => err ? reject(err) : resolve();
+    }
+  );
+  onStep?.({ name: "sending-request-data" });
+  try {
+    if (redactionMode === "zk") {
+      await writeRedactedZk();
+    } else {
+      await writeRedactedWithKeyUpdate();
+    }
+    logger.info("wrote request to server");
+  } catch (err) {
+    logger.error(
+      { err },
+      "session errored during write, waiting for stream end"
+    );
+  }
+  onStep?.({ name: "waiting-for-response" });
+  await waitForAllData;
+  await tunnel.close();
+  logger.info("session closed, processing response");
+  if (updateProviderParams) {
+    const { params: updatedParms, secretParams: updatedSecretParms } = await updateProviderParams(tunnel.transcript, tlsVersion ?? "TLS1_2");
+    params = { ...params, ...updatedParms };
+    secretParams = { ...secretParams, ...updatedSecretParms };
+  }
+  const signatureAlg = SIGNATURES[client.metadata.signatureType];
+  let serverIV;
+  let clientIV;
+  const [serverBlock] = getLastBlocks("server", 1);
+  if (serverBlock?.message.type === "ciphertext") {
+    serverIV = serverBlock.message.fixedIv;
+  }
+  const [clientBlock] = getLastBlocks("client", 1);
+  if (clientBlock?.message.type === "ciphertext") {
+    clientIV = clientBlock.message.fixedIv;
+  }
+  const transcript = await generateTranscript();
+  const claimTunnelReq = ClaimTunnelRequest.create({
+    request: createTunnelReq,
+    data: {
+      provider: name,
+      parameters: canonicalStringify(params),
+      context: canonicalStringify(context),
+      timestampS: timestampS ?? unixTimestampSeconds(),
+      owner: getAddress()
+    },
+    transcript,
+    zkEngine: getEngineProto(zkEngine),
+    fixedServerIV: serverIV,
+    fixedClientIV: clientIV
+  });
+  onStep?.({ name: "waiting-for-verification" });
+  const claimTunnelBytes = ClaimTunnelRequest.encode(claimTunnelReq).finish();
+  const requestSignature = await signatureAlg.sign(claimTunnelBytes, ownerPrivateKey);
+  claimTunnelReq.signatures = { requestSignature };
+  const result = await client.rpc("claimTunnel", claimTunnelReq);
+  logger.info({ success: !!result.claim }, "recv claim response");
+  return result;
+  async function fetchCertificateBytesFromAttestor(url) {
+    if (!client) {
+      throw new Error("attestor client not initialized");
+    }
+    const result2 = await client.rpc("fetchCertificateBytes", { url });
+    return result2.bytes;
+  }
+  async function writeRedactedWithKeyUpdate() {
+    let currentIndex = 0;
+    for (const section of redactions) {
+      const block2 = requestData.slice(currentIndex, section.fromIndex);
+      if (block2.length) {
+        await writeWithReveal(block2, true);
+      }
+      const redacted = requestData.slice(section.fromIndex, section.toIndex);
+      await writeWithReveal(redacted, false);
+      currentIndex = section.toIndex;
+    }
+    const lastBlockStart = redactions?.[redactions.length - 1]?.toIndex || 0;
+    const block = requestData.slice(lastBlockStart);
+    if (block.length) {
+      await writeWithReveal(block, true);
+    }
+  }
+  async function writeRedactedZk() {
+    let blocksWritten = tunnel.transcript.length;
+    await tunnel.tls.write(requestData);
+    blocksWritten = tunnel.transcript.length - blocksWritten;
+    setRevealOfLastSentBlocks(
+      {
+        type: "zk",
+        redactedPlaintext: redactSlices(requestData, redactions)
+      },
+      blocksWritten
+    );
+  }
+  async function writeWithReveal(data, reveal) {
+    if (reveal !== lastMsgRevealed) {
+      await tunnel.tls.updateTrafficKeys();
+    }
+    let blocksWritten = tunnel.transcript.length;
+    await tunnel.write(data);
+    blocksWritten = tunnel.transcript.length - blocksWritten;
+    setRevealOfLastSentBlocks(reveal ? { type: "complete" } : void 0, blocksWritten);
+    lastMsgRevealed = reveal;
+  }
+  function setRevealOfLastSentBlocks(reveal, nBlocks = 1) {
+    const lastBlocks = getLastBlocks("client", nBlocks);
+    if (!lastBlocks.length) {
+      return;
+    }
+    for (const block of lastBlocks) {
+      setRevealOfMessage(block.message, reveal);
+    }
+  }
+  function getLastBlocks(sender, nBlocks) {
+    const lastBlocks = [];
+    for (let i = tunnel.transcript.length - 1; i >= 0; i--) {
+      const block = tunnel.transcript[i];
+      if (block.sender === sender) {
+        lastBlocks.push(block);
+        if (lastBlocks.length === nBlocks) {
+          break;
+        }
+      }
+    }
+    return lastBlocks;
+  }
+  async function generateTranscript() {
+    await addServerSideReveals();
+    const startMs = Date.now();
+    const revealedMessages = await preparePacketsForReveal(
+      tunnel.transcript,
+      revealMap,
+      {
+        logger,
+        cipherSuite,
+        onZkProgress(done, total) {
+          const timeSinceStartMs = Date.now() - startMs;
+          const timePerBlockMs = timeSinceStartMs / done;
+          const timeLeftMs = timePerBlockMs * (total - done);
+          onStep?.({
+            name: "generating-zk-proofs",
+            proofsDone: done,
+            proofsTotal: total,
+            approxTimeLeftS: Math.round(timeLeftMs / 1e3)
+          });
+        },
+        ...zkOpts
+      }
+    );
+    return revealedMessages;
+  }
+  async function addServerSideReveals() {
+    const allPackets = tunnel.transcript;
+    let serverPacketsToReveal = "all";
+    const packets = [];
+    const serverBlocks = [];
+    for (const b of allPackets) {
+      if (b.message.type !== "ciphertext" || !isApplicationData(b.message, tlsVersion)) {
+        continue;
+      }
+      const plaintext = tlsVersion === "TLS1_3" ? b.message.plaintext.slice(0, -1) : b.message.plaintext;
+      packets.push({
+        message: plaintext,
+        sender: b.sender
+      });
+      if (b.sender === "server") {
+        serverBlocks.push({
+          plaintext,
+          message: b.message
+        });
+      }
+    }
+    if (provider.getResponseRedactions) {
+      serverPacketsToReveal = await getBlocksToReveal(
+        serverBlocks,
+        (total) => provider.getResponseRedactions({
+          response: total,
+          params,
+          logger,
+          ctx: PROVIDER_CTX
+        }),
+        performOprf
+      );
+    }
+    const revealedPackets = packets.filter((p) => p.sender === "client");
+    if (serverPacketsToReveal === "all") {
+      for (const { message, sender } of allPackets) {
+        if (sender === "server") {
+          setRevealOfMessage(message, { type: "complete" });
+        }
+      }
+      revealedPackets.push(...packets.filter((p) => p.sender === "server"));
+    } else {
+      for (const {
+        block,
+        redactedPlaintext,
+        overshotToprfFromPrevBlock,
+        toprfs,
+        oprfRawMarkers
+      } of serverPacketsToReveal) {
+        setRevealOfMessage(block.message, {
+          type: "zk",
+          redactedPlaintext,
+          toprfs,
+          oprfRawMarkers,
+          overshotToprfFromPrevBlock
+        });
+        revealedPackets.push(
+          { sender: "server", message: redactedPlaintext }
+        );
+        if (updateParametersFromOprfData && toprfs) {
+          let strParams = canonicalStringify(params);
+          for (const toprf of toprfs) {
+            const ogText = uint8ArrayToStr(toprf.plaintext);
+            const hashedText = binaryHashToStr(
+              toprf.nullifier,
+              toprf.dataLocation.length
+            );
+            strParams = strParams.replaceAll(ogText, hashedText);
+          }
+          params = JSON.parse(strParams);
+        }
+      }
+    }
+    await provider.assertValidProviderReceipt({
+      receipt: revealedPackets,
+      params: {
+        ...params,
+        // provide secret params for proper
+        // request body validation
+        secretParams
+      },
+      logger,
+      ctx: PROVIDER_CTX
+    });
+    for (const p of allPackets) {
+      if (p.message.type !== "ciphertext") {
+        continue;
+      }
+      if (isApplicationData(p.message, tlsVersion)) {
+        break;
+      }
+      setRevealOfMessage(p.message, { type: "complete" });
+    }
+  }
+  async function performOprf(plaintext) {
+    logger.info({ length: plaintext.length }, "generating OPRF...");
+    const oprfOperator = zkOpts.oprfOperators?.["chacha20"] || makeDefaultOPRFOperator(
+      "chacha20",
+      zkEngine,
+      logger
+    );
+    const reqData = await oprfOperator.generateOPRFRequestData(
+      plaintext,
+      TOPRF_DOMAIN_SEPARATOR,
+      logger
+    );
+    const res = await client.rpc("toprf", {
+      maskedData: reqData.maskedData,
+      engine: getEngineProto(zkEngine)
+    });
+    const nullifier = await oprfOperator.finaliseOPRF(
+      client.initResponse.toprfPublicKey,
+      reqData,
+      [res]
+    );
+    const data = {
+      nullifier,
+      responses: [res],
+      mask: reqData.mask,
+      dataLocation: void 0,
+      plaintext
+    };
+    return data;
+  }
+  function setRevealOfMessage(message, reveal) {
+    if (reveal) {
+      revealMap.set(message, reveal);
+      return;
+    }
+    revealMap.delete(message);
+  }
+  function getAddress() {
+    const { getAddress: getAddress2, getPublicKey } = signatureAlg;
+    const pubKey = getPublicKey(ownerPrivateKey);
+    return getAddress2(pubKey);
+  }
+}
+export {
+  createClaimOnAttestor
+};

package/lib/browser/client/index.d.ts

@@ -0,0 +1,3 @@
+export * from './create-claim.ts';
+export * from './utils/attestor-pool.ts';
+export * from './utils/client-socket.ts';

package/lib/browser/client/index.js

@@ -0,0 +1,3 @@
+export * from "./create-claim.js";
+export * from "./utils/attestor-pool.js";
+export * from "./utils/client-socket.js";

package/lib/browser/client/tunnels/make-rpc-tcp-tunnel.d.ts

@@ -0,0 +1,16 @@
+import type { CreateTunnelRequest } from '#src/proto/api.ts';
+import type { IAttestorClient, MakeTunnelFn } from '#src/types/index.ts';
+export type TCPTunnelCreateOpts = {
+    /**
+     * The tunnel ID to communicate with.
+     */
+    tunnelId: CreateTunnelRequest['id'];
+    client: IAttestorClient;
+};
+/**
+ * Makes a tunnel communication wrapper for a TCP tunnel.
+ *
+ * It listens for messages and disconnect events from the server,
+ * and appropriately calls the `onMessage` and `onClose` callbacks.
+ */
+export declare const makeRpcTcpTunnel: MakeTunnelFn<TCPTunnelCreateOpts>;

package/lib/browser/client/tunnels/make-rpc-tcp-tunnel.js

@@ -0,0 +1,53 @@
+import { AttestorError } from "../../utils/index.js";
+const makeRpcTcpTunnel = ({
+  tunnelId,
+  client,
+  onClose,
+  onMessage
+}) => {
+  let closed = false;
+  client.addEventListener("tunnel-message", onMessageListener);
+  client.addEventListener("tunnel-disconnect-event", onDisconnectListener);
+  client.addEventListener("connection-terminated", onConnectionTerminatedListener);
+  return {
+    async write(message) {
+      await client.sendMessage({ tunnelMessage: { tunnelId, message } });
+    },
+    async close(err) {
+      if (closed) {
+        return;
+      }
+      onErrorRecv(err);
+      await client.rpc("disconnectTunnel", { id: tunnelId });
+    }
+  };
+  function onMessageListener({ data }) {
+    if (data.tunnelId !== tunnelId) {
+      return;
+    }
+    onMessage?.(data.message);
+  }
+  function onDisconnectListener({ data }) {
+    if (data.tunnelId !== tunnelId) {
+      return;
+    }
+    onErrorRecv(
+      data.error?.code ? AttestorError.fromProto(data.error) : void 0
+    );
+  }
+  function onConnectionTerminatedListener({ data }) {
+    onErrorRecv(data);
+  }
+  function onErrorRecv(err) {
+    client.logger?.debug({ tunnelId, err }, "TCP tunnel closed");
+    client.removeEventListener("tunnel-message", onMessageListener);
+    client.removeEventListener("tunnel-disconnect-event", onDisconnectListener);
+    client.removeEventListener("connection-terminated", onConnectionTerminatedListener);
+    onClose?.(err);
+    onClose = void 0;
+    closed = true;
+  }
+};
+export {
+  makeRpcTcpTunnel
+};

package/lib/browser/client/tunnels/make-rpc-tls-tunnel.d.ts

@@ -0,0 +1,26 @@
+import type { TLSConnectionOptions } from '@reclaimprotocol/tls';
+import { makeTLSClient } from '#src/utils/tls-imports.ts';
+import type { CreateTunnelRequest, RPCMessage } from '#src/proto/api.ts';
+import type { CompleteTLSPacket, IAttestorClient, Logger, MakeTunnelFn, Transcript } from '#src/types/index.ts';
+type ExtraTLSOptions = {
+    request: Partial<CreateTunnelRequest>;
+    logger: Logger;
+    /**
+     * Either create a client with the given initMessages,
+     * or simply send the messages to the server via an existing
+     * client
+     *
+     * @returns the client that was used to send the messages
+     */
+    connect(initMessages: Partial<RPCMessage>[]): IAttestorClient;
+    tlsOpts?: TLSConnectionOptions;
+};
+type TLSTunnelProperties = {
+    transcript: Transcript<CompleteTLSPacket>;
+    tls: ReturnType<typeof makeTLSClient>;
+};
+/**
+ * Makes a TLS tunnel that connects to the server via RPC protocol
+ */
+export declare const makeRpcTlsTunnel: MakeTunnelFn<ExtraTLSOptions, TLSTunnelProperties>;
+export {};

package/lib/browser/client/tunnels/make-rpc-tls-tunnel.js

@@ -0,0 +1,127 @@
+import { concatenateUint8Arrays, makeTLSClient } from "../../utils/tls-imports.js";
+import { makeRpcTcpTunnel } from "../../client/tunnels/make-rpc-tcp-tunnel.js";
+import { DEFAULT_HTTPS_PORT } from "../../config/index.js";
+import { generateRpcMessageId, generateTunnelId } from "../../utils/index.js";
+const makeRpcTlsTunnel = async ({
+  onMessage,
+  onClose,
+  tlsOpts,
+  request,
+  connect,
+  logger
+}) => {
+  const transcript = [];
+  const tunnelId = request.id || generateTunnelId();
+  let tunnel;
+  let client;
+  let handshakeResolve;
+  let handshakeReject;
+  const waitForHandshake = new Promise((resolve, reject) => {
+    handshakeResolve = resolve;
+    handshakeReject = reject;
+  });
+  const tls = makeTLSClient({
+    host: request.host,
+    ...tlsOpts,
+    logger,
+    onHandshake() {
+      handshakeResolve?.();
+    },
+    onApplicationData(plaintext) {
+      return onMessage?.(plaintext);
+    },
+    onTlsEnd: onConnectionClose,
+    async write(packet, ctx) {
+      const message = concatenateUint8Arrays([
+        packet.header,
+        packet.content
+      ]);
+      transcript.push({
+        sender: "client",
+        message: { ...ctx, data: message }
+      });
+      if (!tunnel) {
+        const createTunnelReqId = generateRpcMessageId();
+        client = connect([
+          {
+            id: createTunnelReqId,
+            createTunnelRequest: {
+              host: request.host || "",
+              port: request.port || DEFAULT_HTTPS_PORT,
+              geoLocation: request.geoLocation || "",
+              proxySessionId: request.proxySessionId || "",
+              id: tunnelId
+            }
+          },
+          { tunnelMessage: { tunnelId, message } }
+        ]);
+        try {
+          await makeTunnel();
+          await client.waitForResponse(createTunnelReqId);
+        } catch (err) {
+          onConnectionClose(err);
+        }
+        return;
+      }
+      return tunnel.write(message);
+    },
+    onRead(packet, ctx) {
+      transcript.push({
+        sender: "server",
+        message: {
+          ...ctx,
+          data: concatenateUint8Arrays([
+            packet.header,
+            // the TLS package sends us the decrypted
+            // content, so we need to get the orginal
+            // ciphertext received from the server
+            // as that's part of the true transcript.
+            ctx.type === "ciphertext" ? ctx.ciphertext : packet.content
+          ])
+        }
+      });
+    }
+  });
+  await tls.startHandshake();
+  await waitForHandshake;
+  handshakeResolve = handshakeReject = void 0;
+  return {
+    transcript,
+    tls,
+    write(data) {
+      return tls.write(data);
+    },
+    async close(err) {
+      onConnectionClose(err);
+      try {
+        await tunnel.close(err);
+      } catch (err2) {
+        logger?.error({ err: err2 }, "err in close tunnel");
+      }
+    }
+  };
+  function onConnectionClose(err) {
+    onClose?.(err);
+    onClose = void 0;
+    handshakeReject?.(
+      err || new Error("TLS connection closed")
+    );
+  }
+  async function makeTunnel() {
+    tunnel = await makeRpcTcpTunnel({
+      tunnelId,
+      client,
+      onMessage(data) {
+        tls.handleReceivedBytes(data);
+      },
+      onClose(err) {
+        tls.end(err);
+      }
+    });
+    logger?.debug("plaintext tunnel created");
+    return tunnel;
+  }
+};
+export {
+  makeRpcTlsTunnel
+};

package/lib/browser/client/utils/attestor-pool.d.ts

@@ -0,0 +1,8 @@
+import type { IAttestorClient, IAttestorClientCreateOpts } from '#src/types/index.ts';
+/**
+ * Get a attestor client from the pool,
+ * if it doesn't exist, create one.
+ * @param [getCreateOpts] - Function to get the options for creating a new client.
+ *  called synchronously, in the same tick as this function.
+ */
+export declare function getAttestorClientFromPool(url: string | URL, getCreateOpts?: () => Omit<IAttestorClientCreateOpts, 'url'>): IAttestorClient;