zksync-sso 0.5.0-beta.3 → 1.0.0-beta.2

package/src/client/session/monitor.ts

@@ -0,0 +1,292 @@
+/**
+ * Session monitoring utilities for tracking session state changes
+ *
+ * These utilities help monitor session expiration and state changes,
+ * similar to the legacy SDK's onSessionStateChange callback functionality.
+ */
+
+import type { Chain, Client, PublicActions, Transport } from "viem";
+
+import type {
+  GetSessionStateParams,
+  SessionEventType,
+  SessionState,
+  SessionStateEventCallback,
+} from "../actions/sessions.js";
+import { getSessionState, SessionStatus } from "../actions/sessions.js";
+import type { SessionSpec } from "../session/types.js";
+
+/**
+ * Parameters for starting session monitoring
+ */
+export type StartSessionMonitoringParams = {
+  /**
+   * Callback to invoke when session state changes
+   */
+  onSessionStateChange: SessionStateEventCallback;
+
+  /**
+   * Interval in milliseconds to check session state (default: 60000 = 1 minute)
+   */
+  checkIntervalMs?: number;
+
+  /**
+   * Threshold in seconds for warning about session expiration (default: 3600 = 1 hour)
+   */
+  expirationWarningThresholdSeconds?: number;
+
+  /**
+   * Threshold percentage for warning about fee limit (default: 80 = 80%)
+   */
+  feeLimitWarningThresholdPercent?: number;
+};
+
+/**
+ * Session monitor handle for stopping monitoring
+ */
+export type SessionMonitor = {
+  /**
+   * Stop monitoring the session
+   */
+  stop: () => void;
+
+  /**
+   * Force an immediate check of session state
+   */
+  checkNow: () => Promise<void>;
+};
+
+/**
+ * Start monitoring a session for state changes
+ *
+ * This function periodically checks the session state and invokes the callback
+ * when important events occur (expiration, revocation, fee limit warnings, etc.).
+ *
+ * @param client - A viem public client with chain and transport
+ * @param sessionParams - Parameters for querying session state
+ * @param monitoringParams - Monitoring configuration
+ * @returns A SessionMonitor handle to stop monitoring
+ *
+ * @example
+ * ```typescript
+ * const monitor = startSessionMonitoring(
+ *   publicClient,
+ *   {
+ *     account: smartAccountAddress,
+ *     sessionSpec: mySessionSpec,
+ *     contracts: {
+ *       sessionValidator: sessionValidatorAddress,
+ *     },
+ *   },
+ *   {
+ *     onSessionStateChange: (event) => {
+ *       if (event.type === SessionEventType.Expired) {
+ *         console.error("Session expired!");
+ *       } else if (event.type === SessionEventType.Warning) {
+ *         console.warn(event.message);
+ *       }
+ *     },
+ *     checkIntervalMs: 30000, // Check every 30 seconds
+ *   }
+ * );
+ *
+ * // Later, stop monitoring
+ * monitor.stop();
+ * ```
+ */
+export function startSessionMonitoring<
+  TTransport extends Transport = Transport,
+  TChain extends Chain | undefined = Chain | undefined,
+>(
+  client: Client<TTransport, TChain> & PublicActions,
+  sessionParams: GetSessionStateParams,
+  monitoringParams: StartSessionMonitoringParams,
+): SessionMonitor {
+  const {
+    onSessionStateChange,
+    checkIntervalMs = 60000, // Default: 1 minute
+    expirationWarningThresholdSeconds = 3600, // Default: 1 hour
+    feeLimitWarningThresholdPercent = 80, // Default: 80%
+  } = monitoringParams;
+
+  let intervalHandle: ReturnType<typeof setInterval> | null = null;
+  let expirationTimeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  let hasExpired = false;
+  let hasRevoked = false;
+  let lastFeeWarning = false;
+
+  const checkSessionState = async () => {
+    try {
+      const { sessionState } = await getSessionState(client, sessionParams);
+      const now = BigInt(Math.floor(Date.now() / 1000));
+
+      // Check if session has been revoked/closed
+      if (sessionState.status === SessionStatus.Closed && !hasRevoked) {
+        hasRevoked = true;
+        onSessionStateChange({
+          type: "session_revoked" as SessionEventType,
+          message: "Session has been revoked",
+          sessionState,
+        });
+        return; // Don't continue monitoring after revocation
+      }
+
+      // Check if session is inactive
+      if (sessionState.status === SessionStatus.NotInitialized) {
+        onSessionStateChange({
+          type: "session_inactive" as SessionEventType,
+          message: "Session is not initialized",
+          sessionState,
+        });
+        return; // Don't continue monitoring if not initialized
+      }
+
+      // Check if session has expired
+      if (sessionParams.sessionSpec.expiresAt <= now && !hasExpired) {
+        hasExpired = true;
+        onSessionStateChange({
+          type: "session_expired" as SessionEventType,
+          message: "Session has expired",
+          sessionState,
+        });
+        return; // Don't continue monitoring after expiration
+      }
+
+      // Check for expiration warning
+      const timeToExpiry = sessionParams.sessionSpec.expiresAt - now;
+      if (
+        timeToExpiry > 0n
+        && timeToExpiry <= BigInt(expirationWarningThresholdSeconds)
+        && !hasExpired
+      ) {
+        const minutes = Number(timeToExpiry) / 60;
+        onSessionStateChange({
+          type: "session_warning" as SessionEventType,
+          message: `Session will expire in ${minutes.toFixed(1)} minutes`,
+          sessionState,
+        });
+      }
+
+      // Check for fee limit warning
+      if (
+        sessionState.status === SessionStatus.Active
+        && sessionParams.sessionSpec.feeLimit.limit > 0n
+      ) {
+        const feeUsedPercent = Number(
+          (sessionParams.sessionSpec.feeLimit.limit
+            - sessionState.feesRemaining)
+            * 100n
+            / sessionParams.sessionSpec.feeLimit.limit,
+        );
+
+        if (
+          feeUsedPercent >= feeLimitWarningThresholdPercent
+          && !lastFeeWarning
+        ) {
+          lastFeeWarning = true;
+          onSessionStateChange({
+            type: "session_warning" as SessionEventType,
+            message: `Session fee limit is ${feeUsedPercent.toFixed(0)}% exhausted (${sessionState.feesRemaining} remaining)`,
+            sessionState,
+          });
+        } else if (feeUsedPercent < feeLimitWarningThresholdPercent) {
+          // Reset warning flag if usage drops below threshold
+          lastFeeWarning = false;
+        }
+      }
+    } catch (error) {
+      console.error("Error checking session state:", error);
+    }
+  };
+
+  // Set up expiration timeout
+  const now = BigInt(Math.floor(Date.now() / 1000));
+  const timeToExpiry = sessionParams.sessionSpec.expiresAt - now;
+  if (timeToExpiry > 0n) {
+    const timeoutMs = Number(timeToExpiry) * 1000;
+    expirationTimeoutHandle = setTimeout(() => {
+      if (!hasExpired) {
+        hasExpired = true;
+        void getSessionState(client, sessionParams).then(({ sessionState }) => {
+          onSessionStateChange({
+            type: "session_expired" as SessionEventType,
+            message: "Session has expired",
+            sessionState,
+          });
+        });
+      }
+    }, timeoutMs);
+  }
+
+  // Start periodic monitoring
+  intervalHandle = setInterval(() => {
+    void checkSessionState();
+  }, checkIntervalMs);
+
+  // Do an immediate check
+  void checkSessionState();
+
+  return {
+    stop: () => {
+      if (intervalHandle) {
+        clearInterval(intervalHandle);
+        intervalHandle = null;
+      }
+      if (expirationTimeoutHandle) {
+        clearTimeout(expirationTimeoutHandle);
+        expirationTimeoutHandle = null;
+      }
+    },
+    checkNow: checkSessionState,
+  };
+}
+
+/**
+ * Check if a session should show a warning based on its state
+ */
+export function shouldWarnAboutSession(
+  sessionSpec: SessionSpec,
+  sessionState: SessionState,
+  options: {
+    expirationWarningThresholdSeconds?: number;
+    feeLimitWarningThresholdPercent?: number;
+  } = {},
+): { shouldWarn: boolean; reason?: string } {
+  const {
+    expirationWarningThresholdSeconds = 3600,
+    feeLimitWarningThresholdPercent = 80,
+  } = options;
+
+  const now = BigInt(Math.floor(Date.now() / 1000));
+
+  // Check expiration
+  const timeToExpiry = sessionSpec.expiresAt - now;
+  if (timeToExpiry > 0n && timeToExpiry <= BigInt(expirationWarningThresholdSeconds)) {
+    const minutes = Number(timeToExpiry) / 60;
+    return {
+      shouldWarn: true,
+      reason: `Session will expire in ${minutes.toFixed(1)} minutes`,
+    };
+  }
+
+  // Check fee limit
+  if (
+    sessionState.status === SessionStatus.Active
+    && sessionSpec.feeLimit.limit > 0n
+  ) {
+    const feeUsedPercent = Number(
+      (sessionSpec.feeLimit.limit - sessionState.feesRemaining)
+      * 100n
+      / sessionSpec.feeLimit.limit,
+    );
+
+    if (feeUsedPercent >= feeLimitWarningThresholdPercent) {
+      return {
+        shouldWarn: true,
+        reason: `Fee limit is ${feeUsedPercent.toFixed(0)}% exhausted`,
+      };
+    }
+  }
+
+  return { shouldWarn: false };
+}

package/src/client/session/types.ts

@@ -0,0 +1,205 @@
+import type { Address, Hex } from "viem";
+
+/**
+ * Limit types for usage tracking
+ * Uses numeric values to match contract enum
+ */
+export enum LimitType {
+  Unlimited = 0,
+  Lifetime = 1,
+  Allowance = 2,
+}
+
+/**
+ * Period constants for time-based allowances (in seconds)
+ */
+export const LIMIT_PERIODS = {
+  Hourly: 3600n,
+  Daily: 86400n,
+  Weekly: 604800n,
+  Monthly: 2592000n, // 30 days
+  Yearly: 31536000n, // 365 days
+} as const;
+
+/**
+ * Usage limit structure
+ * @member limitType - Type of limit (Unlimited, Lifetime, or time-based allowance)
+ * @member limit - Maximum value allowed (as bigint for U256 compatibility)
+ * @member period - Period in seconds for allowance limits (0 for Unlimited/Lifetime)
+ */
+export type UsageLimit = {
+  limitType: LimitType;
+  limit: bigint;
+  period: bigint;
+};
+
+/**
+ * Constraint condition for parameter validation
+ * Uses string values to match Rust serialization format
+ */
+export enum ConstraintCondition {
+  Unconstrained = "Unconstrained",
+  Equal = "Equal",
+  Greater = "Greater",
+  Less = "Less",
+  GreaterEqual = "GreaterEqual",
+  LessEqual = "LessEqual",
+  NotEqual = "NotEqual",
+}
+
+/**
+ * Constraint for validating transaction parameters
+ * @member condition - Comparison condition
+ * @member index - Parameter index in calldata
+ * @member refValue - Reference value for comparison (as hex string)
+ * @member limit - Usage limit for this constraint
+ */
+export type Constraint = {
+  condition: ConstraintCondition;
+  index: bigint;
+  refValue: Hex;
+  limit: UsageLimit;
+};
+
+/**
+ * Policy for contract function calls
+ * @member target - Contract address
+ * @member selector - Function selector (4 bytes)
+ * @member maxValuePerUse - Maximum value per transaction
+ * @member valueLimit - Total value limit with tracking period
+ * @member constraints - Parameter validation constraints
+ */
+export type CallPolicy = {
+  target: Address;
+  selector: Hex;
+  maxValuePerUse: bigint;
+  valueLimit: UsageLimit;
+  constraints: Constraint[];
+};
+
+/**
+ * Policy for simple value transfers (no calldata)
+ * @member target - Recipient address
+ * @member maxValuePerUse - Maximum value per transaction
+ * @member valueLimit - Total value limit with tracking period
+ */
+export type TransferPolicy = {
+  target: Address;
+  maxValuePerUse: bigint;
+  valueLimit: UsageLimit;
+};
+
+/**
+ * Complete session specification
+ * @member signer - Session key public address (can sign transactions within policy limits)
+ * @member expiresAt - Unix timestamp when session expires
+ * @member feeLimit - Maximum cumulative fees the session can pay
+ * @member callPolicies - Policies for contract calls (requires calldata)
+ * @member transferPolicies - Policies for value transfers (no calldata)
+ */
+export type SessionSpec = {
+  signer: Address;
+  expiresAt: bigint;
+  feeLimit: UsageLimit;
+  callPolicies: CallPolicy[];
+  transferPolicies: TransferPolicy[];
+};
+
+/**
+ * Helper to create unlimited limit
+ */
+export const LimitUnlimited: UsageLimit = {
+  limitType: LimitType.Unlimited,
+  limit: 0n,
+  period: 0n,
+};
+
+/**
+ * Helper to create zero (disabled) limit
+ */
+export const LimitZero: UsageLimit = {
+  limitType: LimitType.Lifetime,
+  limit: 0n,
+  period: 0n,
+};
+
+/**
+ * Helper to create lifetime limit (no period tracking)
+ */
+export const createLifetimeLimit = (limit: bigint): UsageLimit => ({
+  limitType: LimitType.Lifetime,
+  limit,
+  period: 0n,
+});
+
+/**
+ * Helper to create time-based allowance limit
+ * @param period - Period in seconds for the allowance window
+ * @param limit - Maximum value allowed within the period
+ */
+export const createAllowanceLimit = (
+  period: bigint,
+  limit: bigint,
+): UsageLimit => ({
+  limitType: LimitType.Allowance,
+  limit,
+  period,
+});
+
+// ============================================================================
+// Enum Conversion Helpers for Contract ABIs
+// ============================================================================
+
+/**
+ * Convert LimitType enum to numeric value for contract calls
+ */
+export function limitTypeToNumber(limitType: LimitType): number {
+  switch (limitType) {
+    case LimitType.Unlimited:
+      return 0;
+    case LimitType.Lifetime:
+      return 1;
+    case LimitType.Allowance:
+      return 2;
+    default:
+      throw new Error(`Unknown LimitType: ${limitType}`);
+  }
+}
+
+/**
+ * Convert ConstraintCondition enum to numeric value for contract calls
+ */
+export function conditionToNumber(condition: ConstraintCondition): number {
+  switch (condition) {
+    case ConstraintCondition.Unconstrained:
+      return 0;
+    case ConstraintCondition.Equal:
+      return 1;
+    case ConstraintCondition.Greater:
+      return 2;
+    case ConstraintCondition.Less:
+      return 3;
+    case ConstraintCondition.GreaterEqual:
+      return 4;
+    case ConstraintCondition.LessEqual:
+      return 5;
+    case ConstraintCondition.NotEqual:
+      return 6;
+    default:
+      throw new Error(`Unknown ConstraintCondition: ${condition}`);
+  }
+}
+
+// ============================================================================
+// Backward Compatibility Type Aliases (for legacy SDK migration)
+// ============================================================================
+
+/**
+ * @deprecated Use SessionSpec instead. Provided for backward compatibility with legacy SDK.
+ */
+export type SessionConfig = SessionSpec;
+
+/**
+ * @deprecated Use UsageLimit instead. Provided for backward compatibility with legacy SDK.
+ */
+export type Limit = UsageLimit;

