User Management and Security

User Management & Security

Bindarr is built from the ground up as a multi-user, self-hosted platform. It ensures strict data isolation between users while providing administrators with full control over instance access, backups, and scan models.

---

Authentication Architecture

Bindarr uses a database-backed opaque session token authentication model rather than stateless JWTs:

• Password Storage: Passwords are cryptographically hashed using PBKDF2 with individual salts and iterations embedded in the hash string.
• Session Tokens: Upon login, a cryptographically secure random token is generated and stored in the sessions table with an expiration timestamp.
• Header Transmission: Clients transmit the token via the HTTP Authorization: Bearer <token> header.
• Instant Revocation: Logging out deletes the session row from the database, instantly invalidating the session token across all devices.

---

Initial Admin Account Bootstrap

On a fresh install with an empty database:

1. Web Bootstrap: Navigating to the web interface presents the Setup screen. Submitting a password initializes the default admin account. Passwords are never written to container logs.
2. Environment Variable Bootstrap: If you set DEFAULT_ADMIN_PASSWORD=your_password in your .env or docker-compose.yml, Bindarr initializes the admin account on first boot automatically. (Note: This variable is only evaluated when the users table is completely empty. It will not alter the password of an existing user).

---

User Roles & Permissions

Bindarr supports two distinct user roles:

Capability	Standard User (user)	Administrator (admin)
Manage personal card collection & inventory	Yes	Yes
Create binders, boxes & custom sorting rules	Yes	Yes
Build & check out deck lists	Yes	Yes
Generate read-only personal API keys	Yes	Yes
Share collection via public read-only link	Yes	Yes
Access Admin Dashboard	No	Yes
Create, edit, or delete other user accounts	No	Yes
Trigger automated scan catalog builds	No	Yes
Create and download database backup snapshots	No	Yes
Modify global instance settings & registration toggles	No	Yes

---

Registration Modes

In the Admin Panel, or via the ALLOW_REGISTRATION environment variable:

• Invite-Only (Default - Recommended): Self-registration is disabled. Only administrators can create new user accounts in Admin → Users.
• Open Registration (ALLOW_REGISTRATION=true): A "Register" tab is displayed on the login screen, allowing anyone with access to the URL to create an account.

---

Public Read-Only Collection Sharing

Each user can optionally generate a public share link to showcase their collection to friends or trading communities without exposing account credentials:

1. Go to Settings → Public Sharing.
2. Toggle Enable Public Share Link.
3. Copy your unique share URL (e.g. https://cards.example.com/share/abc123token).
4. Visitors can search, filter, and view high-resolution card artwork and pricing without being able to edit your inventory.
5. You can disable or regenerate the share token at any time to immediately revoke access.

---

Security Controls & Hardening

• Helmet & Content Security Policy (CSP): Protects against cross-site scripting (XSS), clickjacking, and content sniffing. Card image domains (Scryfall, Pokémon TCG API, TCGCSV) are explicitly allow-listed.
• Built-in Rate Limiting: Protects authentication endpoints (/api/auth/*), search queries, and import operations against brute-force attacks.
• Reverse Proxy Protection (TRUST_PROXY): Set TRUST_PROXY=1 when behind a reverse proxy so that rate limiters track the client's actual remote IP rather than the internal proxy IP.
• Read-Only API Credentials: External API keys generated under Settings → API Keys are strictly restricted to HTTP GET operations. Non-GET operations and admin endpoints return 403 Forbidden.