Refactor SimDeck auth and unblock native API handlers

Author: DjDeveloperr

README.md

@@ -63,6 +63,7 @@ To focus a specific simulator, open
 The Rust server exposes HTTP on the requested port and WebTransport on `port + 1`.
 The browser bootstrap comes from `GET /api/health`, which returns the WebTransport URL template,
 certificate hash, and packet version needed by the client.
+The served browser UI receives the generated API access token automatically; direct HTTP callers can use the startup token with `X-SimDeck-Token` or `Authorization: Bearer`.
 
 ## Service
 

docs/api/health.md

@@ -14,7 +14,7 @@ Returns the static bootstrap information the browser client needs to open a WebT
   "timestamp": 1714094761.234,
   "videoCodec": "hevc",
   "webTransport": {
-    "urlTemplate": "https://127.0.0.1:4311/wt/simulators/{udid}",
+    "urlTemplate": "https://127.0.0.1:4311/wt/simulators/{udid}?simdeckToken=...",
     "certificateHash": {
       "algorithm": "sha-256",
       "value": "3f...e9"
@@ -30,11 +30,11 @@ Returns the static bootstrap information the browser client needs to open a WebT
 | `httpPort` / `wtPort`                | Numeric ports for the HTTP and WebTransport servers. WebTransport is always `httpPort + 1`.   |
 | `timestamp`                          | Server-side `time.now()` as a fractional Unix epoch in seconds.                               |
 | `videoCodec`                         | Active encoder. One of `hevc`, `h264`, `h264-software`. See [Video Pipeline](/guide/video).   |
-| `webTransport.urlTemplate`           | URL with a `{udid}` placeholder for the simulator stream. Substitute and dial.                |
+| `webTransport.urlTemplate`           | URL with a `{udid}` placeholder and access token query for the simulator stream.              |
 | `webTransport.certificateHash.value` | SHA-256 of the server's self-signed cert. Pin via `serverCertificateHashes` in the WT client. |
 | `webTransport.packetVersion`         | The current binary packet protocol version. Clients should refuse to parse unknown versions.  |
 
-The certificate is regenerated every time the server restarts. A client that caches the hash should refetch `/api/health` after any disconnection.
+The certificate and default access token are regenerated every time the server restarts. A client that caches the hash should refetch `/api/health` after any disconnection.
 
 ## `GET /api/metrics`
 

docs/api/rest.md

@@ -1,8 +1,8 @@
 # REST Endpoints
 
-The SimDeck server exposes one REST API over plain HTTP. Every route lives under `/api/`. Responses are JSON unless explicitly noted otherwise. Errors return a JSON body with `{"error": {"message": "..."}}` and an appropriate HTTP status.
+The SimDeck server exposes one REST API over plain HTTP. Every route lives under `/api/`. Responses are JSON unless explicitly noted otherwise. Errors return a JSON body with `{"error": "..."}` and an appropriate HTTP status.
 
-CORS is wide open (`Access-Control-Allow-Origin: *`) so you can call the API from any browser tab on the same network.
+The served browser UI receives the generated access token automatically through a strict same-site cookie. Direct API callers must send `X-SimDeck-Token: <token>` or `Authorization: Bearer <token>`.
 
 ## Conventions
 
@@ -25,7 +25,7 @@ Returns server health, the WebTransport URL template, and the certificate hash t
   "timestamp": 1714094761.234,
   "videoCodec": "hevc",
   "webTransport": {
-    "urlTemplate": "https://127.0.0.1:4311/wt/simulators/{udid}",
+    "urlTemplate": "https://127.0.0.1:4311/wt/simulators/{udid}?simdeckToken=...",
     "certificateHash": {
       "algorithm": "sha-256",
       "value": "3f...e9"

docs/api/webtransport.md

@@ -7,10 +7,10 @@ Live video and the per-session control handshake travel over WebTransport. The h
 The exact URL is reported by `GET /api/health`. The template looks like:
 
 ```text
-https://<advertise-host>:<wt-port>/wt/simulators/{udid}
+https://<advertise-host>:<wt-port>/wt/simulators/{udid}?simdeckToken=<token>
 ```
 
-Replace `{udid}` with the simulator UDID from `GET /api/simulators`.
+Replace `{udid}` with the simulator UDID from `GET /api/simulators`. The `simdeckToken` query parameter is included in the authenticated `/api/health` response and is required by the WebTransport server.
 
 ## Certificate pinning
 

docs/cli/commands.md

@@ -9,6 +9,7 @@ Start the HTTP and WebTransport servers in the foreground. This is the only comm
 ```sh
 simdeck serve [--port <u16>] [--bind <ip>] [--advertise-host <host>]
                        [--client-root <path>] [--video-codec <codec>]
+                       [--access-token <token>]
 ```
 
 | Flag               | Default               | Description                                                                            |
@@ -18,13 +19,15 @@ simdeck serve [--port <u16>] [--bind <ip>] [--advertise-host <host>]
 | `--advertise-host` | matches `--bind`      | Hostname or IP advertised to remote clients in the WebTransport URL template and cert. |
 | `--client-root`    | bundled `client/dist` | Override the static client directory.                                                  |
 | `--video-codec`    | `hevc`                | One of `hevc`, `h264`, `h264-software`. See [Video Pipeline](/guide/video).            |
+| `--access-token`   | generated at startup  | Token accepted by `X-SimDeck-Token`, `Authorization: Bearer`, or the served UI cookie. |
 
 When the server is up it prints something like:
 
 ```text
 HTTP listening on http://127.0.0.1:4310
 WebTransport listening on https://127.0.0.1:4311/wt/simulators/{udid}
 Serving client from /usr/local/lib/node_modules/simdeck/client/dist
+API access token: 9f...
 ```
 
 `Ctrl-C` shuts both servers down cleanly.
@@ -36,6 +39,7 @@ Install SimDeck as a per-user `launchd` service. Same flags as `serve`:
 ```sh
 simdeck service on [--port <u16>] [--bind <ip>] [--advertise-host <host>]
                             [--client-root <path>] [--video-codec <codec>]
+                            [--access-token <token>]
 ```
 
 The command writes `~/Library/LaunchAgents/dev.nativescript.simdeck.plist`, bootstraps it into `gui/<uid>`, and immediately kickstarts it. See [Background Service](/guide/service) for details.

docs/cli/flags.md

@@ -67,6 +67,14 @@ Override the static client directory. The Rust server serves the contents at the
 
 Encoder used by the native bridge. See [Video Pipeline](/guide/video) for when to switch.
 
+### `--access-token <token>`
+
+| Default | generated at startup |
+| ------- | -------------------- |
+| Type    | string               |
+
+HTTP API and WebTransport access token. The served browser UI receives it automatically through a strict same-site cookie, so normal local use does not require copying the token. Direct API callers should send either `X-SimDeck-Token: <token>` or `Authorization: Bearer <token>`.
+
 ## Positional arguments
 
 Subcommands that take positionals expect them in the order shown:

docs/extensions/browser-client.md

@@ -103,4 +103,4 @@ The browser client is designed to live inside any container that can host a webv
 
 1. Point the host at `http://<simdeck-host>:<port>/`.
 2. Allow the host to talk to the same WebTransport endpoint exposed by the server.
-3. Optionally, gate the host behind your own auth — SimDeck assumes a trusted local network.
+3. For direct API calls outside the served origin, pass the SimDeck access token with `X-SimDeck-Token` or `Authorization: Bearer`.

docs/guide/lan-access.md

@@ -56,7 +56,7 @@ The server generates a fresh self-signed certificate every time it starts. The c
   "wtPort": 4311,
   "videoCodec": "hevc",
   "webTransport": {
-    "urlTemplate": "https://192.168.1.50:4311/wt/simulators/{udid}",
+    "urlTemplate": "https://192.168.1.50:4311/wt/simulators/{udid}?simdeckToken=...",
     "certificateHash": {
       "algorithm": "sha-256",
       "value": "..."
@@ -72,16 +72,24 @@ Restarting the server invalidates the previous certificate. Open clients reconne
 
 ## Authentication and security
 
-SimDeck assumes a trusted local network. The HTTP API has no built-in authentication and the WebTransport endpoint accepts any client that knows the URL.
+SimDeck generates an API access token at startup unless you pass `--access-token <token>`. The served browser UI receives the token automatically through a strict same-site cookie, so opening `http://<advertise-host>:<port>` remains seamless.
+
+Direct API callers must send one of:
+
+```text
+X-SimDeck-Token: <token>
+Authorization: Bearer <token>
+```
+
+The WebTransport URL template returned by authenticated `GET /api/health` includes a `simdeckToken` query parameter for the browser stream worker.
 
 Recommended practice for shared networks:
 
 - Run SimDeck only on networks you control.
+- Use `--access-token <stable-secret>` for background services or scripted LAN access.
 - Combine with macOS Application Firewall to restrict inbound access to known peers.
 - For shared NativeScript inspectors, set an `authToken` when starting the [Swift in-app agent](/inspector/swift#auth-token) so app-side requests must include the token.
 
-A roadmap item is to add an optional bearer-token header for the HTTP API and WebTransport `?token=` parameter. Until that lands, treat SimDeck like any unauthenticated dev tool.
-
 ## Quick checklist
 
 To make a SimDeck server reachable from another device:

docs/guide/service.md

@@ -21,6 +21,7 @@ You can pass any of:
 | `--advertise-host` | matches `--bind`      | Hostname advertised to remote clients.                             |
 | `--client-root`    | bundled `client/dist` | Override the static client directory.                              |
 | `--video-codec`    | `hevc`                | One of `hevc`, `h264`, `h264-software`. See [Video](/guide/video). |
+| `--access-token`   | generated at startup  | Stable API token for direct HTTP/WebTransport integrations.        |
 
 The command: