# O20010.06 - HT Portal Smartphone App

Native Android and iOS companions, distributed as **HT Portal VPN**, for device
VPN sessions started from HT Portal. From the native app, **Sign in and select a
device** opens the dedicated portal flow in an Android Custom Tab or an iOS
Safari View Controller, keeping sign-in and device selection inside the app UX.
The portal then creates an opaque, one-time handoff and returns to the app through
`https://connect.portal.hivetechnology.net/vpn/#handoff=...`. The token is redeemed by the native
app and is never sent to the landing page server, stored in browser history, or
written to application logs.

## Layout

- `core`: shared C bridge and embedded n3n 3.4.6 edge.
- `android`: Kotlin/Compose application using `VpnService` (Android 10+).
- `ios`: SwiftUI application and Network Extension (iOS 16+).
- `web`: universal/app-link fallback page and association templates.
- `third_party/n3n`: upstream source pinned as a Git submodule.

## Distribution boundary

The mobile packet tunnel and n3n bridge are GPL-3.0-only. On iOS they are built
as the separate `PacketTunnel.appex` executable; the main `HTPortalVPN`
executable does not link n3n and remains proprietary. On Android, n3n and the
bridge are confined to the native `libo20010_06.so`; the Kotlin application
remains proprietary. Every distributed build must include the notices and
publish its corresponding source archive. See
[`docs/IOS_RELEASE_GATE.md`](docs/IOS_RELEASE_GATE.md).

Run the portable core tests with:

```sh
cmake -S core -B core/.build -DHTP_BUILD_N3N=OFF
cmake --build core/.build
ctest --test-dir core/.build --output-on-failure
```

The Android build additionally requires JDK 17 and a configured Android SDK/NDK.
The iOS project is generated with XcodeGen and requires Xcode on macOS.
