[agentHits]

What is this PR about?

Adds a per-user super password. A leaked API key or browser session can no longer write through API keys, reveal secrets or change access without it. Entering it once in Profile opens a 24-hour super session.

This PR includes and supersedes #26 (fix/docker-logs-traefik-access): its commits are merged in, and its hard denies for Traefik TLS files and panel system containers become "allowed only with an open super session". #26 can be closed after this one lands.

Behaviour

• Not set (default): nothing changes for that user, so the owner's AI agent keeps working until the owner sets a password. Profile shows a "Not set" warning.
• Set, super session closed: API keys are read-only. Every tRPC mutation or subscription through an API key returns FORBIDDEN: "API key write access is locked. Open it in Profile → Super password." Queries still work, and their secrets are already redacted. Browser sessions keep regular writes (create, update, deploy, env edits). Dangerous actions need the super password.
• Set, super session open (24 h): the user's API keys can write again. Dangerous actions work only from the browser session. API keys can never run them.
• superPassword.status returns { isSet, hint, active, expiresAt, lockedUntil, … }, never the hash. It also works through API keys, so the MCP/AI agent can tell why a write failed.

Dangerous actions (browser session + open super session)

The central registry is apps/dokploy/server/api/utils/procedure-access.ts. It classifies all 650 app router procedures as read, write or dangerous. A test fails when a procedure added by an upstream merge is not classified.

