@vowifi-rs/vowifi 0.1.9 → 0.1.11

package/README.md

@@ -1,47 +1,482 @@
 # @vowifi-rs/vowifi
 
-Node.js binding for the hardware-independent `vowifi-client` facade.
+Hardware-independent VoWiFi SMS 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 sends or receives SMS 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.
+
+**Node.js API**
+
+- Hardware-independent async AKA callback; the addon does not own a modem or serial port.
+- Pull-based event delivery backed by a bounded queue.
+- 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.
+
+### 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.
+
+### Planned or possible future work
+
+- MMTel voice calling, SIP call control, RTP/RTCP media, and host-provided audio-device bridging.
+- 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.
+
+Voice is not part of the current API, but it is a potential extension of the existing ePDG, IPsec,
+IMS registration, and session-lifecycle foundation rather than a permanently excluded feature.
+
+## 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
+
+```bash
+npm install @vowifi-rs/vowifi
+```
+
+```bash
+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
 
 ```js
-const { VowifiSession } = require('@vowifi-rs/vowifi')
+const { VowifiSession, initLogging } = require('@vowifi-rs/vowifi')
+
+initLogging(process.env.VOWIFI_LOG)
 
 const session = await VowifiSession.connect({
-  subscription: { imsi, mcc, mnc, imei, imeisv },
-  aka: async ({ rand, autn }) => device.authenticateAka(rand, autn),
+  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)
+  },
 })
 
-const result = await session.sendSms({ recipient: '777', text: 'BAL', smsc })
-const event = await session.nextEvent()
-await session.shutdown()
+try {
+  console.log('online using carrier profile:', session.carrierProfileId)
+
+  const result = await session.sendSms({
+    recipient: '+1555...',
+    text: 'Hello over VoWiFi',
+    // smsc: '+15550000000', // Optional RP destination address.
+  })
+
+  console.log('send result:', result)
+
+  for (;;) {
+    const event = await session.nextEvent()
+    if (!event) break
+
+    if (event.kind === 'incomingSms') {
+      const { sender, content } = event.message
+      if (content.kind === 'text') {
+        console.log(`SMS from ${sender}: ${content.text}`)
+      }
+    }
+  }
+} finally {
+  await session.shutdown()
+}
 ```
 
-The package does not scan serial ports or own a modem. The host supplies subscription identity and
-one asynchronous AKA callback. `examples/serial-uicc-aka.js` demonstrates a development adapter
-using the `serialport` dev dependency; it is not part of the production API.
+`VowifiSession.connect()` resolves only after IMS registration succeeds. Call `shutdown()` during
+normal application shutdown so the library can deregister IMS and release network resources.
 
-Run the local checks with:
+## Supplying AKA Authentication
 
-```powershell
-pnpm install
-pnpm run build
-pnpm test
+The package deliberately does not depend on a serial-port library or own a modem. The host supplies
+one asynchronous AKA callback:
+
+```ts
+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 }
 ```
 
-`examples/one-nz-balance.js` is an opt-in real-network regression. It reads its identity and port
-from `VOWIFI_*` environment variables, sends `BAL` to One NZ short code `777`, waits for the reply,
-and performs an explicit IMS deregistration.
+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`](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
+
+```ts
+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:
+
+```js
+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:
+
+```js
+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
+```
 
-## Release
+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.
 
-Releases are published by GitHub Actions from tags matching `v*.*.*`. Update
-the version in `package.json`, push the commit, then push the matching tag:
+## 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:
+
+```js
+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:
+
+```js
+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:
+
+```js
+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.
+
+## Receiving Events
+
+`nextEvent()` waits for the next event and returns `null` after the event stream closes:
+
+```ts
+type VowifiEvent =
+  | { kind: 'registered'; expiresSeconds: number }
+  | { kind: 'refreshed'; expiresSeconds: number; securityReplaced: boolean }
+  | { kind: 'deregistered' }
+  | { kind: 'incomingSms'; message: SmsMessage }
+```
+
+Incoming SMS messages contain the sender, PID, DCS, the raw service-centre timestamp, and either
+decoded text or binary content:
+
+```ts
+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 `incomingSms` is emitted. Consume events
+continuously while the session is online so application processing does not fill the bounded event
+queue.
+
+## Sending SMS
+
+```js
+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.
+
+The result distinguishes network-layer acceptance from an RP-level confirmation:
+
+```ts
+type SmsSendResult =
+  | { kind: 'rpConfirmed'; parts: number; statuses: [] }
+  | { kind: 'sipAcceptedUnconfirmed'; parts: number; statuses: number[] }
+```
+
+`rpConfirmed` means all parts received the expected RP acknowledgement. `sipAcceptedUnconfirmed`
+means SIP accepted the message but no matching RP confirmation was observed; inspect `statuses` and
+apply application-specific delivery semantics.
+
+## Session State and Recovery
+
+```js
+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`:
+
+```js
+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`:
+
+```js
+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:
+
+```js
+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
+
+```ts
+class VowifiSession {
+  static connect(options: ConnectOptions): Promise<VowifiSession>
+  readonly carrierProfileId: string
+  status(): SessionState
+  nextEvent(): Promise<VowifiEvent | null>
+  sendSms(message: SmsSendOptions): Promise<SmsSendResult>
+  shutdown(): Promise<void>
+}
+
+function resolveCarrierProfile(options: ResolveCarrierProfileOptions): ResolvedCarrierProfile
+function initLogging(filter?: string): boolean
+```
+
+See the bundled [`index.d.ts`](index.d.ts) for the complete TypeScript contract.
+
+## Local Development
 
 ```bash
-git tag v0.1.1
-git push origin v0.1.1
+pnpm install
+pnpm run build
+pnpm test
 ```
 
-The repository secret `NPM_TOKEN` must be an npm token with publish access to
-the `@vowifi-rs` scope. The workflow builds the Windows x64, Linux x64, and
-Linux arm64 native packages, then publishes the root package and its optional
-platform packages.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vowifi-rs/vowifi",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Hardware-independent VoWiFi SMS session for Node.js",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -45,8 +45,8 @@
     ]
   },
   "optionalDependencies": {
-    "@vowifi-rs/vowifi-win32-x64-msvc": "0.1.9",
-    "@vowifi-rs/vowifi-linux-x64-gnu": "0.1.9",
-    "@vowifi-rs/vowifi-linux-arm64-gnu": "0.1.9"
+    "@vowifi-rs/vowifi-win32-x64-msvc": "0.1.11",
+    "@vowifi-rs/vowifi-linux-x64-gnu": "0.1.11",
+    "@vowifi-rs/vowifi-linux-arm64-gnu": "0.1.11"
   }
 }