Account Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/server.js
• src/util.js
• PLAN.md
• src/views.js
• README.md
• test/app.test.js

Account Management in PuppyPad handles the lifecycle of user identities, site ownership, and security credentials. The system governs site registration, authentication through multiple factors, and the administrative oversight of member content. It serves as the bridge between the centralized puppypad.org management interface and the decentralized name.puppypad.org member sites.

The module manages persistent user data in a SQLite database and enforces safety constraints such as name reservations and phishing flags. It enables members to manage their presence through profile updates, site renames, and account deletions while providing administrators with tools for moderation and ban enforcement.

Sources: PLAN.md:16-32, README.md:9-15, src/server.js:25-50

User Lifecycle and Registration

Registration creates a new member account and an associated site directory. The system validates the requested username against reserved terms and format rules before proceeding with account creation.

Registration Process

1. Validation: The system checks if the username contains 3-30 lowercase letters, numbers, or hyphens and ensures it is not a reserved name or recently released.
2. Honeypot/Captcha: Signups use a hidden "website" field to trap bots and optionally require a Cloudflare Turnstile verdict.
3. Credential Hashing: Passwords are hashed using scrypt before storage.
4. Site Provisioning: The server creates a directory under ./data/sites/{username} and populates it with a starter index.html.
5. Verification: The account remains unverified until the user clicks a link sent to their email. Unverified accounts are purged after 3 days.

Sources: src/server.js:464-515, src/util.js:27-36, test/app.test.js:33-40

The diagram shows the flow from initial signup submission through automated bot checks to final account activation.
Sources: src/server.js:472-525, PLAN.md:120-131

Authentication and Security

PuppyPad implements session-based authentication with optional Two-Factor Authentication (2FA).

Session Management

The system issues a sid (or __Host-sid in secure environments) cookie upon successful login. Using the __Host- prefix prevents member subdomains from reading or overwriting the session cookie, isolating the management dashboard from user-generated scripts.

Sources: src/server.js:35-36, PLAN.md:68-70

Two-Factor Authentication (TOTP)

Members may enable 2FA using TOTP-compliant authenticator apps. When enabled, the login process requires a secondary 6-digit code or a one-time recovery code.

• Key Storage: Only the SHA256 hash of the recovery codes is stored.
• Step Verification: The system tracks the last used TOTP time step to prevent replay attacks.
• Revocation: Changing or resetting a password automatically revokes API keys and can trigger logouts on other devices.

Sources: src/server.js:774-825, README.md:46-48, src/views.js:415-442

Security Feature	Implementation Detail	Purpose
Password Hashing	scrypt via U.hashPw	Secure credential storage
Session Cookie	__Host-sid (Secure)	Protection against cross-subdomain cookie tossing
CSRF Protection	Token + Origin Check	Prevention of unauthorized form submissions
Account Purge	3-day window	Removal of unconfirmed/spam accounts
Name Hold	90-day duration	Prevention of impersonation after account deletion

Sources: PLAN.md:68-81, src/server.js:37-39, test/app.test.js:132-137

Site Management and Renaming

Members manage their site identity through the dashboard. This includes updating taglines, tags, and changing the site's primary subdomain.

Renaming Logic

Renaming a site involves a atomic transaction that:

1. Updates the username and renamed_at timestamp in the users table.
2. Moves the site's directory on disk.
3. Records the old name in the released_names table to maintain a redirect for 90 days.
4. Updates associated moderation reports to the new name.

A member can rename their site only once every RENAME_DAYS (default 30).

Sources: src/server.js:828-854, README.md:27-29, src/views.js:625-634

The sequence diagram illustrates the atomic operations required to rename a site while ensuring the old name remains reserved and redirects function correctly.
Sources: src/server.js:828-854, PLAN.md:144-148

Administrative Oversight and Moderation

Administrators (defined by ADMIN_EMAILS) possess elevated privileges to manage all accounts and sites.

Moderation Tools

• Banning: Administrators can "roll up" a pad, which returns a 410 Gone status for the site and disables dashboard editing.
• Deletions: Admins can permanently delete accounts and their associated files.
• Phishing Flags: An automated system scans HTML, JS, and SVG uploads for password fields or brand impersonation, flagging sites for manual review in the /admin queue.
• Audit Log: The admin_log table records every take-down, restore, and deletion action performed by moderators.

Sources: src/server.js:936-980, PLAN.md:154-159, src/views.js:773-802

Configuration Limits

Account behavior is constrained by global settings defined in environment variables:

Variable	Default Value	Description
QUOTA_MB	500 MB	Storage limit per member
MAX_FILE_MB	5 MB	Maximum size for a single file upload
BANDWIDTH_MB	1024 MB	Daily bandwidth quota per site
RENAME_DAYS	30	Cooldown period between site renames

Sources: src/server.js:25-34, README.md:21-25

API Access

Members can generate an API key to manage their account programmatically.

• Endpoint: POST /dashboard/api creates a key prefixed with pp_.
• Storage: The server stores only the SHA256 hash of the key.
• Capabilities: The API allows for file listing, uploads, and deletions via Authorization: Bearer headers.
• Rate Limiting: API requests are limited to 120 per minute per member.

Sources: src/server.js:725-770, README.md:31-35, src/views.js:685-715

Account management ensures that PuppyPad remains a secure and manageable platform by balancing user autonomy with robust administrative controls and automated security scanning.