@lamalibre/create-portlama 1.0.20 → 1.0.22

package/README.md

@@ -5,7 +5,7 @@ One-command setup for secure reverse tunnels with a management dashboard.
 ## Quick Start
 
 ```bash
-ssh root@<droplet-ip> "npx @lamalibre/create-portlama"
+ssh root@<droplet-ip> "apt install -y npm && npx @lamalibre/create-portlama"
 ```
 
 The installer runs unattended on a fresh Ubuntu 24.04 droplet and provisions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/create-portlama",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "One-command setup for secure reverse tunnels with a management dashboard",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",

package/src/index.js

@@ -304,7 +304,7 @@ ${chalk.cyan.bold('│')}  This will install Portlama on this machine.
 ${chalk.cyan.bold('│')}                                                             ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}  The following changes will be made:                         ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}                                                             ${chalk.cyan.bold('│')}
-${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Reset UFW firewall (allow ports 22, 443, 9292 only)    ${chalk.cyan.bold('│')}
+${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Reset UFW firewall (allow ports 22, 80, 443, 9292)     ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Harden SSH (disable password authentication)           ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Install fail2ban, Node.js 20, nginx, certbot           ${chalk.cyan.bold('│')}
 ${chalk.cyan.bold('│')}    ${chalk.yellow('•')} Generate mTLS certificates for browser access          ${chalk.cyan.bold('│')}

package/src/tasks/mtls.js

@@ -163,9 +163,8 @@ export function mtlsTasks(ctx, task) {
           `${pkiDir}/client.crt`,
           '-certfile',
           `${pkiDir}/ca.crt`,
-          '-passout',
-          `pass:${password}`,
-        ]);
+          '-passout', 'stdin',
+        ], { input: password });
 
         // Save password to file (no trailing newline)
         await writeFile(`${pkiDir}/.p12-password`, password, { mode: 0o600 });

package/vendor/panel-client/dist/docs/00-introduction/how-it-works.md

@@ -50,6 +50,7 @@ Portlama has three phases of life: installation, onboarding, and daily operation
 You SSH into a fresh Ubuntu droplet and run one command:
 
 ```bash
+apt install -y npm
 npx @lamalibre/create-portlama
 ```
 
@@ -284,7 +285,7 @@ Onboarding Wizard
     ├── Write domain-based nginx vhosts
     ├── Create systemd service units for Chisel + Authelia
     ├── Start all services
-    └── Update panel.json → onboarding status: COMPLETE
+    └── Update panel.json → onboarding status: COMPLETED
 ```
 
 After provisioning, onboarding endpoints return `410 Gone` and management endpoints become available.
@@ -339,7 +340,7 @@ Layer 7: Least-privilege sudoers
 The panel operates in distinct states:
 
 ```
-FRESH ──────→ DOMAIN_SET ──────→ DNS_VERIFIED ──────→ PROVISIONING ──────→ COMPLETE
+FRESH ──────→ DOMAIN_SET ──────→ DNS_READY ──────→ PROVISIONING ──────→ COMPLETED
   │               │                   │                    │                  │
   │  Onboarding   │  Onboarding       │  Onboarding        │  Onboarding      │ Management
   │  endpoints    │  endpoints        │  endpoints         │  endpoints       │ endpoints

package/vendor/panel-client/dist/docs/00-introduction/quickstart.md

@@ -56,6 +56,7 @@ ssh root@203.0.113.42
 Once connected:
 
 ```bash
+apt install -y npm
 npx @lamalibre/create-portlama
 ```
 
@@ -269,12 +270,12 @@ Alternatively, you can run the Chisel client manually on your Mac:
 
 ```bash
 chisel client \
-  --auth user:password \
-  wss://example.com \
-  R:8001:localhost:8001
+  --tls-skip-verify \
+  https://tunnel.example.com:443 \
+  R:127.0.0.1:8001:127.0.0.1:8001
 ```
 
-The `R:8001:localhost:8001` part means: "Reverse-forward port 8001 on the server to port 8001 on my Mac."
+The `R:127.0.0.1:8001:127.0.0.1:8001` part means: "Reverse-forward port 8001 on the server's localhost to port 8001 on my Mac."
 
 ---
 
@@ -335,6 +336,7 @@ npx @lamalibre/create-portlama [flags]
 | `--yes`, `-y` | Skip the confirmation prompt |
 | `--skip-harden` | Skip OS hardening (swap, UFW, fail2ban, SSH) |
 | `--dev` | Allow private/non-routable IP addresses |
