@portal-hq/web 3.17.0 → 3.18.0

package/src/rpc.test.ts

@@ -0,0 +1,190 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { isPortalHostedUrl } from './shared/rpc/auth'
+import { buildDefaultRpcConfig, DEFAULT_RPC_HOST } from './shared/rpc/defaults'
+import Portal from '.'
+
+// ─── isPortalHostedUrl ───────────────────────────────────────────────────────
+
+describe('isPortalHostedUrl', () => {
+  describe('trusted Portal domains', () => {
+    const trusted = [
+      'https://web.portalhq.io/rpc/v1/eip155/1',
+      'https://portalhq.io',
+      'https://staging.portalhq.io/rpc/v1/eip155/1',
+      'https://x.portalhq.io',
+      'https://web.portalhq.dev/rpc/v1/eip155/1',
+      'https://portalhq.dev',
+      'https://sub.portalhq.dev',
+      'https://portalhq-passkey.io',
+      'https://sub.portalhq-passkey.io',
+      'https://portalhq-passkey.dev',
+      'https://sub.portalhq-passkey.dev',
+    ]
+
+    for (const url of trusted) {
+      it(`returns true for ${url}`, () => {
+        expect(isPortalHostedUrl(url)).toBe(true)
+      })
+    }
+  })
+
+  describe('untrusted / third-party domains', () => {
+    const untrusted = [
+      'https://mainnet.infura.io/v3/KEY',
+      'https://eth-mainnet.alchemyapi.io/v2/KEY',
+      'https://rpc.ankr.com/eth',
+      'https://notportalhq.io/rpc/v1/eip155/1',
+      'https://portalhq.io.evil.com/rpc',      // subdomain spoofing
+      'https://evil-portalhq.io/rpc',           // prefix attack
+      'https://portalhq.iomalicious.com',       // suffix attack
+      'http://localhost:8545',                  // localhost — not trusted here (iframe-only)
+      'http://127.0.0.1:8545',
+    ]
+
+    for (const url of untrusted) {
+      it(`returns false for ${url}`, () => {
+        expect(isPortalHostedUrl(url)).toBe(false)
+      })
+    }
+  })
+
+  it('returns false for an invalid URL', () => {
+    expect(isPortalHostedUrl('not-a-url')).toBe(false)
+    expect(isPortalHostedUrl('')).toBe(false)
+  })
+
+  it('handles trailing dot in hostname (valid DNS normalisation)', () => {
+    // 'web.portalhq.io.' is technically valid DNS — must still be trusted
+    expect(isPortalHostedUrl('https://web.portalhq.io./rpc/v1/eip155/1')).toBe(true)
+  })
+})
+
+// ─── buildDefaultRpcConfig ───────────────────────────────────────────────────
+
+describe('buildDefaultRpcConfig', () => {
+  it('returns exactly 13 entries', () => {
+    expect(Object.keys(buildDefaultRpcConfig(DEFAULT_RPC_HOST))).toHaveLength(13)
+  })
+
+  it('includes all 11 expected EVM chains', () => {
+    const cfg = buildDefaultRpcConfig(DEFAULT_RPC_HOST)
+    const evmChains = [
+      'eip155:1',
+      'eip155:11155111',
+      'eip155:137',
+      'eip155:80002',
+      'eip155:8453',
+      'eip155:84532',
+      'eip155:143',
+      'eip155:10143',
+      'eip155:10',
+      'eip155:42161',
+      'eip155:43114',
+    ]
+    for (const chain of evmChains) {
+      expect(cfg).toHaveProperty(chain)
+    }
+  })
+
+  it('includes both Solana chains', () => {
+    const cfg = buildDefaultRpcConfig(DEFAULT_RPC_HOST)
+    expect(cfg).toHaveProperty('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp')
+    expect(cfg).toHaveProperty('solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1')
+  })
+
+  it('does NOT include deprecated Polygon Mumbai (eip155:80001)', () => {
+    expect(buildDefaultRpcConfig(DEFAULT_RPC_HOST)).not.toHaveProperty('eip155:80001')
+  })
+
+  it('every URL follows the template https://{rpcHost}/rpc/v1/{namespace}/{reference}', () => {
+    const cfg = buildDefaultRpcConfig(DEFAULT_RPC_HOST)
+    for (const [chainId, url] of Object.entries(cfg)) {
+      const [namespace, reference] = chainId.split(':')
+      expect(url).toBe(`https://${DEFAULT_RPC_HOST}/rpc/v1/${namespace}/${reference}`)
+    }
+  })
+
+  it('uses the production host by default', () => {
+    const cfg = buildDefaultRpcConfig()
+    expect(cfg['eip155:1']).toBe('https://web.portalhq.io/rpc/v1/eip155/1')
+  })
+
+  it('uses a custom rpcHost when provided', () => {
+    const cfg = buildDefaultRpcConfig('web.portalhq.dev')
+    for (const url of Object.values(cfg)) {
+      expect(url).toContain('https://web.portalhq.dev/rpc/v1/')
+    }
+    expect(cfg['eip155:1']).toBe('https://web.portalhq.dev/rpc/v1/eip155/1')
+  })
+
+  it('does not contain the production host when a custom host is used', () => {
+    const cfg = buildDefaultRpcConfig('web.portalhq.dev')
+    for (const url of Object.values(cfg)) {
+      expect(url).not.toContain(DEFAULT_RPC_HOST)
+    }
+  })
+})
+
+// ─── Portal constructor — rpcConfig resolution ───────────────────────────────
+
+describe('Portal constructor — rpcConfig resolution', () => {
+  it('generates 13 default chains when rpcConfig is omitted', () => {
+    const portal = new Portal({ apiKey: 'test-key' })
+    expect(Object.keys(portal.rpcConfig)).toHaveLength(13)
+  })
+
+  it('uses web.portalhq.io gateway URLs when rpcConfig is omitted', () => {
+    const portal = new Portal({ apiKey: 'test-key' })
+    expect(portal.rpcConfig['eip155:1']).toBe(
+      'https://web.portalhq.io/rpc/v1/eip155/1',
+    )
+  })
+
+  it('treats {} identically to omitting rpcConfig', () => {
+    const portalA = new Portal({ apiKey: 'test-key' })
+    const portalB = new Portal({ apiKey: 'test-key', rpcConfig: {} })
+    expect(portalB.rpcConfig).toEqual(portalA.rpcConfig)
+  })
+
+  it('uses an explicit non-empty rpcConfig verbatim (no merge with defaults)', () => {
+    const custom = { 'eip155:1': 'https://my-node.example.com/eth' }
+    const portal = new Portal({ apiKey: 'test-key', rpcConfig: custom })
+    expect(portal.rpcConfig).toEqual(custom)
+    expect(Object.keys(portal.rpcConfig)).toHaveLength(1)
+  })
+
+  it('does not inject defaults alongside an explicit config', () => {
+    const custom = { 'eip155:1': 'https://my-node.example.com/eth' }
+    const portal = new Portal({ apiKey: 'test-key', rpcConfig: custom })
+    expect(portal.rpcConfig['eip155:137']).toBeUndefined()
+  })
+
+  it('uses a custom gatewayHost in the generated default URLs', () => {
+    const portal = new Portal({ apiKey: 'test-key', gatewayHost: 'web.portalhq.dev' })
+    expect(portal.rpcConfig['eip155:1']).toBe(
+      'https://web.portalhq.dev/rpc/v1/eip155/1',
+    )
+  })
+
+  it('all default URLs contain the custom gatewayHost', () => {
+    const portal = new Portal({ apiKey: 'test-key', gatewayHost: 'web.portalhq.dev' })
+    for (const url of Object.values(portal.rpcConfig)) {
+      expect(url).toContain('https://web.portalhq.dev/rpc/v1/')
+    }
+  })
+
+  it('getRpcUrl returns the default URL for a standard chain', () => {
+    const portal = new Portal({ apiKey: 'test-key' })
+    expect(portal.getRpcUrl('eip155:1')).toBe(
+      'https://web.portalhq.io/rpc/v1/eip155/1',
+    )
+  })
+
+  it('getRpcUrl throws for a chain not in the config', () => {
+    const portal = new Portal({ apiKey: 'test-key' })
+    expect(() => portal.getRpcUrl('eip155:99999')).toThrow()
+  })
+})

package/src/shared/rpc/auth.ts

@@ -0,0 +1,27 @@
+const PORTAL_TRUSTED_DOMAINS = [
+  'portalhq.io',
+  'portalhq.dev',
+  'portalhq-passkey.io',
+  'portalhq-passkey.dev',
+]
+
+/**
+ * Returns true iff the URL's hostname is owned by Portal.
+ *
+ * Guards Authorization header injection — prevents credential leakage to
+ * third-party RPC providers (Infura, Alchemy, etc.).
+ *
+ * Localhost trust is intentionally excluded: that is an iframe-only
+ * concern (dev CORS proxies) and is handled separately in the iframe.
+ */
+export function isPortalHostedUrl(url: string): boolean {
+  try {
+    // Normalise: strip trailing dots from hostname (valid DNS but unusual)
+    const hostname = new URL(url).hostname.toLowerCase().replace(/\.$/, '')
+    return PORTAL_TRUSTED_DOMAINS.some(
+      (domain) => hostname === domain || hostname.endsWith(`.${domain}`),
+    )
+  } catch {
+    return false
+  }
+}

package/src/shared/rpc/defaults.ts

@@ -0,0 +1,41 @@
+import type { RpcConfig } from '../types/common'
+
+/**
+ * Production Portal RPC gateway hostname.
+ * Staging equivalent: `web.portalhq.dev`.
+ * Used as the fallback when neither `gatewayHost` nor `host` is supplied.
+ */
+export const DEFAULT_RPC_HOST = 'web.portalhq.io'
+
+/**
+ * Builds the default Portal-managed RPC gateway config from a given gateway host.
+ *
+ * URL template: https://{rpcHost}/rpc/v1/{namespace}/{reference}
+ *
+ * Covers 13 chains — 11 EVM + 2 Solana. Polygon Amoy (eip155:80002) is used;
+ * the deprecated Mumbai (eip155:80001) is intentionally excluded.
+ *
+ * When rpcConfig is undefined or {} in the Portal constructor, this function is
+ * called automatically. An explicit non-empty rpcConfig always takes precedence
+ * verbatim — no merging with defaults.
+ */
+export function buildDefaultRpcConfig(
+  rpcHost: string = DEFAULT_RPC_HOST,
+): RpcConfig {
+  const base = `https://${rpcHost}/rpc/v1`
+  return {
+    'eip155:1': `${base}/eip155/1`,
+    'eip155:11155111': `${base}/eip155/11155111`,
+    'eip155:137': `${base}/eip155/137`,
+    'eip155:80002': `${base}/eip155/80002`,
+    'eip155:8453': `${base}/eip155/8453`,
+    'eip155:84532': `${base}/eip155/84532`,
+    'eip155:143': `${base}/eip155/143`,
+    'eip155:10143': `${base}/eip155/10143`,
+    'eip155:10': `${base}/eip155/10`,
+    'eip155:42161': `${base}/eip155/42161`,
+    'eip155:43114': `${base}/eip155/43114`,
+    'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp': `${base}/solana/5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`,
+    'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1': `${base}/solana/EtWTRABZaYq6iMfeYKouRu166VU2xqa1`,
+  }
+}

package/src/shared/types/common.ts

@@ -416,6 +416,30 @@ export interface BuiltTronTransaction {
   }
 }
 
+export interface TronTypedDataDomain {
+  name?: string
+  version?: string
+  chainId?: number
+  verifyingContract?: string
+  salt?: string
+}
+
+export type TronTypedDataValue =
+  | string
+  | number
+  | boolean
+  | bigint
+  | TronTypedDataObject
+  | TronTypedDataValue[]
+
+export type TronTypedDataObject = { [key: string]: TronTypedDataValue }
+
+export interface TronTypedData {
+  domain: TronTypedDataDomain
+  types: Record<string, Array<{ name: string; type: string }>>
+  value: TronTypedDataObject
+}
+
 // Simulation types
 export interface SimulateTransactionParam {
   to: string

package/src/shared/types/index.ts

@@ -17,6 +17,7 @@ export * from './yieldxyz'
 export * from './zero-x'
 export * from './lifi'
 export * from './noah'
+export * from './meld'
 export * from './hypernative'
 export * from './blockaid'
 

package/src/shared/types/meld.ts

@@ -0,0 +1,302 @@
+import type { PortalApiSuccessEnvelope } from './noah'
+
+
+export type MeldCustomerType = 'INDIVIDUAL' | 'BUSINESS'
+
+export type MeldSessionType = 'BUY' | 'SELL' | 'TRANSFER'
+
+
+export interface MeldCustomerName {
+  firstName?: string
+  lastName?: string
+}
+
+export interface MeldCustomerAddressDetails {
+  lineOne?: string
+  lineTwo?: string
+  city?: string
+  region?: string
+  postalCode?: string
+  country?: string
+}
+
+export interface MeldCustomerAddress {
+  id: string
+  customerId: string
+  type: 'BILLING' | 'SHIPPING' | 'RESIDENCE'
+  status: 'ACTIVE' | 'INACTIVE'
+  addressDetails: MeldCustomerAddressDetails
+}
+
+export interface MeldCustomer {
+  id: string
+  accountId: string
+  externalId: string
+  name?: MeldCustomerName
+  email?: string
+  phone?: string
+  dateOfBirth?: string
+  type?: MeldCustomerType
+  status?: 'ACTIVE' | 'INACTIVE'
+  addresses?: MeldCustomerAddress[]
+  serviceProviders?: Record<string, unknown>
+}
+
+export interface MeldSearchCustomerResponseData {
+  customers: MeldCustomer[]
+  count: number
+  remaining: number
+}
+
+export interface MeldRampIntelligence {
+  rampScore?: number | null
+  lowKyc?: boolean | null
+  previouslyUsed?: boolean | null
+}
+
+export interface MeldQuote {
+  transactionType: string
+  sourceAmount: number
+  sourceAmountWithoutFees?: number | null
+  sourceCurrencyCode: string
+  destinationAmount: number
+  destinationAmountWithoutFees?: number | null
+  destinationCurrencyCode: string
+  exchangeRate: number
+  transactionFee: number
+  networkFee?: number | null
+  partnerFee?: number | null
+  totalFee: number
+  fiatAmountWithoutFees?: number | null
+  paymentMethodType: string
+  serviceProvider: string
+  countryCode?: string
+  customerScore?: number | null
+  institutionName?: string | null
+  isNativeAvailable?: boolean | null
+  rampIntelligence?: MeldRampIntelligence | null
+}
+
+export interface MeldGetRetailQuoteResponseData {
+  quotes: MeldQuote[]
+  message?: string | null
+  error?: string | null
+  timestamp?: string | null
+}
+
+export interface MeldSessionData {
+  countryCode: string
+  serviceProvider: string
+  sourceCurrencyCode: string
+  /** String amount as required by the Meld widget API. Note: MeldGetRetailQuoteRequest.sourceAmount uses number. */
+  sourceAmount: string
+  destinationCurrencyCode: string
+  walletAddress?: string
+  walletTag?: string
+  paymentMethodType?: string
+  redirectUrl?: string
+  lockFields?: string[]
+}
+
+export interface MeldCreateRetailWidgetResponseData {
+  id: string
+  token: string
+  customerId: string
+  externalCustomerId: string
+  externalSessionId: string
+  widgetUrl: string
+  // serviceProviderWidgetUrl exists in the Meld API response but is stripped by the backend controller
+}
+
+export interface MeldTransaction {
+  id: string
+  sessionId: string
+  externalSessionId?: string | null
+  externalCustomerId?: string | null
+  status: string
+  transactionType: string
+  serviceProvider: string
+  sourceAmount?: number | null
+  sourceCurrencyCode?: string | null
+  destinationAmount?: number | null
+  destinationCurrencyCode?: string | null
+  destinationWalletAddress?: string | null
+  createdAt: string
+  updatedAt: string
+  paymentMethodType?: string | null
+  cryptoPurchaseDetails?: Record<string, unknown> | null
+  serviceProviderDetails?: Record<string, unknown> | null
+  [key: string]: unknown
+}
+
+export interface MeldSearchRetailTransactionsResponseData {
+  count: number
+  remaining: number
+  totalCount: number
+  transactions: MeldTransaction[]
+}
+
+export interface MeldGetRetailTransactionResponseData {
+  transaction: MeldTransaction
+}
+
+
+export interface MeldServiceProvider {
+  serviceProvider: string
+  name: string
+  status?: string
+  categories?: string[]
+  categoryStatuses?: Record<string, string>
+  websiteUrl?: string
+  customerSupportUrl?: string
+  logos?: {
+    dark?: string
+    light?: string
+    darkShort?: string
+    lightShort?: string
+  }
+}
+
+export interface MeldCountry {
+  countryCode: string
+  name: string
+  flagImageUrl?: string
+  regions?: { regionCode: string; name: string }[] | null
+}
+
+export interface MeldFiatCurrency {
+  currencyCode: string
+  name: string
+  symbolImageUrl?: string
+}
+
+export interface MeldCryptoCurrency {
+  currencyCode: string
+  name: string
+  chainCode?: string
+  chainName?: string
+  chainId?: string | null
+  contractAddress?: string
+  symbolImageUrl?: string
+}
+
+export interface MeldPaymentMethod {
+  paymentMethod: string
+  name: string
+  paymentType?: string
+  logos?: { dark?: string; light?: string }
+}
+
+export interface MeldCountryDefault {
+  countryCode: string
+  defaultCurrencyCode: string
+  defaultPaymentMethods: string[]
+}
+
+export interface MeldFiatCurrencyPurchaseLimit {
+  currencyCode: string
+  defaultAmount: number | null
+  minimumAmount: number
+  maximumAmount: number
+}
+
+export interface MeldCryptoCurrencySellLimit {
+  currencyCode: string
+  chainCode?: string | null
+  defaultAmount: number | null
+  minimumAmount: number
+  maximumAmount: number
+}
+
+export interface MeldKycLimitTier {
+  dailyLimit?: number | null
+  weeklyLimit?: number | null
+  monthlyLimit?: number | null
+  yearlyLimit?: number | null
+  transactionLimit?: number | null
+}
+
+export interface MeldKycFiatLevel {
+  currencyCode: string
+  level1?: MeldKycLimitTier
+  level2?: MeldKycLimitTier
+  level3?: MeldKycLimitTier
+}
+
+
+export interface MeldCreateCustomerRequest {
+  // externalId is auto-injected by the backend from the authenticated client identity; do not send it
+  name?: MeldCustomerName
+  email?: string
+  phone?: string
+  dateOfBirth?: string
+  type?: MeldCustomerType
+}
+
+export interface MeldGetRetailQuoteRequest {
+  countryCode: string
+  sourceCurrencyCode: string
+  destinationCurrencyCode: string
+  /** Numeric amount. Note: MeldSessionData.sourceAmount uses string for the same concept. */
+  sourceAmount: number
+  walletAddress?: string
+  // externalCustomerId is auto-injected by the backend from the authenticated client identity; do not send it
+  customerId?: string
+  paymentMethodType?: string
+  serviceProviders?: string[]
+  subdivision?: string
+}
+
+export interface MeldCreateRetailWidgetRequest {
+  sessionType: MeldSessionType
+  sessionData: MeldSessionData
+  externalSessionId?: string
+  // externalCustomerId is auto-injected by the backend from the authenticated client identity; do not send it
+  customerId?: string
+  bypassKyc?: boolean
+}
+
+/** externalCustomerIds is auto-injected by the backend; all other string query params are forwarded to Meld */
+export interface MeldSearchRetailTransactionsParams {
+  status?: string
+  limit?: string
+  offset?: string
+  [key: string]: string | undefined
+}
+
+export interface MeldDiscoveryParams {
+  countryCode?: string
+  [key: string]: string | undefined
+}
+
+
+export type MeldCreateCustomerResponse =
+  PortalApiSuccessEnvelope<MeldCustomer>
+export type MeldSearchCustomerResponse =
+  PortalApiSuccessEnvelope<MeldSearchCustomerResponseData>
+export type MeldGetRetailQuoteResponse =
+  PortalApiSuccessEnvelope<MeldGetRetailQuoteResponseData>
+export type MeldCreateRetailWidgetResponse =
+  PortalApiSuccessEnvelope<MeldCreateRetailWidgetResponseData>
+export type MeldSearchRetailTransactionsResponse =
+  PortalApiSuccessEnvelope<MeldSearchRetailTransactionsResponseData>
+export type MeldGetRetailTransactionResponse =
+  PortalApiSuccessEnvelope<MeldGetRetailTransactionResponseData>
+export type MeldGetServiceProvidersResponse =
+  PortalApiSuccessEnvelope<MeldServiceProvider[]>
+export type MeldGetCountriesResponse =
+  PortalApiSuccessEnvelope<MeldCountry[]>
+export type MeldGetFiatCurrenciesResponse =
+  PortalApiSuccessEnvelope<MeldFiatCurrency[]>
+export type MeldGetCryptoCurrenciesResponse =
+  PortalApiSuccessEnvelope<MeldCryptoCurrency[]>
+export type MeldGetPaymentMethodsResponse =
+  PortalApiSuccessEnvelope<MeldPaymentMethod[]>
+export type MeldGetDefaultsResponse =
+  PortalApiSuccessEnvelope<MeldCountryDefault[]>
+export type MeldGetBuyLimitsResponse =
+  PortalApiSuccessEnvelope<MeldFiatCurrencyPurchaseLimit[]>
+export type MeldGetSellLimitsResponse =
+  PortalApiSuccessEnvelope<MeldCryptoCurrencySellLimit[]>
+export type MeldGetKycLimitsResponse =
+  PortalApiSuccessEnvelope<MeldKycFiatLevel[]>