@thru/wallet 0.2.25 → 0.2.28

package/src/provider/chains/ThruChain.ts

@@ -2,11 +2,42 @@ import {
   AddressType,
   type IThruChain,
   type ThruSigningContext,
+  type ThruSigningSession,
+  type ThruSigningSessionCreateOptions,
+  type ThruSigningSessionDescriptor,
+  type ThruSigningSessionInstruction,
+  type ThruSigningSessionInstructionCreateOptions,
+  type ThruPasskeyChallengeIntent,
+  type ThruPasskeyChallengeSignature,
   type ThruTransactionIntent,
 } from "../../interfaces";
 import { POST_MESSAGE_REQUEST_TYPES, createRequestId } from "../../protocol";
+import { base64ToBytes } from "../../encoding";
 import type { EmbeddedProvider } from "../EmbeddedProvider";
 import type { IframeManager } from "../IframeManager";
+import {
+  SigningSessionDescriptorStore,
+  assertSigningSessionWalletAccountIdx,
+  resolveSessionExpirySeconds,
+} from "../../signing-sessions";
+
+function descriptorFromWire(session: {
+  id: string;
+  walletAddress: string;
+  publicKey: string;
+  authIdx: number;
+  expiresAt: string;
+  createdAt: string;
+}): ThruSigningSessionDescriptor {
+  return {
+    id: session.id,
+    walletAddress: session.walletAddress,
+    publicKey: session.publicKey,
+    authIdx: session.authIdx,
+    expiresAt: Number(BigInt(session.expiresAt)),
+    createdAt: Number(BigInt(session.createdAt)),
+  };
+}
 
 /**
  * EmbeddedThruChain - postMessage-backed Thru chain adapter.
@@ -14,10 +45,16 @@ import type { IframeManager } from "../IframeManager";
 export class EmbeddedThruChain implements IThruChain {
   private readonly iframeManager: IframeManager;
   private readonly provider: EmbeddedProvider;
+  private readonly signingSessions?: SigningSessionDescriptorStore;
 
-  constructor(iframeManager: IframeManager, provider: EmbeddedProvider) {
+  constructor(
+    iframeManager: IframeManager,
+    provider: EmbeddedProvider,
+    signingSessions?: SigningSessionDescriptorStore,
+  ) {
     this.iframeManager = iframeManager;
     this.provider = provider;
+    this.signingSessions = signingSessions;
   }
 
   get connected(): boolean {
@@ -58,29 +95,198 @@ export class EmbeddedThruChain implements IThruChain {
   }
 
   async signTransaction(transaction: ThruTransactionIntent): Promise<string> {
-    if (!this.provider.isConnected()) {
+    const signingSessionId = transaction.signingSessionId;
+    if (!signingSessionId && !this.provider.isConnected()) {
       throw new Error("Wallet not connected");
     }
 
-    this.iframeManager.show();
+    const session = signingSessionId
+      ? await this.requireSigningSession(signingSessionId)
+      : null;
+    const shouldShowWallet = !signingSessionId;
+    if (shouldShowWallet) {
+      this.iframeManager.show();
+    }
 
     try {
       const response = await this.iframeManager.sendMessage({
         id: createRequestId(),
         type: POST_MESSAGE_REQUEST_TYPES.SIGN_TRANSACTION,
         payload: {
-          walletAddress: transaction.walletAddress,
+          walletAddress: transaction.walletAddress ?? session?.walletAddress,
           programAddress: transaction.programAddress,
           instructionData: transaction.instructionData,
           readWriteAddresses: transaction.readWriteAddresses,
           readOnlyAddresses: transaction.readOnlyAddresses,
           review: transaction.review,
+          signingSessionId,
         },
         origin: window.location.origin,
       });
       return response.result.signedTransaction;
+    } finally {
+      if (shouldShowWallet) {
+        this.iframeManager.hide();
+      }
+    }
+  }
+
+  async signPasskeyChallenge(
+    challenge: ThruPasskeyChallengeIntent,
+  ): Promise<ThruPasskeyChallengeSignature> {
+    if (!this.provider.isConnected()) {
+      throw new Error("Wallet not connected");
+    }
+
+    this.iframeManager.show();
+    try {
+      const response = await this.iframeManager.sendMessage({
+        id: createRequestId(),
+        type: POST_MESSAGE_REQUEST_TYPES.SIGN_PASSKEY_CHALLENGE,
+        payload: {
+          challenge: challenge.challenge,
+          walletAddress: challenge.walletAddress,
+        },
+        origin: window.location.origin,
+      });
+      return response.result;
+    } finally {
+      this.iframeManager.hide();
+    }
+  }
+
+  async createSigningSession(
+    options: ThruSigningSessionCreateOptions,
+  ): Promise<ThruSigningSession> {
+    if (!this.provider.isConnected()) {
+      throw new Error("Wallet not connected");
+    }
+    if (!this.signingSessions) {
+      throw new Error("Signing session storage is not available");
+    }
+
+    const expiresAt = resolveSessionExpirySeconds(options);
+    this.iframeManager.show();
+    try {
+      const response = await this.iframeManager.sendMessage({
+        id: createRequestId(),
+        type: POST_MESSAGE_REQUEST_TYPES.CREATE_SIGNING_SESSION,
+        payload: {
+          walletAddress: options.walletAddress,
+          expiresAt: String(expiresAt),
+          review: options.review,
+        },
+        origin: window.location.origin,
+      });
+      const descriptor = descriptorFromWire(response.result.session);
+      await this.signingSessions.saveReplacingWalletSessions(descriptor);
+      return this.toSigningSession(descriptor);
     } finally {
       this.iframeManager.hide();
     }
   }
+
+  async createSigningSessionInstruction(
+    options: ThruSigningSessionInstructionCreateOptions,
+  ): Promise<ThruSigningSessionInstruction> {
+    if (!this.provider.isConnected()) {
+      throw new Error("Wallet not connected");
+    }
+    if (!this.signingSessions) {
+      throw new Error("Signing session storage is not available");
+    }
+
+    const expiresAt = resolveSessionExpirySeconds(options);
+    assertSigningSessionWalletAccountIdx(options.walletAccountIdx);
+    const response = await this.iframeManager.sendMessage({
+      id: createRequestId(),
+      type: POST_MESSAGE_REQUEST_TYPES.CREATE_SIGNING_SESSION_INSTRUCTION,
+      payload: {
+        walletAddress: options.walletAddress,
+        expiresAt: String(expiresAt),
+        walletAccountIdx: options.walletAccountIdx,
+      },
+      origin: window.location.origin,
+    });
+    const descriptor = descriptorFromWire(response.result.session);
+    return {
+      session: this.toSigningSession(descriptor),
+      programAddress: response.result.programAddress,
+      instructionData: base64ToBytes(response.result.instructionData),
+    };
+  }
+
+  async confirmSigningSession(id: string): Promise<ThruSigningSession> {
+    if (!this.provider.isConnected()) {
+      throw new Error("Wallet not connected");
+    }
+    if (!this.signingSessions) {
+      throw new Error("Signing session storage is not available");
+    }
+
+    const response = await this.iframeManager.sendMessage({
+      id: createRequestId(),
+      type: POST_MESSAGE_REQUEST_TYPES.CONFIRM_SIGNING_SESSION,
+      payload: { sessionId: id },
+      origin: window.location.origin,
+    });
+    const descriptor = descriptorFromWire(response.result.session);
+    await this.signingSessions.saveReplacingWalletSessions(descriptor);
+    return this.toSigningSession(descriptor);
+  }
+
+  async getSigningSession(id: string): Promise<ThruSigningSession | null> {
+    if (!this.signingSessions) return null;
+    const descriptor = await this.signingSessions.get(id);
+    return descriptor ? this.toSigningSession(descriptor) : null;
+  }
+
+  async getSigningSessions(): Promise<ThruSigningSession[]> {
+    if (!this.signingSessions) return [];
+    return (await this.signingSessions.list()).map((descriptor) =>
+      this.toSigningSession(descriptor),
+    );
+  }
+
+  async revokeSigningSession(id: string): Promise<void> {
+    try {
+      await this.iframeManager.sendMessage({
+        id: createRequestId(),
+        type: POST_MESSAGE_REQUEST_TYPES.REVOKE_SIGNING_SESSION,
+        payload: { sessionId: id },
+        origin: window.location.origin,
+      });
+    } finally {
+      await this.signingSessions?.remove(id);
+    }
+  }
+
+  private async requireSigningSession(
+    id: string,
+  ): Promise<ThruSigningSessionDescriptor> {
+    if (!this.signingSessions) {
+      throw new Error("Signing session storage is not available");
+    }
+    const session = await this.signingSessions.get(id);
+    if (!session) {
+      throw new Error("Signing session is not known to this app");
+    }
+    return session;
+  }
+
+  private toSigningSession(
+    descriptor: ThruSigningSessionDescriptor,
+  ): ThruSigningSession {
+    return {
+      ...descriptor,
+      signTransaction: (transaction) =>
+        this.signTransaction({
+          ...transaction,
+          walletAddress: transaction.walletAddress ?? descriptor.walletAddress,
+          signingSessionId: descriptor.id,
+        }),
+      revoke: () => this.revokeSigningSession(descriptor.id),
+      toJSON: () => ({ ...descriptor }),
+    };
+  }
 }

package/src/provider/types/messages.ts

@@ -10,13 +10,26 @@ export {
   type EmbeddedProviderEvent,
   type PostMessageRequest,
   type ConnectRequestMessage,
+  type CreateSigningSessionPayload,
+  type CreateSigningSessionRequestMessage,
+  type CreateSigningSessionResult,
+  type ConfirmSigningSessionPayload,
+  type ConfirmSigningSessionRequestMessage,
+  type ConfirmSigningSessionResult,
+  type CreateSigningSessionInstructionPayload,
+  type CreateSigningSessionInstructionRequestMessage,
+  type CreateSigningSessionInstructionResult,
   type DisconnectRequestMessage,
   type SignMessageRequestMessage,
   type SignTransactionRequestMessage,
+  type SignPasskeyChallengeRequestMessage,
   type GetAccountsRequestMessage,
   type GetSigningContextRequestMessage,
   type ManageAccountsRequestMessage,
   type SelectAccountRequestMessage,
+  type RevokeSigningSessionPayload,
+  type RevokeSigningSessionRequestMessage,
+  type RevokeSigningSessionResult,
   type DisconnectResult,
   type GetAccountsResult,
   type GetSigningContextResult,
@@ -34,4 +47,7 @@ export {
   type SignMessageResult,
   type SignTransactionPayload,
   type SignTransactionResult,
+  type SignPasskeyChallengePayload,
+  type SignPasskeyChallengeResult,
+  type SigningSessionDescriptorPayload,
 } from "../../protocol";

package/src/react/index.ts

@@ -25,6 +25,12 @@ export type {
   SignMessageParams,
   SignMessageResult,
   ThruSigningContext,
+  ThruSigningSession,
+  ThruSigningSessionCreateOptions,
+  ThruSigningSessionDescriptor,
+  ThruSigningSessionTimestamp,
   ThruTransactionEncoding,
+  ThruTransactionIntent,
   WalletAccount,
 } from "../interfaces";
+export type { SigningSessionStorage } from "../signing-sessions";

package/src/signing-sessions.test.ts

@@ -0,0 +1,182 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  SigningSessionDescriptorStore,
+  assertSigningSessionWalletAccountIdx,
+  resolveSessionExpirySeconds,
+  resolveSigningSessionStorageKey,
+} from "./signing-sessions";
+
+class MemoryStorage {
+  values = new Map<string, string>();
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null;
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value);
+  }
+
+  removeItem(key: string): void {
+    this.values.delete(key);
+  }
+}
+
+describe("signing session descriptor storage", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-06-11T12:00:00.000Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("scopes default storage keys by wallet origin and app origin", () => {
+    const appA = resolveSigningSessionStorageKey({
+      walletOrigin: "https://wallet.example",
+      appOrigin: "https://app-a.example",
+    });
+    const appB = resolveSigningSessionStorageKey({
+      walletOrigin: "https://wallet.example",
+      appOrigin: "https://app-b.example",
+    });
+
+    expect(appA).not.toBe(appB);
+    expect(appA).toContain(encodeURIComponent("https://wallet.example"));
+    expect(appA).toContain(encodeURIComponent("https://app-a.example"));
+  });
+
+  it("stores only active sessions and prunes expired descriptors locally", async () => {
+    const storage = new MemoryStorage();
+    const store = new SigningSessionDescriptorStore(storage, "sessions");
+
+    await store.save({
+      id: "expired",
+      walletAddress: "wallet",
+      publicKey: "expired-pubkey",
+      authIdx: 1,
+      expiresAt: Math.floor(Date.now() / 1000) - 1,
+      createdAt: Math.floor(Date.now() / 1000) - 10,
+    });
+    await store.save({
+      id: "active",
+      walletAddress: "wallet",
+      publicKey: "active-pubkey",
+      authIdx: 2,
+      expiresAt: Math.floor(Date.now() / 1000) + 60,
+      createdAt: Math.floor(Date.now() / 1000),
+    });
+
+    expect(await store.get("expired")).toBeNull();
+    expect(await store.get("active")).toMatchObject({
+      id: "active",
+      publicKey: "active-pubkey",
+      authIdx: 2,
+    });
+    expect(await store.list()).toHaveLength(1);
+  });
+
+  it("replaces a descriptor with the same session id", async () => {
+    const store = new SigningSessionDescriptorStore(new MemoryStorage(), "sessions");
+    const expiresAt = Math.floor(Date.now() / 1000) + 60;
+
+    await store.save({
+      id: "session",
+      walletAddress: "wallet-a",
+      publicKey: "pubkey-a",
+      authIdx: 1,
+      expiresAt,
+      createdAt: Math.floor(Date.now() / 1000),
+    });
+    await store.save({
+      id: "session",
+      walletAddress: "wallet-b",
+      publicKey: "pubkey-b",
+      authIdx: 2,
+      expiresAt,
+      createdAt: Math.floor(Date.now() / 1000),
+    });
+
+    expect(await store.list()).toEqual([
+      expect.objectContaining({
+        id: "session",
+        walletAddress: "wallet-b",
+        publicKey: "pubkey-b",
+        authIdx: 2,
+      }),
+    ]);
+  });
+
+  it("replaces older descriptors for the same wallet when saving a usable session", async () => {
+    const store = new SigningSessionDescriptorStore(new MemoryStorage(), "sessions");
+    const nowSeconds = Math.floor(Date.now() / 1000);
+
+    await store.save({
+      id: "old-wallet-a",
+      walletAddress: "wallet-a",
+      publicKey: "old-pubkey",
+      authIdx: 1,
+      expiresAt: nowSeconds + 60,
+      createdAt: nowSeconds,
+    });
+    await store.save({
+      id: "wallet-b",
+      walletAddress: "wallet-b",
+      publicKey: "wallet-b-pubkey",
+      authIdx: 2,
+      expiresAt: nowSeconds + 60,
+      createdAt: nowSeconds,
+    });
+    await store.saveReplacingWalletSessions({
+      id: "new-wallet-a",
+      walletAddress: "wallet-a",
+      publicKey: "new-pubkey",
+      authIdx: 3,
+      expiresAt: nowSeconds + 120,
+      createdAt: nowSeconds + 1,
+    });
+
+    expect(await store.list()).toEqual([
+      expect.objectContaining({
+        id: "wallet-b",
+        walletAddress: "wallet-b",
+      }),
+      expect.objectContaining({
+        id: "new-wallet-a",
+        walletAddress: "wallet-a",
+        publicKey: "new-pubkey",
+        authIdx: 3,
+      }),
+    ]);
+    expect(await store.get("old-wallet-a")).toBeNull();
+  });
+
+  it("accepts exactly one of durationSeconds or expiresAt", () => {
+    const nowSeconds = Math.floor(Date.now() / 1000);
+
+    expect(resolveSessionExpirySeconds({ durationSeconds: 30 })).toBe(nowSeconds + 30);
+    expect(resolveSessionExpirySeconds({ expiresAt: String(nowSeconds + 45) })).toBe(
+      nowSeconds + 45,
+    );
+    expect(() => resolveSessionExpirySeconds({})).toThrow(
+      "Provide exactly one of durationSeconds or expiresAt",
+    );
+    expect(() =>
+      resolveSessionExpirySeconds({ durationSeconds: 1, expiresAt: nowSeconds + 1 }),
+    ).toThrow("Provide exactly one of durationSeconds or expiresAt");
+  });
+
+  it("rejects invalid signing session wallet account indexes", () => {
+    expect(() => assertSigningSessionWalletAccountIdx(2)).not.toThrow();
+    expect(() => assertSigningSessionWalletAccountIdx(0)).toThrow(
+      "walletAccountIdx must be an account index between 2 and 65535",
+    );
+    expect(() => assertSigningSessionWalletAccountIdx(1.5)).toThrow(
+      "walletAccountIdx must be an account index between 2 and 65535",
+    );
+    expect(() => assertSigningSessionWalletAccountIdx(0x10000)).toThrow(
+      "walletAccountIdx must be an account index between 2 and 65535",
+    );
+  });
+});

package/src/signing-sessions.ts

@@ -0,0 +1,204 @@
+import type {
+  ThruSigningSessionCreateOptions,
+  ThruSigningSessionDescriptor,
+  ThruSigningSessionTimestamp,
+} from "./interfaces";
+
+export interface SigningSessionStorage {
+  getItem: (key: string) => string | null | Promise<string | null>;
+  setItem: (key: string, value: string) => void | Promise<void>;
+  removeItem: (key: string) => void | Promise<void>;
+}
+
+interface SigningSessionStorePayload {
+  version: 1;
+  sessions: ThruSigningSessionDescriptor[];
+}
+
+const STORAGE_VERSION = 1;
+const KEY_PREFIX = "thru.wallet.signing-sessions.v1";
+
+function encodeKeyPart(input: string): string {
+  return encodeURIComponent(input).replace(/[!'()*]/g, (char) =>
+    `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+function nowSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+export function resolveSigningSessionStorageKey(params: {
+  walletOrigin: string;
+  appOrigin: string;
+  storageKey?: string;
+}): string {
+  if (params.storageKey) return params.storageKey;
+  return `${KEY_PREFIX}:${encodeKeyPart(params.walletOrigin)}:${encodeKeyPart(params.appOrigin)}`;
+}
+
+export function getDefaultBrowserSigningSessionStorage(): SigningSessionStorage | null {
+  if (typeof window === "undefined") return null;
+  try {
+    return window.localStorage ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeExpiresAt(
+  value: ThruSigningSessionTimestamp,
+  label = "expiresAt",
+): number {
+  if (value instanceof Date) {
+    const millis = value.getTime();
+    if (!Number.isFinite(millis)) throw new Error(`${label} must be a valid Date`);
+    return Math.floor(millis / 1000);
+  }
+
+  if (typeof value === "bigint") {
+    if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error(`${label} must fit in a JavaScript safe integer`);
+    }
+    return Number(value);
+  }
+
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed)) {
+      throw new Error(`${label} must be a Unix timestamp in seconds`);
+    }
+    return normalizeExpiresAt(BigInt(trimmed), label);
+  }
+
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a finite positive Unix timestamp`);
+  }
+  return Math.floor(value);
+}
+
+export function resolveSessionExpirySeconds(
+  options: ThruSigningSessionCreateOptions,
+): number {
+  const hasDuration = options.durationSeconds !== undefined;
+  const hasExpiresAt = options.expiresAt !== undefined;
+  if (hasDuration === hasExpiresAt) {
+    throw new Error("Provide exactly one of durationSeconds or expiresAt");
+  }
+
+  if (hasDuration) {
+    const duration = options.durationSeconds;
+    if (
+      typeof duration !== "number" ||
+      !Number.isFinite(duration) ||
+      duration <= 0
+    ) {
+      throw new Error("durationSeconds must be a positive number");
+    }
+    return nowSeconds() + Math.floor(duration);
+  }
+
+  return normalizeExpiresAt(options.expiresAt!, "expiresAt");
+}
+
+export function assertSigningSessionWalletAccountIdx(walletAccountIdx: number): void {
+  if (!Number.isInteger(walletAccountIdx) || walletAccountIdx < 2 || walletAccountIdx > 0xffff) {
+    throw new Error("walletAccountIdx must be an account index between 2 and 65535");
+  }
+}
+
+function normalizeDescriptor(
+  descriptor: ThruSigningSessionDescriptor,
+): ThruSigningSessionDescriptor {
+  return {
+    id: descriptor.id,
+    walletAddress: descriptor.walletAddress,
+    publicKey: descriptor.publicKey,
+    authIdx: Number(descriptor.authIdx),
+    expiresAt: normalizeExpiresAt(descriptor.expiresAt, "descriptor.expiresAt"),
+    createdAt: normalizeExpiresAt(descriptor.createdAt, "descriptor.createdAt"),
+  };
+}
+
+function isActive(descriptor: ThruSigningSessionDescriptor): boolean {
+  return nowSeconds() < descriptor.expiresAt;
+}
+
+export class SigningSessionDescriptorStore {
+  private readonly storage: SigningSessionStorage;
+  private readonly key: string;
+
+  constructor(storage: SigningSessionStorage, key: string) {
+    this.storage = storage;
+    this.key = key;
+  }
+
+  async list(): Promise<ThruSigningSessionDescriptor[]> {
+    const sessions = await this.read();
+    const active = sessions.filter(isActive);
+    if (active.length !== sessions.length) {
+      await this.write(active);
+    }
+    return active;
+  }
+
+  async get(id: string): Promise<ThruSigningSessionDescriptor | null> {
+    const sessions = await this.list();
+    return sessions.find((session) => session.id === id) ?? null;
+  }
+
+  async save(descriptor: ThruSigningSessionDescriptor): Promise<void> {
+    const normalized = normalizeDescriptor(descriptor);
+    const sessions = (await this.list()).filter((session) => session.id !== normalized.id);
+    sessions.push(normalized);
+    await this.write(sessions);
+  }
+
+  async saveReplacingWalletSessions(
+    descriptor: ThruSigningSessionDescriptor,
+  ): Promise<void> {
+    const normalized = normalizeDescriptor(descriptor);
+    const sessions = (await this.list()).filter(
+      (session) =>
+        session.id === normalized.id ||
+        session.walletAddress !== normalized.walletAddress,
+    );
+    const withoutCurrent = sessions.filter((session) => session.id !== normalized.id);
+    withoutCurrent.push(normalized);
+    await this.write(withoutCurrent);
+  }
+
+  async remove(id: string): Promise<void> {
+    const sessions = (await this.list()).filter((session) => session.id !== id);
+    if (sessions.length === 0) {
+      await this.storage.removeItem(this.key);
+      return;
+    }
+    await this.write(sessions);
+  }
+
+  private async read(): Promise<ThruSigningSessionDescriptor[]> {
+    const raw = await this.storage.getItem(this.key);
+    if (!raw) return [];
+
+    try {
+      const parsed = JSON.parse(raw) as Partial<SigningSessionStorePayload>;
+      if (parsed.version !== STORAGE_VERSION || !Array.isArray(parsed.sessions)) {
+        await this.storage.removeItem(this.key);
+        return [];
+      }
+      return parsed.sessions.map(normalizeDescriptor);
+    } catch {
+      await this.storage.removeItem(this.key);
+      return [];
+    }
+  }
+
+  private async write(sessions: ThruSigningSessionDescriptor[]): Promise<void> {
+    const payload: SigningSessionStorePayload = {
+      version: STORAGE_VERSION,
+      sessions: sessions.map(normalizeDescriptor),
+    };
+    await this.storage.setItem(this.key, JSON.stringify(payload));
+  }
+}