@vlayer/sdk 0.1.0-nightly-20250127-96fc5df → 0.1.0-nightly-20250128-0a32cfc

package/src/api/utils/versions.test.ts

@@ -0,0 +1,52 @@
+import { describe, test, expect } from "vitest";
+import { checkVersionCompatibility } from "./versions";
+
+describe("versions compatibility", () => {
+  test("throws if major version mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "2.1.3");
+    }).toThrowError(
+      "SDK version 2.1.3 is incompatible with prover version 1.2.3",
+    );
+  });
+
+  test("throws if major version mismatches with metadata after dash", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3-dev-123456-deadbeef", "2.1.3");
+    }).toThrowError(
+      "SDK version 2.1.3 is incompatible with prover version 1.2.3-dev-123456-deadbeef",
+    );
+  });
+
+  test("throws if major version is 0 and minor version mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3", "0.1.3");
+    }).toThrowError(
+      "SDK version 0.1.3 is incompatible with prover version 0.2.3",
+    );
+  });
+
+  test("does not throw if major and minor versions match", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "1.2.13");
+    }).not.toThrow();
+  });
+
+  test("does not throw if major version is >0 and minor mismatches", () => {
+    expect(() => {
+      checkVersionCompatibility("1.2.3", "1.5.8");
+    }).not.toThrow();
+  });
+
+  test("does not throw if major version is 0 and minor matches", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3", "0.2.7");
+    }).not.toThrow();
+  });
+
+  test("works for semvers with metadata after dash", () => {
+    expect(() => {
+      checkVersionCompatibility("0.2.3-dev-123456-deadbeef", "0.2.7");
+    }).not.toThrow();
+  });
+});

package/src/api/utils/versions.ts

@@ -0,0 +1,31 @@
+import { parse, type SemVer } from "semver";
+import { VersionError } from "../lib/errors";
+
+function safeParseSemver(semverString: string): SemVer {
+  const parsed = parse(semverString);
+  if (parsed === null) {
+    throw new VersionError(`Invalid semver string: ${semverString}`);
+  }
+  return parsed;
+}
+
+export function checkVersionCompatibility(
+  proverSemver: string,
+  sdkSemver: string,
+) {
+  const { major: proverMajor, minor: proverMinor } =
+    safeParseSemver(proverSemver);
+  const { major: sdkMajor, minor: sdkMinor } = safeParseSemver(sdkSemver);
+
+  if (proverMajor !== sdkMajor) {
+    throw new VersionError(
+      `SDK version ${sdkSemver} is incompatible with prover version ${proverSemver}`,
+    );
+  }
+
+  if (proverMajor === 0 && proverMinor !== sdkMinor) {
+    throw new VersionError(
+      `SDK version ${sdkSemver} is incompatible with prover version ${proverSemver}`,
+    );
+  }
+}

package/src/api/v_call.ts

