Product View

Feature Inventory

What the Code Does That the Spec Doesn't Mention

1. Timing attack prevention on login — When a user provides an email that doesn't exist, the system still runs Argon2 password verification against a dummy hash (DUMMY_HASH at backend/app/crud.py:42) to ensure response times are consistent. This is a security hardening measure not typically documented in specs.

2. Automatic password hash rehashing — When a user logs in and the password hash algorithm has been upgraded (e.g., Argon2 parameters change), the system transparently re-hashes and stores the updated hash during authentication (backend/app/crud.py:55-59). This is a silent migration mechanism.

3. Dual hashing algorithm support — The system supports both Argon2 and bcrypt password hashers simultaneously (backend/app/core/security.py:11-16). This allows gradual migration between algorithms.

4. Private/internal user creation endpoint — POST /private/users/ at backend/app/api/routes/private.py:23-38 is only available in local environment. It has no authentication requirement and accepts an is_verified field that is ignored (the field is defined in the Pydantic model but never used in the handler).

5. Password recovery HTML preview endpoint — POST /password-recovery-html-content/{email} at backend/app/api/routes/login.py:100-120 is a superuser-only endpoint that returns the rendered HTML of the password recovery email. This is a debugging/QA tool not typically exposed.

6. Anti-enumeration on password recovery — The password recovery endpoint always returns the same message ("If that email is registered, we sent a password recovery link") regardless of whether the email exists (backend/app/api/routes/login.py:72-74). This prevents email enumeration attacks.

7. Anti-enumeration on password reset — If a valid reset token references a deleted user, the system returns "Invalid token" rather than revealing the user doesn't exist (backend/app/api/routes/login.py:86-88).

8. New account email with plaintext password — When a superuser creates a user account, the system sends the user's plaintext password in the welcome email (backend/app/api/routes/users.py:69-77). This is a security consideration — the password is transmitted in clear text via email.

Spec Gaps

1. No self-service registration — The UserRegister model exists at backend/app/models.py:26-29 but there is no endpoint that uses it. Users cannot sign up on their own. This appears to be scaffolding for a feature that was planned but not implemented.

2. Database migrations not wired up — The code at backend/app/core/db.py:16-22 explicitly says tables should be created with Alembic migrations, but the migration setup is commented out. The init_db function only creates the first superuser — it does not create database tables. This means the application will fail on first run unless tables are created manually or the commented-out create_all is enabled.

3. is_verified field is dead code — The PrivateUserCreate model at backend/app/api/routes/private.py:16-20 has an is_verified field, but it is never read or stored in the handler. The field exists in the API contract but has no effect.

4. No rate limiting on login — The login endpoint has no rate limiting or account lockout mechanism. This is a security gap for production deployments.

5. No email verification flow — While there's an is_verified field concept in the private API, there is no email verification endpoint or flow for users to verify their email addresses.

Open Questions for Engineering

1. Self-service registration — The UserRegister model exists but is unused. Was self-registration planned for the roadmap? If so, is there a frontend component that was supposed to call it? Should we add a POST /users/register endpoint?

2. Database initialization — How are database tables created in production? The code comments say "use Alembic migrations" but there's no Alembic configuration. Is this handled by an external deployment script, or is this a known gap?

3. Private endpoint security — The POST /private/users/ endpoint has no authentication and is only gated by environment. Is this intentional for local development only, or should it have some form of authentication even in local mode?

4. Password in welcome email — Sending plaintext passwords in welcome emails is a security anti-pattern. Should we switch to a "set your password" link instead?

5. Rate limiting — There's no rate limiting on login or password recovery endpoints. Is this acceptable for the current deployment, or should we add it before the next release?

6. is_verified field — The PrivateUserCreate model accepts is_verified but it's never stored. Is this a bug, or is the field intended for future use? Should we remove it or implement the verification flow?

7. Token expiration — The access token expires in 8 days (60 * 24 * 8 minutes at backend/app/core/config.py:36). Is this appropriate for the product's security requirements? No refresh token mechanism exists.