• Revealing secrets: revealEnvironment for application, compose and the 6 databases; docker.getConfig (container env); settings.readTraefikEnv; cluster.addManager/addWorker (swarm join tokens); backup.manualBackupWebServer and web-server backup.create/update (dump of the panel DB).
• Traefik TLS files (acme.json, *.key, dynamic/certificates): read and write for owner/admin only. They stay hidden from the tree and denied while the super session is closed, as in fix: scope container files, service logs and traefik files access #26.
• Panel system containers and their volumes (dokploy, its postgres and redis, traefik, any local container without a Dokploy service): available in the file manager for owner/admin only. Service containers work as in fix: scope container files, service logs and traefik files access #26.
• WebSocket terminals: local host, remote servers and containers.
• Users and access, in tRPC: members, invitations, roles, custom roles, API key create/delete, user removal and account deletion, SSO and SCIM settings, forward auth, enforce SSO. Also user.update when the email or password changes.
• Users and access, in better-auth hooks.before (packages/server/src/lib/super-session-auth.ts): /api-key/* writes, change email/password, delete user, link/unlink, organization member/invitation/role/team endpoints, 2FA enable/disable/backup codes/TOTP URI, passkey register/delete, SSO provider endpoints. Sign-in, sign-out, session refresh, 2FA and passkey verification during sign-in, password reset and session revocation are not gated.
• Notification destinations: create, update, delete. Email is the reset channel.
• Host level: dokploy-server schedules (create, update, run); main Traefik config, env, ports, middlewares, web server Traefik config, dashboard toggle, Traefik file writes; panel domain, IP, update and reload; SSH keys (create, update, delete, save/clean the host key); server create/update/delete; backup and volume backup restore; cleanUnusedVolumes.
• Deletions: project, environment, application, compose, the 6 databases, server, destination, registry, git provider, certificate, docker volume.

Container and volume file reads (service containers) count as writes for API keys, so a leaked key without an open super session cannot read files such as /proc/1/environ.

Super password rules

• Set only from a browser session, by owner/admin. It must differ from the credential (login) password, and a later login password change cannot reuse it. Optional hint of up to 200 characters that must not contain the password (case-insensitive).
• Stored as a bcrypt hash, like login passwords. Changing it or turning it off needs the current super password. Turning it off also ends the super session.
• 5 wrong attempts lock unlocking for 15 minutes. Every wrong attempt and the lockout are announced on the alert channels (see below).
• Extend resets the expiry to now + 24 h without the password, only while the session is open and only from a browser session.

Alerts and recovery over notification channels

• New notification toggle "Super password" ("Security alerts and recovery links for the super password") in the "Select the actions" list of every notification type. It is stored in notification.superPassword (default off) and wired through all create/update schemas and services.
• Alerts go to every channel with the toggle on in the organizations where the user is owner or admin, through the existing senders: Telegram (keeps message_thread_id), email, Resend, Discord, Slack, Mattermost, Gotify, ntfy, Lark, Pushover, Teams and custom webhook.
• Events: access opened and extended (time left, expiry, IP, user agent), closed (via panel, "This wasn't me" link or SSH), wrong attempt, lockout after 5 attempts, super password set, changed, turned off or reset (by link or over SSH), reset link requested, and alert channel changes.
• Opened and extended alerts carry a one-time "This wasn't me – close access" link to /super-password/lock. Telegram shows it as an inline URL button; when the panel URL is localhost or a bare IP, which Telegram buttons reject, it is a plain link instead. The page needs no sign-in, can only close access, and closes it on a button press, so link scanners cannot trigger it.
• Links use the panel URL the same way other notifications do (getDokployUrl). Alerts never contain the hint, hashes or other secrets.
• Sending is fire-and-forget. A failing or hanging channel never blocks unlock, extend or any other action.
• Turning the toggle on or off for a channel, changing the destination of a channel that has it, or deleting such a channel is announced to every channel with the toggle, including the old state of the changed channel. Creating, updating and deleting notifications stay dangerous actions, so an API key cannot add its own channel.
• The earlier email-only reset and alert path is removed. An email channel is now just one of the channels.

Sample Telegram alert (HTML, with the inline button below it):

🔐 Super password access opened
Dangerous actions and API key writes are open.

User: owner@example.com
Time: 2026-10-07 06:24 UTC
Time left: 24 h 0 min
Expires: 2026-10-08 06:24 UTC
IP address: 203.0.113.7
User agent: Mozilla/5.0 …
[ This wasn't me – close access ]

Reset and emergency lock

• Panel: "Close access now" in Profile. Under "Forgot super password?", the user picks any channel with the toggle on, for example a Telegram bot or an email channel, and gets a single-use reset link there (30 min, stored hashed). The other channels get a "reset link requested" alert without the link. At most 3 links per hour per user. The link opens /dashboard/settings/super-password-reset and works only for the same signed-in user. Resetting closes the super session. With no channel, Profile says "No recovery channel: enable 'Super password' on a notification, or use SSH".
• SSH (the panel container is the dokploy swarm task):

# remove the super password and close the super session (owner by default, or by email)
docker exec -it $(docker ps -q -f 'name=^dokploy\.') bun run reset-super-password
docker exec -it $(docker ps -q -f 'name=^dokploy\.') bun run reset-super-password user@example.com

# close the super session only (owner by default, or by email)
docker exec -it $(docker ps -q -f 'name=^dokploy\.') bun run lock-super-session
docker exec -it $(docker ps -q -f 'name=^dokploy\.') bun run lock-super-session user@example.com

UI

• New "Super password" card on /dashboard/settings/profile: set form, unlock form with hint, "Access open: 17 h 42 min left" countdown (warns under 1 hour), Extend, Close access now, Change, Turn off, and the recovery channel picker or the "No recovery channel" note.
• Notification form: the "Super password" toggle next to App Deploy, Dokploy Restart and the other actions.
• Global unlock dialog: when a browser request fails with the super session reason (data.superSession), a tRPC link asks for the super password and retries the request. For better-auth endpoints the dialog opens, and the user runs the action again.

Data

• Migration 0204_super_password, generated with drizzle-kit. It sorts after every migration in AgentHits-Dev and adds super_password, super_session and super_password_token (hashed, single-use, expired tokens cleaned up when new ones are created).
• Migration 0205_super_password_alert_channels, also generated with drizzle-kit. It adds notification.superPassword (boolean, default false) and the reset-link rate limit counters on super_password.

Checks

• CI=true bunx vitest run --config __test__/vitest.config.ts on the new and changed test files: service (hashing, same-as-login, hint, 5-attempt lock, extend only while open, token single-use and expiry, emails), tRPC guard (API-key writes locked/open, dangerous via API key always blocked, dangerous from the browser closed/open, conditional procedures, "not set" unchanged), router classification, env upsert REST endpoint, better-auth gated paths, WebSocket terminals (real http server and ws client), Traefik TLS files, and system containers and volumes. Alert tests cover:

  • the toggle in every schema and its persistence;
  • alerts only to toggled channels in managed organizations;
  • every event type, and no secrets in any payload;
  • the lock link on opened/extended alerts;
  • Telegram Bot API payload shape (stubbed fetch: chat, message_thread_id, HTML, inline button, plain-link fallback);
  • reset over a chosen channel with single use;
  • the 3-per-hour limit;
  • failing or hanging senders not blocking unlock or extend;
  • the no-recovery-channel state;
  • toggle on/off, redirect and delete alerts that include the old destination.

  All pass. They fail on the code before this branch: missing modules, fix: scope container files, service logs and traefik files access #26's hard deny, and the guard or terminal gate switched off. The alert tests fail on the branch before the notification-channel commits.

• Full suite: 260 test files and 2307 tests pass. The 2 *.real.test.ts files need Docker swarm. They passed separately on a local OrbStack swarm with a dokploy-network overlay; the swarm and test images were cleaned up afterwards.

• bun run typecheck: exit 0. bunx biome check on changed files: 0 errors. The 2 warnings are in pre-existing lines of server/wss/*.

• Manual: ran the app locally (Postgres on OrbStack, dev server on 127.0.0.1). Checked the Profile card, the same-as-login rejection, the unlock dialog with retry on API key creation, the wrong-password counter, the countdown with the under-1-hour warning, extend, close, API-key write lock and dangerous refusal over /api/trpc, the 2FA endpoint refusal, the lock page, the reset page, the system container file browser, and both CLI commands. esbuild bundles the CLI entries. Notification channels: created a channel with the toggle on and saw it in the Profile recovery picker. A send failure shows a clear error, and with the toggle off Profile shows "No recovery channel". No real messages were sent anywhere: senders are mocked in tests, and the local check used an unresolvable host.

Rollout notes

• Deploy as usual; the migration only adds tables. Nothing changes for anyone until a user sets a super password.
• Owner's AI agent / MCP: works exactly as today until the super password is set. After that, its API key writes only while a super session is open: open it in Profile, then use Extend or reopen every 24 h. Dangerous actions (revealing env, deletions, users and access, host settings, terminals) are never available through API keys, even while open. Reads, deploys, env upserts and other regular writes work while open. superPassword.status tells the agent whether access is open.
• Turn on the "Super password" toggle on at least one notification channel (for example the Telegram bot) before setting the super password, so alerts and reset links have somewhere to go. Otherwise use the SSH commands above.
• The Telegram sender swallows Bot API errors, so a reset link that Telegram rejects is not reported as a failure in Profile.
• Remaining risk: a stolen browser session can still do regular writes, such as deploying a container with host bind mounts, by design of this feature. The super password protects API keys fully and puts the obvious secret and access paths behind a second secret.
• Observed but not changed: in local dev, OpenAPI routes /api/<procedure> answer 500 because of the dockerDiskUsage.getDiskUsage input schema (detailLimit). This also happens without this PR.

🤖 Generated with Claude Code