@@ -0,0 +1,58 @@
+import {
+  type CallContext,
+  type CallParams,
+  type VCallResponse,
+} from "./lib/types/vlayer";
+import { parseVCallResponseError } from "./lib/errors";
+import debug from "debug";
+
+const log = debug("vlayer:v_call");
+
+function v_callBody(call: CallParams, context: CallContext) {
+  console.log("call", call);
+  console.log("context", context);
+  return {
+    method: "v_call",
+    params: [call, context],
+    id: 1,
+    jsonrpc: "2.0",
+  };
+}
+
+export async function v_call(
+  call: CallParams,
+  context: CallContext,
+  url: string = "http://127.0.0.1:3000",
+  token?: string,
+): Promise<VCallResponse> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (token !== undefined) {
+    headers["Authorization"] = "Bearer " + token;
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_callBody(call, context)),
+    headers,
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  log("response_json", response_json);
+  assertObject(response_json);
+  if ("error" in response_json) {
+    throw parseVCallResponseError(
+      response_json.error as { message: string | undefined },
+    );
+  }
+  return response_json as Promise<VCallResponse>;
+}
+
+function assertObject(x: unknown): asserts x is object {
+  if (typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+}

package/src/api/v_getProofReceipt.ts

@@ -0,0 +1,48 @@
+import {
+  type VGetProofReceiptParams,
+  type VGetProofReceiptResponse,
+} from "./lib/types/vlayer";
+import { parseVCallResponseError } from "./lib/errors";
+import { vGetProofReceiptSchema } from "./lib/types/vlayer";
+import debug from "debug";
+
+const log = debug("vlayer:v_getProofReceipt");
+
+function v_getProofReceiptBody(params: VGetProofReceiptParams) {
+  return {
+    method: "v_getProofReceipt",
+    params: params,
+    id: 1,
+    jsonrpc: "2.0",
+  };
+}
+
+export async function v_getProofReceipt(
+  params: VGetProofReceiptParams,
+  url: string = "http://127.0.0.1:3000",
+): Promise<VGetProofReceiptResponse> {
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_getProofReceiptBody(params)),
+    headers: { "Content-Type": "application/json" },
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  log("response_json", response_json);
+  assertObject(response_json);
+  if ("error" in response_json) {
+    throw parseVCallResponseError(
+      response_json.error as { message: string | undefined },
+    );
+  }
+  return vGetProofReceiptSchema.parse(response_json);
+}
+
+function assertObject(x: unknown): asserts x is object {
+  if (typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+}

package/src/api/v_versions.ts

@@ -0,0 +1,68 @@
+import debug from "debug";
+
+const log = debug("vlayer:v_versions");
+
+const v_versionsBody = {
+  method: "v_versions",
+  params: [],
+  id: 1,
+  jsonrpc: "2.0",
+};
+
+interface VVersionsResponseResult {
+  call_guest_id: string;
+  chain_guest_id: string;
+  api_version: string;
+}
+
+export interface VVersionsResponse {
+  jsonrpc: string;
+  result: VVersionsResponseResult;
+  id: number;
+}
+
+export async function v_versions(
+  url: string = "http://127.0.0.1:3000",
+): Promise<VVersionsResponse> {
+  const response = await fetch(url, {
+    method: "POST",
+    body: JSON.stringify(v_versionsBody),
+    headers: { "Content-Type": "application/json" },
+  });
+  log("response", response);
+  if (!response.ok) {
+    throw new Error(`HTTP error! status: ${response.status}`);
+  }
+  const response_json = await response.json();
+  assertResponseObject(response_json);
+  return response_json;
+}
+
+function isFieldAString(
+  x: object,
+  field: keyof VVersionsResponseResult,
+): boolean {
+  return (
+    field in x && typeof (x as VVersionsResponseResult)[field] === "string"
+  );
+}
+
+function assertResponseObject(x: unknown): asserts x is VVersionsResponse {
+  if (!x || typeof x !== "object") {
+    throw new Error("Expected object");
+  }
+  if (!("result" in x) || !x.result || typeof x.result !== "object") {
+    throw new Error(
+      `Unexpected \`v_versions\` response: ${JSON.stringify(x, null, 2)}`,
+    );
+  }
+  if (
+    !isFieldAString(x.result, "call_guest_id") ||
+    !isFieldAString(x.result, "chain_guest_id") ||
+    !isFieldAString(x.result, "api_version")
+  ) {
+    throw new Error(
+      `Unexpected \`v_versions\` response: ${JSON.stringify(x, null, 2)}`,
+    );
+  }
+}

package/src/api/webProof/createWebProofRequest.ts

@@ -0,0 +1,15 @@
+import {
+  type WebProofRequest,
+  type WebProofRequestInput,
+} from "../lib/types/webProofProvider";
+
+export const createWebProofRequest = ({
+  logoUrl,
+  steps,
+}: WebProofRequestInput) => {
+  return {
+    logoUrl,
+    steps,
+    isWebProof: true,
+  } as WebProofRequest;
+};

package/src/api/webProof/index.ts

@@ -0,0 +1,3 @@
+export * from "./createWebProofRequest";
+export * from "./steps";
+export * from "./providers";

package/src/api/webProof/providers/extension.test.ts

@@ -0,0 +1,122 @@
+import { createExtensionWebProofProvider } from "./extension";
+import { describe, it, expect, vi } from "vitest";
+import { expectUrl, startPage, notarize } from "../steps";
+import { StepValidationError } from "../../../web-proof-commons";
+
+const chrome = {
+  runtime: {
+    disconnectCallbacks: [] as (() => void)[],
+    connect: vi.fn().mockImplementation(() => ({
+      postMessage: vi.fn().mockImplementation(() => {}),
+      onMessage: {
+        addListener: vi.fn().mockImplementation(() => {}),
+      },
+      onDisconnect: {
+        addListener: vi.fn().mockImplementation((callback: () => void) => {
+          chrome.runtime.disconnectCallbacks.push(callback);
+        }),
+      },
+    })),
+    disconnect: vi.fn().mockImplementation(() => {
+      chrome.runtime.disconnectCallbacks.forEach((callback) => {
+        callback();
+      });
+    }),
+  },
+};
+
+vi.stubGlobal("chrome", chrome);
+
+const defaults = {
+  logoUrl: "https://example.com/logo.png",
+  proverCallCommitment: {
+    address: "0x" as `0x${string}`,
+    proverAbi: [],
+    chainId: 1,
+    functionName: "test",
+    commitmentArgs: null as never,
+  },
+};
+
+const invalidUrl = "http:/example.com";
+const invalidUrlPattern = "http://+.test";
+const validUrl = "https://example.com";
+const validUrlPattern = "https://example.com/test";
+const label = "test";
+
+describe("ExtensionWebProofProvider", () => {
+  it("should properly validate startPage step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [startPage(invalidUrl, label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("should properly validate expectUrl step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [expectUrl(invalidUrlPattern, label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("should properly validate notarize step", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [notarize(invalidUrlPattern, "GET", label)],
+      }),
+    ).toThrow(StepValidationError);
+  });
+
+  it("successfully validates all steps", () => {
+    const provider = createExtensionWebProofProvider();
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [
+          startPage(validUrl, label),
+          expectUrl(validUrlPattern, label),
+          notarize(validUrlPattern, "GET", label),
+        ],
+      }),
+    ).not.toThrow(StepValidationError);
+  });
+
+  it("should properly work backward compatible way with only urls used", () => {
+    const provider = createExtensionWebProofProvider();
+
+    expect(() =>
+      provider.requestWebProof({
+        ...defaults,
+        steps: [
+          startPage(validUrl, label),
+          expectUrl(validUrl, label),
+          expectUrl(validUrl, label),
+          notarize(validUrl, "GET", label),
+        ],
+      }),
+    ).not.toThrow();
+  });
+
+  it("should reconnect extension on disconnect", () => {
+    const provider = createExtensionWebProofProvider();
+    provider.requestWebProof({
+      ...defaults,
+      steps: [
+        startPage(validUrl, label),
+        expectUrl(validUrlPattern, label),
+        notarize(validUrlPattern, "GET", label),
+      ],
+    });
+    chrome.runtime.connect.mockClear();
+    chrome.runtime.disconnect();
+    expect(chrome.runtime.connect).toHaveBeenCalled();
+  });
+});

