DOCS / 01

How the system works

Connect a phone or laptop to Wi-Fi. The router first waits for approval of the new device. It then applies the rules of the assigned zone: some connections are allowed, others are stopped.

How the system works - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

a guest phone uses internet access in its own zone. The administrator assigns devices to zones and configures permitted directions.

What happens technically

  1. Join the network

    New devices enter Isolation. Administrator approval assigns a zone and appropriate permissions.

  2. Assign access

    The administrator approves a device and assigns a zone. The system distinguishes physical MAC hosts from mTLS certificate identities. Each zone controls permitted traffic flows.

  3. Enforce rules

    The native nftables firewall controls L3/L4 traffic; CAKE SQM active queue management eliminates bufferbloat on WAN; the DNS resolver applies configured profiles and lists.

Terms and mechanisms

Zone
A group of devices with shared access rules: Admin, Trusted, Guest, IoT or Isolation. The administrator chooses permitted communication directions and approves devices waiting in quarantine.
Firewall
Native nftables firewall (Linux kernel) enforces L3/L4 rules. CAKE SQM active queue management eliminates bufferbloat on WAN, and Client Isolation can be enabled for guests and IoT.
DNS
Unbound validates DNSSEC for signed domains and encrypts upstream queries through DoT. Enabled RPZ lists, including CERT Polska and OpenPhish, block the selected domains.
HTTPS
HTTPS encrypts the browser-to-website connection. GADNET Browser applies content rules during browsing, while router policies control domains and connections.

Scope and limitations

Zones organize device access. The administrator chooses permitted directions, and client isolation adds controls within a zone. CAKE SQM helps manage WAN queues. Website HTTPS remains encrypted between the browser and server.

DOCS / 02

Creating the first administrator

Read the setup Wi-Fi details and PIN on the router screen. Your phone guides you through trusting the router and creating the first administrator.

Creating the first administrator - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

Setting up a new router: connect a monitor, join the setup Wi-Fi and confirm your presence with its PIN.

What happens technically

  1. Reach the setup portal

    A monitor connected to the router shows the setup Wi-Fi name, password and QR code, and a six-digit PIN that changes every 90 seconds. Join that Wi-Fi or plug in Ethernet; the phone’s network sign-in sheet opens the portal.

  2. Prove you are at the router

    Enter the PIN from the screen; five wrong attempts lock the address for three minutes. Download the household Root CA, which the router created itself at first start, then continue in the HTTPS wizard.

  3. Create the credential

    Register a passkey with user verification, or choose a PIN-protected device certificate on a supported phone. A setup probe checks that the phone presents the certificate from its system keystore. The router then restarts.

Terms and mechanisms

Root CA
The household certificate authority is created on the router at first boot and forms the foundation of local mTLS trust.
Passkey / certificate
FIDO2 / Passkey AAL2 with user verification. The setup alternative is a device certificate protected by a PIN from the platform keystore.
Stage 1 / Stage 2
In Stage 1 the router acts as an open gateway with co-equal Ethernet and Wi-Fi setup. In Stage 2 new devices go straight to Isolation and brute-force PIN attempts are blocked (5 fails = 3 min lockout).

Scope and limitations

Under the security contract, the router boots into Stage 1 where LAN devices have normal WAN access and the captive portal operates co-equally on Ethernet (br-lan) and setup Wi-Fi (wlan0). The PIN is visible only on the HDMI screen; 5 wrong attempts lock the client IP for 3 minutes. The moment the administrator account is created (Stage 2), new devices immediately go to Isolation, setup endpoints return 410 Gone, and setup Wi-Fi shuts down once main Wi-Fi is configured.

DOCS / 03

How updates work

The router checks who signed the update and whether it fits the system. It prepares a way back, installs the change and checks its services.

How updates work - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

An overnight update ends with health checks. If services fail, the router returns to the previous code.

What happens technically

  1. Verify the release

    The router checks the manifest signature against a trusted key. Accepting an update requires a valid publisher signature.

  2. Prepare the change

    Bundle integrity and Python dependency compatibility are checked. A changed requirements.lock needs an offline update. Operator settings live outside the replaced application tree.

  3. Confirm health

    The default window is 03:10-03:50 on the router clock. Services are checked after installation; failures trigger rollback and an interrupted operation is recovered at boot.

