feat: add session key authentication support (#103)

* feat: add session key authentication support

Adds session key mode as an alternative to private key authentication,
allowing delegated authorisation without wallet prompts. Session keys
are verified to have 30+ minutes remaining validity at initialization.
The owner wallet's private key isn't required for CreateDataSet or
AddPieces operations in this mode, so we only require the owner address.

- add AddressOnlySigner for read-only owner wallet access
- add WALLET_ADDRESS and SESSION_KEY env var support to add/import commands
- fix FIL balance check to use owner wallet instead of session key

NOTE: This will fail if the owner wallet doesn't meet the payments setup
requirements, there's no ability to auto-fix funding or authorisation setup
without being able to sign with that wallet.

* chore: clean up typing

Author: rvagg

src/add/add.ts

@@ -94,14 +94,24 @@ export async function runAdd(options: AddOptions): Promise<AddResult> {
     // Initialize Synapse SDK (without storage context)
     spinner.start('Initializing Synapse SDK...')
 
-    if (!options.privateKey) {
-      spinner.stop(`${pc.red('✗')} Private key required via --private-key or PRIVATE_KEY env`)
-      cancel('Add cancelled')
+    // Check for session key auth (env vars only for now)
+    const walletAddress = process.env.WALLET_ADDRESS
+    const sessionKey = process.env.SESSION_KEY
+
+    // Validate authentication (either standard or session key mode)
+    const hasStandardAuth = options.privateKey != null
+    const hasSessionKeyAuth = walletAddress != null && sessionKey != null
+
+    if (!hasStandardAuth && !hasSessionKeyAuth) {
+      spinner.stop(`${pc.red('✗')} Authentication required`)
+      cancel('Provide either PRIVATE_KEY or both WALLET_ADDRESS + SESSION_KEY env vars')
       process.exit(1)
     }
 
     const config = {
       privateKey: options.privateKey,
+      walletAddress,
+      sessionKey,
       rpcUrl: options.rpcUrl || RPC_URLS.calibration.websocket,
       // Other config fields not needed for add
       port: 0,

src/core/payments/index.ts

@@ -131,7 +131,7 @@ export async function checkFILBalance(synapse: Synapse): Promise<{
 
   try {
     const provider = synapse.getProvider()
-    const signer = synapse.getSigner()
+    const signer = synapse.getClient() // owner wallet
     const address = await signer.getAddress()
 
     // Get native token balance

src/core/synapse/address-only-signer.ts

@@ -0,0 +1,41 @@
+/**
+ * Address-only signer for session key authentication
+ *
+ * This signer provides an address but throws on any signing operations.
+ * Used as the "owner" signer when authenticating with session keys,
+ * where the actual signing is done by the session key wallet.
+ */
+
+import { AbstractSigner, type Provider, type TransactionRequest } from 'ethers'
+
+const cannotSign = (thing: string) =>
+  `Cannot sign ${thing} - this is an address-only signer for session key authentication. Signing operations should be performed by the session key.`
+
+export class AddressOnlySigner extends AbstractSigner {
+  readonly address: string
+
+  constructor(address: string, provider?: Provider) {
+    super(provider)
+    this.address = address
+  }
+
+  async getAddress(): Promise<string> {
+    return this.address
+  }
+
+  connect(provider: Provider): AddressOnlySigner {
+    return new AddressOnlySigner(this.address, provider)
+  }
+
+  async signTransaction(_tx: TransactionRequest): Promise<string> {
+    throw new Error(cannotSign('transaction'))
+  }
+
+  async signMessage(_message: string | Uint8Array): Promise<string> {
+    throw new Error(cannotSign('message'))
+  }
+
+  async signTypedData(_domain: any, _types: Record<string, any[]>, _value: Record<string, any>): Promise<string> {
+    throw new Error(cannotSign('typed data'))
+  }
+}

src/core/synapse/index.ts

@@ -1,4 +1,6 @@
 import {
+  ADD_PIECES_TYPEHASH,
+  CREATE_DATA_SET_TYPEHASH,
   METADATA_KEYS,
   type ProviderInfo,
   RPC_URLS,
@@ -8,7 +10,9 @@ import {
   Synapse,
   type SynapseOptions,
 } from '@filoz/synapse-sdk'
+import { type Provider as EthersProvider, JsonRpcProvider, Wallet, WebSocketProvider } from 'ethers'
 import type { Logger } from 'pino'
+import { AddressOnlySigner } from './address-only-signer.js'
 
 const WEBSOCKET_REGEX = /^ws(s)?:\/\//i
 
@@ -51,13 +55,22 @@ export interface Config {
 
 /**
  * Configuration for Synapse initialization
- * Extends the main Config but makes privateKey required and rpcUrl optional
+ *
+ * Supports two authentication modes:
+ * 1. Standard: privateKey only
+ * 2. Session Key: walletAddress + sessionKey
  */
-export interface SynapseSetupConfig extends Partial<Omit<Config, 'privateKey' | 'rpcUrl'>> {
-  /** Private key used for signing transactions. */
-  privateKey: string
+export interface SynapseSetupConfig {
+  /** Private key for standard authentication (mutually exclusive with session key mode) */
+  privateKey?: string | undefined
+  /** Wallet address for session key mode (requires sessionKey) */
+  walletAddress?: string | undefined
+  /** Session key private key (requires walletAddress) */
+  sessionKey?: string | undefined
   /** RPC endpoint for the target Filecoin network. Defaults to calibration. */
   rpcUrl?: string | undefined
+  /** Optional override for WarmStorage contract address */
+  warmStorageAddress?: string | undefined
 }
 
 /**
@@ -136,89 +149,122 @@ export function resetSynapseService(): void {
   activeProvider = null
 }
 
+/**
+ * Validate authentication configuration
+ */
+function validateAuthConfig(config: SynapseSetupConfig): 'standard' | 'session-key' {
+  const hasStandardAuth = config.privateKey != null
+  const hasSessionKeyAuth = config.walletAddress != null && config.sessionKey != null
+
+  if (!hasStandardAuth && !hasSessionKeyAuth) {
+    throw new Error('Authentication required: provide either a privateKey or walletAddress + sessionKey')
+  }
+
+  if (hasStandardAuth && hasSessionKeyAuth) {
+    throw new Error('Conflicting authentication: provide either a privateKey or walletAddress + sessionKey, not both')
+  }
+
+  return hasStandardAuth ? 'standard' : 'session-key'
+}
+
+/**
+ * Create ethers provider for the given RPC URL
+ */
+function createProvider(rpcURL: string): EthersProvider {
+  if (WEBSOCKET_REGEX.test(rpcURL)) {
+    return new WebSocketProvider(rpcURL)
+  }
+  return new JsonRpcProvider(rpcURL)
+}
+
+/**
+ * Setup and verify session key, throws if expired
+ */
+async function setupSessionKey(synapse: Synapse, sessionWallet: Wallet, logger: Logger): Promise<void> {
+  const sessionKey = synapse.createSessionKey(sessionWallet)
+
+  // Verify permissions - fail fast if expired or expiring soon
+  const expiries = await sessionKey.fetchExpiries([CREATE_DATA_SET_TYPEHASH, ADD_PIECES_TYPEHASH])
+  const now = Math.floor(Date.now() / 1000)
+  const bufferTime = 30 * 60 // 30 minutes in seconds
+  const minValidTime = now + bufferTime
+  const createExpiry = Number(expiries[CREATE_DATA_SET_TYPEHASH])
+  const addExpiry = Number(expiries[ADD_PIECES_TYPEHASH])
+
+  if (createExpiry <= minValidTime || addExpiry <= minValidTime) {
+    throw new Error(
+      `Session key expired or expiring soon (requires 30+ minutes validity). CreateDataSet: ${new Date(createExpiry * 1000).toISOString()}, AddPieces: ${new Date(addExpiry * 1000).toISOString()}`
+    )
+  }
+
+  logger.info({ event: 'synapse.session_key.verified', createExpiry, addExpiry }, 'Session key verified')
+
+  synapse.setSession(sessionKey)
+  logger.info({ event: 'synapse.session_key.activated' }, 'Session key activated')
+}
+
 /**
  * Initialize the Synapse SDK without creating storage context
  *
- * This function initializes the Synapse SDK connection without creating
- * a storage context. This method is primarily a wrapper for handling our
- * custom configuration needs and adding detailed logging.
+ * Supports two authentication modes:
+ * - Standard: privateKey only
+ * - Session Key: walletAddress + sessionKey
  *
- * @param config - Application configuration with privateKey and RPC URL
+ * @param config - Application configuration with authentication credentials
  * @param logger - Logger instance for detailed operation tracking
  * @returns Initialized Synapse instance
  */
 export async function initializeSynapse(config: SynapseSetupConfig, logger: Logger): Promise<Synapse> {
   try {
-    // Log the configuration status
-    logger.info(
-      {
-        hasPrivateKey: config.privateKey != null,
-        rpcUrl: config.rpcUrl,
-      },
-      'Initializing Synapse'
-    )
+    const authMode = validateAuthConfig(config)
+    const rpcURL = config.rpcUrl ?? RPC_URLS.calibration.websocket
 
-    // IMPORTANT: Private key is required for transaction signing
-    // In production, this should come from secure environment variables, or a wallet integration
-    const privateKey = config.privateKey
-    if (privateKey == null) {
-      const error = new Error('PRIVATE_KEY environment variable is required for Synapse integration')
-      logger.error(
-        {
-          event: 'synapse.init.failed',
-          error: error.message,
-        },
-        'Synapse initialization failed: missing PRIVATE_KEY'
-      )
-      throw error
-    }
-
-    logger.info({ event: 'synapse.init' }, 'Initializing Synapse SDK')
-
-    // Configure Synapse with network settings
-    // Network options: 314 (mainnet) or 314159 (calibration testnet)
-    const synapseOptions: SynapseOptions = {
-      privateKey,
-      rpcURL: config.rpcUrl ?? RPC_URLS.calibration.websocket, // Default to calibration testnet
-    }
+    logger.info({ event: 'synapse.init', authMode, rpcUrl: rpcURL }, 'Initializing Synapse SDK')
 
-    // Optional: Override the default Warm Storage contract address
-    // Useful for testing with custom deployments
-    if (config.warmStorageAddress != null) {
+    const synapseOptions: SynapseOptions = { rpcURL }
+    if (config.warmStorageAddress) {
       synapseOptions.warmStorageAddress = config.warmStorageAddress
     }
 
-    const synapse = await Synapse.create(synapseOptions)
-
-    // Store reference to the provider for cleanup if it's a WebSocket provider
-    if (synapseOptions.rpcURL && WEBSOCKET_REGEX.test(synapseOptions.rpcURL)) {
+    let synapse: Synapse
+
+    if (authMode === 'session-key') {
+      // Session key mode - validation guarantees these are defined
+      const walletAddress = config.walletAddress
+      const sessionKey = config.sessionKey
+      if (!walletAddress || !sessionKey) {
+        throw new Error('Internal error: session key config validated but values missing')
+      }
+
+      // Create provider and signers for session key mode
+      const provider = createProvider(rpcURL)
+      activeProvider = provider
+
+      const ownerSigner = new AddressOnlySigner(walletAddress, provider)
+      const sessionWallet = new Wallet(sessionKey, provider)
+
+      // Initialize with owner signer, then activate session key
+      synapse = await Synapse.create({ ...synapseOptions, signer: ownerSigner })
+      await setupSessionKey(synapse, sessionWallet, logger)
+    } else {
+      // Standard mode - validation guarantees privateKey is defined
+      const privateKey = config.privateKey
+      if (!privateKey) {
+        throw new Error('Internal error: standard auth validated but privateKey missing')
+      }
+
+      synapse = await Synapse.create({ ...synapseOptions, privateKey })
       activeProvider = synapse.getProvider()
     }
 
-    // Get network info for logging
     const network = synapse.getNetwork()
-    logger.info(
-      {
-        event: 'synapse.init',
-        network,
-        rpcUrl: synapseOptions.rpcURL,
-      },
-      'Synapse SDK initialized'
-    )
+    logger.info({ event: 'synapse.init.success', network }, 'Synapse SDK initialized')
 
-    // Store instance for cleanup
     synapseInstance = synapse
-
     return synapse
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error)
-    logger.error(
-      {
-        event: 'synapse.init.failed',
-        error: errorMessage,
-      },
-      `Failed to initialize Synapse SDK: ${errorMessage}`
-    )
+    logger.error({ event: 'synapse.init.failed', error: errorMessage }, 'Failed to initialize Synapse SDK')
     throw error
   }
 }

src/core/unixfs/browser-car-builder.ts

@@ -6,7 +6,7 @@
  */
 
 import { unixfs } from '@helia/unixfs'
-import { CarWriter } from '@ipld/car'
+import { CarReader, CarWriter } from '@ipld/car'
 import { CID } from 'multiformats/cid'
 import { CARWritingBlockstore } from '../car/browser-car-blockstore.js'
 
@@ -251,9 +251,6 @@ async function updateRootCidInCar(carBytes: Uint8Array, rootCid: CID): Promise<U
   // We need to replace the placeholder CID with the actual root CID
   // The easiest way is to re-read the CAR and write a new one with the correct root
 
-  // Import CarReader to read the existing CAR
-  const { CarReader } = await import('@ipld/car')
-
   const reader = await CarReader.fromBytes(carBytes)
 
   // Create new CAR writer with correct root

src/import/import.ts

@@ -165,14 +165,24 @@ export async function runCarImport(options: ImportOptions): Promise<ImportResult
     // Step 4: Initialize Synapse SDK (without storage context)
     spinner.start('Initializing Synapse SDK...')
 
-    if (!options.privateKey) {
-      spinner.stop(`${pc.red('✗')} Private key required via --private-key or PRIVATE_KEY env`)
-      cancel('Import cancelled')
+    // Check for session key auth (env vars only for now)
+    const walletAddress = process.env.WALLET_ADDRESS
+    const sessionKey = process.env.SESSION_KEY
+
+    // Validate authentication (either standard or session key mode)
+    const hasStandardAuth = options.privateKey != null
+    const hasSessionKeyAuth = walletAddress != null && sessionKey != null
+
+    if (!hasStandardAuth && !hasSessionKeyAuth) {
+      spinner.stop(`${pc.red('✗')} Authentication required`)
+      cancel('Provide either PRIVATE_KEY or both WALLET_ADDRESS + SESSION_KEY env vars')
       process.exit(1)
     }
 
     const config = {
       privateKey: options.privateKey,
+      walletAddress,
+      sessionKey,
       rpcUrl: options.rpcUrl || RPC_URLS.calibration.websocket,
       // Other config fields not needed for import
       port: 0,

src/logger.ts

@@ -1,7 +1,6 @@
 import { type Logger, pino } from 'pino'
-import type { SynapseSetupConfig } from './core/synapse/index.js'
 
-export function createLogger(config: Pick<SynapseSetupConfig, 'logLevel'>): Logger {
+export function createLogger(config: { logLevel?: string }): Logger {
   return pino({
     level: config.logLevel ?? 'info',
   })

src/test/unit/dataset-management.test.ts

@@ -25,7 +25,7 @@ describe('Dataset Management', () => {
       privateKey: '0x0000000000000000000000000000000000000000000000000000000000000001',
       rpcUrl: 'wss://wss.calibration.node.glif.io/apigw/lotus/rpc/v1',
     }
-    logger = createLogger(config)
+    logger = createLogger({ logLevel: 'info' })
     resetSynapseService()
     vi.clearAllMocks()
   })

src/test/unit/import.test.ts

@@ -364,7 +364,9 @@ describe('CAR Import', () => {
       }
 
       await expect(runCarImport(options)).rejects.toThrow('process.exit called')
-      expect(consoleMocks.error).toHaveBeenCalledWith('Import cancelled')
+      expect(consoleMocks.error).toHaveBeenCalledWith(
+        'Provide either PRIVATE_KEY or both WALLET_ADDRESS + SESSION_KEY env vars'
+      )
     })
 
     it('should use custom RPC URL if provided', async () => {

src/test/unit/payments-setup.test.ts

@@ -74,6 +74,7 @@ describe('Payment Setup Tests', () => {
     mockSynapse = {
       getProvider: vi.fn().mockReturnValue(mockProvider),
       getSigner: vi.fn().mockReturnValue(mockSigner),
+      getClient: vi.fn().mockReturnValue(mockSigner),
       getNetwork: vi.fn().mockReturnValue('calibration'),
       getPaymentsAddress: vi.fn().mockReturnValue('0xpayments'),
       getWarmStorageAddress: vi.fn().mockReturnValue('0xwarmstorage'),