@lombard.finance/sdk-common 4.0.0 → 4.1.0-canary.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lombard.finance/sdk-common",
-  "version": "4.0.0",
+  "version": "4.1.0-canary.9",
   "description": "Shared utilities and types for the Lombard SDK packages",
   "exports": {
     ".": {

package/src/modules.ts

@@ -72,8 +72,10 @@ export interface SdkModule<TId extends string = string, TService = unknown> {
  * }
  * ```
  */
-export interface ChainModule<TChain extends string = string, TService = unknown>
-  extends SdkModule<TChain, TService> {
+export interface ChainModule<
+  TChain extends string = string,
+  TService = unknown,
+> extends SdkModule<TChain, TService> {
   /** Chain type this module provides services for */
   chain: TChain;
 }
@@ -94,8 +96,10 @@ export type ModuleId<TModule> =
 /**
  * Extract service type from a module by ID
  */
-export type ServiceOf<TModule extends SdkModule<string, unknown>, TId extends string> =
-  TModule extends SdkModule<TId, infer TService> ? TService : never;
+export type ServiceOf<
+  TModule extends SdkModule<string, unknown>,
+  TId extends string,
+> = TModule extends SdkModule<TId, infer TService> ? TService : never;
 
 /**
  * @deprecated Use ServiceOf instead

package/src/services/auth.ts

@@ -0,0 +1,84 @@
+/**
+ * Wallet Auth Service
+ *
+ * Contract for the wallet-based authentication flow used by the Lombard
+ * backend (v2):
+ *
+ *   1. `requestChallenge` — server returns a payload the wallet must sign.
+ *   2. `verifySignature`  — server validates the signature and issues a JWT.
+ *   3. `revokeToken`      — invalidates a JWT server-side (e.g. on disconnect).
+ *
+ * Signing the challenge with the user's wallet is intentionally NOT part of
+ * this contract — signing primitives are chain-specific and live in the
+ * corresponding chain SDK packages.
+ */
+
+/**
+ * Supported chain identifiers accepted by the auth API.
+ *
+ * Free-form string to stay open to chains added on the backend before the
+ * SDK is updated. Common values: `'ethereum'`, `'solana'`, `'sui'`,
+ * `'starknet'`, `'cosmos'`.
+ */
+export type WalletAuthChain = string;
+
+export interface WalletChallengeRequest {
+  /** Wallet address performing the auth flow. */
+  address: string;
+  /** Chain the address belongs to. */
+  chain: WalletAuthChain;
+}
+
+export interface WalletChallengeResponse {
+  /** Random nonce embedded in the payload. */
+  nonce: string;
+  /** Chain-specific payload the user must sign with their wallet. */
+  payload: string;
+  /** ISO-8601 timestamp when this challenge expires. */
+  expiresAt: string;
+}
+
+export interface WalletVerifyRequest {
+  address: string;
+  /** The payload returned by `requestChallenge`. */
+  payload: string;
+  /** Signature produced by the wallet over `payload`. */
+  signature: string;
+  chain: WalletAuthChain;
+  /**
+   * Required for chains where the public key cannot be recovered from the
+   * signature (Starknet, Cosmos). Ignored elsewhere.
+   */
+  publicKey?: string;
+}
+
+export interface WalletVerifyResponse {
+  /** JWT bound to the verified wallet address. */
+  jwt: string;
+  /** ISO-8601 timestamp when the JWT expires. */
+  expiresAt: string;
+}
+
+export interface RevokeWalletTokenRequest {
+  /** JWT to invalidate server-side. */
+  jwt: string;
+}
+
+/**
+ * Wallet auth service contract. Implementations live in `@lombard.finance/sdk`.
+ */
+export interface WalletAuthService {
+  /** Request a challenge payload for the given wallet. */
+  requestChallenge(
+    params: WalletChallengeRequest,
+  ): Promise<WalletChallengeResponse>;
+
+  /** Submit a signed challenge and receive a JWT. */
+  verifySignature(params: WalletVerifyRequest): Promise<WalletVerifyResponse>;
+
+  /**
+   * Invalidate a JWT server-side. Best-effort: implementations may swallow
+   * network errors so callers can always clear local state.
+   */
+  revokeToken(params: RevokeWalletTokenRequest): Promise<void>;
+}

package/src/services/index.ts

@@ -13,6 +13,7 @@
 
 // Core services (provided by sdk)
 export * from './api';
+export * from './auth';
 export * from './btc';
 export * from './evm';