+| `--force-full` | Run full installation even on existing installs |
 | `--uninstall` | Print manual removal guide and exit |
 
 The `--dev` flag is useful for testing on local VMs that do not have public IP addresses.
@@ -364,12 +366,12 @@ For local development without a VPS:
 cd packages/panel-server
 CONFIG_FILE=../../dev/panel.json NODE_ENV=development node src/index.js
 
-# Terminal 2: Start panel frontend (Vite dev server, proxies /api to :9292)
+# Terminal 2: Start panel frontend (Vite dev server, proxies /api to :3100)
 cd packages/panel-client
 npx vite
 ```
 
-In development mode (`NODE_ENV=development`), the panel server skips mTLS client certificate verification, so you can access it without importing a certificate.
+In development mode (`NODE_ENV=development` or `NODE_ENV` unset), the panel server skips mTLS client certificate verification, so you can access it without importing a certificate.
 
 ### Troubleshooting
 
@@ -414,6 +416,7 @@ In development mode (`NODE_ENV=development`), the panel server skips mTLS client
 # 1. Create droplet (Ubuntu 24.04, 512MB, $4/mo)
 # 2. SSH in and install
 ssh root@203.0.113.42
+apt install -y npm
 npx @lamalibre/create-portlama
 
 # 3. Download cert (from your local machine)

package/vendor/panel-client/dist/docs/00-introduction/what-is-portlama.md

@@ -46,13 +46,15 @@ Portlama solves the problem of exposing local services to the internet securely.
 
 ## For Developers
 
-Portlama is a monorepo with three packages:
+Portlama is a monorepo with five packages:
 
 | Package | Technology | Purpose |
 |---------|------------|---------|
 | `create-portlama` | Node.js ESM, Listr2, execa | Zero-prompt installer CLI |
 | `panel-server` | Fastify 5, Node.js ESM | REST API + WebSocket backend |
 | `panel-client` | React 18, Vite, Tailwind | Management UI (SPA) |
+| `portlama-agent` | Node.js ESM | Mac tunnel agent CLI |
+| `portlama-desktop` | Tauri v2 | Desktop agent (WIP) |
 
 **Architecture summary:**
 
@@ -86,4 +88,4 @@ The installer (`npx @lamalibre/create-portlama`) is completely non-interactive
 | **State storage** | JSON files (no database) |
 | **RAM usage** | ~245MB total (all services) |
 | **npm package** | `@lamalibre/create-portlama` |
-| **License** | MIT |
+| **License** | Polyform Noncommercial 1.0.0 |

package/vendor/panel-client/dist/docs/01-concepts/authentication.md

@@ -20,34 +20,37 @@ These two systems are completely independent. Admin certificate holders do not a
 
 | Person | Accesses | Authentication method |
 |--------|----------|----------------------|
-| You (the admin) | Management panel at `panel.example.com` or `https://IP:9292` | Client certificate (mTLS) |
+| You (the admin) | Management panel at `https://<IP>:9292` | Client certificate (mTLS) |
 | Your users | Tunneled apps at `myapp.example.com` | Username + password + TOTP code |
 
 ### Managing users
 
 From the Users page in the management panel, you can:
 
-- **Create users** — set a username and password; Portlama generates a TOTP secret
+- **Create users** — set a username, display name, email, and password
 - **Delete users** — remove a user (you cannot delete the last user)
-- **Reset TOTP** — generate a new TOTP secret if a user loses their authenticator
+- **Reset TOTP** — generate a new TOTP secret if a user loses their authenticator (separate step via `POST /api/users/:username/reset-totp`)
 - **Update password** — change a user's password
 
 ### Creating a user
 
 1. Navigate to the Users page in the management panel
 2. Click "Add User"
-3. Enter a username and password
-4. Portlama creates the user and generates a TOTP secret
-5. A QR code is displayed — the user scans this with their authenticator app
-6. The user is now ready to log in
+3. Enter a username, display name, email, and password
+4. Portlama creates the user in `users.yml` and restarts Authelia
+5. Share the credentials with the user — they enroll in TOTP on first login
 
 ### TOTP enrollment flow
 
-When you create a user, Portlama generates a TOTP secret and displays it as both a QR code and a text string. The user opens their authenticator app (Google Authenticator, Authy, 1Password, etc.) and scans the QR code. From that point, the app generates a fresh 6-digit code every 30 seconds.
+TOTP enrollment is a separate step from user creation. There are two paths:
+
+**First-login enrollment:** When a new user visits a Portlama-protected app for the first time, Authelia presents a QR code during their initial login. The user scans it with their authenticator app to complete enrollment.
+
+**Admin-initiated reset:** If a user loses their authenticator, the admin clicks "Reset TOTP" on the Users page, which calls `POST /api/users/:username/reset-totp`. This writes the new TOTP secret to Authelia's SQLite database via the `authelia storage user totp generate` CLI command. A QR code is displayed for the user to scan.
 
 ```
-Admin creates user → Portlama generates TOTP secret
-                   → QR code displayed in panel
+Admin creates user → User visits protected app
+                   → Authelia prompts for TOTP enrollment on first login
                    → User scans QR code with authenticator app
                    → Authenticator generates 6-digit codes every 30 seconds
 ```
@@ -118,14 +121,15 @@ The full configuration is written during onboarding provisioning (`packages/pane
 
 ```yaml
 server:
-  host: 127.0.0.1
-  port: 9091
+  address: 'tcp://127.0.0.1:9091/'
 
 log:
   level: info
   file_path: /var/log/authelia/authelia.log
 
-jwt_secret: <random-64-byte-hex>
+identity_validation:
+  reset_password:
+    jwt_secret: <random-64-byte-hex>
 
 authentication_backend:
   file:
@@ -136,15 +140,23 @@ authentication_backend:
         cost: 12
 
 access_control:
-  default_policy: one_factor
+  default_policy: two_factor
 
 session:
   name: portlama_session
   secret: <random-64-byte-hex>
-  domain: example.com
+  cookies:
+    - domain: example.com
+      authelia_url: https://auth.example.com
+      default_redirection_url: https://example.com
   expiration: 12h
   inactivity: 2h
 
+regulation:
+  max_retries: 5
+  find_time: 2m
+  ban_time: 5m
+
 storage:
   encryption_key: <random-64-byte-hex>
   local:
@@ -162,9 +174,9 @@ totp:
 
 Key configuration choices:
 
-- **`host: 127.0.0.1`** — binds to localhost only; nginx handles public access
-- **`default_policy: one_factor`** — Authelia uses "one_factor" for TOTP-based authentication
-- **`session.domain`** — the base domain, so session cookies work across subdomains
+- **`server.address: 'tcp://127.0.0.1:9091/'`** — binds to localhost only; nginx handles public access
+- **`default_policy: two_factor`** — requires password + TOTP for all authenticated users
+- **`session.cookies`** — array format (Authelia v4.38+) specifying the domain and Authelia URL for session cookies
 - **`notifier.filesystem`** — writes notifications to a file instead of sending email (suitable for small-scale use)
 - **`totp.period: 30`** — standard 30-second TOTP window
 
@@ -394,7 +406,7 @@ sudo systemctl restart authelia
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/users` | List all users (without password hashes) |
-| POST | `/api/users` | Create user with password and TOTP |
+| POST | `/api/users` | Create user with username, displayname, email, and password |
 | PUT | `/api/users/:username` | Update user password or display name |
 | DELETE | `/api/users/:username` | Delete user (not the last one) |
 | POST | `/api/users/:username/reset-totp` | Generate new TOTP secret |

package/vendor/panel-client/dist/docs/01-concepts/dns-and-domains.md

@@ -128,7 +128,7 @@ When creating a tunnel, the subdomain must follow DNS naming rules:
 - Maximum 63 characters
 - Must be unique (no two tunnels can use the same subdomain)
 
-Reserved subdomains that cannot be used for tunnels:
+Reserved subdomains that cannot be used for tunnels or static sites:
 
 | Subdomain | Reason |
 |-----------|--------|
@@ -136,6 +136,9 @@ Reserved subdomains that cannot be used for tunnels:
 | `auth` | Authelia portal |
 | `tunnel` | Chisel WebSocket endpoint |
 | `www` | Conventionally the main site |
+| `mail` | Email subdomain |
+| `ftp` | File transfer subdomain |
+| `api` | API subdomain |
 
 ### DNS and TLS certificate issuance
 
@@ -271,6 +274,10 @@ Once set during onboarding, the domain is used throughout the system for constru
 | `panel` | Admin panel |
 | `auth` | Authelia login portal |
 | `tunnel` | Chisel WebSocket endpoint |
+| `www` | Conventionally the main site |
+| `mail` | Email subdomain |
+| `ftp` | File transfer subdomain |
+| `api` | API subdomain |
 
 ### Subdomain naming rules
 

package/vendor/panel-client/dist/docs/01-concepts/mtls.md

@@ -224,6 +224,11 @@ This snippet is included in every nginx vhost that should require mTLS. The `ssl
 The panel vhost includes this snippet:
 
 ```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
 server {
     listen 9292 ssl;
     server_name _;
@@ -235,8 +240,42 @@ server {
 
     # Show help page when client cert is missing
     error_page 495 496 /cert-help.html;
-
-    # ... proxy to panel-server
+    location = /cert-help.html {
+        root /opt/portlama/panel-client;
+        internal;
+    }
+
+    # Proxy to panel-server
+    location / {
+        proxy_pass http://127.0.0.1:3100;
+
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # API paths with WebSocket upgrade support
+    location /api {
+        proxy_pass http://127.0.0.1:3100;
+        proxy_http_version 1.1;
+
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
 }
 ```
 
@@ -253,15 +292,16 @@ After TLS negotiation succeeds, nginx forwards client certificate information to
 ```nginx
 proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
 proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
 ```
 
-The panel server's mTLS middleware checks `X-SSL-Client-Verify`:
+The panel server's mTLS middleware checks these headers in order:
 
-- `SUCCESS` — valid client certificate presented
-- `FAILED` — certificate presented but invalid
-- `NONE` — no certificate presented
+1. **`X-SSL-Client-Verify`** — must be `SUCCESS` (valid client cert); any other value (`FAILED`, `NONE`) results in a 403 Forbidden response.
+2. **`X-SSL-Client-Serial`** — checked against the revocation list (`revoked.json`); if the serial is revoked, the request is rejected with 403.
+3. **`X-SSL-Client-DN`** — the CN is parsed to determine the role. `CN=admin` grants full access; `CN=agent:<label>` grants capability-based access with permissions looked up from the agent registry.
 
-In production, any value other than `SUCCESS` results in a 403 Forbidden response. In development (`NODE_ENV=development`), the check is skipped.
+In development (`NODE_ENV=development`), all checks are skipped.
 
 ### Certificate rotation
 

package/vendor/panel-client/dist/docs/01-concepts/nginx-reverse-proxy.md

@@ -77,6 +77,11 @@ All Portlama vhost files are prefixed with `portlama-` to distinguish them from
 This vhost is created during installation and is the only vhost that exists before onboarding:
 
 ```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
 server {
     listen 9292 ssl;
     server_name _;
@@ -99,27 +104,41 @@ server {
         internal;
     }
 
-    # Client cert headers forwarded to backend
-    proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
-    proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
-
-    # Standard proxy headers
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-
-    # Static files and API
+    # Proxy to panel-server
     location / {
         proxy_pass http://127.0.0.1:3100;
+
+        # Client cert headers — set from nginx TLS variables, never passed through from client
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
     }
 
-    # WebSocket support for API paths
+    # API paths with WebSocket upgrade support
     location /api {
         proxy_pass http://127.0.0.1:3100;
         proxy_http_version 1.1;
+
+        # Client cert headers — set from nginx TLS variables, never passed through from client
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket: only upgrade when client requests it
         proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+        proxy_set_header Connection $connection_upgrade;
     }
 }
 ```
@@ -165,30 +184,45 @@ server {
     ssl_ciphers HIGH:!aNULL:!MD5;
     ssl_prefer_server_ciphers on;
 
-    # Client cert headers
-    proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
-    proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
-
-    # Standard proxy headers
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-
     location / {
         proxy_pass http://127.0.0.1:3100;
+
+        # Client cert headers — set from nginx TLS variables, never passed through from client
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
     }
 
+    # API paths with WebSocket upgrade support
     location /api {
         proxy_pass http://127.0.0.1:3100;
         proxy_http_version 1.1;
+
+        # Client cert headers — set from nginx TLS variables, never passed through from client
+        proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+        proxy_set_header X-SSL-Client-DN $ssl_client_s_dn;
+        proxy_set_header X-SSL-Client-Serial $ssl_client_serial;
+
+        # Standard proxy headers
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket: only upgrade when client requests it
         proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
+        proxy_set_header Connection $connection_upgrade;
     }
 }
 ```
 
-The difference from the IP vhost: port 443 instead of 9292, Let's Encrypt certificates instead of self-signed, and a specific `server_name` instead of catch-all.
+The difference from the IP vhost: port 443 instead of 9292, Let's Encrypt certificates instead of self-signed, and a specific `server_name` instead of catch-all. Requires the same `map $http_upgrade $connection_upgrade` block to be present.
 
 ### App tunnel vhost with Authelia
 
@@ -211,26 +245,31 @@ server {
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
 
-    # Authelia forward authentication
-    location /authelia {
+    # Authelia forward authentication (AuthRequest implementation for nginx)
+    location /internal/authelia/authz {
         internal;
-        proxy_pass http://127.0.0.1:9091/api/verify?rd=https://auth.example.com/;
+
+        proxy_pass http://127.0.0.1:9091/api/authz/auth-request;
         proxy_pass_request_body off;
+
         proxy_set_header Content-Length "";
+        proxy_set_header Connection "";
+        proxy_set_header X-Original-Method $request_method;
         proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
-        proxy_set_header X-Forwarded-Method $request_method;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        proxy_set_header X-Forwarded-Host $http_host;
-        proxy_set_header X-Forwarded-Uri $request_uri;
         proxy_set_header X-Forwarded-For $remote_addr;
+
+        proxy_http_version 1.1;
+        proxy_buffers 4 32k;
+        proxy_next_upstream error timeout invalid_header http_500 http_502 http_503;
     }
 
     location / {
-        auth_request /authelia;
+        auth_request /internal/authelia/authz;
         auth_request_set $user $upstream_http_remote_user;
         auth_request_set $groups $upstream_http_remote_groups;
         auth_request_set $name $upstream_http_remote_name;
         auth_request_set $email $upstream_http_remote_email;
+        auth_request_set $redirection_url $upstream_http_location;
 
         proxy_set_header Remote-User $user;
         proxy_set_header Remote-Groups $groups;
@@ -248,11 +287,12 @@ server {
         proxy_send_timeout 86400s;
     }
 
-    error_page 401 =302 https://auth.example.com/?rd=$scheme://$http_host$request_uri;
+    # Redirect unauthenticated requests to Authelia login portal
+    error_page 401 =302 $redirection_url;
 }
 ```
 
-The `location /authelia` block is marked `internal`, meaning it cannot be accessed directly by clients. It is only triggered by the `auth_request` directive in the main `location /` block.
+The `location /internal/authelia/authz` block is marked `internal`, meaning it cannot be accessed directly by clients. It is only triggered by the `auth_request` directive in the main `location /` block.
 
 ### Tunnel (Chisel) vhost
 
@@ -290,12 +330,21 @@ WebSocket connections start as HTTP and then "upgrade" to the WebSocket protocol
 ```nginx
 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
-proxy_set_header Connection "upgrade";
+proxy_set_header Connection $connection_upgrade;
+```
+
+The `$connection_upgrade` variable comes from a `map` block defined at the top of the IP panel vhost:
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
 ```
 
 - **`proxy_http_version 1.1`** — WebSocket requires HTTP/1.1 (not 1.0)
 - **`Upgrade`** — forwards the client's upgrade request to the backend
-- **`Connection "upgrade"`** — tells the backend to switch protocols
+- **`Connection $connection_upgrade`** — set to `upgrade` when the client requests a WebSocket upgrade, or `close` for regular HTTP requests. This avoids keeping non-WebSocket connections open unnecessarily
 
 These headers appear in three places: the panel vhost (for live log streaming), the tunnel vhost (for Chisel), and app vhosts (for apps that use WebSockets).
 
@@ -310,12 +359,13 @@ Every vhost sets standard proxy headers so backend services know about the origi
 | `X-Forwarded-For` | `$proxy_add_x_forwarded_for` | Chain of proxy IPs |
 | `X-Forwarded-Proto` | `$scheme` | Original protocol (http or https) |
 
-For mTLS vhosts, two additional headers are set:
+For mTLS vhosts, three additional headers are set:
 
 | Header | nginx variable | Purpose |
 |--------|---------------|---------|
 | `X-SSL-Client-Verify` | `$ssl_client_verify` | `SUCCESS`, `FAILED`, or `NONE` |
 | `X-SSL-Client-DN` | `$ssl_client_s_dn` | Client certificate subject DN |
+| `X-SSL-Client-Serial` | `$ssl_client_serial` | Client certificate serial number |
 
 ### Safe write-with-rollback
 
@@ -472,7 +522,7 @@ ls /etc/nginx/sites-enabled/portlama-*
 | Directive | Purpose |
 |-----------|---------|
 | `ssl_verify_client on` | Require client certificate (mTLS) |
-| `auth_request /authelia` | Delegate auth to Authelia subrequest |
+| `auth_request /internal/authelia/authz` | Delegate auth to Authelia subrequest |
 | `proxy_http_version 1.1` | Required for WebSocket upgrade |
 | `proxy_read_timeout 86400s` | Keep WebSocket connections alive (24h) |
 | `error_page 495 496` | Handle missing/invalid client cert |