Terms and mechanisms

Manifest / SHA-256
The manifest describes a release; SHA-256 checks bundle integrity.
SLH-DSA
A trusted publisher key verifies the package signature before installation.
Rollback
Rollback restores earlier code after installation or service-check problems. Configuration backups provide a separate way to restore settings and data.

Scope and limitations

GADNET code, Alpine packages and browser installers have separate update paths. Alpine packages come from Alpine repositories. Kernel, bootloader, musl and busybox require the new-image path.

DOCS / 04

How the browser works

The browser learns your household rules and applies them when opening websites. It can block addresses or hide matching content. Away from home, it keeps the last saved rules.

How the browser works - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

A guardian chooses channel and keyword rules. GADNET Browser applies them to the person’s profile; a blocked page can be sent to the guardian for approval.

What happens technically

  1. Trust the right router

    Setup pins the approved Root CA fingerprint. Pairing binds the app to a person and key; DPoP proofs demonstrate possession of that key.

  2. Apply household rules and cut-off

    In GADNET Browser mode, standalone YouTube and TikTok apps lose Internet access on the child device. Content is accessed through the browser under guardian rules: creator allowlists, enforced SafeSearch in Google, Bing and DuckDuckGo, and granular AI access controls (ChatGPT, Claude, Gemini).

  3. Keep rules away from home

    At home, web traffic goes through a local proxy and router gateway. Away, the app keeps enforcing its last saved rules. Rule changes and guardian replies need a reachable router; on Windows the vault can also be unlocked through the remote relay.

Terms and mechanisms

Policy
Rules fetched from the router for a person. SSE events notify the app of changes.
DPoP / pinned CA
The app key proves its identity; an approved CA fingerprint identifies the correct router.
Local filtering
The GADNET Browser engine evaluates URLs, metadata and page text within the app’s supported scope.

Scope and limitations

Content filtering applies to GADNET Browser. When enabled, the router cuts off traffic to standalone YouTube and TikTok apps. Key protection depends on hardware (TPM / StrongBox).

DOCS / 05

Remote access through a relay

You are away from home and want to connect to your home storage, for example. An intermediary helps the app reach your router. The router checks who you are and which device you may access; the intermediary only carries the encrypted conversation between the app and router.

Remote access through a relay - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

a paired app opens the approved NAS service on an administrator-selected port. Permissions define the particular service available to that person.

What happens technically

  1. Connect the transport

    The router maintains an outbound WSS channel. The relay connects the paired app with the router connector.

  2. Authorize access

    TLS 1.3 runs between the app and router inside WSS. The router checks identity, DPoP and a passkey with user verification, then issues a resource-specific grant.

  3. Keep checking the session

    The router resolves the target from its DHCP lease and zone assignment, then repeats access checks. Revocation ends the stream. /stream serves a resource; /mux carries multiple TCP connections to allowed device ports.

/stream serves a resource; /mux carries multiple TCP connections to allowed device ports. Targets are permitted private RFC1918 addresses; router addresses and the administrator panel are excluded.

Terms and mechanisms

WSS
WebSocket over TLS. The app connects to /client on the relay, while the router maintains an outbound /connector. After receiving the stream ID, the router opens a one-time /attach. This TLS layer ends at the VPS.
TLS 1.3
A separate TLS connection runs between the app and router inside the transport. The app uses the approved household Root CA, while the relay handles transport and its metadata.
DPoP / passkey
DPoP proves possession of the paired app key. A passkey with user verification authenticates the person. Their private GADNET code is also required when configured.
Grant / TCP
A grant restricts access to a selected resource. The router checks MAC, zone and the current DHCP lease; it opens TCP only to the allowed target and ports. Repeated permission checks allow streams to be closed when access is revoked.

Scope and limitations

Remote access requires a configured relay and permission for a selected service. TLS connects the app to the router, while the LAN leg uses the service’s protocol. The administrator panel remains a separate management channel.

