@idos-network/kwil-infra 1.5.0 → 2.2.2

package/src/create-kgw-authenticated-fetch.ts

@@ -0,0 +1,321 @@
+import { type KwilSigner, NodeKwil } from "@idos-network/kwil-js";
+import { BlobGateway, type BlobGatewayParams } from "@idos-network/utils/blob-gateway";
+
+import type { KwilActionClient } from "./create-kwil-client";
+import type { MmTokenAuth } from "./mm-token/create-mm-token-kwil-signer";
+
+import { isMmTokenAuth } from "./mm-token/create-mm-token-kwil-signer";
+
+const KGW_AUTH_ERROR_CODE = -901;
+
+/** Return true when the response means KGW auth is missing/expired.
+ *  May read the body only for `application/json` responses (those are probed via a clone). */
+export type KgwAuthFailurePredicate = (response: Response) => Promise<boolean> | boolean;
+
+export type CreateKgwAuthenticatedFetchParams = {
+  kwilClient: KwilActionClient;
+  signer: KwilSigner;
+  fetchFn?: typeof fetch;
+  isAuthFailure?: KgwAuthFailurePredicate;
+};
+
+export type CreateKgwAuthenticatedBlobGatewayParams = CreateKgwAuthenticatedFetchParams & {
+  url: string;
+  maxFetchBytes?: BlobGatewayParams["maxFetchBytes"];
+  /**
+   * UKYC storage authority for blob requests. Defaults to `signer` when that signer
+   * is itself an MM authentication object, so the capability is never passed twice.
+   */
+  mmAuth?: MmTokenAuth;
+};
+
+type KgwSessionNodeKwil = NodeKwil & {
+  authenticateKGWAndSetCookie(signer: KwilSigner): Promise<string>;
+  getKgwCookie(): string | undefined;
+};
+
+export function createKgwAuthenticatedBlobGateway({
+  url,
+  maxFetchBytes,
+  mmAuth,
+  ...fetchParams
+}: CreateKgwAuthenticatedBlobGatewayParams): BlobGateway {
+  const storageAuth =
+    mmAuth ?? (isMmTokenAuth(fetchParams.signer) ? fetchParams.signer : undefined);
+
+  return new BlobGateway({
+    url,
+    maxFetchBytes,
+    accessToken: storageAuth?.accessToken,
+    fetchFn: createKgwAuthenticatedFetch(fetchParams),
+  });
+}
+
+export function createKgwAuthenticatedFetch({
+  kwilClient,
+  signer,
+  fetchFn = fetch,
+  isAuthFailure = defaultKgwAuthFailurePredicate,
+}: CreateKgwAuthenticatedFetchParams): typeof fetch {
+  const nodeKwil = getNodeKwilClient(kwilClient);
+  // Coalesce in-flight re-auths. Node isn't multi-threaded, but concurrent awaits still
+  // interleave: two fetches can both see an auth failure and both call refreshCookie before
+  // either finishes. Without this, that would kick off two authenticateKGWAndSetCookie calls.
+  // See "shares one refresh across parallel auth failures".
+  let refreshPromise: Promise<string> | undefined;
+
+  const refreshCookie = async (): Promise<string> => {
+    refreshPromise ??= nodeKwil.authenticateKGWAndSetCookie(signer).finally(() => {
+      refreshPromise = undefined;
+    });
+
+    return refreshPromise;
+  };
+
+  const ensureCookie = async (): Promise<{ cookie: string; refreshed: boolean }> => {
+    const existingCookie = nodeKwil.getKgwCookie();
+    if (existingCookie) {
+      return { cookie: existingCookie, refreshed: false };
+    }
+
+    return { cookie: await refreshCookie(), refreshed: true };
+  };
+
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const { cookie } = await ensureCookie();
+    const bufferedRequest = await bufferRequestBody(input, init);
+    const response = await fetchFn(
+      ...withCookie(input, withMaterializedBody(bufferedRequest), cookie),
+    );
+
+    const probe = authFailureProbe(response);
+    if (!(await isAuthFailure(probe.response))) {
+      return response;
+    }
+
+    // Discard the failed response so an unread body doesn't keep streaming.
+    await discardUnreadBodies(probe.discardResponses);
+    const refreshedCookie = await refreshCookie();
+    return fetchFn(...withCookie(input, withMaterializedBody(bufferedRequest), refreshedCookie));
+  };
+}
+
+type AuthFailureProbe = {
+  response: Response;
+  discardResponses: Response[];
+};
+
+/**
+ * Body is one-shot. Only clone when the default predicate might call `.json()`
+ * (JSON content-type). Cloning a large blob response would tee the stream and
+ * risk buffering the download on an abandoned branch — and in Node, canceling
+ * that unread tee branch hangs.
+ *
+ * When a cloned response is thrown away after an auth failure, cancel both tee
+ * branches together; canceling only one branch can wait forever for the other.
+ */
+function authFailureProbe(response: Response): AuthFailureProbe {
+  const contentType = response.headers.get("content-type");
+  if (contentType?.includes("application/json")) {
+    const probe = response.clone();
+    return { response: probe, discardResponses: [response, probe] };
+  }
+
+  return { response, discardResponses: [response] };
+}
+
+async function discardUnreadBodies(responses: Response[]): Promise<void> {
+  await Promise.all(responses.map(discardUnreadBody));
+}
+
+async function discardUnreadBody(response: Response): Promise<void> {
+  if (response.bodyUsed || !response.body) {
+    return;
+  }
+
+  try {
+    await response.body.cancel();
+  } catch {
+    // Already locked/closed by a concurrent reader.
+  }
+}
+
+type BufferedFormDataEntry =
+  | { key: string; value: string }
+  | { key: string; value: ArrayBuffer; fileName: string; type: string };
+
+type BufferedBody =
+  | { kind: "body"; value: BodyInit }
+  | { kind: "form-data"; entries: BufferedFormDataEntry[] };
+
+type BufferedRequestBody = {
+  requestInit: RequestInit | undefined;
+  bufferedBody?: BufferedBody;
+};
+
+async function bufferRequestBody(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<BufferedRequestBody> {
+  if (init?.body != null) {
+    return {
+      requestInit: init,
+      bufferedBody: await bufferBody(init.body),
+    };
+  }
+
+  if (input instanceof Request && input.body != null) {
+    const requestClone = input.clone();
+    return {
+      requestInit: {
+        ...init,
+        method: init?.method ?? input.method,
+      },
+      bufferedBody: await bufferBody(requestClone.body!),
+    };
+  }
+
+  return { requestInit: init };
+}
+
+function withMaterializedBody({
+  requestInit,
+  bufferedBody,
+}: BufferedRequestBody): RequestInit | undefined {
+  if (!bufferedBody) {
+    return requestInit;
+  }
+
+  return {
+    ...requestInit,
+    body: materializeBody(bufferedBody),
+  };
+}
+
+async function bufferBody(body: BodyInit): Promise<BufferedBody> {
+  if (
+    typeof body === "string" ||
+    body instanceof Blob ||
+    body instanceof ArrayBuffer ||
+    body instanceof URLSearchParams
+  ) {
+    return { kind: "body", value: body };
+  }
+
+  if (ArrayBuffer.isView(body)) {
+    return {
+      kind: "body",
+      value: new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+    };
+  }
+
+  if (body instanceof FormData) {
+    const entries: Promise<BufferedFormDataEntry>[] = [];
+
+    body.forEach((value, key) => {
+      entries.push(bufferFormDataEntry(key, value));
+    });
+
+    return { kind: "form-data", entries: await Promise.all(entries) };
+  }
+
+  if (body instanceof ReadableStream) {
+    return {
+      kind: "body",
+      value: await new Response(body).arrayBuffer(),
+    };
+  }
+
+  return { kind: "body", value: body };
+}
+
+async function bufferFormDataEntry(
+  key: string,
+  value: FormDataEntryValue,
+): Promise<BufferedFormDataEntry> {
+  if (typeof value === "string") {
+    return { key, value };
+  }
+
+  return {
+    key,
+    value: await new Response(value).arrayBuffer(),
+    fileName: value instanceof File ? value.name : "blob",
+    type: value.type || "application/octet-stream",
+  };
+}
+
+function materializeBody(bufferedBody: BufferedBody): BodyInit {
+  if (bufferedBody.kind === "body") {
+    return bufferedBody.value;
+  }
+
+  const formData = new FormData();
+
+  for (const entry of bufferedBody.entries) {
+    if ("fileName" in entry) {
+      formData.append(entry.key, new Blob([entry.value], { type: entry.type }), entry.fileName);
+    } else {
+      formData.append(entry.key, entry.value);
+    }
+  }
+
+  return formData;
+}
+
+function getNodeKwilClient(kwilClient: KwilActionClient): KgwSessionNodeKwil {
+  if (!(kwilClient.client instanceof NodeKwil)) {
+    throw new Error("KGW authenticated fetch can only be created from a NodeKwil client");
+  }
+
+  if (!hasKgwSessionHelpers(kwilClient.client)) {
+    throw new Error("NodeKwil client does not expose KGW session cookie helpers");
+  }
+
+  return kwilClient.client;
+}
+
+function hasKgwSessionHelpers(client: NodeKwil): client is KgwSessionNodeKwil {
+  const maybeClient = client as Partial<KgwSessionNodeKwil>;
+
+  return (
+    typeof maybeClient.getKgwCookie === "function" &&
+    typeof maybeClient.authenticateKGWAndSetCookie === "function"
+  );
+}
+
+function withCookie(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+  cookie: string,
+): Parameters<typeof fetch> {
+  const headers = new Headers(input instanceof Request ? input.headers : undefined);
+
+  if (init?.headers) {
+    new Headers(init.headers).forEach((value, key) => {
+      headers.set(key, value);
+    });
+  }
+
+  headers.set("Cookie", cookie);
+
+  return [input, { ...init, headers }];
+}
+
+async function defaultKgwAuthFailurePredicate(response: Response): Promise<boolean> {
+  if (response.status === 401) {
+    return true;
+  }
+
+  const contentType = response.headers.get("content-type");
+  if (!contentType?.includes("application/json")) {
+    return false;
+  }
+
+  try {
+    const body = (await response.json()) as { error?: { code?: number } };
+    return body.error?.code === KGW_AUTH_ERROR_CODE;
+  } catch {
+    return false;
+  }
+}

package/src/create-kwil-client.ts

@@ -1,10 +1,6 @@
-import type { Config } from "@idos-network/kwil-js/dist/api_client/config";
-import type {
-  ActionBody,
-  CallBody,
-  PositionalParams,
-} from "@idos-network/kwil-js/dist/core/action";
-import type { DataInfo } from "@idos-network/kwil-js/dist/core/database";
+import type { ActionBody, CallBody, PositionalParams } from "@idos-network/kwil-js/action";
+import type { Config } from "@idos-network/kwil-js/config";
+import type { DataInfo } from "@idos-network/kwil-js/database";
 
 import { type KwilSigner, NodeKwil, WebKwil } from "@idos-network/kwil-js";
 import invariant from "tiny-invariant";
@@ -12,6 +8,9 @@ import invariant from "tiny-invariant";
 import type { ActionSchemaElement } from "./actions";
 
 import { actionSchema } from "./actions";
+import { waitForKwilTx } from "./wait-for-kwil-tx";
+
+export { KwilTxFailedError, KwilTxPollTimeoutError } from "./wait-for-kwil-tx";
 
 type CreateKwilClientParams = {
   chainId?: string;
@@ -87,12 +86,15 @@ export class KwilActionClient {
 
   /**
    * Executes an action on the kwil nodes. This similar to `POST` like request.
+   *
+   * When `synchronous` is true (default), the tx is broadcast without blocking the node,
+   * then confirmed by polling `txInfo` with exponential backoff.
    */
   async execute(
     params: KwilExecuteActionRequestParams,
     signer: KwilSigner | undefined = this.signer,
     synchronous = true,
-  ): Promise<string | undefined> {
+  ): Promise<string> {
     invariant(signer, "Signer is not set, you must set it before executing an action");
     const action: ActionBody = {
       name: params.name,
@@ -101,8 +103,29 @@ export class KwilActionClient {
       inputs: [this.#createActionInputs(params.name, params.inputs)],
       types: this.#actionTypes(params.name),
     };
-    const response = await this.client.execute(action, signer, synchronous);
-    return response.data?.tx_hash;
+    const response = await this.client.execute(action, signer, false);
+    const txHash = response.data?.tx_hash;
+
+    if (!txHash) {
+      throw new Error(`Kwil execute "${params.name}" did not return a transaction hash`);
+    }
+
+    if (synchronous) {
+      await this.waitForTx(txHash);
+    }
+
+    return txHash;
+  }
+
+  /**
+   * Polls the node until a broadcast transaction is mined, or throws
+   * `KwilTxFailedError` / `KwilTxPollTimeoutError`.
+   *
+   * Called through `this` rather than directly so that it is a seam an
+   * instrumentation can wrap — the wait dominates the latency of `execute`.
+   */
+  async waitForTx(txHash: string): Promise<void> {
+    await waitForKwilTx((hash) => this.client.txInfo(hash), txHash);
   }
 
   setSigner(signer: KwilSigner | undefined): void {

package/src/create-kwil-signer.test.ts

@@ -0,0 +1,80 @@
+import { base64UrlEncode, utf8Encode } from "@idos-network/utils/codecs";
+import { MemoryStore } from "@idos-network/utils/store";
+import nacl from "tweetnacl";
+import { describe, expect, it, vi } from "vitest";
+
+import type { KwilActionClient } from "./create-kwil-client";
+
+import { createClientKwilSigner, createServerKwilSigner } from "./create-kwil-signer";
+import { createMmTokenAuth } from "./mm-token/create-mm-token-kwil-signer";
+
+function mmToken(signingKeyByte: number): string {
+  return base64UrlEncode(
+    utf8Encode(
+      JSON.stringify({
+        payload: {
+          signing_public_key: base64UrlEncode(new Uint8Array(32).fill(signingKeyByte)),
+          storage_id: "storage-abc",
+        },
+        signature: base64UrlEncode(new Uint8Array(64).fill(9)),
+      }),
+    ),
+  );
+}
+
+function kwilClientWithLogout(logoutKGW: () => Promise<void>): KwilActionClient {
+  return { client: { auth: { logoutKGW } } } as unknown as KwilActionClient;
+}
+
+describe("createClientKwilSigner with MM authentication", () => {
+  it("reports the MM signing identity as address and public key", async () => {
+    const auth = createMmTokenAuth(mmToken(7));
+    const logoutKGW = vi.fn(async () => {});
+
+    const [signer, address, publicKey, walletType] = await createClientKwilSigner(
+      new MemoryStore(),
+      kwilClientWithLogout(logoutKGW),
+      auth,
+    );
+
+    expect(signer).toBe(auth);
+    expect(walletType).toBe("MM");
+    expect(address).toBe(base64UrlEncode(auth.identifier));
+    expect(publicKey).toBe(address);
+  });
+
+  it("clears the KGW session only when the MM signing identity changes", async () => {
+    const store = new MemoryStore();
+    const logoutKGW = vi.fn(async () => {});
+    const kwilClient = kwilClientWithLogout(logoutKGW);
+
+    await createClientKwilSigner(store, kwilClient, createMmTokenAuth(mmToken(7)));
+    expect(logoutKGW).toHaveBeenCalledTimes(1);
+
+    // Same identity, freshly issued token: the existing KGW cookie stays valid.
+    await createClientKwilSigner(store, kwilClient, createMmTokenAuth(mmToken(7)));
+    expect(logoutKGW).toHaveBeenCalledTimes(1);
+
+    await createClientKwilSigner(store, kwilClient, createMmTokenAuth(mmToken(8)));
+    expect(logoutKGW).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createServerKwilSigner with MM authentication", () => {
+  it("uses the MM authentication object as the Kwil signer", async () => {
+    const auth = createMmTokenAuth(mmToken(7));
+
+    expect(await createServerKwilSigner(auth)).toEqual([auth, base64UrlEncode(auth.identifier)]);
+  });
+});
+
+describe("createServerKwilSigner with Nacl sign key pair", () => {
+  it("emits lowercase hex SignerAddress matching kwild ed25519 @caller format", async () => {
+    const keyPair = nacl.sign.keyPair();
+    const [kwilSigner, signerAddress] = await createServerKwilSigner(keyPair);
+
+    expect(signerAddress).toMatch(/^[0-9a-f]{64}$/);
+    expect(signerAddress).toBe(signerAddress.toLowerCase());
+    expect(kwilSigner).toBeDefined();
+  });
+});

package/src/create-kwil-signer.ts

@@ -6,13 +6,15 @@ import type { KeyPair as NearKeyPair } from "near-api-js";
 import type { KeyPair as XrpKeyPair } from "ripple-keypairs/src/types";
 
 import { KwilSigner } from "@idos-network/kwil-js";
-import { bs58Encode, hexDecode, hexEncode } from "@idos-network/utils/codecs";
+import { base64UrlEncode, bs58Encode, hexDecode, hexEncode } from "@idos-network/utils/codecs";
 import nacl from "tweetnacl";
 
 import type { WalletType } from "./actions";
 import type { KwilActionClient } from "./create-kwil-client";
+import type { MmTokenAuth } from "./mm-token/create-mm-token-kwil-signer";
 
 import { FaceSignSignerProvider } from "./facesign/facesign-signer";
+import { isMmTokenAuth } from "./mm-token/create-mm-token-kwil-signer";
 import {
   createNearWalletKwilSigner,
   implicitAddressFromPublicKey,
@@ -28,6 +30,7 @@ export type Wallet =
   | JsonRpcSigner
   | NearWallet
   | CustomKwilSigner
+  | MmTokenAuth
   | FaceSignSignerProvider;
 
 /**
@@ -108,7 +111,8 @@ export type KwilSignerType =
   | nacl.SignKeyPair
   | JsonRpcSigner
   | StellarKeypair
-  | XrpKeyPair;
+  | XrpKeyPair
+  | MmTokenAuth;
 
 export type SignerAddress = string;
 export type SignerPublicKey = string | undefined;
@@ -122,6 +126,10 @@ export type SignerPublicKey = string | undefined;
 export async function createServerKwilSigner(
   signer: KwilSignerType,
 ): Promise<[KwilSigner, SignerAddress]> {
+  if (isMmTokenAuth(signer)) {
+    return [signer, base64UrlEncode(signer.identifier)];
+  }
+
   if (isNaclSignKeyPair(signer)) {
     return [
       new KwilSigner(
@@ -134,10 +142,11 @@ export async function createServerKwilSigner(
   }
 
   if (isNearKeyPair(signer)) {
-    const publicKey = implicitAddressFromPublicKey(signer.getPublicKey().toString());
+    const rawPublicKey = signer.getPublicKey().toString();
+    const hexPublicKey = implicitAddressFromPublicKey(rawPublicKey);
     return [
-      new KwilSigner(kwilNep413Signer("idos-issuer")(signer), publicKey, "nep413"),
-      publicKey,
+      new KwilSigner(kwilNep413Signer("idos-issuer")(signer), hexPublicKey, "nep413"),
+      rawPublicKey,
     ];
   }
 
@@ -238,6 +247,23 @@ export async function createClientKwilSigner(
     ];
   }
 
+  if (isMmTokenAuth(wallet)) {
+    const currentAddress = base64UrlEncode(wallet.identifier);
+    const storedAddress = await store.get<string>("signer-address");
+
+    if (storedAddress !== currentAddress) {
+      // A different MM signing identity must not re-use the previous KGW cookie.
+      store.set("signer-address", currentAddress);
+      try {
+        await kwilClient.client.auth.logoutKGW();
+      } catch (error) {
+        console.log("error logoutKGW", error);
+      }
+    }
+
+    return [wallet, currentAddress, currentAddress, "MM"];
+  }
+
   if (isCustomKwilSigner(wallet) || wallet instanceof FaceSignSignerProvider) {
     const storedAddress = await store.get<string>("signer-address");
 

package/src/facesign/facesign-signer.test.ts

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { FaceSignSignerProvider } from "./facesign-signer";
+
+const ENCLAVE_ORIGIN = "https://facesign.example";
+
+function provider() {
+  return new FaceSignSignerProvider({
+    metadata: { name: "idOS Dashboard", description: "FaceSign signer" },
+    enclaveUrl: ENCLAVE_ORIGIN,
+  });
+}
+
+function iframeWindow(): Window {
+  const iframe = document.querySelector("iframe");
+  if (!iframe?.contentWindow) {
+    throw new Error("FaceSign iframe did not load");
+  }
+  return iframe.contentWindow;
+}
+
+describe("FaceSignSignerProvider.reset", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    document.body.replaceChildren();
+  });
+
+  it("asks the enclave to delete its key before tearing the iframe down", async () => {
+    const signer = provider();
+    const posted: unknown[] = [];
+    const reset = signer.reset();
+
+    await vi.waitFor(() => {
+      expect(document.querySelector("iframe")).not.toBeNull();
+    });
+
+    const contentWindow = iframeWindow();
+    vi.spyOn(contentWindow, "postMessage").mockImplementation((message) => {
+      posted.push(message);
+    });
+
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        origin: ENCLAVE_ORIGIN,
+        data: { type: "facesign_ready", hasKey: true },
+      }),
+    );
+
+    await vi.waitFor(() => {
+      expect(posted).toContainEqual({ type: "reset", data: { id: 1 } });
+    });
+
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        origin: ENCLAVE_ORIGIN,
+        data: { type: "reset_complete", data: { id: 1, ok: true } },
+      }),
+    );
+
+    await reset;
+    expect(document.querySelector("iframe")).toBeNull();
+  });
+
+  it("rejects within the reset deadline when the enclave never becomes ready", async () => {
+    vi.useFakeTimers();
+    const signer = provider();
+    const reset = signer.reset();
+    const rejected = expect(reset).rejects.toThrow("FaceSign enclave failed to load");
+
+    await vi.advanceTimersByTimeAsync(15_000);
+
+    await rejected;
+    expect(document.querySelector("iframe")).toBeNull();
+  });
+});