@lamalibre/create-portlama 1.0.33 → 1.0.34

package/package.json

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

package/src/lib/service-config.js

@@ -74,31 +74,36 @@ portlama ALL=(root) NOPASSWD: /usr/bin/systemctl restart portlama-panel
 # --- nginx config test ---
 portlama ALL=(root) NOPASSWD: /usr/sbin/nginx -t
 
-# --- certbot: restrict certonly to --nginx (code always passes --non-interactive) ---
-# Note: trailing wildcard allows additional flags; trust boundary is @lamalibre/ scope
-portlama ALL=(root) NOPASSWD: /usr/bin/certbot certonly --nginx *
-portlama ALL=(root) NOPASSWD: /usr/bin/certbot renew
-portlama ALL=(root) NOPASSWD: /usr/bin/certbot renew --cert-name *
-portlama ALL=(root) NOPASSWD: /usr/bin/certbot certificates
-
-# --- openssl: restricted to PKI and Let's Encrypt paths ---
-portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -in /etc/portlama/pki/* *
-portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -in /etc/letsencrypt/live/* *
+# --- certbot: restrict to exact flag patterns used by the application ---
+portlama ALL=(root) NOPASSWD: /usr/bin/certbot certonly --nginx -d * --email * --agree-tos --non-interactive
+portlama ALL=(root) NOPASSWD: /usr/bin/certbot renew --non-interactive
+portlama ALL=(root) NOPASSWD: /usr/bin/certbot renew --cert-name * --non-interactive
+portlama ALL=(root) NOPASSWD: /usr/bin/certbot renew --cert-name * --force-renewal --non-interactive
+portlama ALL=(root) NOPASSWD: /usr/bin/certbot certificates --non-interactive
+
+# --- openssl: read-only operations (no trailing wildcards) ---
+portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -in /etc/portlama/pki/* -serial -noout
+portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -in /etc/portlama/pki/* -enddate -noout
+portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -checkend 86400 -noout -in /etc/letsencrypt/live/*
+portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -enddate -noout -in /etc/letsencrypt/live/*
+portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -in /etc/letsencrypt/live/* -enddate -noout
+# --- openssl: PKI generation and signing (trailing * for variable -subj CN) ---
+# Trust boundary: only @lamalibre/ scoped code runs as portlama user
 portlama ALL=(root) NOPASSWD: /usr/bin/openssl x509 -req -in /etc/portlama/pki/* *
 portlama ALL=(root) NOPASSWD: /usr/bin/openssl genrsa -out /etc/portlama/pki/* *
 portlama ALL=(root) NOPASSWD: /usr/bin/openssl req -new -key /etc/portlama/pki/* *
 portlama ALL=(root) NOPASSWD: /usr/bin/openssl pkcs12 -export -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1 -out /etc/portlama/pki/*
 
-# --- mv: restrict source to /tmp/ or known config paths ---
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /var/www/portlama/*
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/nginx/sites-available/*
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/systemd/system/chisel.service
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/systemd/system/authelia.service
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/systemd/system/portlama-panel.service
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/portlama/pki/*
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /usr/local/bin/chisel
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /usr/local/bin/authelia
-portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/* /etc/authelia/*
+# --- mv: restrict source to known temp-file prefixes (no bare /tmp/*) ---
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/site-index-* /var/www/portlama/*
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/site-upload-* /var/www/portlama/*
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/invite-page-* /var/www/portlama/*
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/nginx-* /etc/nginx/sites-available/*
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/chisel-service-* /etc/systemd/system/chisel.service
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/authelia-service-* /etc/systemd/system/authelia.service
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/chisel-* /usr/local/bin/chisel
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/authelia-* /usr/local/bin/authelia
+portlama ALL=(root) NOPASSWD: /usr/bin/mv /tmp/portlama-authelia-* /etc/authelia/*
 portlama ALL=(root) NOPASSWD: /usr/bin/mv /etc/portlama/pki/*.new /etc/portlama/pki/*
 portlama ALL=(root) NOPASSWD: /usr/bin/mv /etc/nginx/sites-available/*.bak /etc/nginx/sites-available/*
 

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

@@ -93,13 +93,13 @@ Source Agent                    Panel                     Target Agent
      │                           │  POST /tickets/validate    │
      │                           │  {ticketId}                │
      │                           │◀───────────────────────────│
-     │                           │ ── timing-safe compare     │
+     │                           │ ── HMAC timing-safe compare │
      │                           │ ── mark as used            │
      │                           │  { valid, transport }      │
      │                           │───────────────────────────▶│
      │                           │                            │
      │                           │  POST /tickets/sessions    │
-     │                           │  {ticketId, sessionId}     │
+     │                           │  {ticketId}                │
      │                           │◀───────────────────────────│
      │                           │  { session }               │
      │                           │───────────────────────────▶│
@@ -119,10 +119,16 @@ Source Agent                    Panel                     Target Agent
 2. **Multi-stage validation** — panel checks: source has capability, target has capability, source owns instance, instance is active (not stale/dead), source is not targeting itself, target is assigned to instance
 3. **Issuance** — 256-bit random ticket ID (`crypto.randomBytes(32)`), 30-second expiry
 4. **Delivery** — ticket appears in target's inbox (`GET /api/tickets/inbox`)
-5. **Validation** — target calls `POST /api/tickets/validate` with the ticket ID; timing-safe comparison marks it as used atomically
-6. **Session** — target creates a session (`POST /api/tickets/sessions`); panel tracks with heartbeat re-validation
+5. **Validation** — target calls `POST /api/tickets/validate` with the ticket ID; HMAC-based timing-safe comparison marks it as used atomically
+6. **Session** — target reports session creation (`POST /api/tickets/sessions`) with only the ticket ID; the panel generates the session ID server-side (`crypto.randomBytes(16)`) and sets all timestamps server-side, then tracks with heartbeat re-validation
 7. **Cleanup** — tickets expire after 1 hour (removed from store); dead sessions cleaned after 24 hours
 
+### Server-Generated Session IDs and Timestamps
+
+Session IDs are always generated server-side via `crypto.randomBytes(16).toString('hex')`. The client sends only the `ticketId` when creating a session; the server generates and returns the session ID. This guarantees uniqueness without trusting client input.
+
+Similarly, `lastActivityAt` timestamps are always set server-side. The client cannot influence when a session was last active; heartbeats update the timestamp on the server when they arrive, not when the client claims to have sent them.
+
 ### Session Heartbeat Re-validation
 
 Every heartbeat checks six conditions. If any fails, the session is terminated:
@@ -144,7 +150,19 @@ Security-sensitive endpoints use generic error responses:
 - `POST /api/tickets/validate` — returns 401 "Invalid ticket" for all failures (expired, used, wrong target, not found)
 - `DELETE /api/tickets/instances/:id` — returns 404 for unauthorized deregistration attempts
 
-Ticket validation uses `crypto.timingSafeEqual` to prevent timing attacks.
+Ticket validation uses HMAC-based timing-safe comparison to prevent timing attacks. Both the submitted and stored ticket IDs are HMAC-SHA256'd with a per-process random key before being compared with `crypto.timingSafeEqual`. The HMAC step produces fixed-length digests, eliminating the length-leak that raw `timingSafeEqual` would expose if inputs differed in length, and the per-process key prevents pre-computation attacks if an attacker gains read access to the source code.
+
+### Host Validation (SSRF Prevention)
+
+When an instance registers with a `direct` transport strategy, the `host` field is validated against a deny list of private, reserved, and metadata IP ranges. The following are rejected:
+
+- Loopback: `localhost`, `127.0.0.1`, `::1`
+- Private IPv4: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
+- Link-local: `169.254.0.0/16`
+- Cloud metadata endpoints: `169.254.169.254`, `metadata.google.internal`
+- Zero network: `0.0.0.0/8`
+
+This prevents agents from using the ticket system to probe internal services on the panel's network (SSRF).
 
 ### Capability Integration
 
@@ -184,6 +202,7 @@ The integration flow:
         "port": 9000,
         "protocol": "wss"
       },
+      "hooks": {},              // Reserved for future hook configuration
       "installedAt": "2026-03-26T10:00:00.000Z"
     }
   ],
@@ -201,7 +220,7 @@ The integration flow:
   "assignments": [
     {
       "agentLabel": "linux-agent",
-      "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4",
+      "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "assignedAt": "2026-03-26T10:10:00.000Z",
       "assignedBy": "admin"
     }
@@ -217,7 +236,7 @@ The integration flow:
     {
       "id": "64-hex-char-ticket-id",
       "scope": "shell:connect",
-      "instanceId": "a7f3b2c9d1e2f3a4",
+      "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "source": "macbook-pro",
       "target": "linux-agent",
       "createdAt": "2026-03-26T10:15:00.000Z",
@@ -230,10 +249,10 @@ The integration flow:
   ],
   "sessions": [
     {
-      "sessionId": "session-id",
+      "sessionId": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
       "ticketId": "64-hex-char-ticket-id",
       "scope": "shell:connect",
-      "instanceId": "a7f3b2c9d1e2f3a4",
+      "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "source": "macbook-pro",
       "target": "linux-agent",
       "createdAt": "2026-03-26T10:15:30.000Z",
@@ -245,6 +264,20 @@ The integration flow:
 }
 ```
 
+### Client SDK (`@lamalibre/portlama-tickets`)
+
+The `@lamalibre/portlama-tickets` package is a TypeScript SDK that provides the client-side ticket lifecycle for plugins and agents. It uses `undici` for HTTP with mTLS dispatcher support and has no other runtime dependencies.
+
+The SDK exports three main classes:
+
+- **`TicketClient`** — low-level HTTP client for all ticket API endpoints. Handles mTLS authentication, response validation (`assertObject`/`assertField` checks before type assertions), and structured error reporting via `TicketHttpError` (carries the HTTP status code for retriable vs. permanent error distinction).
+
+- **`TicketInstanceManager`** (source side) — manages the full instance lifecycle: creates the mTLS dispatcher, registers an instance for a scope, heartbeats it every 60 seconds, requests tickets with a per-agent cooldown (default 120 seconds) to avoid exhausting the global ticket cap, and auto-re-registers on 404 (instance expired). On `stop()`, it deregisters the instance from the panel immediately rather than waiting for the heartbeat timeout.
+
+- **`TicketSessionManager`** (target side) — manages the session lifecycle: polls the ticket inbox for matching tickets (filtering by scope, discarding tickets with less than 5 seconds remaining TTL, picking the freshest), validates them, creates sessions, heartbeats every 60 seconds, transitions through `waiting` / `authorized` / `grace` / `terminated` / `stopped` states, and notifies the consuming plugin via an `onStateChange` callback.
+
+The dispatcher factory (`createTicketDispatcher`) supports both PEM (cert + key + CA files) and P12 (single .p12 bundle) certificate configurations.
+
 ### Source Files
 
 | File                                                    | Purpose                                   |
@@ -253,6 +286,10 @@ The integration flow:
 | `packages/panel-server/src/routes/management/tickets.js` | HTTP route handlers                       |
 | `packages/panel-client/src/pages/management/Tickets.jsx` | Admin UI (5-tab interface)               |
 | `packages/portlama-agent/src/lib/panel-api.js`          | Agent-side API functions                  |
+| `packages/portlama-tickets/src/client.ts`               | SDK: mTLS HTTP client for ticket API      |
+| `packages/portlama-tickets/src/instance-manager.ts`     | SDK: source-side instance lifecycle       |
+| `packages/portlama-tickets/src/session-manager.ts`      | SDK: target-side session lifecycle        |
+| `packages/portlama-tickets/src/types.ts`                | SDK: shared type definitions              |
 
 ## Quick Reference
 
@@ -263,7 +300,7 @@ The integration flow:
 | ID length   | 64 hex characters (256-bit)       |
 | Expiry      | 30 seconds                        |
 | Usage       | Single-use                        |
-| Comparison  | Timing-safe (`crypto.timingSafeEqual`) |
+| Comparison  | HMAC-SHA256 + `crypto.timingSafeEqual` (per-process random key) |
 | Rate limit  | 10 per agent per minute           |
 
 ### Instance lifecycle
@@ -274,7 +311,7 @@ The integration flow:
 | Heartbeat       | stays active     | `lastHeartbeat` updated                |
 | 5 min no beat   | → stale          | New tickets rejected                   |
 | 1 hr no beat    | → dead           | Removed; assignments, tickets, sessions cleaned |
-| Deregistration  | removed          | Same cleanup as dead                   |
+| Deregistration  | removed          | Same cleanup as dead; SDK calls `DELETE` on `stop()` |
 
 ### Session states
 

package/vendor/panel-client/dist/docs/03-architecture/panel-server.md

@@ -464,11 +464,14 @@ Agent-to-agent authorization with scopes, instances, tickets, and sessions. Prov
 - **Scope registry** — register/unregister capability sets with transport configuration
 - **Instance management** — register, heartbeat, deregister with liveness tracking (active → stale → dead)
 - **Assignment management** — link agents to instances (admin-only)
-- **Ticket operations** — request, validate (timing-safe), revoke with rate limiting (10/agent/min) and hard caps (200 instances, 1000 tickets, 500 sessions)
-- **Session management** — create from validated ticket, heartbeat with multi-layer re-validation, status updates
+- **Ticket operations** — request, validate (HMAC-SHA256 + `timingSafeEqual` with per-process random key), revoke with rate limiting (10/agent/min) and hard caps (200 instances, 1000 tickets, 500 sessions)
+- **Session management** — create from validated ticket (server-generated session IDs via `crypto.randomBytes(16)`, server-enforced timestamps), heartbeat with multi-layer re-validation, status updates
+- **Host validation** — `transport.direct.host` rejects private/reserved IPs and cloud metadata endpoints (SSRF prevention)
 - **Periodic cleanup** — stale/dead instances, expired tickets, dead sessions
 - **Concurrency** — promise-chain mutex with atomic file writes (temp → fsync → rename)
 
+Client SDK: `@lamalibre/portlama-tickets` (TypeScript, undici) provides `TicketClient`, `TicketInstanceManager` (source side), and `TicketSessionManager` (target side) for plugin integration.
+
 State files: `/etc/portlama/ticket-scopes.json` (scopes, instances, assignments) and `/etc/portlama/tickets.json` (tickets, sessions).
 
 ### services.js — Service Management

package/vendor/panel-client/dist/docs/04-api-reference/tickets.md

@@ -111,11 +111,23 @@ Register an instance offering a specific scope. Idempotent: re-registration with
 
 | Field                     | Type     | Required | Description                                |
 | ------------------------- | -------- | -------- | ------------------------------------------ |
-| `scope`                   | string   | Yes      | Capability name (e.g., `shell:connect`)    |
+| `scope`                   | string   | Yes      | Capability name in `scope:action` format (e.g., `shell:connect`) |
 | `transport`               | object   | Yes      | Transport configuration                    |
 | `transport.strategies`    | string[] | Yes      | Array of `"tunnel"`, `"relay"`, `"direct"` |
 | `transport.preferred`     | string   | No       | Preferred strategy                         |
-| `transport.direct`        | object   | No       | Direct connection details (host, port)     |
+| `transport.direct`        | object   | No       | Direct connection details                  |
+| `transport.direct.host`   | string   | Yes*     | Public hostname or IP (1-255 chars). Private/reserved IPs are rejected (see below) |
+| `transport.direct.port`   | number   | Yes*     | Port number (1024-65535)                   |
+
+\* Required when `transport.direct` is provided.
+
+**Host validation:** The `transport.direct.host` field rejects private and reserved addresses to prevent SSRF. The following are rejected with a 400 error:
+
+- Private IPv4 ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
+- Link-local: `169.254.0.0/16`
+- Loopback: `localhost`, `127.0.0.1`, `::1`
+- Metadata endpoints: `169.254.169.254`, `metadata.google.internal`
+- Zero network: `0.0.0.0/8`
 
 **Response (201 new, 200 re-registration):**
 
@@ -127,7 +139,7 @@ Register an instance offering a specific scope. Idempotent: re-registration with
 }
 ```
 
-**Errors:** 403 (insufficient capability), 404 (scope not found), 503 (hard cap: 200 instances)
+**Errors:** 400 (missing agent label, or private/reserved IP in `transport.direct.host`), 403 (insufficient capability), 404 (scope not found), 503 (hard cap: 200 instances)
 
 ---
 
@@ -164,7 +176,7 @@ POST /api/tickets/instances/:instanceId/heartbeat
 
 **Auth:** Admin or owning Agent
 
-Updates the instance's `lastHeartbeat` timestamp and maintains active status.
+Updates the instance's `lastHeartbeat` timestamp and resets status to active. Re-validates that the owning agent still has the scope capability — returns 404 if the agent is revoked or the capability has been removed.
 
 **Response (200):**
 
@@ -174,7 +186,7 @@ Updates the instance's `lastHeartbeat` timestamp and maintains active status.
 }
 ```
 
-**Errors:** 404 (not found)
+**Errors:** 400 (missing agent label), 404 (not found, or agent revoked/lacks capability)
 
 ---
 
@@ -209,7 +221,7 @@ Assign an agent to an instance scope, granting it permission to receive tickets
   "ok": true,
   "assignment": {
     "agentLabel": "linux-agent",
-    "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4",
+    "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
     "assignedAt": "2026-03-26T10:10:00.000Z",
     "assignedBy": "admin"
   }
@@ -296,7 +308,7 @@ Request a ticket to authorize communication with a target agent.
   "ticket": {
     "id": "64-hex-char-ticket-id",
     "scope": "shell:connect",
-    "instanceId": "a7f3b2c9d1e2f3a4",
+    "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
     "source": "macbook-pro",
     "target": "linux-agent",
     "expiresAt": "2026-03-26T10:15:30.000Z"
@@ -326,7 +338,7 @@ Returns non-expired, unused tickets where the caller is the target.
     {
       "id": "...",
       "scope": "shell:connect",
-      "instanceId": "a7f3b2c9d1e2f3a4",
+      "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "source": "macbook-pro",
       "expiresAt": "2026-03-26T10:15:30.000Z",
       "transport": {}
@@ -361,7 +373,7 @@ Validate and consume a ticket. This is an atomic operation — the ticket is mar
 {
   "valid": true,
   "scope": "shell:connect",
-  "instanceId": "a7f3b2c9d1e2f3a4",
+  "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
   "source": "macbook-pro",
   "target": "linux-agent",
   "transport": {}
@@ -424,14 +436,13 @@ POST /api/tickets/sessions
 
 **Auth:** Admin or Agent (requires `certLabel`)
 
-Create a session from a validated (used) ticket. The caller must be the ticket's target.
+Create a session from a validated (used) ticket. The caller must be the ticket's target. The server generates the `sessionId` — clients do not provide it.
 
 **Request body:**
 
 | Field       | Type   | Required | Description                                    |
 | ----------- | ------ | -------- | ---------------------------------------------- |
 | `ticketId`  | string | Yes      | Hex ticket ID (1-128 chars)                    |
-| `sessionId` | string | Yes      | Caller-chosen session ID (1-128 chars, alphanumeric + `-_`) |
 
 **Response (201):**
 
@@ -442,7 +453,7 @@ Create a session from a validated (used) ticket. The caller must be the ticket's
     "sessionId": "...",
     "ticketId": "...",
     "scope": "shell:connect",
-    "instanceId": "a7f3b2c9d1e2f3a4",
+    "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
     "source": "macbook-pro",
     "target": "linux-agent",
     "createdAt": "2026-03-26T10:15:30.000Z",
@@ -483,7 +494,7 @@ Re-validates the session's authorization and updates activity timestamp.
 }
 ```
 
-Or if authorization failed:
+Or if authorization failed (session is terminated):
 
 ```json
 {
@@ -492,7 +503,9 @@ Or if authorization failed:
 }
 ```
 
-**Errors:** 404 (session not found)
+Possible `reason` values: `admin_killed`, `source_revoked`, `capability_removed`, `target_revoked`, `assignment_removed`.
+
+**Errors:** 400 (missing certLabel), 404 (session not found)
 
 ---
 
@@ -502,16 +515,17 @@ Or if authorization failed:
 PATCH /api/tickets/sessions/:sessionId
 ```
 
-**Auth:** Admin or Agent (requires `certLabel`)
+**Auth:** Admin or Agent (requires `certLabel` — caller can be either the session's source or target)
 
-Update session status (e.g., entering grace period for reconnection).
+Update session status (e.g., entering grace period for reconnection). Re-validates authorization on every status transition: checks that the source certificate is not revoked, source still has the scope capability, and the target's assignment is still valid. If any check fails, the session is terminated and the endpoint returns 409.
 
 **Request body:**
 
 | Field            | Type   | Required | Description                        |
 | ---------------- | ------ | -------- | ---------------------------------- |
 | `status`         | string | Yes      | `"active"` or `"grace"`           |
-| `lastActivityAt` | string | No       | ISO 8601 datetime                  |
+
+The server sets `lastActivityAt` automatically — clients cannot provide or override this field.
 
 **Response (200):**
 
@@ -521,7 +535,7 @@ Update session status (e.g., entering grace period for reconnection).
 }
 ```
 
-**Errors:** 404 (session not found), 409 (cannot reactivate dead session)
+**Errors:** 400 (missing certLabel), 404 (session not found), 409 (session is terminated — dead, or authorization re-validation failed)
 
 ---
 

package/vendor/panel-client/dist/docs/06-reference/config-files.md

@@ -222,6 +222,7 @@ Stores the ticket scope registry: registered scopes, active instances, and agent
       "description": "Remote shell access",
       "scopes": [{ "name": "shell:connect", "description": "Connect to shell", "instanceScoped": true }],
       "transport": { "strategies": ["tunnel"], "preferred": "tunnel", "port": 9000, "protocol": "wss" },
+      "hooks": {},              // Reserved for future hook configuration
       "installedAt": "2026-03-26T10:00:00.000Z"
     }
   ],
@@ -239,7 +240,7 @@ Stores the ticket scope registry: registered scopes, active instances, and agent
   "assignments": [
     {
       "agentLabel": "linux-agent",
-      "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4",
+      "instanceScope": "shell:connect:a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "assignedAt": "2026-03-26T10:10:00.000Z",
       "assignedBy": "admin"
     }
@@ -247,6 +248,22 @@ Stores the ticket scope registry: registered scopes, active instances, and agent
 }
 ```
 
+**Instance transport sub-schema:**
+
+The instance `transport` object may include a `direct` sub-object when the `direct` strategy is listed:
+
+| Field                      | Type     | Required | Description                                                     |
+| -------------------------- | -------- | -------- | --------------------------------------------------------------- |
+| `transport.strategies`     | string[] | Yes      | Array of `"tunnel"`, `"relay"`, `"direct"`                      |
+| `transport.preferred`      | string   | No       | Preferred strategy (must be in `strategies`)                    |
+| `transport.direct`         | object   | No       | Direct connection details (required when using `direct` strategy) |
+| `transport.direct.host`    | string   | Yes*     | Public hostname or IP (1-255 chars). Private/reserved IPs rejected (SSRF prevention) |
+| `transport.direct.port`    | number   | Yes*     | Port number (1024-65535)                                        |
+
+\* Required when `transport.direct` is provided.
+
+**Host validation:** The `transport.direct.host` field rejects private and reserved addresses: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `169.254.0.0/16`, loopback (`localhost`, `127.0.0.1`, `::1`), cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`), and the zero network (`0.0.0.0/8`).
+
 **Write pattern:** Atomic — temp file, `fsync()`, `rename()`. Concurrency controlled by promise-chain mutex.
 
 ---
@@ -260,7 +277,7 @@ Stores active tickets and sessions for agent-to-agent authorization. Created aut
 | Field      | Type  | Description                                                    |
 | ---------- | ----- | -------------------------------------------------------------- |
 | `tickets`  | array | Issued tickets (id, scope, instanceId, source, target, expiry) |
-| `sessions` | array | Active sessions (sessionId, ticketId, status, heartbeat)       |
+| `sessions` | array | Active sessions (server-generated sessionId, ticketId, status, heartbeat) |
 
 **Example:**
 
@@ -270,7 +287,7 @@ Stores active tickets and sessions for agent-to-agent authorization. Created aut
     {
       "id": "64-hex-char-ticket-id",
       "scope": "shell:connect",
-      "instanceId": "a7f3b2c9d1e2f3a4",
+      "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "source": "macbook-pro",
       "target": "linux-agent",
       "createdAt": "2026-03-26T10:15:00.000Z",
@@ -283,10 +300,10 @@ Stores active tickets and sessions for agent-to-agent authorization. Created aut
   ],
   "sessions": [
     {
-      "sessionId": "session-1",
+      "sessionId": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
       "ticketId": "64-hex-char-ticket-id",
       "scope": "shell:connect",
-      "instanceId": "a7f3b2c9d1e2f3a4",
+      "instanceId": "a7f3b2c9d1e2f3a4b5c6d7e8f9a0b1c2",
       "source": "macbook-pro",
       "target": "linux-agent",
       "createdAt": "2026-03-26T10:15:30.000Z",

package/vendor/panel-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamalibre/portlama-panel-server",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Portlama management panel backend",
   "private": true,
   "type": "module",

package/vendor/panel-server/src/lib/authelia.js

@@ -60,7 +60,7 @@ async function getInstalledVersion() {
  * Write content to a system path using a temp file and sudo mv.
  */
 async function sudoWriteFile(destPath, content, mode = '644') {
-  const tmpFile = path.join(tmpdir(), `portlama-${crypto.randomBytes(4).toString('hex')}`);
+  const tmpFile = path.join(tmpdir(), `portlama-authelia-${crypto.randomBytes(4).toString('hex')}`);
   await fsWriteFile(tmpFile, content, 'utf-8');
   await execa('sudo', ['mv', tmpFile, destPath]);
   await execa('sudo', ['chmod', mode, destPath]);

package/vendor/panel-server/src/lib/certbot.js

@@ -100,7 +100,7 @@ export async function issueAppCert(subdomain, domain, email) {
 export async function listCerts() {
   let stdout;
   try {
-    const result = await execa('sudo', ['certbot', 'certificates']);
+    const result = await execa('sudo', ['certbot', 'certificates', '--non-interactive']);
     stdout = result.stdout;
   } catch (err) {
     // certbot certificates returns non-zero if no certs exist
@@ -165,10 +165,15 @@ export async function listCerts() {
  * Renew a specific certificate by name.
  *
  * @param {string} domain - Certificate name (usually the domain)
+ * @param {{ forceRenewal?: boolean }} [options]
  */
-export async function renewCert(domain) {
+export async function renewCert(domain, options = {}) {
+  const args = ['certbot', 'renew', '--cert-name', domain];
+  if (options.forceRenewal) args.push('--force-renewal');
+  args.push('--non-interactive');
+
   try {
-    await execa('sudo', ['certbot', 'renew', '--cert-name', domain]);
+    await execa('sudo', args);
     return { renewed: true, domain };
   } catch (err) {
     throw new Error(`Failed to renew certificate for ${domain}: ${err.stderr || err.message}`);
@@ -180,7 +185,7 @@ export async function renewCert(domain) {
  */
 export async function renewAll() {
   try {
-    const { stdout } = await execa('sudo', ['certbot', 'renew']);
+    const { stdout } = await execa('sudo', ['certbot', 'renew', '--non-interactive']);
     return { renewed: true, output: stdout };
   } catch (err) {
     throw new Error(`Failed to renew certificates: ${err.stderr || err.message}`);

package/vendor/panel-server/src/lib/tickets.js

@@ -90,13 +90,32 @@ export const RegisterScopeSchema = z.object({
   transport: TransportSchema,
 });
 
+// Hostname/IP validation: reject private, loopback, link-local, and metadata IPs
+const HostnameSchema = z.string().min(1).max(255).refine((host) => {
+  // Block metadata endpoint (AWS/GCP/Azure)
+  if (host === '169.254.169.254' || host === 'metadata.google.internal') return false;
+  // Block loopback
+  if (host === 'localhost' || host === '127.0.0.1' || host === '::1') return false;
+  // Block IPv4 private ranges and link-local
+  const ipv4Match = host.match(/^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/);
+  if (ipv4Match) {
+    const [, a, b] = ipv4Match.map(Number);
+    if (a === 10) return false;                         // 10.0.0.0/8
+    if (a === 172 && b >= 16 && b <= 31) return false;  // 172.16.0.0/12
+    if (a === 192 && b === 168) return false;            // 192.168.0.0/16
+    if (a === 169 && b === 254) return false;            // 169.254.0.0/16 link-local
+    if (a === 0) return false;                           // 0.0.0.0/8
+  }
+  return true;
+}, { message: 'Host must be a public hostname or IP address' });
+
 export const RegisterInstanceSchema = z.object({
   scope: CapabilityStringSchema,
   transport: z.object({
     strategies: z.array(TransportStrategySchema).min(1),
     preferred: TransportStrategySchema.optional(),
     direct: z.object({
-      host: z.string().min(1).max(255),
+      host: HostnameSchema,
       port: z.number().int().min(1024).max(65535),
     }).optional(),
   }),
@@ -114,12 +133,10 @@ export const ValidateTicketSchema = z.object({
 
 export const CreateSessionSchema = z.object({
   ticketId: z.string().min(1).max(128).regex(/^[a-f0-9]+$/),
-  sessionId: z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/),
 });
 
 export const UpdateSessionSchema = z.object({
   status: z.enum(['active', 'grace']),
-  lastActivityAt: z.string().datetime().optional(),
 });
 
 export const AssignmentSchema = z.object({
@@ -213,10 +230,15 @@ function cleanTickets(store) {
 
 // --- Timing-safe comparison ---
 
+// Per-process random key prevents pre-computation if source is read
+const COMPARE_KEY = crypto.randomBytes(32);
+
 function safeCompare(a, b) {
   if (typeof a !== 'string' || typeof b !== 'string') return false;
-  if (a.length !== b.length) return false;
-  return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+  // HMAC both values to get fixed-length digests, avoiding length-leak in timingSafeEqual.
+  const ha = crypto.createHmac('sha256', COMPARE_KEY).update(a).digest();
+  const hb = crypto.createHmac('sha256', COMPARE_KEY).update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
 }
 
 // --- Rate limiting ---
@@ -817,7 +839,7 @@ export function revokeTicket(ticketId, logger) {
 
 // --- Session management ---
 
-export function createSession(ticketId, sessionId, callerLabel, logger) {
+export function createSession(ticketId, callerLabel, logger) {
   return withTicketLock(async () => {
     const store = await loadTicketStore();
 
@@ -836,6 +858,8 @@ export function createSession(ticketId, sessionId, callerLabel, logger) {
       throw Object.assign(new Error('Session limit reached'), { statusCode: 503 });
     }
 
+    // Generate session ID server-side for uniqueness guarantee
+    const sessionId = crypto.randomBytes(16).toString('hex');
     const now = new Date().toISOString();
     const session = {
       sessionId,
@@ -936,7 +960,7 @@ export function sessionHeartbeat(sessionId, callerLabel) {
   });
 }
 
-export function updateSession(sessionId, status, lastActivityAt, callerLabel) {
+export function updateSession(sessionId, status, callerLabel) {
   return withTicketLock(async () => {
     const store = await loadTicketStore();
     const session = store.sessions.find(
@@ -988,7 +1012,8 @@ export function updateSession(sessionId, status, lastActivityAt, callerLabel) {
     }
 
     session.status = status;
-    if (lastActivityAt) session.lastActivityAt = lastActivityAt;
+    // Always set server-side timestamp to prevent clients from extending session lifetime
+    session.lastActivityAt = new Date().toISOString();
     await saveTicketStore(store);
 
     return { ok: true };

package/vendor/panel-server/src/routes/management/certs.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { execa } from 'execa';
-import { listCerts } from '../../lib/certbot.js';
+import { listCerts, renewCert } from '../../lib/certbot.js';
 import {
   getMtlsCerts,
   readCertExpiry,
@@ -577,21 +577,17 @@ export default async function certsRoutes(fastify, _opts) {
       const { domain } = params;
 
       try {
-        // Force renewal via certbot
-        await execa('sudo', ['certbot', 'renew', '--cert-name', domain, '--force-renewal'], {
-          timeout: 90000,
-        });
+        await renewCert(domain, { forceRenewal: true });
       } catch (err) {
-        const stderr = err.stderr || err.message;
+        const msg = err.message || '';
 
-        if (stderr.includes('No certificate found') || stderr.includes('not found')) {
+        if (msg.includes('No certificate found') || msg.includes('not found')) {
           return reply.code(404).send({ error: 'Certificate not found' });
         }
 
         request.log.error({ err, domain }, 'Certificate renewal failed');
         return reply.code(500).send({
           error: 'Certificate renewal failed',
-          details: stderr,
         });
       }
 

package/vendor/panel-server/src/routes/management/tickets.js

@@ -155,6 +155,14 @@ export default async function ticketRoutes(fastify, _opts) {
         if (!agentLabel) {
           return reply.code(400).send({ error: 'Agent label required' });
         }
+        // Defense-in-depth: reject agents with no capabilities before acquiring
+        // the lock. The library's instanceHeartbeat verifies the specific scope.
+        if (request.certRole === 'agent') {
+          const caps = request.certCapabilities || [];
+          if (caps.length === 0) {
+            return reply.code(404).send({ error: 'Not found' });
+          }
+        }
         const result = await instanceHeartbeat(instanceId, agentLabel);
         return result;
       } catch (err) {
@@ -342,7 +350,7 @@ export default async function ticketRoutes(fastify, _opts) {
         if (!callerLabel) {
           return reply.code(400).send({ error: 'Agent label required' });
         }
-        const result = await createSession(body.ticketId, body.sessionId, callerLabel, request.log);
+        const result = await createSession(body.ticketId, callerLabel, request.log);
         return reply.code(201).send(result);
       } catch (err) {
         const statusCode = err.statusCode || 500;
@@ -386,7 +394,6 @@ export default async function ticketRoutes(fastify, _opts) {
         const result = await updateSession(
           sessionId,
           body.status,
-          body.lastActivityAt,
           callerLabel,
         );
         return result;