.cursorrules

# Cursor rules for aut.hair

# Testing & tooling
- Run tests with: PHPUNIT_DISABLE_RESULT_CACHE=1 /usr/local/bin/sail phpunit
- Use --filter for focused runs; keep cache disabled instead of changing file perms. If permission errors are encountered ask for help getting them changed before trying to continue.

# OIDC Core 1.0 alignment
- Signing: ID tokens MUST be RS256; JWKS MUST expose the matching key (n/e/kty/use/kid/alg) and kid must match the ID token header.
- Flows: Only authorization_code (and refresh) issue ID tokens; no implicit/hybrid/device/password/client_credentials ID tokens.
- Required ID token claims: iss, sub, aud, exp, iat, auth_time. Include nonce if provided in the auth request/code. Include at_hash when an access token is issued alongside the ID token.
- Nonce: propagate from auth request → auth code → ID token.
- PKCE: Require S256; plain is not allowed. Discovery must list only ["S256"] for code_challenge_methods_supported.
- max_age/auth_time: Record auth_time at login; if max_age is supplied and (now - auth_time) > max_age, force re-auth (e.g., redirect to login).
- UserInfo: Requires openid scope; claims gated by scopes (profile → name/picture, email → email/email_verified). Always include sub; do NOT include token claims (iss/aud/exp) in userinfo.
- Machine clients: Use OAuth2 client_credentials to mint access tokens (no ID token). /api/machine-info requires openid scope and returns client metadata.
- Logout: Validate id_token_hint when possible; post_logout_redirect_uri must be registered for the client; may fallback to parse for blacklist. RP logout is non-normative—keep validation strict.
- Revocation (RFC 7009): Requires client auth; revoke stored tokens and blacklist JWTs by jti.

# Discovery (/.well-known/openid-configuration)
- response_types_supported: ["code"]
- grant_types_supported: ["authorization_code","refresh_token","client_credentials"]
- code_challenge_methods_supported: ["S256"]
- id_token_signing_alg_values_supported: ["RS256"]
- subject_types_supported: ["public"]
- token_endpoint_auth_methods_supported: ["client_secret_post","client_secret_basic"]

# Middleware / routes
- /oauth/authorize uses OIDC auth_time middleware to capture auth_time and enforce max_age.
- Keep CSRF middleware on; disable per-test only when necessary.

# Code style & comments
- ASCII only unless file already uses Unicode. Add brief comments only for non-obvious/security-sensitive logic.
- Absolutely no editing vendor/ files; an alternative solution (like copying the file to our app and using composer to override the autoload, or implementing or extending something in order to make something redeployable work for production)
# Frontend / UI practices
- Stack: Vue 3 + Inertia + Vite; match the existing Options API SFC style unless fully migrating a file.
- Styling: Tailwind utilities first; keep light/dark variants paired and avoid inline styles when utilities cover it.
- Components: Prefer shared Jetstream/HeadlessUI pieces and existing shared components before adding new ones; use @heroicons/vue for icons with consistent sizing (e.g., w-5 h-5).
- Forms & requests: Stick with axios/Inertia patterns present in the file; surface server validation; debounce live queries when user typing drives network calls.
- UX: Provide loading/disabled states for async actions; keep keyboard/focus accessibility; set button types explicitly.
- Layout: Preserve responsive flex/stack behavior; sanity-check small and large viewport layouts.

# Testing patterns
- Use Carbon::setTestNow with explicit fixed instants.
- For max_age tests, set now to auth_time + (max_age + 1) to assert re-auth is required.
- PKCE tests: code_verifier length 43–128; code_challenge_method = S256.
- Token endpoint requests should be form-encoded (not JSON) unless the endpoint expects JSON.

# Security posture
- Do NOT re-enable implicit/hybrid flows.
- Do NOT issue ID tokens for password or client_credentials grants.
- Keep PKCE plain disabled.

# Process
- Add failing tests first for new OIDC features (TDD), then implement.
- If touching logout/revocation, validate id_token_hint and registered redirects per spec.