Merge pull request #270 from gosuda/feat/keyless-time

Feat/keyless time

Author: gosunuts

.gitignore

@@ -42,8 +42,8 @@ profile.cov
 /target
 
 # Docker Compose Override
-docker-compose.override.yml
-docker-compose.override.yaml
+/docker-compose.override.yml
+/docker-compose.override.yaml
 
 # Added by goreleaser init:
 dist/

cmd/portal-tunnel/README.md

@@ -394,7 +394,8 @@ resource = "/"
 
 ## Install Behavior
 
-- `install.sh` installs the downloaded binary as `portal`.
+- `install.sh` installs the downloaded binary as `portal` and adds the install
+  directory to the user's shell profile when it is not already on `PATH`.
 - `install.ps1` installs `portal.exe` for the current Windows user and updates
   the user `PATH`.
 - The installer does not write a config file.
@@ -429,8 +430,8 @@ resource = "/"
   are dropped from the active set after their retry budget is exhausted.
 - Tenant TLS is provisioned automatically through the relay keyless signer. The
   SDK fetches the relay certificate chain and uses `/v1/sign` for remote signing.
-- `portal expose` enables MITM strict enforcement by default. Use
-  `--ban-mitm=false` for warning-only behavior.
+- `portal expose` logs MITM self-probe failures by default. Use `--ban-mitm`
+  when suspected TLS termination should ban the relay automatically.
 - When the local stream target is unreachable, the tunnel returns an HTTP 503
   page to browser-style clients.
 - `--tcp` requires the relay to have TCP port transport enabled and a valid

cmd/portal-tunnel/agent/manager.go

@@ -687,7 +687,7 @@ func (t *managedTunnel) runOnce(ctx context.Context) error {
 	if cfg.Discovery != nil {
 		discovery = *cfg.Discovery
 	}
-	banMITM := true
+	banMITM := false
 	if cfg.BanMITM != nil {
 		banMITM = *cfg.BanMITM
 	}

cmd/portal-tunnel/installer/install.sh

@@ -34,7 +34,40 @@ RELAY_URL="${RELAY_URL:-https://your-relay.example.com}"
 
 is_local_https_url() {
   case "$1" in
-    https://localhost|https://localhost:*|https://127.0.0.1|https://127.0.0.1:*|https://[::1]|https://[::1]:*|https://*.localhost|https://*.localhost:*)
+    https://*) ;;
+    *) return 1 ;;
+  esac
+
+  URL_HOSTPORT="${1#https://}"
+  URL_HOSTPORT="${URL_HOSTPORT%%/*}"
+  URL_HOSTPORT="${URL_HOSTPORT%%\?*}"
+  URL_HOSTPORT="${URL_HOSTPORT%%#*}"
+
+  case "$URL_HOSTPORT" in
+    \[::1\]:*)
+      URL_HOST="[::1]"
+      URL_PORT="${URL_HOSTPORT#\[::1\]:}"
+      ;;
+    \[::1\])
+      URL_HOST="[::1]"
+      URL_PORT=""
+      ;;
+    *:*)
+      URL_HOST="${URL_HOSTPORT%%:*}"
+      URL_PORT="${URL_HOSTPORT#*:}"
+      ;;
+    *)
+      URL_HOST="$URL_HOSTPORT"
+      URL_PORT=""
+      ;;
+  esac
+
+  case "$URL_PORT" in
+    *[!0-9]*) return 1 ;;
+  esac
+
+  case "$URL_HOST" in
+    localhost|127.0.0.1|\[::1\]|*.localhost)
       return 0
       ;;
   esac
@@ -137,7 +170,33 @@ echo "Installed portal to $INSTALL_PATH" >&2
 case ":$PATH:" in
   *":$INSTALL_DIR:"*) ;;
   *)
-    echo "Warning: $INSTALL_DIR is not on PATH. Add it before running 'portal expose 3000'." >&2
+    PROFILE_PATH=""
+    if [ -n "${HOME:-}" ]; then
+      SHELL_NAME="${SHELL:-}"
+      SHELL_NAME="${SHELL_NAME##*/}"
+      case "$SHELL_NAME" in
+        zsh) PROFILE_PATH="$HOME/.zshrc" ;;
+        bash) PROFILE_PATH="$HOME/.bashrc" ;;
+        *) PROFILE_PATH="$HOME/.profile" ;;
+      esac
+    fi
+
+    if [ -n "$PROFILE_PATH" ]; then
+      mkdir -p "$(dirname "$PROFILE_PATH")" 2>/dev/null || true
+      if [ ! -f "$PROFILE_PATH" ] || ! grep -F "$INSTALL_DIR" "$PROFILE_PATH" >/dev/null 2>&1; then
+        {
+          printf '\n# Added by Portal installer\n'
+          printf 'export PATH="%s:$PATH"\n' "$INSTALL_DIR"
+        } >> "$PROFILE_PATH" || PROFILE_PATH=""
+      fi
+    fi
+
+    if [ -n "$PROFILE_PATH" ]; then
+      echo "Added $INSTALL_DIR to PATH in $PROFILE_PATH" >&2
+      echo "Open a new shell or run: export PATH=\"$INSTALL_DIR:\$PATH\"" >&2
+    else
+      echo "Warning: $INSTALL_DIR is not on PATH. Add it before running 'portal expose 3000'." >&2
+    fi
     ;;
 esac
 

cmd/portal-tunnel/main.go

@@ -90,7 +90,7 @@ func runExposeCommand(args []string) error {
 	utils.StringFlag(fs, &flags.relayCSV, "relays", "", "Additional Portal relay server API URLs (comma-separated; scheme omitted defaults to https)")
 	utils.StringFlagEnv(fs, &flags.multiHopCSV, "multi-hop", "", "Ordered multi-hop relay API URLs, comma-separated", "MULTI_HOP")
 	utils.BoolFlag(fs, &flags.discovery, "discovery", true, "Include bootstrap relays and discover additional relays")
-	utils.BoolFlagEnv(fs, &flags.banMITM, "ban-mitm", true, "Ban relay when the MITM self-probe detects TLS termination", "BAN_MITM")
+	utils.BoolFlagEnv(fs, &flags.banMITM, "ban-mitm", false, "Ban relay when the MITM self-probe detects TLS termination", "BAN_MITM")
 	utils.StringFlagEnv(fs, &flags.identityPath, "identity-path", "identity.json", "identity json file path", "IDENTITY_PATH")
 	utils.StringFlagEnv(fs, &flags.identityJSON, "identity-json", "", "identity json payload; overrides --identity-path contents and is persisted there when both are set", "IDENTITY_JSON")
 	utils.StringFlag(fs, &flags.name, "name", "", "Public hostname prefix (single DNS label); auto-generated when omitted")

docs/src/routes/cli-reference/+page.md

@@ -32,7 +32,8 @@ If your relay publishes its own installer:
 curl -sSL https://portal.example.com/api/install.sh | bash
 ```
 
-The installer writes the `portal` binary only. It does not write a config file.
+The installer downloads the `portal` binary and adds it to your `PATH`. It does
+not create a config file.
 
 ## Command Overview
 
@@ -88,7 +89,7 @@ not supported.
 | `--max-active-relays` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
 | `--multi-hop` | string | | Ordered multi-hop relay API URLs, comma-separated |
 | `--multi-hop-depth` | int | `0` | Automatically select one multi-hop route with this hop count; `0` or `1` disables multi-hop |
-| `--ban-mitm` | bool | `true` | Ban relay when the MITM self-probe detects TLS termination |
+| `--ban-mitm` | bool | `false` | Ban relay when the MITM self-probe detects TLS termination |
 | `--identity-path` | string | `identity.json` | Identity JSON file path; created automatically when missing |
 | `--identity-json` | string | | Identity JSON payload; overrides `--identity-path` contents and is persisted there when both are set |
 | `--name` | string | auto | Public hostname prefix, one DNS label |
@@ -246,10 +247,10 @@ Ask Portal to select one three-hop route:
 portal expose 3000 --multi-hop-depth 3
 ```
 
-Keep MITM probe failures warning-only:
+Ban relays on MITM probe detection:
 
 ```bash
-portal expose 3000 --ban-mitm=false
+portal expose 3000 --ban-mitm
 ```
 
 ## `portal list`

docs/src/routes/concepts/+page.md

@@ -142,8 +142,8 @@ Portal runs a TLS passthrough self-probe after real stream traffic starts:
 4. Matching exporter values indicate passthrough for that sampled connection.
 5. A mismatch is treated as suspected relay-side TLS termination.
 
-By default, `portal expose` bans a relay when the self-probe detects
-termination. Use `--ban-mitm=false` for warning-only behavior.
+By default, `portal expose` logs self-probe detections without banning the relay.
+Use `--ban-mitm` when suspected TLS termination should ban the relay.
 
 The probe is a detection signal, not a mathematical proof for every future
 connection. It raises the cost of relay-side termination while preserving the

docs/src/routes/configuration/+page.md

@@ -80,7 +80,7 @@ variables:
 | `PORT` | `8081` | int | Frontend API HTTP listen port |
 | `PORTAL_API_BASE_URL` | `https://portal:4017` | string | Relay API base URL used to compose frontend-owned state |
 | `LANDING_PAGE_ENABLED` | `false` | bool | Default landing page flag when no frontend state has been saved yet |
-| `PORTAL_FRONTEND_STATE_PATH` | `""` | string | Optional JSON file path for persisted frontend-owned state; bundled Compose stores this under `./.portal-certs/frontend-state/state.json` |
+| `PORTAL_FRONTEND_STATE_PATH` | `""` | string | Optional JSON file path for persisted frontend-owned state; a Compose deployment can store this under `./.portal-certs/frontend-state/state.json` |
 | `HEADLESS_SHELL_URL` | `""` | string | Headless Chrome CDP WebSocket URL; leave empty to disable generated thumbnails |
 
 ### Cloudflare
@@ -141,7 +141,7 @@ The `portal expose` subcommand accepts the following flags. Flags that read from
 | `--multi-hop` | `MULTI_HOP` | string | | Ordered multi-hop relay API URLs, comma-separated |
 | `--multi-hop-depth` | `MULTI_HOP_DEPTH` | int | `0` | Automatically select one multi-hop route with this hop count; 0 or 1 disables multi-hop |
 | `--max-active-relays` | `MAX_ACTIVE_RELAYS` | int | `3` | Maximum auto-selected relays to keep connected; explicit relays are always included |
-| `--ban-mitm` | `BAN_MITM` | bool | `true` | Ban relay when the MITM self-probe detects TLS termination |
+| `--ban-mitm` | `BAN_MITM` | bool | `false` | Ban relay when the MITM self-probe detects TLS termination |
 
 ### Identity
 

docs/src/routes/deployment/+page.md

@@ -104,7 +104,7 @@ Open only the public ports that match the topology:
 
 | Port | Required | Purpose |
 |---|---|---|
-| `80/tcp` | optional | HTTP to HTTPS redirect in the bundled nginx example |
+| `80/tcp` | optional | HTTP to HTTPS redirect in a front nginx |
 | `443/tcp` | yes | Public nginx edge for dashboard, relay API path routing, and wildcard TCP passthrough |
 | `WIREGUARD_PORT/udp` | when `DISCOVERY=true` | Relay discovery WireGuard transport |
 | `SNI_PORT/udp` | when UDP transport is enabled | QUIC tunnel ingress |
@@ -121,33 +121,26 @@ Keep these ports private or loopback-only in the recommended topology:
 
 Certificate files are also split by owner:
 
-| Certificate | Default path in the example | Used by |
+| Certificate | Location | Used by |
 |---|---|---|
-| Browser-facing HTTPS certificate | `./certs/fullchain.pem`, `./certs/privkey.pem` | nginx public edge |
+| Browser-facing HTTPS certificate | Edge-specific certificate path | nginx instance that terminates `portal.example.com` |
 | Relay API and SNI certificate | `./.portal-certs/fullchain.pem`, `./.portal-certs/privatekey.pem` | `portal` unless managed ACME is configured |
 
-Portal-managed ACME can manage the relay certificate and relay DNS records. The bundled nginx example still expects a browser-facing certificate in `./certs`; manage that with your normal edge certificate process.
+Portal-managed ACME can manage the relay certificate and relay DNS records. If a separate front nginx only TCP-passthroughs Portal hostnames, it does not need Portal certificate material; the Portal nginx or relay edge behind it still terminates the Portal root host.
 
 ## 3. Deploy the Recommended Stack
 
-Start from the single-domain nginx example:
+Deploy the Portal services with your own Compose, systemd, or orchestration
+manifest. If another nginx already owns public `443/tcp`, use the nginx
+passthrough example only for SNI routing to the Portal nginx:
 
 ```bash
-mkdir -p portal-deploy
-cd portal-deploy
-
-cp <repo>/docs/static/examples/nginx-proxy/docker-compose.yaml ./docker-compose.yaml
 cp <repo>/docs/static/examples/nginx-proxy/nginx.conf ./nginx.conf
-cp <repo>/docs/static/examples/nginx-proxy/.env.example ./.env
-cp <repo>/docs/static/examples/nginx-proxy/deploy_portal.sh ./deploy_portal.sh
-cp <repo>/docs/static/examples/nginx-proxy/watch_and_deploy.sh ./watch_and_deploy.sh
-cp <repo>/docs/static/examples/nginx-proxy/nginx_deploy.sh ./nginx_deploy.sh
-chmod +x deploy_portal.sh watch_and_deploy.sh nginx_deploy.sh
 ```
 
-Replace every `portal.example.com` in `nginx.conf` and `.env`.
-
-For deployments with multiple additional services behind the same edge nginx, use `docs/static/examples/nginx-proxy-multi-service` instead. The same Portal routing rules apply.
+Replace `portal.example.com` and the `portal_nginx` upstream in `nginx.conf`.
+The example does not deploy Portal containers, write Portal `.env` files, or
+reload Portal services.
 
 ### Configure `.env`
 
@@ -176,7 +169,10 @@ TRUSTED_PROXY_CIDRS=
 LANDING_PAGE_ENABLED=false
 ```
 
-`API_PORT` defaults to `4017`. If you change it, update the relay `proxy_pass` targets in the bundled `nginx.conf` to the same port. Keep `SNI_PORT=443` because this is the public SNI port advertised to tunnel clients. The single-domain Compose example maps the relay container's SNI listener to `127.0.0.1:4443` on the host so nginx can own public `443/tcp` and still pass wildcard TCP traffic to the relay. Do not open `4443/tcp` publicly; it is only a host-local upstream in that example.
+`API_PORT` defaults to `4017`. Keep `SNI_PORT=443` because this is the public
+SNI port advertised to tunnel clients. If a separate nginx sits in front of
+Portal's own nginx, it should TCP-passthrough `portal.example.com` and
+`*.portal.example.com` instead of proxying Portal API paths itself.
 
 If the relay joins public discovery, set `BOOTSTRAPS` to at least one reachable relay URL and keep `WIREGUARD_PORT/udp` open.
 
@@ -361,10 +357,36 @@ It owns:
 - `/ui/policy/*` composition, while relay-enforced policy changes are still forwarded to `portal`.
 - `/ui/service/status`, derived from relay state for quick-start UI checks.
 - `/ui/thumbnail/<hostname>`, when optional screenshot generation is enabled.
-- The landing-page flag persisted at `PORTAL_FRONTEND_STATE_PATH`; the bundled Compose files store it under `./.portal-certs/frontend-state/state.json`.
+- The landing-page flag persisted at `PORTAL_FRONTEND_STATE_PATH`; a Compose deployment can store it under `./.portal-certs/frontend-state/state.json`.
 
 The Go relay remains the owner of authentication, policy enforcement, lease state, tunnel ingress, install scripts, discovery, and x402 facilitator paths.
 
+### Custom Frontend
+
+To attach your own dashboard frontend, replace only the `portal-frontend`
+service image. Keep the service name `portal-frontend` and serve plain HTTP on
+port `8080` so the existing nginx route for SPA paths can continue to point at
+`portal-frontend:8080`.
+
+The custom frontend should use same-origin browser requests and leave these
+paths owned by the Portal services:
+
+| Path | Owner |
+|---|---|
+| `/ui/*` | `portal-api` presentation API |
+| `/api/*` | `portal` relay API |
+| `/sdk/*`, `/discovery*`, `/v1/sign` | `portal` relay protocols |
+| `*.portal.example.com` | `portal` SNI listener |
+
+```bash
+cp <repo>/docs/static/examples/custom-frontend/docker-compose.override.yaml ./docker-compose.override.yaml
+docker compose up -d portal-frontend
+```
+
+If the automated release updater should also track your custom frontend image,
+set `IMAGES` to include that image in addition to the Portal release-track
+images.
+
 ### Thumbnail Screenshots
 
 Generated thumbnails are optional and disabled by default. Without this feature, apps without a custom thumbnail simply use the default card background.
@@ -384,33 +406,30 @@ thumbnail captured hostname=myapp.portal.example.com size=36209
 
 Disable the feature by removing `HEADLESS_SHELL_URL` and stopping the `headless-shell` container.
 
-## 7. Auto-Update
+## 7. Automated Release Updates
 
 Auto-update should follow a published release tag, not `latest`. The `latest`
 image tag tracks default-branch image builds, so using it can update production
 on a `main` merge before the GitHub Release and tunnel binaries are published.
 
-The bundled Compose examples use the v2 release track directly. Auto-update must
-pull all production images from that same release track:
+Production deployments should follow the v2 release track directly.
+Auto-update must pull all production images from that same release track:
 
 - `ghcr.io/gosuda/portal:2`
 - `ghcr.io/gosuda/portal-frontend:2`
 - `ghcr.io/gosuda/portal-api:2`
 
-The bundled `deploy_portal.sh` pulls all Portal images together and reloads nginx after the services are updated:
+The auto-update example watches those image digests, pulls the changed official
+images, recreates the Portal services, and reloads the Portal nginx:
 
 ```bash
-#!/bin/bash
-set -e
-
-docker compose pull portal portal-frontend portal-api
-docker compose up -d portal portal-frontend portal-api
-bash nginx_deploy.sh
+cp <repo>/docs/static/examples/auto-update/watch_and_deploy.sh ./watch_and_deploy.sh
+chmod +x watch_and_deploy.sh
 ```
 
-The bundled `watch_and_deploy.sh` reads the Portal images from Docker Compose,
-polls their remote digests, and runs the deploy script when any watched release
-tag changes.
+The example watcher reads Portal images from Docker Compose when available,
+falls back to the v2 image set, and updates `portal`, `portal-frontend`, and
+`portal-api` when any watched release tag changes.
 
 Systemd example:
 
@@ -430,7 +449,6 @@ ExecStart=/bin/bash <path-to-project>/watch_and_deploy.sh
 Restart=always
 RestartSec=10
 Environment=INTERVAL=60
-Environment=DEPLOY_SCRIPT=deploy_portal.sh
 
 [Install]
 WantedBy=multi-user.target
@@ -461,7 +479,7 @@ Logs like `"\x16\x03\x01..." 400` mean a client sent HTTPS to the plain HTTP `po
 
 ### Relay Logs Show `tls: unknown certificate`
 
-This usually means a browser or proxy hit the relay API certificate directly instead of the public nginx certificate, or an upstream proxy tried to verify the relay's internal certificate. In the bundled nginx example, public browsers verify nginx's certificate, while nginx proxies to the relay API over internal HTTPS.
+This usually means a browser or proxy hit the relay API certificate directly instead of the public nginx certificate, or an upstream proxy tried to verify the relay's internal certificate. In the recommended topology, public browsers verify the Portal HTTPS edge certificate, while the edge proxies to the relay API over internal HTTPS.
 
 ### Root Host Works but Wildcard Apps Fail
 

docs/src/routes/portal-agent/+page.md

@@ -170,7 +170,7 @@ Common fields:
 | `tcp` | Dedicated raw TCP port setting |
 | `multi_hop` | Explicit ordered multi-hop relay URLs |
 | `multi_hop_depth` | Automatically choose one multi-hop route with this depth |
-| `ban_mitm` | Ban relays when the TLS self-probe detects termination |
+| `ban_mitm` | Ban relays when the TLS self-probe detects termination; defaults to warning-only |
 | `description`, `tags`, `owner`, `thumbnail`, `hide` | Public relay metadata |
 
 Constraints match `portal expose`: