@vowifi-rs/vowifi

Hardware-independent VoWiFi SMS and voice sessions for Node.js.

@vowifi-rs/vowifi connects a SIM subscription to its operator's ePDG, establishes an IKEv2/EAP-AKA/IPsec tunnel, registers with IMS, and exchanges SMS or voice media over Wi-Fi. The package exposes a small session API and delegates only SIM authentication to the host application.

Project status: experimental. Mobile-originated and mobile-terminated SMS have completed an end-to-end commercial-network verification. Interoperability still depends on the operator, subscription, provisioning, ePDG availability, and carrier profile.

Implementation Status

Implemented

Carrier and network setup

• Deterministic built-in carrier-profile selection from home MCC/MNC and optional IMSI, SPN, GID, and ICCID matchers.
• Application-provided carrier profiles and explicit ePDG hostname overrides.
• Standard 3GPP ePDG FQDN discovery from the home PLMN.
• Direct UDP egress with optional local-address binding.
• SOCKS5 UDP egress with optional username/password authentication. A local Clash/Mihomo SOCKS listener can bridge this to VLESS, AnyTLS, or another upstream protocol.

IKEv2 and IPsec

• IKE_SA_INIT, NAT detection, UDP/4500 NAT traversal, and retransmission handling.
• RFC 5998 EAP-only authentication with EAP-AKA and UICC synchronization-failure handling.
• Child SA negotiation and configuration-payload processing for tunnel address, DNS, and P-CSCF.
• Userspace ESP encryption/decryption, integrity verification, sequence handling, and anti-replay protection.
• Userspace raw-IP data plane with DNS, ICMP, UDP, TCP, and inbound IP fragment reassembly.
• IKE INFORMATIONAL, DPD, peer/local Delete handling, and bounded session shutdown.

IMS and SMS

• IMS registration with IMS AKA and ipsec-3gpp security agreement.
• SIP over TCP and UDP as selected by the carrier profile.
• Registration refresh, explicit deregistration, Retry-After handling, and bounded recovery.
• Mobile-originated SMS with SIP transaction tracking and RP acknowledgement correlation.
• Mobile-terminated SMS with SIP 200, RP-ACK, retransmission deduplication, and delayed application delivery until protocol acknowledgement is complete.
• GSM 7-bit and UCS-2 text encoding/decoding.
• Automatic outgoing multipart segmentation.
• Incoming 8-bit and 16-bit concatenated SMS reassembly, including duplicate and out-of-order segment handling.
• Text and binary incoming SMS events.
• International numbers, national numbers, and operator short codes.

IMS voice and media

• Single-call outgoing and incoming IMS SIP lifecycle, including reliable provisional responses, PRACK, ACK, CANCEL, rejection, and BYE.
• Automatic SDP offer/answer negotiation for octet-aligned AMR-NB and AMR-WB.
• Userspace RTP endpoint with bounded reordering, packet-loss concealment, 20 ms pacing, and AMR/PCM/Opus conversion.
• Periodic RTCP SR/RR + SDES, RTCP BYE cleanup, and call-scoped media statistics.
• Call-scoped mono Opus Duplex stream at 8 kHz or 16 kHz with one 20 ms packet per chunk.

Node.js API

• Hardware-independent async AKA callback; the addon does not own a modem or serial port.
• EventEmitter-based control delivery through a bounded native queue; no application polling loop.
• Bounded call-audio Duplex with a one-write-per-Opus-packet contract and aggregated drop events.
• On-demand call.audioStats() snapshots without a Node.js telemetry loop.
• Structured session states and stable JavaScript error codes.
• Built-in carrier-profile inspection through resolveCarrierProfile().
• Optional Rust tracing subscriber through initLogging().
• TypeScript declarations and platform-specific prebuilt native packages.

Implemented but awaiting broader real-network validation

• Automatic IMS registration refresh across a full operator-issued registration lifetime.
• Recovery from transport, IKE, and IMS failures under real network outages and address changes.
• Long outgoing and incoming SMS against a real operator; multipart behavior currently has protocol fixtures and local tests but no stable carrier regression source.
• RP-ACK/RP-ERROR terminal-result differences across operators. The verified deployment accepts MO SMS at the SIP layer and returns the requested service response, but this does not cover every operator's RP behavior.
• IPv6-only ePDG, Child SA, and IMS deployments. Current built-in profiles use IPv4.
• Real-operator outgoing and incoming voice, early media, and bidirectional AMR-NB/AMR-WB audio.

Not implemented

• Emergency calling, supplementary services, USSD, MMS, RCS, or video calling.
• VoLTE or access through a cellular packet core; this package targets untrusted Wi-Fi access via ePDG.
• EAP-AKA' and operator deployments that require it.
• Production-ready certificate-authenticated ePDG profiles, carrier trust-root distribution, OCSP, and revocation caching. The currently verified path uses RFC 5998 EAP-only authentication.
• Full long-lived IKE/Child-SA rekey and every optional IPsec cipher suite, transform, or ESN mode.
• Automatic modem discovery, serial-port management, SIM identity reads, UICC APDU transport, or SMSC discovery. These remain host responsibilities.
• Persistent SMS storage, offline queues, scheduled sending, cross-process deduplication, HTTP APIs, authentication, or a user interface.
• Remote carrier-profile updates or a comprehensive carrier configuration database.
• Native binaries outside the platforms listed below.
• EVS, SRTP toward applications, conferencing, transfer, and multiple simultaneous calls.

Planned or possible future work

• Real-network voice interoperability and aggregated RTCP/media diagnostics.
• Additional carrier profiles and real-network interoperability coverage.
• EAP-AKA', certificate-authenticated ePDG deployments, and broader IPsec transform support as required by verified carrier configurations.
• Additional native platforms and higher-level integrations.

Mobile audio capture/playback, WebSocket transport, AEC, AGC, noise suppression, and system call UI remain responsibilities of the host application and mobile client.

Interoperability

The complete SMS path has been verified with a real UICC and a commercial Wi-Fi Calling network: ePDG discovery, IKEv2/NAT-T, EAP-AKA, Child SA, P-CSCF communication, protected IMS registration, MO SMS, MT SMS, protocol acknowledgements, recovery injection, and explicit deregistration.

This is evidence for one tested configuration, not a compatibility claim for every carrier, plan, SIM generation, or roaming location. Carrier-specific test details are intentionally maintained separately from the npm package overview.

Requirements

• Node.js 20 or newer.
• A SIM/eSIM subscription provisioned by its operator for Wi-Fi Calling.
• Access to the subscription identity: at minimum IMSI and home MCC/MNC.
• A host implementation capable of passing RAND and AUTN to the UICC and returning the AKA result.
• Network access to the operator's ePDG. Some operators restrict access by source network or geography.

Prebuilt packages are currently published for:

| Platform | Architecture | Runtime | | --- | --- | --- | | Windows | x64 | MSVC | | Linux | x64 | glibc | | Linux | arm64 | glibc |

Alpine/musl, macOS, Windows ARM64, and other targets are not currently published.

Installation

npm install @vowifi-rs/vowifi

pnpm add @vowifi-rs/vowifi

The root package selects and installs the matching native package through npm optional dependencies. A Rust toolchain is not required for supported prebuilt targets.

Quick Start

const { VowifiSession, initLogging } = require('@vowifi-rs/vowifi')

initLogging(process.env.VOWIFI_LOG)

const session = await VowifiSession.connect({
  subscription: {
    imsi: '00101...',
    mcc: '001',
    mnc: '01',
    imei: '...',
    imeisv: '...',
  },

  // Forward the challenge to your modem, smart-card reader, Android UICC API,
  // or another trusted hardware adapter.
  aka: async ({ rand, autn }) => {
    return uicc.authenticateAka(rand, autn)
  },
})

try {
  console.log('online using carrier profile:', session.carrierProfileId)

  session.on('sms', message => {
    if (message.content.kind === 'text') {
      console.log(`SMS from ${message.sender}: ${message.content.text}`)
    }
  })

  const result = await session.sendSms({
    recipient: '+1555...',
    text: 'Hello over VoWiFi',
    // smsc: '+15550000000', // Optional RP destination address.
  })

  console.log('send result:', result)
} finally {
  await session.shutdown()
}

VowifiSession.connect() resolves only after IMS registration succeeds. Call shutdown() during normal application shutdown so the library can deregister IMS and release network resources.

Supplying AKA Authentication

The package deliberately does not depend on a serial-port library or own a modem. The host supplies one asynchronous AKA callback:

interface AkaRequest {
  rand: Buffer
  autn: Buffer
}

type AkaResult =
  | { kind: 'success'; res: Buffer; ck: Buffer; ik: Buffer; kc?: Buffer }
  | { kind: 'synchronizationFailure'; auts: Buffer }
  | { kind: 'rejected'; sw1: number; sw2: number }

The callback should perform a 3GPP USIM authentication operation and return:

• success when the UICC returns RES, CK, and IK.
• synchronizationFailure when the UICC returns AUTS for sequence-number resynchronization.
• rejected when the UICC rejects the command with status words.

Transport failures should reject the Promise with an Error. Calls may occur during initial tunnel authentication, IMS authentication, or session recovery, so the adapter must remain available for the full session lifetime and serialize access if the underlying UICC transport requires it.

The repository contains a development-only serial implementation in examples/serial-uicc-aka.js. It uses serialport and AT/APDU commands as an example; it is not required by or bundled into the production API.

Subscription Identity

interface SubscriptionIdentity {
  imsi: string
  mcc: string
  mnc: string
  imei?: string
  imeisv?: string
  spn?: string
  gid1?: string
  gid2?: string
  iccid?: string
}

imsi, mcc, and mnc are required. MCC/MNC must describe the home subscription, not the currently visited cellular network. Optional SPN, GID, ICCID, and IMSI-prefix data can disambiguate MVNO or carrier-specific profiles. IMEI/IMEISV may be used in IMS identity headers where required.

Create a new session after changing the physical SIM or active eSIM profile.

Carrier Profiles

By default, the package selects a built-in profile from the subscription identity:

const session = await VowifiSession.connect({
  subscription,
  carrierProfile: 'auto',
  aka,
})

The registry includes a generic 3GPP fallback and carrier-specific profiles. Automatic matching uses deterministic priority and specificity rules. Unknown operators fall back to the conservative generic profile, which does not guarantee interoperability.

Inspect the selected profile before connecting:

const { resolveCarrierProfile } = require('@vowifi-rs/vowifi')

const resolved = resolveCarrierProfile({
  subscription,
  carrierProfile: 'auto',
})

console.log(resolved.profile.id)
console.log(resolved.source)    // builtin, override, custom, or fallback
console.log(resolved.matchedBy) // fields responsible for the match

Applications may select a profile by ID or pass versioned profile objects through carrierOverrides. Carrier profiles describe protocol policy, not subscriber secrets or live session state.

ePDG Discovery and Network Egress

The library normally derives standard 3GPP ePDG hostnames from the home MCC/MNC. Override discovery when testing or when an operator publishes a non-standard hostname:

const session = await VowifiSession.connect({
  subscription,
  explicitEpdgHostnames: ['epdg.example.operator'],
  aka,
})

Direct egress is the default. A local source address can be selected when the host already has the required routing configuration:

egress: {
  kind: 'direct',
  localAddress: '192.0.2.10',
}

SOCKS5 egress is useful when the operator's ePDG must be reached through a specific network exit. It can point to a local Clash/Mihomo SOCKS listener even when the upstream proxy uses VLESS, AnyTLS, or another protocol:

egress: {
  kind: 'socks5',
  proxy: '127.0.0.1:7891',
  username: 'optional',
  password: 'optional',
}

The proxy must support the SOCKS5 UDP association needed by IKE/IPsec traffic.

Voice Calls and Opus Audio

Carrier codec preference and bounded application-audio buffering are selected at connect time:

const session = await VowifiSession.connect({
  subscription,
  aka,
  voice: {
    preferredCodecs: ['AMR-WB', 'AMR'],
    uplinkBufferMs: 200,
    downlinkBufferMs: 200,
  },
})

function attachCall(call) {
  call.on('state', state => console.log('call state:', state))
  call.on('audio', audio => attachAudio(audio))
  call.on('ended', result => console.log('call ended:', result))
}

function attachAudio(audio) {
  console.log(audio.callId, audio.format)
  audio.on('data', opusPacket => sendBinaryAudioToClient(opusPacket))
  clientAudio.on('data', opusPacket => audio.write(opusPacket))
  audio.on('audioDrop', ({ direction, frames }) => {
    console.warn('real-time audio dropped', { direction, frames })
  })
}

session.on('incomingCall', async call => {
  attachCall(call)
  await call.ring()
  await call.answer()
})

const call = await session.dial({ number: '+15551234567' })
attachCall(call)
console.log(call.audioStats())

Each readable chunk and writable write carries one complete 20 ms mono Opus packet. The negotiated sample rate is 8 kHz for AMR-NB or 16 kHz for AMR-WB; the application profile uses 20 kbps with FEC and DTX disabled initially. Internal PCM does not cross the addon boundary. The host owns WebSocket transport, mobile audio capture/playback, echo cancellation, system call UI, and policy for hanging up when a remote audio connection disappears.

Receiving Events

VowifiSession is an EventEmitter. Listen to focused events or the complete event stream:

session.on('sms', message => console.log('incoming SMS:', message))
session.on('smsStatus', event => console.log('outgoing SMS update:', event))
session.on('incomingCall', call => console.log('incoming call:', call.remoteUri))
session.on('event', event => console.log('all protocol events:', event))

The complete event union is:

type VowifiEvent =
  | { kind: 'registered'; expiresSeconds: number }
  | { kind: 'refreshed'; expiresSeconds: number; securityReplaced: boolean }
  | { kind: 'deregistered' }
  | { kind: 'incomingSms'; message: SmsMessage }
  | { kind: 'outgoingSmsRpConfirmed'; transactionId: string }
  | { kind: 'outgoingSmsFailed'; transactionId: string; rpCause: number; rpDiagnostic: Buffer }
  | { kind: 'outgoingSmsReportTimeout'; transactionId: string }
  | { kind: 'call'; call: CallEvent }

Incoming SMS messages contain the sender, PID, DCS, the raw service-centre timestamp, and either decoded text or binary content:

interface SmsMessage {
  sender: string
  protocolIdentifier: number
  dataCodingScheme: number
  serviceCentreTimestamp: Buffer
  content:
    | { kind: 'text'; text: string }
    | { kind: 'binary'; data: Buffer }
}

Multipart incoming messages are reassembled before the sms event is emitted. Native event delivery is bounded; listeners should hand off expensive work rather than block the Node.js event loop.

Sending SMS

const result = await session.sendSms({
  recipient: '12345',
  text: 'STATUS',
  smsc: '+1234567890', // Optional; operator dependent.
})

International numbers, national numbers, and operator short codes are accepted. Long text is split into multipart SMS automatically.

sendSms() completes as soon as every part receives a final SIP 2xx response. RP-level reports arrive later through the smsStatus event and never keep the send promise pending:

interface SmsSendResult {
  kind: 'accepted'
  parts: Array<{
    transactionId: string
    sipStatus: number
  }>
}

Match each part's transactionId against outgoing status events. outgoingSmsRpConfirmed records an RP-layer acknowledgement; it does not mean the recipient read the message. outgoingSmsFailed reports a later RP-ERROR. If no matching RP report arrives within the protocol window, outgoingSmsReportTimeout is emitted while the original submission remains accepted.

Session State and Recovery

const state = session.status()

Possible states are stopped, connecting, online, recovering, stopping, and failed. Failures may include a diagnostic message.

The session automatically refreshes IMS registration and can recover from transient transport or protocol failures. Timing and recovery behavior can be tuned with operational:

operational: {
  ioTimeoutMs: 10_000,
  ikeInitialTimeoutMs: 1_000,
  ikeAttempts: 3,
  registrationTimeoutMs: 120_000,
  refreshAtPercent: 80,
  recoveryAttempts: 3,
  recoveryInitialDelayMs: 1_000,
  recoveryMaxDelayMs: 30_000,
}

Most applications should keep the defaults. Use overrides primarily for diagnostics or known operator behavior.

Logging

Logging is opt-in and backed by Rust tracing:

const installed = initLogging(
  'vowifi_client=debug,vowifi_runtime=info,vowifi_transport=info,vowifi_ipsec=warn,vowifi_ims=info',
)

If no argument is provided, VOWIFI_LOG is used, followed by the package default filter. The function returns true when it installs the global subscriber and false when another subscriber is already installed. Call it once, before connecting.

Do not enable verbose protocol logs in production without reviewing their contents. Authentication material and subscriber identifiers require the same handling as other credentials.

Errors

Rejected operations throw JavaScript Error objects with a stable code property:

try {
  await session.sendSms({ recipient, text })
} catch (error) {
  if (error.code === 'SESSION_OFFLINE') {
    // Decide whether to wait for recovery or report the failure.
  }
  throw error
}

Current error codes:

• INVALID_CONFIG
• CARRIER_PROFILE_NOT_FOUND
• EPDG_DISCOVERY_FAILED
• AKA_FAILED
• SESSION_OFFLINE
• IMS_REGISTRATION_FAILED
• SMS_SEND_FAILED
• SHUTDOWN_FAILED

Use code for program flow. Error messages are diagnostic text and may change between releases.

API Summary

class VowifiSession {
  static connect(options: ConnectOptions): Promise<VowifiSession>
  readonly carrierProfileId: string
  readonly activeCall?: VowifiCall
  status(): SessionState
  on(event: 'event' | 'state' | 'sms' | 'smsStatus' | 'incomingCall', listener): this
  sendSms(message: SmsSendOptions): Promise<SmsSendResult>
  dial(options: { number: string }): Promise<VowifiCall>
  shutdown(): Promise<void>
}

class VowifiCall {
  readonly id: string
  readonly direction: 'incoming' | 'outgoing'
  readonly remoteNumber?: string
  readonly remoteUri?: string
  readonly state: CallState
  readonly audio?: CallAudioStream
  audioStats(): CallAudioStats
  ring(): Promise<void>
  answer(): Promise<void>
  reject(status?: number): Promise<void>
  hangup(): Promise<void>
}

function resolveCarrierProfile(options: ResolveCarrierProfileOptions): ResolvedCarrierProfile
function initLogging(filter?: string): boolean

See the bundled index.d.ts for the complete TypeScript contract.

Local Development

pnpm install
pnpm run build
pnpm test

The repository also contains opt-in real-network regression examples. They require an eligible SIM, explicit environment configuration, and deliberate execution; they are not part of the default test suite.

License

Licensed under either of Apache License 2.0 or the MIT license, at your option.