package/src/client/session/utils.ts

@@ -0,0 +1,160 @@
+import { type Address, encodeAbiParameters, type Hex, keccak256 } from "viem";
+
+import { SessionKeyValidatorAbi } from "../../abi/SessionKeyValidator.js";
+import { LimitType, type SessionSpec, type UsageLimit } from "./types.js";
+
+/**
+ * Utility type that converts all bigint values to strings recursively
+ */
+export type ConvertBigIntToString<T> = T extends bigint
+  ? string
+  : T extends Array<infer U>
+    ? Array<ConvertBigIntToString<U>>
+    : T extends object
+      ? { [K in keyof T]: ConvertBigIntToString<T[K]> }
+      : T;
+
+/**
+ * SessionSpec with all bigint values converted to strings for JSON serialization
+ */
+export type SessionSpecJSON = ConvertBigIntToString<SessionSpec>;
+
+/**
+ * Converts a SessionSpec to JSON string format expected by WASM bindings.
+ * All bigint values are converted to strings for safe serialization.
+ */
+export function sessionSpecToJSON(spec: SessionSpec): string {
+  const usageLimitToJSON = (limit: UsageLimit) => {
+    let limitType = "Unlimited";
+    if (limit.limitType === LimitType.Lifetime) limitType = "Lifetime";
+    else if (limit.limitType === LimitType.Allowance) limitType = "Allowance";
+
+    return {
+      limitType,
+      limit: limit.limit.toString(),
+      period: limit.period.toString(),
+    };
+  };
+
+  return JSON.stringify({
+    signer: spec.signer,
+    expiresAt: spec.expiresAt.toString(),
+    feeLimit: usageLimitToJSON(spec.feeLimit),
+    callPolicies: spec.callPolicies.map((policy) => ({
+      target: policy.target,
+      selector: policy.selector,
+      maxValuePerUse: policy.maxValuePerUse.toString(),
+      valueLimit: usageLimitToJSON(policy.valueLimit),
+      constraints: policy.constraints.map((constraint) => ({
+        condition: constraint.condition,
+        index: constraint.index.toString(),
+        refValue: constraint.refValue,
+        limit: usageLimitToJSON(constraint.limit),
+      })),
+    })),
+    transferPolicies: spec.transferPolicies.map((policy) => ({
+      target: policy.target,
+      maxValuePerUse: policy.maxValuePerUse.toString(),
+      valueLimit: usageLimitToJSON(policy.valueLimit),
+    })),
+  });
+}
+
+/**
+ * Extract function selector from calldata (first 4 bytes)
+ */
+export function extractSelector(callData: Hex): Hex | undefined {
+  if (!callData || callData.length < 10) return undefined; // 0x + 8 hex chars = 10
+  return callData.slice(0, 10) as Hex;
+}
+
+/**
+ * Find matching policy for a transaction
+ */
+export function findMatchingPolicy(
+  spec: SessionSpec,
+  target: Address,
+  selector?: Hex,
+): { type: "call" | "transfer"; policy: SessionSpec["callPolicies"][0] | SessionSpec["transferPolicies"][0] } | null {
+  // If selector provided, look for call policy
+  if (selector) {
+    const callPolicy = spec.callPolicies.find(
+      (p) => p.target.toLowerCase() === target.toLowerCase() && p.selector.toLowerCase() === selector.toLowerCase(),
+    );
+    if (callPolicy) return { type: "call", policy: callPolicy };
+  }
+
+  // Otherwise look for transfer policy
+  const transferPolicy = spec.transferPolicies.find(
+    (p) => p.target.toLowerCase() === target.toLowerCase(),
+  );
+  if (transferPolicy) return { type: "transfer", policy: transferPolicy };
+
+  return null;
+}
+
+/**
+ * Validates that a transaction fits within session policies
+ * Returns error message if invalid, null if valid
+ */
+export function validateTransactionAgainstSession(
+  spec: SessionSpec,
+  target: Address,
+  value: bigint,
+  callData?: Hex,
+): string | null {
+  const selector = callData ? extractSelector(callData) : undefined;
+  const match = findMatchingPolicy(spec, target, selector);
+
+  if (!match) {
+    return selector
+      ? `No call policy found for target ${target} with selector ${selector}`
+      : `No transfer policy found for target ${target}`;
+  }
+
+  // Check max value per use
+  if (value > match.policy.maxValuePerUse) {
+    return `Value ${value} exceeds maxValuePerUse ${match.policy.maxValuePerUse}`;
+  }
+
+  return null; // Valid
+}
+
+/**
+ * Checks if a session has expired
+ */
+export function isSessionExpired(
+  spec: SessionSpec,
+  currentTimestamp?: bigint,
+): boolean {
+  const now = currentTimestamp ?? BigInt(Math.floor(Date.now() / 1000));
+  return now > spec.expiresAt;
+}
+
+/**
+ * Gets human-readable expiry time
+ */
+export function getSessionExpiryDate(spec: SessionSpec): Date {
+  return new Date(Number(spec.expiresAt) * 1000);
+}
+
+/**
+ * Computes the hash of a session specification.
+ * This hash is signed by the session key to prove ownership.
+ */
+export function getSessionHash(spec: SessionSpec): Hex {
+  const createSessionFunction = SessionKeyValidatorAbi.find(
+    (x) => x.type === "function" && x.name === "createSession",
+  );
+  if (!createSessionFunction) throw new Error("createSession function not found in SessionKeyValidator ABI");
+
+  const sessionSpecParam = createSessionFunction.inputs.find((x) => x.name === "sessionSpec");
+  if (!sessionSpecParam) throw new Error("sessionSpec parameter not found in createSession function inputs");
+
+  const encoded = encodeAbiParameters(
+    [sessionSpecParam],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [spec as any],
+  );
+  return keccak256(encoded);
+}