@idos-network/client 1.0.0-rc.1.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@idos-network/client",
+  "description": "idOS Client JavaScript SDK for browser environments",
+  "version": "1.0.0-rc.1.0",
+  "clean-package": {
+    "remove": [
+      "devDependencies.@idos-network/core"
+    ]
+  },
+  "dependencies": {
+    "@kwilteam/kwil-js": "^0.9.4",
+    "es-toolkit": "^1.38.0",
+    "tiny-invariant": "^1.3.3"
+  },
+  "devDependencies": {
+    "clean-package": "^2.2.0",
+    "release-it": "^19.0.2",
+    "release-it-pnpm": "^4.6.5",
+    "tsdown": "^0.11.12",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*"
+  ],
+  "homepage": "https://idos.network",
+  "license": "MIT",
+  "module": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "https://github.com/idos-network/idos-sdk-js",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown  --watch",
+    "postpack": "clean-package restore",
+    "prepack": "clean-package",
+    "publint": "pnpx publint --strict",
+    "release-it": "release-it"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "types": "dist/index.d.ts"
+}

package/src/enclave/iframe-enclave.ts

@@ -0,0 +1,237 @@
+import { base64Encode, type idOSCredential } from "@idos-network/core";
+
+import type {
+  DiscoverUserEncryptionPublicKeyResponse,
+  EnclaveOptions,
+  EnclaveProvider,
+  StoredData,
+} from "./types";
+
+export class IframeEnclave implements EnclaveProvider {
+  options: Omit<EnclaveOptions, "container" | "url">;
+  container: string;
+  iframe: HTMLIFrameElement;
+  hostUrl: URL;
+
+  constructor(options: EnclaveOptions) {
+    const { container, ...other } = options;
+
+    this.container = container;
+    this.options = other;
+    this.hostUrl = new URL(other.url ?? "https://enclave.idos.network");
+    this.iframe = document.createElement("iframe");
+    this.iframe.id = "idos-enclave-iframe";
+  }
+
+  async load(): Promise<void> {
+    await this.loadEnclave();
+    await this.requestToEnclave({ configure: this.options });
+  }
+
+  async reconfigure(options: Omit<EnclaveOptions, "container" | "url">): Promise<void> {
+    Object.assign(this.options, options);
+    await this.requestToEnclave({ configure: this.options });
+  }
+
+  async ready(userId: string, expectedUserEncryptionPublicKey?: string): Promise<Uint8Array> {
+    let { encryptionPublicKey: userEncryptionPublicKey } = (await this.requestToEnclave({
+      storage: {
+        userId,
+        expectedUserEncryptionPublicKey,
+      },
+    })) as StoredData;
+
+    while (!userEncryptionPublicKey) {
+      this.showEnclave();
+      try {
+        userEncryptionPublicKey = (await this.requestToEnclave({
+          keys: {},
+        })) as Uint8Array;
+      } catch (e) {
+        if (this.options.throwOnUserCancelUnlock) throw e;
+      } finally {
+        this.hideEnclave();
+      }
+    }
+
+    return userEncryptionPublicKey;
+  }
+
+  async reset(): Promise<void> {
+    this.requestToEnclave({ reset: {} });
+  }
+
+  async confirm(message: string): Promise<boolean> {
+    this.showEnclave();
+
+    return this.requestToEnclave({ confirm: { message } }).then((response) => {
+      this.hideEnclave();
+      return response as boolean;
+    });
+  }
+
+  async encrypt(
+    message: Uint8Array,
+    receiverPublicKey: Uint8Array,
+  ): Promise<{ content: Uint8Array; encryptorPublicKey: Uint8Array }> {
+    return this.requestToEnclave({
+      encrypt: { message, receiverPublicKey },
+    }) as Promise<{ content: Uint8Array; encryptorPublicKey: Uint8Array }>;
+  }
+
+  async decrypt(message: Uint8Array, senderPublicKey: Uint8Array): Promise<Uint8Array> {
+    return this.requestToEnclave({
+      decrypt: { fullMessage: message, senderPublicKey },
+    }) as Promise<Uint8Array>;
+  }
+
+  filterCredentials(
+    credentials: idOSCredential[],
+    privateFieldFilters: { pick: Record<string, unknown[]>; omit: Record<string, unknown[]> },
+  ): Promise<idOSCredential[]> {
+    return this.requestToEnclave({
+      filterCredentials: { credentials, privateFieldFilters },
+    }) as Promise<idOSCredential[]>;
+  }
+
+  async loadEnclave(): Promise<void> {
+    const container =
+      document.querySelector(this.container) ||
+      throwNewError(Error, `Can't find container with selector ${this.container}`);
+
+    // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy#directives
+    const permissionsPolicies = ["publickey-credentials-get", "storage-access"];
+
+    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#sandbox
+    const liftedSandboxRestrictions = [
+      "forms",
+      "modals",
+      "popups",
+      "popups-to-escape-sandbox",
+      "same-origin",
+      "scripts",
+    ].map((toLift) => `allow-${toLift}`);
+
+    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#referrerpolicy
+    const referrerPolicy = "origin";
+
+    const styles = {
+      "aspect-ratio": "4/1",
+      "background-color": "transparent",
+      border: "none",
+      display: "block",
+      width: "100%",
+    };
+
+    this.iframe.allow = permissionsPolicies.join("; ");
+    this.iframe.referrerPolicy = referrerPolicy;
+    this.iframe.sandbox.add(...liftedSandboxRestrictions);
+    this.iframe.src = this.hostUrl.toString();
+    for (const [k, v] of Object.entries(styles)) {
+      this.iframe.style.setProperty(k, v);
+    }
+
+    let el: HTMLElement | null;
+    // biome-ignore lint/suspicious/noAssignInExpressions: it's on purpose
+    while ((el = document.getElementById(this.iframe.id))) {
+      console.log("reinstalling idOS iframe...");
+      container.removeChild(el);
+    }
+    container.appendChild(this.iframe);
+
+    return new Promise((resolve) =>
+      this.iframe.addEventListener(
+        "load",
+        () => {
+          resolve();
+        },
+        { once: true },
+      ),
+    );
+  }
+
+  showEnclave(): void {
+    // biome-ignore lint/style/noNonNullAssertion: Make the explosion visible.
+    this.iframe.parentElement!.classList.add("visible");
+  }
+
+  hideEnclave(): void {
+    // biome-ignore lint/style/noNonNullAssertion: Make the explosion visible.
+    this.iframe.parentElement!.classList.remove("visible");
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: `any` is fine here. We will type it properly later.
+  async requestToEnclave(request: any): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const { port1, port2 } = new MessageChannel();
+
+      port1.onmessage = ({ data }) => {
+        port1.close();
+        data.error ? reject(data.error) : resolve(data.result);
+      };
+
+      // biome-ignore lint/style/noNonNullAssertion: Make the explosion visible.
+      this.iframe.contentWindow!.postMessage(request, this.hostUrl.origin, [port2]);
+    });
+  }
+
+  async backupPasswordOrSecret(): Promise<void> {
+    const abortController = new AbortController();
+    this.showEnclave();
+
+    window.addEventListener(
+      "message",
+      async (event) => {
+        if (event.data.type !== "idOS:store" || event.origin !== this.hostUrl.origin) return;
+
+        let status = "";
+
+        try {
+          status = "success";
+          this.hideEnclave();
+        } catch (_) {
+          status = "failure";
+          this.hideEnclave();
+        }
+
+        event.ports[0].postMessage({
+          result: {
+            type: "idOS:store",
+            status,
+          },
+        });
+        event.ports[0].close();
+        abortController.abort();
+      },
+      { signal: abortController.signal },
+    );
+
+    try {
+      await this.requestToEnclave({
+        backupPasswordOrSecret: {},
+      });
+    } catch (error) {
+      console.error(error);
+    } finally {
+      this.hideEnclave();
+    }
+  }
+
+  async discoverUserEncryptionPublicKey(
+    userId: string,
+  ): Promise<DiscoverUserEncryptionPublicKeyResponse> {
+    if (this.options.mode !== "new")
+      throw new Error("You can only call `discoverUserEncryptionPublicKey` when mode is `new`.");
+
+    const userEncryptionPublicKey = await this.ready(userId);
+
+    return {
+      userId,
+      userEncryptionPublicKey: base64Encode(userEncryptionPublicKey),
+    };
+  }
+}
+
+function throwNewError(ErrorClass: ErrorConstructor, ...args: Parameters<ErrorConstructor>): never {
+  throw new ErrorClass(...args);
+}

