hatch3r 1.7.0 → 1.7.5

package/rules/hatch3r-api-versioning.mdc

@@ -0,0 +1,115 @@
+---
+description: API versioning, deprecation lifecycle, and idempotency — RFC 9457 errors, RFC 9745 Deprecation header, RFC 8594 Sunset, OAuth 2.1, Idempotency-Key, semver vs CalVer for APIs
+globs: ["**/api/**", "**/openapi*", "**/asyncapi*", "**/*.proto", "**/routes/**", "**/handlers/**", "**/controllers/**"]
+alwaysApply: false
+---
+# API Versioning, Deprecation & Idempotency
+
+Lifecycle rules for evolving REST, GraphQL, and gRPC contracts without breaking consumers. Pairs with `rules/hatch3r-api-design.md` (shape) and `rules/hatch3r-contract-testing.md` (verification).
+
+## Versioning Scheme
+
+- **Semver (`v1`, `v2`)** for stable contracts and published SDKs: major version goes in the URL prefix (`/v2/users`) for breaking changes; minor and patch updates are field-level additive and stay within the same major.
+- **CalVer (`2026-05-15`)** for rolling APIs that change frequently (Stripe-style date-based versioning): clients pin a date via `Stripe-Version` / `Api-Version` header; the server transforms newer responses down to the pinned date.
+- Pick one scheme per API and document it in the spec — never mix semver and CalVer in the same surface.
+- Within a major (semver) or pinned date (CalVer), only additive changes ship: new fields, new endpoints, new enum values (when consumers handle `unknown` fallback).
+
+## Deprecation Lifecycle (RFC 9745 + RFC 8594)
+
+Every retirement passes three stages. Skipping any stage breaks downstream consumers.
+
+| Stage | Header(s) | Action |
+|-------|-----------|--------|
+| Announce | `Deprecation: @<unix-ts>` (RFC 9745, Mar 2025 Standards Track) + `Link: <https://docs.example.com/migrate/v2>; rel="deprecation"` | Emit on every deprecated endpoint/field response; log usage by `X-Api-Key` / authenticated identity. |
+| Sunset | `Sunset: <HTTP-date>` (RFC 8594) | Set N months before removal: N=6 public, N=3 partner, N=1 internal. Pair with continued `Deprecation` header. |
+| Remove | HTTP 410 Gone + Problem Details (`type: https://errors.example.com/sunset`, `title: Endpoint removed`) | Only after the sunset date passes AND analytics show <0.1% usage for two consecutive 7-day windows. |
+
+- Field-level deprecation: emit `Deprecation` per endpoint that still returns the field; GraphQL uses `@deprecated(reason: "...")`; protobuf uses `[deprecated = true]`.
+- Document the migration in the `Link: ...rel="deprecation"` target — include before/after code samples, fallback strategy, and the removal date.
+
+## Idempotency-Key (draft-ietf-httpapi-idempotency-key-header)
+
+Every side-effectful endpoint (POST / PATCH / PUT / DELETE that mutates state) accepts an `Idempotency-Key: <client-generated-uuid>` request header.
+
+- **Key format:** UUIDv4 or ULID, max 255 chars. Clients generate; servers never accept server-generated keys.
+- **Storage:** server persists `(tenant_id, api_key, idempotency_key, request_body_hash, response_status, response_body)` for 24 hours (configurable per API; Stripe uses 24h, recommended range 24h-7d).
+- **Replay semantics:**
+  - Exact replay (same key + same request body hash) -> return the original response (same status, same body, same `Idempotency-Replay: true` header).
+  - Conflicting replay (same key + different request body hash) -> 422 with Problem Details `type: https://errors.example.com/idempotency-conflict`.
+  - In-flight replay (same key, original still processing) -> 409 Conflict + `Retry-After: <seconds>`.
+- **Scope:** per `(tenant_id, api_key)`, never global. Hashing the body prevents replay-with-mutation attacks.
+
+## Rate Limit Headers (draft-ietf-httpapi-ratelimit-headers)
+
+Emit structured-field headers on every response (not just 429):
+
+| Header | Value | Purpose |
+|--------|-------|---------|
+| `RateLimit-Policy` | `100;w=60` | Quota + window length (seconds). |
+| `RateLimit-Limit` | `100` | Maximum requests in current window. |
+| `RateLimit-Remaining` | `42` | Remaining quota in current window. |
+| `RateLimit-Reset` | `30` | Seconds until the window resets. |
+
+- On 429, also include `Retry-After: <seconds>` (RFC 9110).
+- Vendor-specific `X-RateLimit-*` headers may be emitted alongside for backward compatibility, but the IETF draft headers are the floor.
+
+## OAuth 2.1 (draft-ietf-oauth-v2-1)
+
+- **PKCE mandatory on all clients** (public and confidential) — `code_challenge` + `code_challenge_method=S256`.
+- **Implicit and password (ROPC) grants removed.** Use authorization code + PKCE for interactive; client credentials for server-server; device code for input-constrained.
+- **Exact redirect-URI matching** — no wildcards, no partial paths. Pre-register each callback URL.
+- **Refresh-token rotation with reuse detection** — on every refresh, issue a new refresh token and invalidate the old one. If the old token is presented after rotation, revoke the entire token family (replay attack signal).
+- Access tokens short-lived (5-15 min). Long-lived refresh tokens, sender-constrained (DPoP or mTLS) for public clients.
+- Full auth detail: `rules/hatch3r-auth-patterns.md`.
+
+## Resource Indicators (RFC 8707)
+
+- Token requests include a `resource=<uri>` parameter naming the protected resource the token will be presented to.
+- Authorization servers bind the token's `aud` claim to the requested resource — prevents audience-confusion attacks across multi-tenant AS deployments.
+- Multi-resource consent flows pass multiple `resource` params; the AS issues separate tokens per audience.
+
+## DPoP (RFC 9449)
+
+- Sender-constrained access and refresh tokens for browser-resident clients (SPAs) — alternative to mTLS for public clients.
+- Client generates a key pair (non-extractable in the browser via WebCrypto), signs a fresh DPoP JWT per request, sends in `DPoP: <jwt>` header.
+- Server binds the access token's `cnf.jkt` claim (JWK thumbprint) to the client's public key; rejects token presentation from any other key.
+- Recommended floor for any token leaving the first-party boundary (third-party SDK consumers, mobile apps with insecure storage).
+
+## Webhook Signing (Standard Webhooks convention)
+
+- Headers: `webhook-id` (unique delivery ID), `webhook-timestamp` (unix seconds), `webhook-signature` (`v1,<base64-HMAC-SHA256(<id>.<timestamp>.<body>)>`).
+- HMAC-SHA256 with a per-tenant shared secret, constant-time comparison.
+- Reject deliveries where `|now - webhook-timestamp| > 300` seconds (5-minute replay window).
+- `webhook-id` doubles as the idempotency key on the receiver — cache for >=5 minutes (Redis/SQLite) to dedupe duplicate deliveries.
+- **Key rotation:** signature spec supports comma-separated versions (`v1,sig1 v2,sig2`); receivers accept any valid version during the rollover window.
+- Deliveries that fail signature verification return HTTP 401 + Problem Details `type: https://errors.example.com/invalid-signature`.
+
+## Backward Compatibility Policy
+
+- **Field additions** are always safe.
+- **Field removal or rename** requires the full RFC 9745 + RFC 8594 lifecycle (Announce -> Sunset -> Remove). Never remove without the lifecycle.
+- **Enum extension** is safe only when consumers handle an `unknown` fallback value. Generated client code (OpenAPI Generator, openapi-typescript) must emit the `unknown` branch.
+- **Nullable transitions** (required -> optional, or non-null -> nullable) require a feature flag and a deprecation window — clients written against the stricter shape will break on `null`.
+- **Type changes** (e.g., `int32` -> `int64` in protobuf, `string` -> `string | null` in OpenAPI) require a new major version unless the wire format is unchanged (protobuf int32->int64 is wire-compatible for small values; document the edge case).
+
+## CI Gates
+
+Every PR touching an API contract runs the matching diff tool against the last shipped tag. Breaking changes block merge.
+
+- `oasdiff breaking` (OpenAPI 3.0 + 3.1, 450+ rules, CNCF Sandbox) — comments on the PR with the breaking-change list.
+- `buf breaking` (Protobuf, default `FILE` rule set) — blocks wire + source incompatibility.
+- `graphql-inspector diff` — blocks GraphQL schema breaking changes.
+
+All three integrate with PR comments and fail the build on a breaking exit code. Cross-reference the gate set in `rules/hatch3r-api-design.md` "Breaking-Change CI Gate".
+
+## References
+
+- RFC 9457 — Problem Details for HTTP APIs (March 2025, obsoletes RFC 7807).
+- RFC 9745 — The Deprecation HTTP Response Header Field (March 2025, Standards Track).
+- RFC 8594 — The Sunset HTTP Response Header Field.
+- RFC 8707 — Resource Indicators for OAuth 2.0.
+- RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP).
+- draft-ietf-oauth-v2-1 — The OAuth 2.1 Authorization Framework.
+- draft-ietf-httpapi-idempotency-key-header — The Idempotency-Key HTTP Header Field.
+- draft-ietf-httpapi-ratelimit-headers — RateLimit Header Fields for HTTP.
+- Standard Webhooks — https://github.com/standard-webhooks/standard-webhooks

package/rules/hatch3r-auth-patterns.md

@@ -0,0 +1,170 @@
+---
+id: hatch3r-auth-patterns
+type: rule
+description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
+scope: "**/auth/**,**/login/**,**/session/**,**/oauth/**,**/oidc/**,**/jwt/**,**/permissions/**,**/policies/**,**/middleware/**"
+tags: [security, implementation]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Authentication & Authorization Patterns
+
+Backend-side identity stack for end-user apps. Pairs with `rules/hatch3r-passkey-server.md` (WebAuthn server ceremony) and the frontend rules `rules/hatch3r-ux-states-and-flows.md` + `rules/hatch3r-ai-ux-patterns.md` (identifier-first login, passkey Conditional UI).
+
+## OAuth 2.1 (Name It)
+
+Adopt OAuth 2.1 (`draft-ietf-oauth-v2-1`, draft-15 Mar 2026) over OAuth 2.0. Reference RFC 9700 (OAuth Security BCP, Jan 2025) as the operative compliance bar.
+
+- PKCE required on every public client (web SPA, mobile, desktop) AND every confidential client.
+- Implicit grant REMOVED. Resource Owner Password Credentials (ROPC) grant REMOVED. Never use either.
+- Exact redirect-URI string matching. No wildcards, no substring match, no prefix match.
+- Refresh-token rotation with reuse detection: on detected reuse, revoke the entire refresh-token family and force re-authentication.
+- Access-token TTL 5-15 min; refresh-token TTL bounded (8-72h sliding for SPAs, longer for native).
+- Authorization Code grant + PKCE is the only public-client grant. Client Credentials for service-to-service.
+
+## OIDC ID-Token Validation
+
+Every ID token received from an OIDC provider must validate ALL of the following before a session is created:
+
+| Check | Rule |
+|-------|------|
+| `iss` | Equal to the expected issuer URL (string match) |
+| `aud` | Contains this client's `client_id` |
+| `azp` | Equals `client_id` when present and when `aud` has multiple values |
+| `exp` | Now < `exp` |
+| `iat` | `now - iat` within tolerable skew (default 5 min) |
+| `auth_time` | Sanity-checked against session policy (max-age, prompt=login) |
+| `nonce` | Equals the nonce generated for this authorization request (replay defense) |
+| Signature | Verified against the issuer's JWKS; `kid` selects the current key |
+
+Logout: implement BOTH RP-initiated logout (`end_session_endpoint` per OIDC RP-Initiated Logout 1.0) AND back-channel logout (server-to-server session-invalidation callback) for SSO sessions. ID-token-only state has no server invalidation path — pair with a server-side session record.
+
+## DPoP — Sender-Constrained Tokens (RFC 9449)
+
+For browser-resident or public-client access tokens, bind tokens to a client-held key with DPoP. Replaces mTLS for clients that cannot manage certificates.
+
+- Client generates an ECDSA or RSA keypair, stored non-extractable (WebCrypto `extractable: false`).
+- Every protected request carries a `DPoP` header — a signed JWT with claims `htm` (HTTP method), `htu` (full URL), `iat`, `jti` (replay-cache key), and the public JWK in `jwk` header.
+- Access token contains a `cnf.jkt` claim — SHA-256 JWK thumbprint of the bound key. Server verifies the DPoP-proof JWK thumbprint matches the access token's `cnf.jkt`.
+- Server replay cache stores `jti` for the proof's `iat` window (default 60s skew + 5 min retention).
+- Service-to-service: prefer mTLS (`x5t#S256` cnf claim) where the certificate chain is manageable; DPoP for browser/mobile.
+
+## JWT Pitfalls (RFC 8725 BCP)
+
+- Reject `alg: none` always. Reject `alg: HS*` when the verification key is public (RS256/ES256 key-confusion attack).
+- Pin the expected `alg` per issuer. Server config names the algorithm — never trust the `alg` header without an allowlist.
+- JWKS endpoint cache TTL 1-24 hours. `kid` selects the current key. Rotation supported by publishing N+1 before retiring N (overlap window >= 2 * cache TTL).
+- Audience binding mandatory. Each service has its own `aud` value and rejects tokens not minted for it.
+- Revocation strategy: short access-TTL + periodic refresh OR introspection (RFC 7662) OR a revocation list for long-TTL tokens. Never assume tokens are revocable without one of these.
+- No PII, no sensitive data in JWT payload. JWT payloads are base64-readable by anyone holding the token.
+
+## Cookie Security
+
+Every auth-bearing cookie must set:
+
+- `__Host-` prefix — implies `Path=/`, `Secure`, no `Domain` attribute. The prefix blocks subdomain shadowing.
+- `HttpOnly` — blocks JS read.
+- `Secure` — TLS-only transmission.
+- `SameSite=Strict` for primary session cookies. Use `Lax` only when cross-site GET reads are required.
+- `SameSite=None` REQUIRES `Partitioned` per CHIPS. Chrome's 2026 enforcement plan treats unpartitioned third-party cookies as deprecated.
+- Short expiry (8-72h sliding); rolling refresh on activity.
+
+CSRF defense ordering: `SameSite=Strict` is the primary defense for session cookies. Add a double-submit token (Origin/Cookie pair) for state-changing requests reachable from `SameSite=Lax` cookies. Validate `Origin` and `Sec-Fetch-Site` headers on high-value mutations.
+
+## MFA and NIST 800-63B-4 AAL Mapping
+
+NIST SP 800-63B-4 (finalized mid-2025) demoted SMS to a restricted authenticator. Email OTP is deprecated. Map operations to AAL:
+
+| Level | Authenticators | Use Case |
+|-------|---------------|----------|
+| AAL1 | Single factor — password OR WebAuthn UV | Low-risk reads, public-facing content |
+| AAL2 | Two factor — password + TOTP, OR passkey (WebAuthn) with UV | Account access, settings changes |
+| AAL3 | Hardware-bound multi-factor — WebAuthn UV with hardware-backed key | Admin actions, financial transfers, key rotation |
+
+Step-up auth pattern: when a session is AAL1 and a sensitive op is requested (delete account, change email, change password, transfer funds, rotate API key, change billing), re-prompt the user for a fresh authentication. Issue a short-lived step-up token (5-15 min) carrying the AAL upgrade, scoped to the operation.
+
+## Authorization Model Rubric
+
+Pick the model per app complexity. Document the choice in the project spec.
+
+| Model | Use When | Engines |
+|-------|----------|---------|
+| **RBAC** (roles to permissions) | Flat-org tools, role count <20, permissions don't depend on resource attributes | App-layer; CASL; Pundit |
+| **ABAC** (attributes to policy) | Access depends on user/resource attributes — department, region, classification, time-of-day | OPA (Rego), AWS Cedar |
+| **ReBAC** (relationships to permissions) | Collaboration apps with sharing graphs — "user can edit doc if member of folder shared with team" | SpiceDB, OpenFGA, Permify, AuthZed |
+
+ReBAC reference: Google Zanzibar paper (USENIX ATC 2019). For new collaboration apps, default to ReBAC over hand-rolled per-resource ACL tables.
+
+**AuthZEN Authorization API 1.0** (OIDF Final, Jan 2026) — engine-neutral PEP-to-PDP wire format. Adopt for service architectures where authorization is centralized.
+
+## Multi-Tenancy Isolation
+
+- Every tenant-scoped table carries a `tenant_id` column.
+- Postgres Row-Level Security policies enforce isolation at the DB layer: `CREATE POLICY tenant_isolation ON {table} USING (tenant_id = current_setting('app.tenant_id')::uuid)`.
+- Per-tenant signing keys for sensitive crypto operations (BYOK pattern for Level 4 data per `rules/hatch3r-data-classification.md`).
+- Cross-tenant access attempts return 404, not 403 — never confirm tenant existence to unauthorized callers.
+- Integration tests assert cross-tenant access returns 404 on every tenant-scoped endpoint.
+
+## Token Storage on Client
+
+- Web: never `localStorage` or `sessionStorage` for tokens. Use `HttpOnly` `__Host-` cookies for sessions, OR in-memory access token + `HttpOnly` refresh cookie (BFF / silent-refresh pattern).
+- Mobile iOS: Keychain Services with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`.
+- Mobile Android: EncryptedSharedPreferences backed by Android Keystore.
+- Never log full tokens. Log the `jti` (token ID) only for audit correlation.
+
+## Secret Rotation Cadence
+
+- Automated via HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager — never manual.
+- Rotation cadence per secret type — see `rules/hatch3r-secrets-management.md`.
+- Zero-downtime rotation pattern: publish N+1, wait >= 2 * cache TTL, switch signing to N+1, retire N after refresh-token max-age.
+
+## Auth Provider 2026 Landscape — Roll vs Buy
+
+Decision rubric: managed for B2B + SSO/SAML/SCIM requirements; self-host when compliance forbids third-party identity OR when cost crosses break-even at scale.
+
+| Provider | Sweet Spot |
+|----------|-----------|
+| Clerk | Best DX for React/Next.js consumer apps |
+| Supabase Auth | Postgres-native + RLS-integrated stacks |
+| WorkOS | Enterprise SSO + SCIM + Directory Sync |
+| Auth0 / Okta | Enterprise B2B with mature compliance |
+| Stytch | Passwordless + WebAuthn focus |
+| Better Auth | OSS framework-agnostic, full control |
+| Auth.js (NextAuth.js) | Next.js with minimal external dependency |
+| FusionAuth / Keycloak / Ory | Self-host with full IdP capability |
+
+## API Key Design
+
+- Prefix convention for secret-scanner detection (`sk_live_*`, `pk_live_*`).
+- Hash-only storage server-side (Argon2id or SHA-256 with per-key salt); never store plaintext.
+- Per-key scope grants (resource + method allowlist).
+- Per-key rate limit; per-key usage analytics with last-used timestamp.
+- Revocation API; rotate quarterly; never log the full key value.
+- For human users, replace API keys with passkeys + short-lived tokens.
+
+## Audit Logging for Auth Events
+
+Every auth event logged with `actor` (user_id), `target` (resource_id), `ip`, `user_agent`, `result` (success/failure/code), `timestamp`, and `trace_id` for SIEM correlation. Tamper-resistant append-only store; 1-year retention minimum.
+
+Required event set: login success, login failure, MFA challenge issued, MFA verified, MFA failed, password reset requested, password reset completed, email change, role/scope grant, role/scope revoke, token issued, token revoked, session terminated, passkey added, passkey removed, step-up auth challenge, step-up auth verified.
+
+## Cross-References
+
+- `rules/hatch3r-passkey-server.md` — server-side WebAuthn ceremony (paired companion).
+- `rules/hatch3r-ux-states-and-flows.md` — frontend identifier-first login + Conditional UI.
+- `rules/hatch3r-ai-ux-patterns.md` — frontend WebAuthn UX patterns.
+- `rules/hatch3r-api-versioning.md` — OAuth 2.1 in the API-versioning context.
+- `rules/hatch3r-secrets-management.md` — JWT signing key + OAuth client secret rotation cadence.
+- `rules/hatch3r-data-classification.md` — multi-tenant data isolation + BYOK.
+
+## References
+
+- RFC 9700 — OAuth 2.0 Security Best Current Practice (Jan 2025).
+- RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP).
+- RFC 8725 — JSON Web Token Best Current Practice.
+- `draft-ietf-oauth-v2-1` — The OAuth 2.1 Authorization Framework.
+- OpenID Connect Core 1.0 + RP-Initiated Logout 1.0 + Back-Channel Logout 1.0.
+- NIST SP 800-63B-4 — Digital Identity Guidelines: Authentication and Authenticator Management.
+- FAPI 2.0 Final (Feb 2025) — Financial-grade API profiles.
+- AuthZEN Authorization API 1.0 Final (OpenID Foundation, Jan 2026).
+- Google Zanzibar — Consistent, Global Authorization (USENIX ATC 2019).

package/rules/hatch3r-auth-patterns.mdc

@@ -0,0 +1,166 @@
+---
+description: Authentication and authorization patterns for end-user apps — OAuth 2.1, OIDC, DPoP, JWT rotation, cookie security, RBAC vs ABAC vs ReBAC rubric
+globs: ["**/auth/**", "**/login/**", "**/session/**", "**/oauth/**", "**/oidc/**", "**/jwt/**", "**/permissions/**", "**/policies/**", "**/middleware/**"]
+alwaysApply: false
+---
+# Authentication & Authorization Patterns
+
+Backend-side identity stack for end-user apps. Pairs with `rules/hatch3r-passkey-server.md` (WebAuthn server ceremony) and the frontend rules `rules/hatch3r-ux-states-and-flows.md` + `rules/hatch3r-ai-ux-patterns.md` (identifier-first login, passkey Conditional UI).
+
+## OAuth 2.1 (Name It)
+
+Adopt OAuth 2.1 (`draft-ietf-oauth-v2-1`, draft-15 Mar 2026) over OAuth 2.0. Reference RFC 9700 (OAuth Security BCP, Jan 2025) as the operative compliance bar.
+
+- PKCE required on every public client (web SPA, mobile, desktop) AND every confidential client.
+- Implicit grant REMOVED. Resource Owner Password Credentials (ROPC) grant REMOVED. Never use either.
+- Exact redirect-URI string matching. No wildcards, no substring match, no prefix match.
+- Refresh-token rotation with reuse detection: on detected reuse, revoke the entire refresh-token family and force re-authentication.
+- Access-token TTL 5-15 min; refresh-token TTL bounded (8-72h sliding for SPAs, longer for native).
+- Authorization Code grant + PKCE is the only public-client grant. Client Credentials for service-to-service.
+
+## OIDC ID-Token Validation
+
+Every ID token received from an OIDC provider must validate ALL of the following before a session is created:
+
+| Check | Rule |
+|-------|------|
+| `iss` | Equal to the expected issuer URL (string match) |
+| `aud` | Contains this client's `client_id` |
+| `azp` | Equals `client_id` when present and when `aud` has multiple values |
+| `exp` | Now < `exp` |
+| `iat` | `now - iat` within tolerable skew (default 5 min) |
+| `auth_time` | Sanity-checked against session policy (max-age, prompt=login) |
+| `nonce` | Equals the nonce generated for this authorization request (replay defense) |
+| Signature | Verified against the issuer's JWKS; `kid` selects the current key |
+
+Logout: implement BOTH RP-initiated logout (`end_session_endpoint` per OIDC RP-Initiated Logout 1.0) AND back-channel logout (server-to-server session-invalidation callback) for SSO sessions. ID-token-only state has no server invalidation path — pair with a server-side session record.
+
+## DPoP — Sender-Constrained Tokens (RFC 9449)
+
+For browser-resident or public-client access tokens, bind tokens to a client-held key with DPoP. Replaces mTLS for clients that cannot manage certificates.
+
+- Client generates an ECDSA or RSA keypair, stored non-extractable (WebCrypto `extractable: false`).
+- Every protected request carries a `DPoP` header — a signed JWT with claims `htm` (HTTP method), `htu` (full URL), `iat`, `jti` (replay-cache key), and the public JWK in `jwk` header.
+- Access token contains a `cnf.jkt` claim — SHA-256 JWK thumbprint of the bound key. Server verifies the DPoP-proof JWK thumbprint matches the access token's `cnf.jkt`.
+- Server replay cache stores `jti` for the proof's `iat` window (default 60s skew + 5 min retention).
+- Service-to-service: prefer mTLS (`x5t#S256` cnf claim) where the certificate chain is manageable; DPoP for browser/mobile.
+
+## JWT Pitfalls (RFC 8725 BCP)
+
+- Reject `alg: none` always. Reject `alg: HS*` when the verification key is public (RS256/ES256 key-confusion attack).
+- Pin the expected `alg` per issuer. Server config names the algorithm — never trust the `alg` header without an allowlist.
+- JWKS endpoint cache TTL 1-24 hours. `kid` selects the current key. Rotation supported by publishing N+1 before retiring N (overlap window >= 2 * cache TTL).
+- Audience binding mandatory. Each service has its own `aud` value and rejects tokens not minted for it.
+- Revocation strategy: short access-TTL + periodic refresh OR introspection (RFC 7662) OR a revocation list for long-TTL tokens. Never assume tokens are revocable without one of these.
+- No PII, no sensitive data in JWT payload. JWT payloads are base64-readable by anyone holding the token.
+
+## Cookie Security
+
+Every auth-bearing cookie must set:
+
+- `__Host-` prefix — implies `Path=/`, `Secure`, no `Domain` attribute. The prefix blocks subdomain shadowing.
+- `HttpOnly` — blocks JS read.
+- `Secure` — TLS-only transmission.
+- `SameSite=Strict` for primary session cookies. Use `Lax` only when cross-site GET reads are required.
+- `SameSite=None` REQUIRES `Partitioned` per CHIPS. Chrome's 2026 enforcement plan treats unpartitioned third-party cookies as deprecated.
+- Short expiry (8-72h sliding); rolling refresh on activity.
+
+CSRF defense ordering: `SameSite=Strict` is the primary defense for session cookies. Add a double-submit token (Origin/Cookie pair) for state-changing requests reachable from `SameSite=Lax` cookies. Validate `Origin` and `Sec-Fetch-Site` headers on high-value mutations.
+
+## MFA and NIST 800-63B-4 AAL Mapping
+
+NIST SP 800-63B-4 (finalized mid-2025) demoted SMS to a restricted authenticator. Email OTP is deprecated. Map operations to AAL:
+
+| Level | Authenticators | Use Case |
+|-------|---------------|----------|
+| AAL1 | Single factor — password OR WebAuthn UV | Low-risk reads, public-facing content |
+| AAL2 | Two factor — password + TOTP, OR passkey (WebAuthn) with UV | Account access, settings changes |
+| AAL3 | Hardware-bound multi-factor — WebAuthn UV with hardware-backed key | Admin actions, financial transfers, key rotation |
+
+Step-up auth pattern: when a session is AAL1 and a sensitive op is requested (delete account, change email, change password, transfer funds, rotate API key, change billing), re-prompt the user for a fresh authentication. Issue a short-lived step-up token (5-15 min) carrying the AAL upgrade, scoped to the operation.
+
+## Authorization Model Rubric
+
+Pick the model per app complexity. Document the choice in the project spec.
+
+| Model | Use When | Engines |
+|-------|----------|---------|
+| **RBAC** (roles to permissions) | Flat-org tools, role count <20, permissions don't depend on resource attributes | App-layer; CASL; Pundit |
+| **ABAC** (attributes to policy) | Access depends on user/resource attributes — department, region, classification, time-of-day | OPA (Rego), AWS Cedar |
+| **ReBAC** (relationships to permissions) | Collaboration apps with sharing graphs — "user can edit doc if member of folder shared with team" | SpiceDB, OpenFGA, Permify, AuthZed |
+
+ReBAC reference: Google Zanzibar paper (USENIX ATC 2019). For new collaboration apps, default to ReBAC over hand-rolled per-resource ACL tables.
+
+**AuthZEN Authorization API 1.0** (OIDF Final, Jan 2026) — engine-neutral PEP-to-PDP wire format. Adopt for service architectures where authorization is centralized.
+
+## Multi-Tenancy Isolation
+
+- Every tenant-scoped table carries a `tenant_id` column.
+- Postgres Row-Level Security policies enforce isolation at the DB layer: `CREATE POLICY tenant_isolation ON {table} USING (tenant_id = current_setting('app.tenant_id')::uuid)`.
+- Per-tenant signing keys for sensitive crypto operations (BYOK pattern for Level 4 data per `rules/hatch3r-data-classification.md`).
+- Cross-tenant access attempts return 404, not 403 — never confirm tenant existence to unauthorized callers.
+- Integration tests assert cross-tenant access returns 404 on every tenant-scoped endpoint.
+
+## Token Storage on Client
+
+- Web: never `localStorage` or `sessionStorage` for tokens. Use `HttpOnly` `__Host-` cookies for sessions, OR in-memory access token + `HttpOnly` refresh cookie (BFF / silent-refresh pattern).
+- Mobile iOS: Keychain Services with `kSecAttrAccessibleWhenUnlockedThisDeviceOnly`.
+- Mobile Android: EncryptedSharedPreferences backed by Android Keystore.
+- Never log full tokens. Log the `jti` (token ID) only for audit correlation.
+
+## Secret Rotation Cadence
+
+- Automated via HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager — never manual.
+- Rotation cadence per secret type — see `rules/hatch3r-secrets-management.md`.
+- Zero-downtime rotation pattern: publish N+1, wait >= 2 * cache TTL, switch signing to N+1, retire N after refresh-token max-age.
+
+## Auth Provider 2026 Landscape — Roll vs Buy
+
+Decision rubric: managed for B2B + SSO/SAML/SCIM requirements; self-host when compliance forbids third-party identity OR when cost crosses break-even at scale.
+
+| Provider | Sweet Spot |
+|----------|-----------|
+| Clerk | Best DX for React/Next.js consumer apps |
+| Supabase Auth | Postgres-native + RLS-integrated stacks |
+| WorkOS | Enterprise SSO + SCIM + Directory Sync |
+| Auth0 / Okta | Enterprise B2B with mature compliance |
+| Stytch | Passwordless + WebAuthn focus |
+| Better Auth | OSS framework-agnostic, full control |
+| Auth.js (NextAuth.js) | Next.js with minimal external dependency |
+| FusionAuth / Keycloak / Ory | Self-host with full IdP capability |
+
+## API Key Design
+
+- Prefix convention for secret-scanner detection (`sk_live_*`, `pk_live_*`).
+- Hash-only storage server-side (Argon2id or SHA-256 with per-key salt); never store plaintext.
+- Per-key scope grants (resource + method allowlist).
+- Per-key rate limit; per-key usage analytics with last-used timestamp.
+- Revocation API; rotate quarterly; never log the full key value.
+- For human users, replace API keys with passkeys + short-lived tokens.
+
+## Audit Logging for Auth Events
+
+Every auth event logged with `actor` (user_id), `target` (resource_id), `ip`, `user_agent`, `result` (success/failure/code), `timestamp`, and `trace_id` for SIEM correlation. Tamper-resistant append-only store; 1-year retention minimum.
+
+Required event set: login success, login failure, MFA challenge issued, MFA verified, MFA failed, password reset requested, password reset completed, email change, role/scope grant, role/scope revoke, token issued, token revoked, session terminated, passkey added, passkey removed, step-up auth challenge, step-up auth verified.
+
+## Cross-References
+
+- `rules/hatch3r-passkey-server.md` — server-side WebAuthn ceremony (paired companion).
+- `rules/hatch3r-ux-states-and-flows.md` — frontend identifier-first login + Conditional UI.
+- `rules/hatch3r-ai-ux-patterns.md` — frontend WebAuthn UX patterns.
+- `rules/hatch3r-api-versioning.md` — OAuth 2.1 in the API-versioning context.
+- `rules/hatch3r-secrets-management.md` — JWT signing key + OAuth client secret rotation cadence.
+- `rules/hatch3r-data-classification.md` — multi-tenant data isolation + BYOK.
+
+## References
+
+- RFC 9700 — OAuth 2.0 Security Best Current Practice (Jan 2025).
+- RFC 9449 — OAuth 2.0 Demonstrating Proof of Possession (DPoP).
+- RFC 8725 — JSON Web Token Best Current Practice.
+- `draft-ietf-oauth-v2-1` — The OAuth 2.1 Authorization Framework.
+- OpenID Connect Core 1.0 + RP-Initiated Logout 1.0 + Back-Channel Logout 1.0.
+- NIST SP 800-63B-4 — Digital Identity Guidelines: Authentication and Authenticator Management.
+- FAPI 2.0 Final (Feb 2025) — Financial-grade API profiles.
+- AuthZEN Authorization API 1.0 Final (OpenID Foundation, Jan 2026).
+- Google Zanzibar — Consistent, Global Authorization (USENIX ATC 2019).

