# PalCenter Security

## Reporting a vulnerability

Do not open a public issue containing credentials, backups, or exploit details.
Contact the repository owner privately and include the affected version,
reproduction steps, and impact without attaching production data.

## Current security model

PalCenter uses SQLite-backed accounts, memory-hard scrypt password hashes,
signed HttpOnly SameSite cookies, session expiration and version invalidation,
login throttling, origin/CSRF checks, strict API schemas, and backend-enforced
Administrator, Moderator, and Visitor permissions.

On first start, PalCenter generates a 384-bit session secret with the operating
system cryptographic random source. It stores the secret only in
`/app/data/system.json`, with owner-only permissions. The value is never
returned by an API or frontend bundle. Existing installations may provide
`PALCENTER_SESSION_SECRET` once: it is copied into a missing `system.json`, and
stored configuration wins on every later start.

Credentials in `servers.json`, `notifications.json`, `users.sqlite`, and
`system.json` are redacted from API responses and known log fields. All of
these files, `history.sqlite`, and backup archives are sensitive and should be
protected by host access controls and encrypted backup storage.

Per-user PalDefender bearer tokens are assigned by Administrators in User
Management and stored in `users.sqlite` alongside account data. They are
write-only: APIs and the frontend never return token material, list responses
report configuration state only, and token values are redacted from logs.
When a user has an assigned token, their PalDefender requests use it and fail
closed on authentication or permission errors without falling back to the
server token.

PalCenter can also generate ready-to-install PalDefender token files. Token
generation is Administrator-only. Each generated file grants the least
privilege derived from the target user's current role, and never includes the
`REST.*` wildcard. The token value is generated with the operating system
cryptographic random source and is shown exactly once as the file content;
PalCenter does not store or log the generated token value or file content.
Optionally storing the token for the account reuses the write-only assignment
behavior above. Generated files use a stable per-user file name; regenerating
for the same user replaces the file with a new token and the user's current
role permissions. Because PalDefender has no REST endpoint for token
management, PalCenter cannot create, change, or remove the installed token
file remotely: an Administrator installs the generated file in the PalDefender
server's `RESTAPI\Tokens` folder, then restarts PalDefender or reloads its
configuration.

The container runs as an unprivileged user. Compose drops Linux capabilities,
enables `no-new-privileges`, and mounts only `/app/data`; PalCenter neither
needs nor should receive the Docker socket or Palworld save directories.

## Deployment recommendations

- Run a pinned release image behind HTTPS and set
  `PALCENTER_SESSION_COOKIE_SECURE=true`.
- Restrict both exposed ports to a trusted management network. Prefer the
  frontend's same-origin API proxy and leave `PALCENTER_CORS_ORIGINS` empty.
- Protect the Docker host and volume, use unique credentials, retain encrypted
  tested backups, and review container logs.
- Back up the complete volume while stopped, or use the authenticated Backup
  page. Never copy a live SQLite file by itself.
- Review users regularly and disable accounts that no longer need access.

## Security review and residual risks

The final audit verified setup is single-use, passwords are never stored in
plaintext, session cookies and expiration are enforced, role checks occur in
the API, the last enabled Administrator is protected, restore is
Administrator-only and validated before replacement, and known sensitive
fields are redacted from logs. Secret generation, persisted migration,
backup-format v3 validation, file permissions, and container privilege
reduction were added as audit remediations.

Known limitations:

- There is no MFA, external identity provider, or per-user audit trail.
- Data and portable backups are not application-encrypted at rest; storage
  encryption and access control are operator responsibilities.
- Login throttling is in memory and resets when the API restarts.
- Palworld REST traffic is only as secure as the configured remote URL; use a
  trusted network or TLS-capable endpoint.
- Directly publishing the API port increases attack surface even though it
  remains authenticated.

Security-relevant administrator activity is represented by current server
events and application logs, but a tamper-resistant authentication and
configuration audit log is intentionally deferred beyond v1.0.