DOCS / 06

DNS, lists and protection profiles

Before opening a site, a device asks for its domain address. The router checks selected lists and the protection profile, then answers or blocks the name.

DNS, lists and protection profiles - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

DNS policies block selected domains. GADNET Browser rules add content controls during browsing.

What happens technically

  1. Choose lists and threat feeds

    The router integrates official threat feeds including CERT Polska (NASK) and OpenPhish. The DNS RPZ filter immediately blocks known credential phishing and SMS scam domains.

  2. Verify DNSSEC signatures

    The local Unbound resolver cryptographically verifies domain RRSIG signatures against the ICANN root trust anchor, stopping DNS spoofing and cache poisoning.

  3. Encrypt upstream queries and prevent bypass

    Upstream queries use DNS-over-TLS (DoT port 853) by default. The nftables firewall intercepts plain port 53 DNS and blocks rogue public DoH/DoT providers to enforce policies.

Terms and mechanisms

DNSSEC / DoT
Unbound cryptographically verifies DNSSEC signatures against root keys to stop cache poisoning, and encrypts upstream queries via DNS-over-TLS (port 853).
NXDOMAIN / RPZ
An NXDOMAIN response for domains blocked by enabled RPZ policies, including CERT Polska and OpenPhish lists.
Bypass prevention
The nftables firewall redirects plain port 53 DNS to the local resolver and blocks rogue public DoH/DoT providers to enforce policies.

Scope and limitations

DNS acts on domains: a blocked name, with its subdomains, is answered as non-existent (NXDOMAIN). Unbound validates DNSSEC locally on the node. Plain DNS requests are automatically intercepted by firewall rules, and rogue encrypted DoH/DoT resolvers are blocked to prevent policy bypass.

DOCS / 07

The private browser vault

History, bookmarks and passwords are saved in the person’s encrypted vault. Unlocking requires identity verification and release of the key by the router.

The private browser vault - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

On a shared Windows computer, household members use separate profiles. A restart locks the vault while browsing rules remain active.

What happens technically

  1. Separate people

    Windows uses separate profiles, app keys and website-data partitions. Android associates the browser with one person per phone.

  2. Open your own data

    Vault access requires app-key proof, identity confirmation and the person’s private GADNET code. A guardian code can open a household-managed vault until its owner sets a private code. An adult’s vault remains under that person’s control.

  3. Browse with a locked vault

    On Windows a restart locks the data while rules keep working; history visits made meanwhile are sealed to an X25519 public key and merged at the next unlock. Android keeps the key sealed in Android Keystore, usable only while the phone is unlocked, and reopens the vault at launch.

Terms and mechanisms

AES-256-GCM / HKDF
HKDF derives a key; AES-256-GCM encrypts data and checks integrity.
Windows / Android
Windows holds the key in memory; restart locks the data. Android seals the key in Android Keystore / StrongBox.
X25519
With the Windows vault locked, visits are sealed to an X25519 public key and merged after unlocking.

Scope and limitations

The router keeps a vault key for each person and their paired apps. Revoking an app retains the key, deleting the account erases it, and an app can keep a protected local copy. Encryption protects stored data; active-session security also depends on operating-system protections.

DOCS / 08

Private PKI and key rotation

Your home has its own certificates; the update publisher has separate signing keys. During key changes, the router checks that new trust follows from an already trusted key.

Private PKI and key rotation - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

A new publisher keyset passes the router’s trust checks before use for later updates.

What happens technically

  1. Establish household trust

    The router creates its own Root and Intermediate CA on the device. The app pins the approved fingerprint; the admin panel, devices and paired apps use certificates issued by that CA.

  2. Protect the right connections

    Supported router connections can negotiate hybrid X25519MLKEM768 or SecP256r1MLKEM768 key exchange. Other website connections use the algorithms supported by the browser and that server.

  3. Rotate the publisher key

    A trusted key and sequence checks validate a new update keyset. The checks retain a usable verification key, while a configured rescue path allows administrator fingerprint confirmation.

Terms and mechanisms

