hatch3r 1.7.1 → 1.7.5

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").

package/rules/hatch3r-container-hardening.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-container-hardening
+type: rule
+description: Container image hardening — digest pinning, distroless / Wolfi base, non-root user, SBOM-in-image, cosign signing + verification, multi-stage builds, CVE scanning
+scope: "**/Dockerfile*,**/docker-compose*,**/*.containerfile,**/charts/**,**/k8s/**,**/kubernetes/**,**/manifests/**"
+tags: [security, devops]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Container Hardening
+
+## Base Image: Wolfi / Chainguard Images
+
+The 2026 baseline for container images is Wolfi-OS via Chainguard Images — rebuilt nightly from source, granular per-package versions, no kernel, distroless philosophy. Distroless (Google) remains a valid fallback when Chainguard's commercial offering is out of scope.
+
+- Pin every base image by digest, never by tag. Mutable tags (`latest`, `1`, `1.2`) are an attack vector — the registry can serve a different image under the same tag at any time.
+- Example: `FROM cgr.dev/chainguard/node:latest@sha256:<64-hex-digest>` (the `latest` tag is acceptable only when paired with a `@sha256:` digest pin; the digest is the authority).
+- Drift detection: a scheduled CI job re-resolves base-image tags and opens a PR when a newer digest publishes; reviewer inspects CVE delta before merging.
+
+## Multi-Stage Builds
+
+Separate the builder from the runtime image. The builder carries the full toolchain (compilers, package managers, dev headers); the runtime carries only the produced artifact plus a distroless or Wolfi base.
+
+- Builder stage: install build deps, compile, run tests. May be heavy.
+- Runtime stage: `FROM cgr.dev/chainguard/static:latest@sha256:...` (for static binaries) or `cgr.dev/chainguard/node:latest@sha256:...` (for Node services). `COPY --from=builder` only the artifacts needed at runtime.
+- Result: smaller image, fewer CVEs at runtime, no source code or build tools shipped to production.
+
+## Non-Root User
+
+Production containers run as a non-root user. Root-in-container plus container-escape-CVE equals root-on-host.
+
+- `USER 65532:65532` (the `nobody` UID on most distros) or a named non-root user declared in the Dockerfile.
+- Kubernetes pod security: `runAsNonRoot: true`, `runAsUser: 65532`, `runAsGroup: 65532`, `readOnlyRootFilesystem: true`, `allowPrivilegeEscalation: false`, `capabilities.drop: [ALL]`.
+- Writable paths use `emptyDir` or `persistentVolumeClaim` mounts, not the root filesystem.
+
+## No Shell, Minimal Binaries
+
+Distroless `:nonroot` variants and Chainguard `static` images ship without `/bin/sh`. A compromised process cannot fall back to a shell for lateral movement.
+
+- Production image set is `:nonroot` or `static`. Debug variants (`:debug`, `:debug-nonroot`) include `sh` and `busybox` and are pulled only for local troubleshooting.
+- `kubectl debug --image=cgr.dev/chainguard/wolfi-base` provides ephemeral debug containers without baking shells into production images.
+
+## SBOM-in-Image
+
+Every image carries a CycloneDX 1.6 SBOM, generated at build time and either embedded in the image or attached as an OCI artifact in the registry.
+
+- Generation: `syft <image> -o cyclonedx-json` or BuildKit `--attest type=sbom`. Chainguard Images already ship with attached SBOMs.
+- Attachment: `cosign attach sbom --sbom sbom.cdx.json <image>:<tag>` or BuildKit attestation in the OCI manifest.
+- Deploy-time consumers fetch the SBOM via `cosign download sbom <image>` and match against the CVE feed before admission.
+
+## Image Signing — cosign
+
+Every image is signed with cosign keyless mode via OIDC. Sigstore Fulcio issues a short-lived signing certificate scoped to the workflow identity; Rekor records the signature for tamper-evident audit.
+
+- Sign in CI: `cosign sign --yes <registry>/<image>@<digest>`. Workflow grants `id-token: write` permission; no long-lived signing key.
+- Verify at deploy: `cosign verify <image> --certificate-identity-regexp 'https://github\.com/org/repo/\.github/workflows/.*' --certificate-oidc-issuer https://token.actions.githubusercontent.com`.
+- Admission enforcement: Sigstore Policy Controller (native admission with CUE or Rego), Kyverno (`verifyImages` rule), or OPA Gatekeeper + Ratify. Unsigned images rejected at admission, not just warned.
+
+## CVE Scanning in CI
+
+Two scanners are run per image build: `trivy` for breadth (Wolfi advisory database, OS+language deps) and `grype` for Chainguard parity. Release is blocked on unpatched Critical or High CVEs without a documented suppression record.
+
+- `trivy image --severity HIGH,CRITICAL --exit-code 1 <image>:<tag>` fails the job on any High/Critical.
+- Periodic re-scan: a nightly job re-pulls each production image digest and rescans — newly-disclosed CVEs in already-deployed images surface here.
+- Suppressions documented in `.trivyignore` with CVE ID, justification, expiry date, and owner. Expired suppressions fail the build.
+
+## Digest Pinning Everywhere
+
+The same digest-not-tag rule extends beyond `FROM` lines to every place the image is referenced.
+
+- Kubernetes manifests: `image: <registry>/<image>@sha256:<digest>` in Deployment, StatefulSet, Job, CronJob.
+- Helm charts: `appVersion` references the digest; `image.tag` is the digest, not a semver tag.
+- GitOps repos (Argo CD, Flux): the source of truth is the digest; image-update controllers (`flux image-update`) bump the digest on signed-image admission events.
+- Pull policy: `imagePullPolicy: IfNotPresent` (digests are immutable so pull-once is safe); `Always` is only required when tags are used.
+
+## Reproducible Builds
+
+Build inputs are pinned so the same `git checkout` produces the same image digest.
+
+- `# syntax=docker/dockerfile:1.<minor>.<patch>` — pin to a specific BuildKit syntax version.
+- Package installs pin versions: `apk add --no-cache nodejs=20.11.1-r0` (Wolfi/Alpine), `apt-get install -y nodejs=20.11.1*` (Debian).
+- Deterministic `COPY` order: copy lockfile and install deps before copying source, so layer caching is stable.
+- `SOURCE_DATE_EPOCH` set from git commit timestamp strips filesystem timestamps.
+- Verify with `reproducible-containers/repro-build`: rebuild and compare digests; mismatches fail.
+
+## Secrets Handling in Images
+
+Secrets never enter the image at build time. Runtime injection only.
+
+- Forbidden: `COPY .env`, `ARG NPM_TOKEN`, `ENV API_KEY=...`. Build args persist in image history and are recoverable by anyone with image pull access.
+- Build-time secrets (private registry tokens, SSH keys) use BuildKit `--mount=type=secret,id=<name>` — mounted at build, never persisted.
+- Runtime secrets injected via container env (from Kubernetes Secret or vault sidecar), mounted file (CSI Secret Store driver), or IAM role / Workload Identity for cloud auth.
+
+## Health Checks
+
+Every long-running container declares readiness, liveness, and startup probes. Cross-reference `rules/hatch3r-operability.md`.
+
+- Dockerfile `HEALTHCHECK CMD <command>` for non-orchestrated deployments.
+- Kubernetes `livenessProbe`, `readinessProbe`, `startupProbe` with HTTP, TCP, or exec checks. Startup probe allows slow boots (e.g., JVM warmup) without failing liveness during startup.
+- Probe endpoints implemented at the application layer; `/healthz` (liveness), `/readyz` (readiness), `/startz` (startup) is the conventional split.
+
+## Image Size Budget
+
+Runtime image targets under 200 MB compressed. Builds exceeding 500 MB compressed page the platform team for review.
+
+- Strip debug symbols and source maps from production artifacts in the builder stage.
+- Single-binary services (Go, Rust) target Chainguard `static` images — typical runtime under 20 MB.
+- Multi-arch images do not multiply the size budget — each architecture is measured independently.
+
+## Verification Gate at Release
+
+Every release pipeline executes the following gates before publish, all green:
+
+- `cosign verify` against the workflow OIDC identity.
+- `trivy image` and `grype` zero Critical, zero High (or all High suppressed with documented expiry).
+- Image digest pinned in every consuming manifest (rejected if any `image:` line uses a tag without digest).
+- Pod spec runs as non-root (`runAsNonRoot: true`), read-only root filesystem, dropped capabilities.
+- SBOM attached and downloadable via `cosign download sbom`.
+
+Cross-reference `agents/hatch3r-security-auditor.md` for runtime security audit; `agents/hatch3r-devops.md` for delivery integration; `rules/hatch3r-secrets-management.md` for OIDC trust-policy conditions; `rules/hatch3r-dependency-management.md` for SBOM tooling and SLSA provenance.
+
+## References
+
+- Chainguard Images: https://edu.chainguard.dev/chainguard/chainguard-images/overview/
+- Distroless: https://github.com/GoogleContainerTools/distroless
+- Sigstore cosign: https://docs.sigstore.dev/cosign/overview/
+- Sigstore Policy Controller: https://docs.sigstore.dev/policy-controller/overview/
+- Kyverno image verification: https://kyverno.io/docs/policy-types/verify-images/sigstore/
+- SLSA v1.0 spec: https://slsa.dev/spec/v1.0/
+- Trivy: https://trivy.dev/latest/docs/target/container_image/
+- CISA tj-actions advisory (CVE-2025-30066): https://www.cisa.gov/news-events/alerts/2025/03/18/supply-chain-compromise-third-party-github-action