package/src/api/webProof/providers/extension.ts

@@ -0,0 +1,197 @@
+import {
+  type WebProofProvider,
+  type WebProofProviderSetup,
+  type WebProofRequestInput,
+} from "../../lib/types/webProofProvider";
+
+import {
+  EXTENSION_STEP,
+  ExtensionAction,
+  type ExtensionMessage,
+  ExtensionMessageType,
+  type WebProofStep,
+  type PresentationJSON,
+  ZkProvingStatus,
+  assertUrl,
+  assertUrlPattern,
+  type RedactionConfig,
+  RedactionItemsArray,
+  type MessageToExtension,
+} from "../../../web-proof-commons";
+
+import debug from "debug";
+
+const log = debug("vlayer:WebProof:provider");
+
+const EXTENSION_ID = "jbchhcgphfokabmfacnkafoeeeppjmpl";
+
+declare let chrome: {
+  runtime: {
+    sendMessage: (
+      extensionId: string | undefined,
+      message: MessageToExtension,
+    ) => void;
+    connect: (extensionId: string) => {
+      onMessage: {
+        addListener: (message: unknown) => void;
+      };
+      postMessage: (message: MessageToExtension) => void;
+      onDisconnect: {
+        addListener: (callback: () => void) => void;
+      };
+    };
+  };
+};
+
+class ExtensionWebProofProvider implements WebProofProvider {
+  private port: ReturnType<typeof chrome.runtime.connect> | null = null;
+
+  private listeners: Partial<
+    Record<
+      ExtensionMessageType,
+      ((
+        args: Extract<ExtensionMessage, { type: ExtensionMessageType }>,
+      ) => void)[]
+    >
+  > = {};
+
+  constructor(
+    private notaryUrl: string,
+    private wsProxyUrl: string,
+  ) {}
+
+  public notifyZkProvingStatus(status: ZkProvingStatus) {
+    if (typeof chrome !== "undefined") {
+      // Chrome does not provide reliable api to check if given extension is installed
+      // what we could do is to use management api but
+      // 1) this will need to provided extra permission
+      // 2) still is not reliable because this api becomes defined when first extension that uses it is installed
+      // so still will need to try catch
+      try {
+        chrome.runtime.sendMessage(EXTENSION_ID, {
+          action: ExtensionAction.NotifyZkProvingStatus,
+          payload: { status },
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (e) {
+        log("Cant send message", "look that extension is not installed ");
+      }
+    }
+  }
+
+  private connectToExtension() {
+    if (!this.port) {
+      this.port = chrome.runtime.connect(EXTENSION_ID);
+      this.port.onDisconnect.addListener(() => {
+        this.port = null;
+        this.connectToExtension();
+      });
+      this.port.onMessage.addListener((message: ExtensionMessage) => {
+        if (message.type === ExtensionMessageType.ProofDone) {
+          this.listeners[ExtensionMessageType.ProofDone]?.forEach((cb) => {
+            cb(message);
+          });
+        }
+        if (message.type === ExtensionMessageType.ProofError) {
+          this.listeners[ExtensionMessageType.ProofError]?.forEach((cb) => {
+            cb(message);
+          });
+        }
+      });
+    }
+    return this.port;
+  }
+
+  public addEventListeners<T extends ExtensionMessageType>(
+    messageType: T,
+    listener: (args: Extract<ExtensionMessage, { type: T }>) => void,
+  ) {
+    this.connectToExtension();
+    if (!this.listeners[messageType]) {
+      this.listeners[messageType] = [];
+    }
+    this.listeners[messageType].push(
+      listener as (args: ExtensionMessage) => void,
+    );
+  }
+
+  public requestWebProof(webProofRequest: WebProofRequestInput) {
+    validateWebProofRequest(webProofRequest);
+    this.connectToExtension().postMessage({
+      action: ExtensionAction.RequestWebProof,
+      payload: {
+        notaryUrl: this.notaryUrl,
+        wsProxyUrl: this.wsProxyUrl,
+        logoUrl: webProofRequest.logoUrl,
+        steps: webProofRequest.steps,
+      },
+    });
+  }
+
+  public async getWebProof(webProofRequest: WebProofRequestInput): Promise<{
+    presentationJSON: PresentationJSON;
+    decodedTranscript: {
+      sent: string;
+      recv: string;
+    };
+  }> {
+    return new Promise<{
+      presentationJSON: PresentationJSON;
+      decodedTranscript: {
+        sent: string;
+        recv: string;
+      };
+    }>((resolve, reject) => {
+      chrome.runtime.sendMessage(EXTENSION_ID, {
+        action: ExtensionAction.RequestWebProof,
+        payload: {
+          notaryUrl: this.notaryUrl,
+          wsProxyUrl: this.wsProxyUrl,
+          logoUrl: webProofRequest.logoUrl,
+          steps: webProofRequest.steps,
+        },
+      });
+
+      this.connectToExtension().onMessage.addListener(
+        (message: ExtensionMessage) => {
+          if (message.type === ExtensionMessageType.ProofDone) {
+            resolve(message.payload);
+          }
+          if (message.type === ExtensionMessageType.ProofError) {
+            reject(new Error(message.payload.error));
+          }
+        },
+      );
+    });
+  }
+}
+
+const validateSteps = (steps: WebProofStep[]) => {
+  steps.forEach((step) => {
+    if (step.step === EXTENSION_STEP.startPage) {
+      assertUrl(step.url);
+    } else {
+      assertUrlPattern(step.url);
+    }
+    if (step.step === EXTENSION_STEP.notarize) {
+      validateRedaction(step.redact ?? []);
+    }
+  });
+};
+
+const validateRedaction = (redaction: RedactionConfig) => {
+  RedactionItemsArray.parse(redaction);
+};
+
+export const validateWebProofRequest = (
+  webProofRequest: WebProofRequestInput,
+) => {
+  validateSteps(webProofRequest.steps);
+};
+
+export const createExtensionWebProofProvider = ({
+  notaryUrl = "https://notary.pse.dev/v0.1.0-alpha.7",
+  wsProxyUrl = "wss://notary.pse.dev/proxy",
+}: WebProofProviderSetup = {}): WebProofProvider => {
+  return new ExtensionWebProofProvider(notaryUrl, wsProxyUrl);
+};

package/src/api/webProof/providers/index.ts

@@ -0,0 +1 @@
+export * from "./extension";

package/src/api/webProof/steps/expectUrl.ts

@@ -0,0 +1,12 @@
+import {
+  EXTENSION_STEP,
+  type WebProofStepExpectUrl,
+} from "../../../web-proof-commons";
+
+export const expectUrl = (url: string, label: string) => {
+  return {
+    url,
+    label,
+    step: EXTENSION_STEP.expectUrl,
+  } as WebProofStepExpectUrl;
+};

package/src/api/webProof/steps/index.ts

@@ -0,0 +1,11 @@
+import { expectUrl } from "./expectUrl";
+import { startPage } from "./startPage";
+import { notarize } from "./notarize";
+
+const steps = {
+  expectUrl,
+  startPage,
+  notarize,
+};
+
+export { expectUrl, startPage, notarize, steps };

package/src/api/webProof/steps/notarize.ts

@@ -0,0 +1,20 @@
+import {
+  EXTENSION_STEP,
+  type WebProofStepNotarize,
+  type RedactionConfig,
+} from "../../../web-proof-commons";
+
+export const notarize = (
+  url: string,
+  method: string = "GET",
+  label: string,
+  redact?: RedactionConfig,
+) => {
+  return {
+    url,
+    method,
+    label,
+    redact: redact ?? [],
+    step: EXTENSION_STEP.notarize,
+  } as WebProofStepNotarize;
+};

package/src/api/webProof/steps/startPage.ts

@@ -0,0 +1,12 @@
+import {
+  EXTENSION_STEP,
+  type WebProofStepStartPage,
+} from "../../../web-proof-commons";
+
+export const startPage = (url: string, label: string) => {
+  return {
+    url,
+    label,
+    step: EXTENSION_STEP.startPage,
+  } as WebProofStepStartPage;
+};