Root / Intermediate CA
Household certificate authorities issue local-network certificates. Separate publisher keys sign software updates.
Keyset
Update keys signed by an already trusted key. Sequence numbers protect against replay of an older keyset.
Hybrid key exchange
The panel and update client offer hybrid key-exchange algorithms to compatible peers. Encryption for external websites is negotiated between the browser and each website server.

Scope and limitations

The household Root CA manages local certificates, while update publisher keys form a separate trust path. Certificate revocation is enforced by peers checking status. PQC support also depends on the client.

DOCS / 09

Backups and recovery

The router saves configuration and creates backups. You can configure an external destination for Redis state. Recovery checks the backup signature before use.

Backups and recovery - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

Store an off-device copy of configuration and prepare a separate recovery-key bundle for storage failure.

What happens technically

  1. Persist configuration

    Alpine Local Backup Utility (LBU) commits configuration daily. A backup at 02:45, before the update window, keeps local copies of configuration, CA, DHCP, DNS and Redis state on storage.

  2. Copy off the device and secure keys

    The administrator can configure an SSH or S3 destination for Redis state. Sensitive Root CA keys and node identity are protected through an asymmetric GPG Recovery & Escrow ceremony tied to a standard BIP-39 recovery mnemonic.

  3. Verify before restoration

    Backups are signed with post-quantum SLH-DSA-128s. The restore tool strictly rejects an invalid signature, guaranteeing state integrity.

Terms and mechanisms

LBU / snapshot
Alpine Local Backup Utility persists /etc configuration daily. A 02:45 nightly snapshot preserves CA, DHCP, DNS and Redis database state.
SSH / S3
Administrator-configured remote destinations for Redis state. Confidentiality and retention depend on the external target.
SLH-DSA / Escrow
Post-quantum SLH-DSA-128s signature validates backup integrity. Root CA keys and node identity are safeguarded by a BIP-39 Recovery & Escrow ceremony.

Scope and limitations

An SLH-DSA signature verifies backup integrity. The selected storage destination supplies encryption and access controls for off-device copies. A previously prepared GPG bundle supports recovery of sensitive router keys.

DOCS / 10

Dynamic protection against scams

Someone on a call urges you to open your bank, make a transfer or start remote desktop software. The router may notice a configured domain and temporarily cut configured services, as well as send a warning.

Dynamic protection against scams - process described below
On mobile, scroll the diagram sideways.Open PNG and zoom ↗
IN PRACTICE

A caller asks someone to run a remote desktop tool and open their bank. An enabled rule can restrict selected connections and give the user time to check the situation. Network signals and configured rules drive protection.

What happens technically

  1. Match a domain

    An enabled protection rule compares the observed name with trigger_domain, including subdomains. The name can come from DNS or passive observation of visible SNI.

  2. Restrict the device’s connections

    A banking-domain match activates the configured domain and optional remote-desktop port blocks for the device. block_duration_minutes sets duration. Continued access to the triggering domain can renew protection.

  3. Correlate events and warn

    The router correlates banking-domain access with call activity. UDP_VOICE examines conntrack connection features, including ports associated with WhatsApp or STUN/TURN. Warnings can reach administrators and affected devices. Configured remote-desktop blocks start on a banking-domain match.

Terms and mechanisms

DNS / SNI
The trigger is a domain match in DNS or visible TLS ClientHello SNI. An unavailable name can prevent this detection path.
Conntrack / UDP_VOICE
The heuristic examines active UDP connection characteristics, including STUN/TURN and high-port traffic. The result identifies a situation worth checking.
Block / notification
Configured domains and optional remote-desktop ports are blocked on a rule match, regardless of call detection. Voice correlation controls the warning; an enforced block also triggers a notification.

Scope and limitations

Protection correlates network signals with configured rules. A warning highlights activity worth checking, while blocking targets selected domains, addresses and ports. Visibility depends on traffic routing, DNS/SNI availability and encryption. The user verifies the caller’s identity and approves banking operations.

These diagrams describe local GADNET system and app mechanisms. Remote access requires a configured relay, a paired app and service permissions. The descriptions help choose settings for a particular installation.