authentication

Files (1)

• SKILL.md

SKILL.md (first lines)

# Authentication Skill

## 1. When to Use
Use this skill when implementing or modifying password verification, session lifecycles, user authentication cookies, external user registration, or authentication operational event logging.

## 2. Core Invariants
- **Password Hashing**: Always use `hashPassword(password)` from `@packages/auth` (scrypt with 16-byte random salt).
- **Password Verification**: Always use `verifyPassword(password, hash)` with timing-safe comparison (`crypto.timingSafeEqual`).
- **Zero Leakage**: Never store or log plaintext passwords. Never return `passwordHash` in API responses or serialization models.
- **Server Sessions**: 32-byte cryptographic random token stored in PostgreSQL as a SHA-256 `tokenHash` and cached in Redis.
- **Cookies**: Transmitted over secure HTTP-only cookies (`app_session`) with `SameSite=Lax`, `Path=/`, and `Secure` in production.
- **Account Invalidation**: `SUSPENDED` / `DISABLED` accounts are rejected at login and during session validation. All active sessions are revoked upon status change.

## 2a. Signup, Verification, Reset and Invitations
- **Signup creates a workspace** and makes the signer its ROOT, in one transaction. `identityType` and `tenantId` are fixed server-side; the request schema is `.strict()`.
- **Email verification is enforced by the API, not the wizard.** `POST /auth/signup` refuses (`400 EMAIL_NOT_VERIFIED`) unless `/auth/otp/verify` succeeded for that address, and the verified marker is spent by the signup.
- **Passwords** go through `createPasswordSchema`: minimum length, lowercase, uppercase, and a number or symbol. One schema serves signup, reset, invite-accept and change-password; `apps/web/src/lib/password.ts` mirrors it and a test pins the two together.
- **Reset**: `POST /auth/password/forgot` answers identically for any address and sends nothing for unknown, suspended or disabled accounts. `POST /auth/password/reset` spends a single-use token, revokes every session, clears the login throttle, and emails a notice.
- **Invitations** use the same token mechanism with a longer life. An invite can only be resent to someone who has never signed in; afterwards it would be a takeover path.
- Emailed tokens live in `ActionTokenService`; see the email skill.

## 3. Operational Event Logging
Log structured auth events without credentials:
- `auth.signup.success` (with `userId`, `identityType`)
- `auth.signup.failure` (with reason code, never passwords)
- `auth.login.success` (with `userId`, `identityType`)
- `auth.login.failure` (with reason code, never passwords)
- `auth.logout` (with `userId`)
- `auth.session.revoked` (with `userId`, `reason`)

## 4. Mandatory Testing Expectations
Every authentication change requires:
1. **Happy Path**: Successful signup (with verification), login, session validation, logout, reset, invite acceptance.
2. **Input Validation**: Rejection of weak passwords, malformed emails, empty inputs.
3. **Security Invariants**: Verification that `passwordHash` is never exposed in user responses or session payloads.
4. **Session Invalidation**: Testing that suspended or disabled accounts have active sessions rejected.
5. **Cookie Security**: Testing that cookies have `httpOnly: true` and `secure: true` in production mode.
6. **Tokens & Codes**: Single use, expiry, wrong purpose, replay, a superseded token, and fail-closed on a Redis error.
7. **No Enumeration**: Login and forgot-password answer identically for known and unknown accounts.

From Mihir-Rabari/create-odoo-app, MIT.

More from Mihir-Rabari/create-odoo-app