cli-auth.ts

/**
 * CLI Authentication Helpers
 *
 * Shared utilities for parsing authentication options from CLI commands
 * and preparing them for use with the Synapse SDK.
 */

import type { Chain, Synapse } from '@filoz/synapse-sdk'
import { getRpcUrl, NETWORK_CHAINS, resolveDevnetConfig } from '../common/get-rpc-url.js'
import { getOwsAccount } from '../core/ows/index.js'
import type { SynapseSetupConfig } from '../core/synapse/index.js'
import { calibration, initializeSynapse } from '../core/synapse/index.js'
import { createLogger } from '../logger.js'

/**
 * Common CLI authentication options interface
 * Used across all commands that require authentication
 */
export interface CLIAuthOptions {
  /** Private key for standard authentication */
  privateKey?: string | undefined
  /** OpenWallet Standard wallet name or ID (signs in-process, key stays in vault) */
  wallet?: string | undefined
  /** Optional passphrase for an OWS-managed wallet */
  walletPassphrase?: string | undefined
  /** Wallet address for session key mode */
  walletAddress?: string | undefined
  /** Session key private key */
  sessionKey?: string | undefined
  /** View-only wallet address (no signing) */
  viewAddress?: string | undefined
  /** Filecoin network: mainnet or calibration */
  network?: string | undefined
  /** RPC endpoint URL (overrides network if specified) */
  rpcUrl?: string | undefined
  /**
   * Provider ID overrides. Holds values from the canonical repeatable
   * `--provider-id` flag and the deprecated comma-separated `--provider-ids`
   * alias, which the CLI layer merges into this array at parse time.
   */
  providerIds?: string[] | undefined
  /**
   * Data set ID overrides. Holds values from the canonical repeatable
   * `--data-set-id` flag and the deprecated `--data-set-ids` (comma-separated)
   * and `--data-set` (single-value) aliases, which the CLI layer merges into
   * this array at parse time.
   */
  dataSetIds?: string[] | undefined
}

/**
 * Parse CLI authentication options into SynapseSetupConfig
 *
 * This function handles reading from CLI options and environment variables,
 * and returns a config ready for initializeSynapse().
 *
 * Note: Validation is performed by initializeSynapse() via validateAuthConfig()
 *
 * @param options - CLI authentication options
 * @returns Synapse setup config (validation happens in initializeSynapse)
 */
export async function parseCLIAuth(options: CLIAuthOptions): Promise<SynapseSetupConfig> {
  const network = options.network?.toLowerCase().trim()
  const isDevnet = network === 'devnet'
  const hasRpcUrl = options.rpcUrl != null && options.rpcUrl !== ''

  // Env vars are bound to the Commander options via .env() (see cli-options.ts),
  // so read everything from `options` rather than process.env here.
  const owsWalletId = options.wallet
  const owsPassphrase = options.walletPassphrase

  // For devnet, fall back to the devnet user's private key if none provided.
  // OWS wallets take precedence over PRIVATE_KEY when explicitly supplied.
  const privateKey = owsWalletId
    ? undefined
    : options.privateKey || (isDevnet ? resolveDevnetConfig().privateKey : undefined)
  const walletAddress = options.walletAddress
  const sessionKey = options.sessionKey
  const viewAddress = options.viewAddress
  const rpcUrl = getRpcUrl(options)

  // --network and --rpc-url are mutually exclusive at the Commander level. Set the chain hint
  // only when --network was chosen; otherwise leave it undefined and let initializeSynapse probe
  // the RPC endpoint. When neither is supplied, default to mainnet.
  let chain: Chain | undefined
  if (isDevnet) {
    chain = resolveDevnetConfig().chain
  } else if (network) {
    chain = NETWORK_CHAINS[network as keyof typeof NETWORK_CHAINS]
  } else if (!hasRpcUrl) {
    chain = NETWORK_CHAINS.mainnet
  }

  // Resolve a single auth mode; initializeSynapse() validates the final shape.
  // Precedence mirrors initializeSynapse: read-only, then session key, then an
  // owner signer (OWS, then private key). View-only and session-key modes never
  // use the owner account, so the OWS account (which lazily loads the native
  // adapter and can fail on platforms without a prebuilt) is resolved only when
  // an owner signer is actually needed.
  const config: {
    privateKey?: string
    walletAddress?: string
    sessionKey?: string
    readOnly?: boolean
    rpcUrl?: string
    chain?: Chain
    account?: Awaited<ReturnType<typeof getOwsAccount>>
  } = {}

  if (viewAddress) {
    config.walletAddress = viewAddress
    config.readOnly = true
  } else if (walletAddress && sessionKey) {
    config.walletAddress = walletAddress
    config.sessionKey = sessionKey
  } else if (owsWalletId) {
    const owsOptions: Parameters<typeof getOwsAccount>[0] = {
      walletId: owsWalletId,
      chain: chain ?? calibration,
    }
    if (owsPassphrase != null) owsOptions.passphrase = owsPassphrase
    config.account = await getOwsAccount(owsOptions)
  } else if (privateKey) {
    config.privateKey = privateKey
  } else if (walletAddress) {
    // Only one half of session-key auth supplied; pass it through so
    // initializeSynapse can emit its targeted "requires both" error.
    config.walletAddress = walletAddress
  } else if (sessionKey) {
    config.sessionKey = sessionKey
  }
  if (rpcUrl) config.rpcUrl = rpcUrl
  if (chain) config.chain = chain
  return config as SynapseSetupConfig
}

