auth-system

name	auth-system
description	Use when creating, updating, reviewing, or debugging authentication, login, registration, sessions, JWT, OAuth, password reset, auth middleware, roles, permissions, or account security.

Auth System

Use this skill for safe authentication, session, token, and authorization work.

Rules

• Follow the project’s existing auth architecture.
• Do not add a new auth library, token strategy, session system, or password hashing library unless already used or explicitly requested.
• Never store plain-text passwords.
• Never log passwords, tokens, session IDs, cookies, reset links, OTP codes, magic links, or secrets.
• Validate all untrusted input.
• Use generic credential failure messages.
• Do not reveal whether an email, account, token, or private resource exists unless the project intentionally does so.
• Keep auth checks server-side.
• Derive user, role, tenant, and permission state from verified session/token/auth context.
• Do not trust client-provided user IDs, roles, permissions, or tenant IDs.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing auth code, check existing patterns for:

• auth provider/library
• session or token strategy
• password hashing
• user/account model
• roles and permissions
• middleware/protected routes
• cookie settings
• OAuth/SSO flow
• password reset flow
• error format
• test style

Implementation Checklist

• Reuse existing auth helpers, middleware, models, and services.
• Validate request input.
• Verify credentials, tokens, sessions, or provider callbacks securely.
• Create, rotate, revoke, or clear tokens/sessions according to project pattern.
• Attach authenticated user context server-side.
• Add authorization checks for protected actions.
• Keep persistence in the existing data-access layer.
• Add or update relevant tests.

Password Rules

• Hash passwords with the project’s existing secure hashing method.
• Use slow password hashing, not fast general-purpose hashing.
• Compare passwords with the existing secure verification helper.
• Rate-limit failed login attempts when the project supports it.
• Password reset must use short-lived safe tokens.
• Invalidate active sessions/tokens after password reset when supported.

Token, Session, and Cookie Rules

• Prefer httpOnly secure cookies for long-lived session or refresh credentials when the project supports cookies.
• Keep access tokens short-lived when using JWT.
• Rotate refresh tokens when the existing strategy supports it.
• Revoke sessions or refresh tokens on logout when server-side persistence exists.
• Use secure cookies in production.
• Use appropriate sameSite, domain, path, and expiry settings.
• Never hardcode secrets.

Authorization Rules

Authentication proves identity. Authorization proves access.

Check authorization for:

• admin actions
• role/permission actions
• user-owned resources
• organization or tenant resources
• billing/account/security changes
• data export or deletion

Do not rely on client-side checks alone.

OAuth / SSO Rules

• Validate callback state/nonce when applicable.
• Do not trust provider data without verification.
• Link or create local users according to existing project rules.
• Do not expose provider tokens to the client unless the project explicitly requires it.

Failure Handling

• Invalid input: return validation error.
• Invalid credentials: return generic unauthorized error.
• Missing or expired session/token: return unauthorized.
• Missing permission: return forbidden.
• Account conflict: return conflict-style error.
• Do not expose internal auth errors, token validation details, or stack traces.

Tests

Cover relevant paths:

• registration
• duplicate registration if supported
• login success
• invalid credentials
• logout
• protected route without auth
• protected route with auth
• forbidden access
• token/session expiry
• refresh flow if supported
• password reset request/completion
• OAuth callback if affected
• middleware behavior