# AI Agent TODOs

Pending tasks for AI agents. Remove items when completed.

## Unreviewed CLAUDE.md Sections

- [ ] Architecture - Web (`/web`) - @MattDHill

## Features

- [ ] Support preferred external ports besides 443 - @dr-bonez

  **Problem**: Currently, port 443 is the only preferred external port that is actually honored. When a
  service requests `preferred_external_port: 8443` (or any non-443 value) for SSL, the system ignores
  the preference and assigns a dynamic-range port (49152-65535). The `preferred_external_port` is only
  used as a label for Tor mappings and as a trigger for the port-443 special case in `update()`.

  **Goal**: Honor `preferred_external_port` for both SSL and non-SSL binds when the requested port is
  available, with proper conflict resolution and fallback to dynamic-range allocation.

  ### Design

  **Key distinction**: There are two separate concepts for SSL port usage:

  1. **Port ownership** (`assigned_ssl_port`) — A port exclusively owned by a binding, allocated from
     `AvailablePorts`. Used for server hostnames (`.local`, mDNS, etc.) and iptables forwards.
  2. **Domain SSL port** — The port used for domain-based vhost entries. A binding does NOT need to own
     a port to have a domain vhost on it. The VHostController already supports multiple hostnames on the
     same port via SNI. Any binding can create a domain vhost entry on any SSL port that the
     VHostController has a listener for, regardless of who "owns" that port.

  For example: the OS owns port 443 as its `assigned_ssl_port`. A service with
  `preferred_external_port: 443` won't get 443 as its `assigned_ssl_port` (it's taken), but it CAN
  still have domain vhost entries on port 443 — SNI routes by hostname.

  #### 1. Preferred Port Allocation for Ownership (`forward.rs`, `binding.rs`)

  Expand `AvailablePorts` to support trying a preferred port before falling back to the dynamic range:

  - Add `try_alloc(port) -> Option<u16>`: Attempts to exclusively allocate a specific port. Returns
    `None` if the port is already allocated or restricted.
  - Enforce the restricted port list (currently noted in `vhost.rs:89`: `<=1024, >=32768, 5355, 5432,
    9050, 6010, 9051, 5353`) — skip the preferred port if restricted, except for ports the OS itself
    uses (80, 443).
  - No SSL-vs-non-SSL distinction or refcounting needed at this layer — ownership is always exclusive.
    SSL port sharing for domains is handled entirely by the VHostController via SNI.

  Modify `BindInfo::new()` and `BindInfo::update()` to attempt the preferred port first:

  ```
  assigned_ssl_port = try_alloc(ssl.preferred_external_port)
                      .unwrap_or(dynamic_pool.alloc())
  assigned_port     = try_alloc(options.preferred_external_port)
                      .unwrap_or(dynamic_pool.alloc())
  ```

  After this change, `assigned_ssl_port` may match the preferred port if it was available, or fall back
  to the dynamic range as before.

  #### 2. Per-Address Enable/Disable (replaces gateway overrides)

  **Current model being removed**: `NetInfo` has `private_disabled: OrdSet<GatewayId>` and
  `public_enabled: OrdSet<GatewayId>` — gateway-level toggles where private gateways are enabled by
  default and public gateways are disabled by default. The `set-gateway-enabled` RPC endpoint and the
  `InterfaceFilter` impl on `NetInfo` use these sets. This model is unintuitive because users think in
  terms of individual addresses, not gateways.

  **New model**: Per-address enable/disable. Each computed address in `hostname_info` gets an `enabled`
  field. Users toggle individual addresses on the View page (see Section 6).

  **How disabling works per address type**:

  The enforcement mechanism varies by address type because different addresses are reached through
  different network paths:

  - **WAN IP:port** (public gateway IP addresses): Disabled via **source-IP gating** in the vhost
    layer (Section 3). Public and private traffic share the same port listener, so we can't just
    remove the vhost entry — that would also block private traffic. Instead, the vhost target is
    tagged with which source-IP classes it accepts. When a WAN IP address is disabled, the vhost
    target rejects connections whose source IP matches the gateway (i.e., NAT'd internet traffic)
    or falls outside the gateway's LAN subnets. LAN traffic to the same port is unaffected.
  - **LAN IP:port** (private gateway IP addresses): Also enforced via **source-IP gating**. When
    disabled, the vhost target rejects connections from LAN subnets on that gateway. This is the
    inverse of the WAN case — same mechanism, different source-IP class.
  - **Hostname-based addresses** (`.local`, domains): Disabled by **not creating the vhost/SNI
    entry** for that hostname. Since hostname-based routing uses SNI (SSL) or Host header (HTTP),
    removing the entry means the hostname simply doesn't resolve to a backend. No traffic reaches
    the service for that hostname.
  - **Onion addresses**: Disabled by **not creating the Tor hidden service mapping**. The Tor
    daemon won't advertise the onion:port, so no traffic arrives.

  **Backend changes**:

  - **Remove from `NetInfo`**: Delete the `private_disabled` and `public_enabled` fields entirely.
  - **Add to `NetInfo`**: A `disabled` set containing identifiers for addresses the user has explicitly
    disabled. The identifier must be stable across network changes — e.g., `(gateway_id, hostname_kind)`
    for IP/Local addresses, `(gateway_id, domain_value)` for domain addresses, or `onion_value` for
    onion addresses. Exact format TBD at implementation time.
  - **Default behavior preserved**: Private-gateway addresses default to enabled, public-gateway
    addresses default to disabled. An address is enabled if it's not in the `disabled` set AND either
    (a) the gateway is private, or (b) the user has explicitly enabled it.
  - **Add `enabled` field to `HostnameInfo`**: The computed `hostname_info` output should include
    whether each address is enabled, derived from the `disabled` set during `NetServiceData::update()`.
  - **Remove `set-gateway-enabled`** RPC endpoint from `binding.rs`.
  - **Remove `InterfaceFilter` impl for `NetInfo`**: The per-gateway filter logic is replaced by
    per-address filtering in `update()`.

  **New RPC endpoint** (`binding.rs`):

  Following the existing `HostApiKind` pattern, replace `set-gateway-enabled` with:

  - **`set-address-enabled`** — Toggle an individual address on or off.

    ```ts
    interface BindingSetAddressEnabledParams {
      internalPort: number
      addressId: AddressId   // identifies a specific HostnameInfo entry
      enabled: boolean
    }
    ```

    Mutates `NetInfo.disabled` and syncs the host. Uses `sync_db` metadata.

    This yields two RPC methods:
    - `server.host.binding.set-address-enabled`
    - `package.host.binding.set-address-enabled`

  #### 3. Eliminate the Port 5443 Hack: Source-IP-Based WAN Blocking (`vhost.rs`, `net_controller.rs`)

  **Current problem**: The `if ssl.preferred_external_port == 443` branch (line 341 of
  `net_controller.rs`) creates a bespoke dual-vhost setup: port 5443 for private-only access and port
  443 for public (or public+private). This exists because both public and private traffic arrive on the
  same port 443 listener, and the current `InterfaceFilter`/`PublicFilter` model distinguishes
  public/private by which *network interface* the connection arrived on — which doesn't work when both
  traffic types share a listener.

  **Solution**: Determine public vs private based on **source IP** at the vhost level. Traffic arriving
  from the gateway IP should be treated as public (the gateway may MASQUERADE/NAT internet traffic, so
  anything from the gateway is potentially public). Traffic from LAN IPs is private.

  This applies to **all** vhost targets, not just port 443:

  - **Add a `public` field to `ProxyTarget`** (or an enum: `Public`, `Private`, `Both`) indicating
    what traffic this target accepts, derived from the binding's user-controlled `public` field.
  - **Modify `VHostTarget::filter()`** (`vhost.rs:342`): Instead of (or in addition to) checking the
    network interface via `GatewayInfo`, check the source IP of the TCP connection against known gateway
    IPs. If the source IP matches a gateway or IP outside the subnet, the connection is public;
    otherwise it's private. Use this to gate against the target's `public` field.
  - **Eliminate the 5443 port entirely**: A single vhost entry on port 443 (or any shared SSL port) can
    serve both public and private traffic, with per-target source-IP gating determining which backend
    handles which connections.

  #### 4. Port Forward Mapping in Patch-DB

  When a binding is marked `public = true`, StartOS must record the required port forwards in patch-db
  so the frontend can display them to the user. The user then configures these on their router manually.

  For each public binding, store:
  - The external port the router should forward (the actual vhost port used for domains, or the
    `assigned_port` / `assigned_ssl_port` for non-domain access)
  - The protocol (TCP/UDP)
  - The StartOS LAN IP as the forward target
  - Which service/binding this forward is for (for display purposes)

  This mapping should be in the public database model so the frontend can read and display it.

  #### 5. Simplify `update()` Domain Vhost Logic (`net_controller.rs`)

  With source-IP gating in the vhost controller:

  - **Remove the `== 443` special case** and the 5443 secondary vhost.
  - For **server hostnames** (`.local`, mDNS, embassy, startos, localhost): use `assigned_ssl_port`
    (the port the binding owns).
  - For **domain-based vhost entries**: attempt to use `preferred_external_port` as the vhost port.
    This succeeds if the port is either unused or already has an SSL listener (SNI handles sharing).
    It fails only if the port is already in use by a non-SSL binding, or is a restricted port. On
    failure, fall back to `assigned_ssl_port`.
  - The binding's `public` field determines the `ProxyTarget`'s public/private gating.
  - Hostname info must exactly match the actual vhost port used: for server hostnames, report
    `ssl_port: assigned_ssl_port`. For domains, report `ssl_port: preferred_external_port` if it was
    successfully used for the domain vhost, otherwise report `ssl_port: assigned_ssl_port`.

  #### 6. Frontend: Interfaces Page Overhaul (View/Manage Split)

  The current interfaces page is a single page showing gateways (with toggle), addresses, public
  domains, Tor domains, and private domains. It gets split into two pages: **View** and **Manage**.

  **SDK**: `preferredExternalPort` is already exposed. No additional SDK changes needed.

  ##### View Page

  Displays all computed addresses for the interface (from `hostname_info`) as a flat list. For each
  address, show: URL, type (IPv4, IPv6, .local, domain, onion), access level (public/private),
  gateway name, SSL indicator (especially relevant for onion addresses which may have both SSL and
  non-SSL entries), enable/disable state, port forward info for public addresses, and a test button
  for reachability (see Section 7).

  No gateway-level toggles. The old `gateways.component.ts` toggle UI is removed.

  **Note**: Exact UI element placement (where toggles, buttons, info badges go) is sensitive.
  Prompt the user for specific placement decisions during implementation.

  ##### Manage Page

  Simple CRUD interface for configuring which addresses exist. Three sections:

  - **Public domains**: Add/remove. Uses existing RPC endpoints:
    - `{server,package}.host.address.domain.public.add`
    - `{server,package}.host.address.domain.public.remove`
  - **Private domains**: Add/remove. Uses existing RPC endpoints:
    - `{server,package}.host.address.domain.private.add`
    - `{server,package}.host.address.domain.private.remove`
  - **Onion addresses**: Add/remove. Uses existing RPC endpoints:
    - `{server,package}.host.address.onion.add`
    - `{server,package}.host.address.onion.remove`

  ##### Key Frontend Files to Modify

  | File | Change |
  |------|--------|
  | `web/projects/ui/src/app/routes/portal/components/interfaces/` | Overhaul: split into view/manage |
  | `web/projects/ui/src/app/routes/portal/components/interfaces/gateways.component.ts` | Remove (replaced by per-address toggles on View page) |
  | `web/projects/ui/src/app/routes/portal/components/interfaces/interface.service.ts` | Update `MappedServiceInterface` to use `enabled` field from `HostnameInfo` |
  | `web/projects/ui/src/app/routes/portal/components/interfaces/addresses/` | Refactor for View page with overflow menu (enable/disable) and test buttons |
  | `web/projects/ui/src/app/routes/portal/routes/services/services.routes.ts` | Add routes for view/manage sub-pages |
  | `web/projects/ui/src/app/routes/portal/routes/system/system.routes.ts` | Add routes for view/manage sub-pages |

  #### 7. Reachability Test Endpoint

  New RPC endpoint that tests whether an address is actually reachable, with diagnostic info on
  failure.

  **RPC endpoint** (`binding.rs` or new file):

  - **`test-address`** — Test reachability of a specific address.

    ```ts
    interface BindingTestAddressParams {
      internalPort: number
      addressId: AddressId
    }
    ```

    The backend simply performs the raw checks and returns the results. The **frontend** owns all
    interpretation — it already knows the address type, expected IP, expected port, etc. from the
    `HostnameInfo` data, so it can compare against the backend results and construct fix messaging.

    ```ts
    interface TestAddressResult {
      dns: string[] | null      // resolved IPs, null if not a domain address or lookup failed
      portOpen: boolean | null  // TCP connect result, null if not applicable
    }
    ```

    This yields two RPC methods:
    - `server.host.binding.test-address`
    - `package.host.binding.test-address`

  The frontend already has the full `HostnameInfo` context (expected IP, domain, port, gateway,
  public/private). It compares the backend's raw results against the expected state and constructs
  localized fix instructions. For example:
  - `dns` returned but doesn't contain the expected WAN IP → "Update DNS A record for {domain}
    to {wanIp}"
  - `dns` is `null` for a domain address → "DNS lookup failed for {domain}"
  - `portOpen` is `false` → "Configure port forward on your router: external {port} TCP →
    {lanIp}:{port}"

  ### Key Files

  | File | Role |
  |------|------|
  | `core/src/net/forward.rs` | `AvailablePorts` — port pool allocation |
  | `core/src/net/host/binding.rs` | `BindInfo`/`NetInfo` — remove gateway overrides, add per-address disable set, new RPC endpoints |
  | `core/src/net/net_controller.rs:259` | `NetServiceData::update()` — compute `enabled` on `HostnameInfo`, vhost/forward/DNS reconciliation, 5443 hack removal |
  | `core/src/net/vhost.rs` | `VHostController` / `ProxyTarget` — source-IP gating for public/private |
  | `core/src/net/gateway.rs` | `InterfaceFilter` — remove `NetInfo` impl, simplify |
  | `core/src/net/service_interface.rs` | `HostnameInfo` — add `enabled` field |
  | `core/src/net/host/address.rs` | Existing domain/onion CRUD endpoints (no changes needed) |
  | `sdk/base/lib/interfaces/Host.ts` | SDK `MultiHost.bindPort()` — no changes needed |
  | `core/src/db/model/public.rs` | Public DB model — port forward mapping |

- [ ] Remove Tor from StartOS core - @dr-bonez

  **Goal**: Remove all built-in Tor functionality from StartOS. Tor will now be provided by a service
  running on StartOS rather than being integrated into the core OS.

  **Scope**: Remove the Arti-based Tor client, onion address management in the networking stack, Tor
  hidden service creation in the vhost/net controller layers, and any Tor-specific configuration in the
  database models. The core should no longer start, manage, or depend on a Tor daemon.

  **Key areas to modify**:

  | Area | Change |
  |------|--------|
  | `core/src/net/tor/` | Remove the Tor module entirely (Arti client, hidden service management) |
  | `core/src/net/net_controller.rs` | Remove Tor hidden service creation/teardown in `update()` |
  | `core/src/net/host/address.rs` | Remove onion address CRUD RPC endpoints (`address.onion.add`, `address.onion.remove`) |
  | `core/src/net/host/binding.rs` | Remove onion-related fields from `NetInfo` |
  | `core/src/net/service_interface.rs` | Remove onion-related variants from `HostnameInfo` |
  | `core/src/db/model/` | Remove Tor/onion fields from public and private DB models |
  | `sdk/base/lib/interfaces/Host.ts` | Remove onion-related types and options from the SDK |
  | `web/projects/ui/` | Remove onion address UI from interfaces pages |
  | `Cargo.toml` / dependencies | Remove Arti and related Tor crate dependencies |

  **Migration**: Existing onion address data in the database should be cleaned up during migration.
  Services that previously relied on the OS-provided Tor integration will need to use the new Tor
  service instead (service-level integration is out of scope for this task).

- [ ] Auto-configure port forwards via UPnP/NAT-PMP/PCP - @dr-bonez

  **Blocked by**: "Support preferred external ports besides 443" (must be implemented and tested
  end-to-end first).

  **Goal**: When a binding is marked public, automatically configure port forwards on the user's router
  using UPnP, NAT-PMP, or PCP, instead of requiring manual router configuration. Fall back to
  displaying manual instructions (the port forward mapping from patch-db) when auto-configuration is
  unavailable or fails.