/**
 * Context selection options for upload (provider IDs and/or data set IDs)
 */
export interface ContextSelectionOptions {
  /** Provider ID overrides for targeting specific providers */
  providerIds?: bigint[]
  /** Data set ID overrides for targeting specific data sets */
  dataSetIds?: bigint[]
}

/**
 * Validate and deduplicate raw ID strings into a bigint[].
 * Each raw value may itself be comma-separated (aliases/env supply lists).
 * Returns bigint[] since all downstream consumers (SDK, contracts) use bigint.
 * Throws on empty input, non-numeric values, or duplicate IDs.
 */
function toIdList(rawValues: string[], label: string): bigint[] {
  const parts = rawValues.flatMap((value) =>
    value
      .split(',')
      .map((s) => s.trim())
      .filter((s) => s !== '')
  )

  if (parts.length === 0) {
    throw new Error(`Invalid ${label}: no IDs provided. Provide one or more numeric IDs.`)
  }

  const ids: bigint[] = []
  for (const part of parts) {
    if (!/^\d+$/.test(part)) {
      throw new Error(`Invalid ${label}: "${part}". Provide positive numeric IDs.`)
    }
    const id = BigInt(part)
    if (id <= 0n) {
      throw new Error(`Invalid ${label}: "${part}". Provide positive numeric IDs.`)
    }
    ids.push(id)
  }

  const unique = [...new Set(ids)]
  if (unique.length !== ids.length) {
    const dupes = ids.filter((id, i) => ids.indexOf(id) !== i)
    throw new Error(`Duplicate ${label}: ${[...new Set(dupes)].join(', ')}`)
  }

  return ids
}

interface IdSelectionSource {
  /**
   * Values from the canonical flag. The CLI layer already merges the deprecated
   * aliases into this array (see `collectDeprecatedAliasId` in cli-options.ts),
   * so it covers both the canonical flag and every deprecated alias.
   */
  canonical?: string[] | undefined
  /** Value from the environment variable */
  env?: string | undefined
  label: string
}

/**
 * Gather IDs from the canonical flag (which already includes any deprecated
 * alias values) and env, in that precedence: the flag fully replaces env rather
 * than merging. Returns `provided: false` when no source supplied any value.
 */
function gatherIdSelection(source: IdSelectionSource): { provided: boolean; ids: bigint[] } {
  const raw: string[] = []
  if (source.canonical != null && source.canonical.length > 0) {
    raw.push(...source.canonical)
  } else {
    const env = source.env?.trim()
    if (env != null && env !== '') {
      raw.push(env)
    }
  }

  if (raw.length === 0) {
    return { provided: false, ids: [] }
  }

  return { provided: true, ids: toIdList(raw, source.label) }
}

/**
 * Parse provider IDs from `--provider-id` (repeatable), the deprecated
 * `--provider-ids` alias, and the `PROVIDER_IDS` env var.
 */
export function parseProviderIdSelection(options?: CLIAuthOptions): bigint[] {
  return gatherIdSelection({
    canonical: options?.providerIds,
    env: process.env.PROVIDER_IDS,
    label: 'provider ID(s)',
  }).ids
}

/**
 * Parse data set IDs from `--data-set-id` (repeatable), the deprecated
 * `--data-set-ids` / `--data-set` aliases, and the `DATA_SET_IDS` env var.
 */
export function parseDataSetIdSelection(options?: CLIAuthOptions): bigint[] {
  return gatherIdSelection({
    canonical: options?.dataSetIds,
    env: process.env.DATA_SET_IDS,
    label: 'data set ID(s)',
  }).ids
}

/**
 * Parse context selection from CLI options and environment variables.
 *
 * Reads provider IDs from `--provider-id` / `PROVIDER_IDS` and data set IDs
 * from `--data-set-id` / `DATA_SET_IDS`. The deprecated `--provider-ids`,
 * `--data-set-ids`, and `--data-set` aliases are still accepted (with a
 * warning). Provider and data set selection are mutually exclusive.
 *
 * @param options - CLI authentication options (may contain provider/data-set fields)
 * @returns Context selection options
 */
export function parseContextSelectionOptions(options?: CLIAuthOptions): ContextSelectionOptions {
  const providerIds = parseProviderIdSelection(options)
  const dataSetIds = parseDataSetIdSelection(options)

  if (providerIds.length > 0 && dataSetIds.length > 0) {
    throw new Error(
      'Cannot specify both provider IDs (--provider-id/PROVIDER_IDS) and data set IDs (--data-set-id/DATA_SET_IDS). Use one or the other.'
    )
  }

  if (providerIds.length > 0) {
    return { providerIds }
  }
  if (dataSetIds.length > 0) {
    return { dataSetIds }
  }
  return {}
}

/**
 * Get a logger instance for use in CLI commands
 *
 * @returns Logger configured for CLI use
 */
export function getCLILogger() {
  return createLogger({ logLevel: process.env.LOG_LEVEL })
}

export async function getCliSynapse(options: CLIAuthOptions): Promise<Synapse> {
  const authConfig = await parseCLIAuth(options)
  const logger = getCLILogger()
  return initializeSynapse(authConfig, logger)
}