package/rules/hatch3r-component-conventions.md

@@ -10,6 +10,15 @@ cache_friendly: true
 ---
 # Component Conventions
 
+## Library and Token Detection (Mandatory Pre-Author Step)
+
+Before authoring any new UI primitive, complete this scan and reuse > extend > create:
+
+- Scan `package.json` for `@radix-ui/*`, shadcn (`components.json`), Tailwind v4, MUI, or Chakra. If a matching primitive exists in those libraries, extend it instead of writing a new one.
+- Locate the token source: `tokens.json` (DTCG spec, 2025.10 revision), `src/styles/tokens.css`, Tailwind `@theme` block (v4), or `tailwind.config.{js,ts}` (v3 fallback). Reference the token by name — never hardcode the resolved value.
+- Map the component library convention before writing files: shadcn projects use `src/components/ui/*`; non-shadcn projects typically use `src/components/primitives/*`. Place new files in the existing directory layout.
+- Cross-reference `rules/hatch3r-design-system-detection.md` for the full detection workflow and tooling.
+
 ## Structure
 
 - Use framework-recommended component syntax (e.g., `<script setup>` for Vue).
@@ -41,6 +50,20 @@ cache_friendly: true
 
 ## State Patterns (Required)
 
+### Four-State Surface Contract
+
+Every async view must render all four states. A missing state is a blocker for merge.
+
+- **Loading:** skeleton with explicit `width` and `height` matching the final content dimensions to prevent Cumulative Layout Shift (CLS). Generic spinners on content surfaces are insufficient.
+- **Empty:** distinguish three sub-types, each with the matching CTA:
+  - Cold-start (no data ever) — onboarding CTA (e.g., "Create your first project").
+  - Active-filter (filters/search exclude all data) — clear-filters CTA.
+  - No-permission (auth scope blocks access) — request-access CTA.
+- **Error:** show the cause, a retry action, and a fallback path; use a corrective verb ("Try again", "Reload"). Never use "Oops" or generic copy that hides the cause.
+- **Partial:** when some data resolves and some fails, render a banner explaining the gap plus the degraded data plus a retry control for the failed slice.
+
+Cross-reference `rules/hatch3r-ux-states-and-flows.md` for the full state-flow specification.
+
 ### Loading States
 - Use skeleton screens (not spinners) for content areas — match the layout shape of the loaded content.
 - Apply a shimmer/pulse CSS animation on skeletons to indicate activity.
@@ -88,6 +111,13 @@ cache_friendly: true
 - Provide clear success feedback: redirect to the result page or display a success toast.
 - Prevent double submission by disabling the button and ignoring duplicate submit events during pending requests.
 
+### Error Recovery
+- Clear inline field errors immediately when the user enters a corrective character — no debounce on the clear path.
+- Re-enable the submit button in real time as the form returns to a valid state.
+- On submit with errors, render an error summary at the top of the form with anchor links to each invalid field; move focus to the summary container, not to the first invalid field.
+- Required attributes on inputs: `autocomplete` (HTML autofill tokens), `inputmode` (matches expected character set), `aria-describedby` (links help/format hints), and `aria-invalid="true"` once invalid.
+- Never use a disabled submit button as the only error signal — disabled state is unreadable to many screen readers and gives no recovery path.
+
 ### Accessible Labels
 - Every `<input>`, `<select>`, and `<textarea>` must have a visible `<label>` element with a matching `for`/`id` pair.
 - Mark required fields with a visual asterisk (`*`) and screen-reader-only text ("required").

package/rules/hatch3r-component-conventions.mdc

@@ -5,6 +5,15 @@ alwaysApply: false
 ---
 # Component Conventions
 
+## Library and Token Detection (Mandatory Pre-Author Step)
+
+Before authoring any new UI primitive, complete this scan and reuse > extend > create:
+
+- Scan `package.json` for `@radix-ui/*`, shadcn (`components.json`), Tailwind v4, MUI, or Chakra. If a matching primitive exists in those libraries, extend it instead of writing a new one.
+- Locate the token source: `tokens.json` (DTCG spec, 2025.10 revision), `src/styles/tokens.css`, Tailwind `@theme` block (v4), or `tailwind.config.{js,ts}` (v3 fallback). Reference the token by name — never hardcode the resolved value.
+- Map the component library convention before writing files: shadcn projects use `src/components/ui/*`; non-shadcn projects typically use `src/components/primitives/*`. Place new files in the existing directory layout.
+- Cross-reference `rules/hatch3r-design-system-detection.md` for the full detection workflow and tooling.
+
 ## Structure
 
 - Use framework-recommended component syntax (e.g., `<script setup>` for Vue).
@@ -36,6 +45,20 @@ alwaysApply: false
 
 ## State Patterns (Required)
 
+### Four-State Surface Contract
+
+Every async view must render all four states. A missing state is a blocker for merge.
+
+- **Loading:** skeleton with explicit `width` and `height` matching the final content dimensions to prevent Cumulative Layout Shift (CLS). Generic spinners on content surfaces are insufficient.
+- **Empty:** distinguish three sub-types, each with the matching CTA:
+  - Cold-start (no data ever) — onboarding CTA (e.g., "Create your first project").
+  - Active-filter (filters/search exclude all data) — clear-filters CTA.
+  - No-permission (auth scope blocks access) — request-access CTA.
+- **Error:** show the cause, a retry action, and a fallback path; use a corrective verb ("Try again", "Reload"). Never use "Oops" or generic copy that hides the cause.
+- **Partial:** when some data resolves and some fails, render a banner explaining the gap plus the degraded data plus a retry control for the failed slice.
+
+Cross-reference `rules/hatch3r-ux-states-and-flows.md` for the full state-flow specification.
+
 ### Loading States
 - Use skeleton screens (not spinners) for content areas — match the layout shape of the loaded content.
 - Apply a shimmer/pulse CSS animation on skeletons to indicate activity.
@@ -83,6 +106,13 @@ alwaysApply: false
 - Provide clear success feedback: redirect to the result page or display a success toast.
 - Prevent double submission by disabling the button and ignoring duplicate submit events during pending requests.
 
+### Error Recovery
+- Clear inline field errors immediately when the user enters a corrective character — no debounce on the clear path.
+- Re-enable the submit button in real time as the form returns to a valid state.
+- On submit with errors, render an error summary at the top of the form with anchor links to each invalid field; move focus to the summary container, not to the first invalid field.
+- Required attributes on inputs: `autocomplete` (HTML autofill tokens), `inputmode` (matches expected character set), `aria-describedby` (links help/format hints), and `aria-invalid="true"` once invalid.
+- Never use a disabled submit button as the only error signal — disabled state is unreadable to many screen readers and gives no recovery path.
+
 ### Accessible Labels
 - Every `<input>`, `<select>`, and `<textarea>` must have a visible `<label>` element with a matching `for`/`id` pair.
 - Mark required fields with a visual asterisk (`*`) and screen-reader-only text ("required").