package/src/enclave/index.ts

@@ -0,0 +1,3 @@
+export { IframeEnclave } from "./iframe-enclave";
+export { MetaMaskSnapEnclave } from "./metamask-snap-enclave";
+export * from "./types";

package/src/enclave/metamask-snap-enclave.ts

@@ -0,0 +1,91 @@
+import type { idOSCredential } from "@idos-network/core";
+import type {
+  DiscoverUserEncryptionPublicKeyResponse,
+  EnclaveOptions,
+  EnclaveProvider,
+} from "./types";
+
+export class MetaMaskSnapEnclave implements EnclaveProvider {
+  // biome-ignore lint/suspicious/noExplicitAny: Types will be added later
+  enclaveHost: any;
+  snapId: string;
+
+  constructor(_?: Record<string, unknown>) {
+    // biome-ignore lint/suspicious/noExplicitAny: Types will be added later.
+    this.enclaveHost = (window as any).ethereum;
+    this.snapId = "npm:@idos-network/metamask-snap-enclave";
+  }
+  reconfigure(_options: Omit<EnclaveOptions, "container" | "url">): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+  filterCredentials(
+    credentials: idOSCredential[],
+    privateFieldFilters: { pick: Record<string, unknown[]>; omit: Record<string, unknown[]> },
+  ): Promise<idOSCredential[]> {
+    console.log(credentials, privateFieldFilters);
+    throw new Error("Method not implemented.");
+  }
+
+  async discoverUserEncryptionPublicKey(): Promise<DiscoverUserEncryptionPublicKeyResponse> {
+    throw new Error("Method not implemented.");
+  }
+
+  async load(): Promise<void> {
+    const snaps = await this.enclaveHost.request({ method: "wallet_getSnaps" });
+    // biome-ignore lint/suspicious/noExplicitAny: Types will be added later
+    const connected = Object.values(snaps).find((snap: any) => snap.id === this.snapId);
+
+    if (!connected)
+      await this.enclaveHost.request({
+        method: "wallet_requestSnaps",
+        params: { [this.snapId]: {} },
+      });
+  }
+
+  async ready(userId: string): Promise<Uint8Array> {
+    let { encryptionPublicKey } = JSON.parse(await this.invokeSnap("storage", { userId }));
+
+    encryptionPublicKey ||= await this.invokeSnap("init");
+    encryptionPublicKey &&= Uint8Array.from(Object.values(encryptionPublicKey));
+
+    return encryptionPublicKey;
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: Using `any` to avoid type errors.
+  invokeSnap(method: string, params: unknown = {}): Promise<any> {
+    return this.enclaveHost.request({
+      method: "wallet_invokeSnap",
+      params: {
+        snapId: this.snapId,
+        request: { method, params },
+      },
+    });
+  }
+
+  async reset(): Promise<void> {
+    return this.invokeSnap("reset");
+  }
+
+  async confirm(message: string): Promise<boolean> {
+    return this.invokeSnap("confirm", { message });
+  }
+
+  async encrypt(
+    message: Uint8Array,
+    receiverPublicKey: Uint8Array,
+  ): Promise<{ content: Uint8Array; encryptorPublicKey: Uint8Array }> {
+    await this.invokeSnap("encrypt", { message, receiverPublicKey });
+
+    throw new Error("The Metamask Enclave needs to be updated");
+  }
+
+  async decrypt(message: Uint8Array, senderPublicKey: Uint8Array): Promise<Uint8Array> {
+    const decrypted = await this.invokeSnap("decrypt", { message, senderPublicKey });
+
+    return Uint8Array.from(Object.values(decrypted));
+  }
+
+  async backupPasswordOrSecret(): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+}

package/src/enclave/types.ts

@@ -0,0 +1,44 @@
+import type { idOSCredential } from "@idos-network/core";
+
+export type StoredData = {
+  encryptionPublicKey?: Uint8Array;
+  userId?: string;
+};
+
+export type DiscoverUserEncryptionPublicKeyResponse = {
+  userId: string;
+  userEncryptionPublicKey: string;
+};
+
+export type EnclaveOptions = {
+  container: string;
+  theme?: "light" | "dark";
+  mode?: "new" | "existing";
+  url?: string;
+  throwOnUserCancelUnlock?: boolean;
+};
+
+export interface EnclaveProvider {
+  load(): Promise<void>;
+  reconfigure(options: Omit<EnclaveOptions, "container" | "url">): Promise<void>;
+
+  ready(userId: string, currentUserEncryptionPublicKey?: string): Promise<Uint8Array>;
+  reset(): Promise<void>;
+  confirm(message: string): Promise<boolean>;
+  encrypt(
+    message: Uint8Array,
+    receiverPublicKey?: Uint8Array,
+  ): Promise<{ content: Uint8Array; encryptorPublicKey: Uint8Array }>;
+  decrypt(message: Uint8Array, senderPublicKey?: Uint8Array): Promise<Uint8Array>;
+  discoverUserEncryptionPublicKey(userId: string): Promise<DiscoverUserEncryptionPublicKeyResponse>;
+
+  filterCredentials(
+    credentials: idOSCredential[],
+    privateFieldFilters: {
+      pick: Record<string, unknown[]>;
+      omit: Record<string, unknown[]>;
+    },
+  ): Promise<idOSCredential[]>;
+
+  backupPasswordOrSecret(): Promise<void>;
+}