📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,276 @@
+# Example: Challenging Custom Auth Build
+
+## Scenario
+
+User proposes building a custom authentication system from scratch instead of using an existing auth provider.
+
+## Challenge Session
+
+### IDENTIFY: Build vs Buy
+
+**Proposal**: "I'm going to build our own authentication system. We'll need password hashing with bcrypt, JWT token generation, refresh token rotation, email verification, password reset flows, and session management."
+
+**Complexity Smell Detected**: Build vs Buy
+- Auth is security-critical with many edge cases
+- Battle-tested solutions exist (Auth0, Clerk, BetterAuth, Lucia)
+- Custom auth requires ongoing security maintenance
+- High risk of subtle vulnerabilities
+
+**Escalation Level**: ◆◆ Hazard
+
+### ALTERNATIVE: Propose Simpler Solutions
+
+**Response**:
+> ◆◆ **Hazard**: Building custom authentication is high-risk. Auth has numerous security considerations: timing attacks, token expiry edge cases, secure password reset flows, account enumeration prevention, brute force protection, and more. Professional auth services employ security teams to handle these. Custom implementations frequently have vulnerabilities.
+>
+> I strongly recommend using a proven auth solution. Here are options by use case:
+
+**Option 1: Clerk (Recommended for most apps)**
+
+```typescript
+// app/layout.tsx
+import { ClerkProvider } from '@clerk/nextjs'
+
+export default function RootLayout({ children }) {
+  return (
+    <ClerkProvider>
+      {children}
+    </ClerkProvider>
+  )
+}
+
+// app/dashboard/page.tsx
+import { auth } from '@clerk/nextjs'
+
+export default async function Dashboard() {
+  const { userId } = auth()
+  if (!userId) redirect('/sign-in')
+
+  return <div>Protected content</div>
+}
+```
+
+**Benefits**:
+- Setup: ~15 minutes
+- Built-in UI components
+- Social login, MFA, user management
+- SOC 2 compliant
+- Free tier for development
+
+**Option 2: BetterAuth (Self-hosted, full control)**
+
+```typescript
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  database: db,
+  emailAndPassword: {
+    enabled: true,
+    requireEmailVerification: true
+  },
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET
+    }
+  }
+})
+
+// Middleware
+export async function middleware(request: Request) {
+  const session = await auth.getSession(request)
+  if (!session) return redirect('/login')
+}
+```
+
+**Benefits**:
+- Self-hosted (full data control)
+- Type-safe, modern DX
+- Handles security edge cases
+- Active maintenance
+- Open source
+
+**Option 3: Lucia (Minimal, framework-agnostic)**
+
+```typescript
+import { Lucia } from 'lucia'
+import { BetterSqlite3Adapter } from '@lucia-auth/adapter-sqlite'
+
+const adapter = new BetterSqlite3Adapter(db)
+export const lucia = new Lucia(adapter, {
+  sessionCookie: {
+    attributes: {
+      secure: process.env.NODE_ENV === 'production'
+    }
+  }
+})
+
+// Usage
+const session = await lucia.createSession(userId, {})
+const sessionCookie = lucia.createSessionCookie(session.id)
+```
+
+**Benefits**:
+- Lightweight core
+- Framework flexibility
+- Session management only (pair with password hashing library)
+- Well-documented
+
+**Comparison**:
+
+| Approach | Setup Time | Security Maintenance | Features | Cost |
+|----------|-----------|---------------------|----------|------|
+| Custom Auth | 40+ hours | Ongoing, high-risk | As implemented | Developer time |
+| Clerk | 15 min | None (managed) | Comprehensive | Free → $25/mo |
+| BetterAuth | 2 hours | Low (library maintained) | Comprehensive | $0 (self-hosted) |
+| Lucia | 4 hours | Medium (some assembly) | Core features | $0 |
+
+### QUESTION: Investigate Constraints
+
+**Critical questions**:
+1. "What specific requirement makes existing auth solutions insufficient?"
+2. "Do you have a security team to review and maintain the auth system?"
+3. "Are you prepared for the ongoing maintenance burden when security vulnerabilities are discovered?"
+4. "What unique auth flow do you need that can't be configured with existing providers?"
+5. "Have you considered the liability if user data is compromised due to an auth vulnerability?"
+6. "What's your threat model? Who are you protecting against?"
+
+### Likely Answers & Responses
+
+**If "We need full control over user data"**:
+> "BetterAuth and Lucia are self-hosted - you maintain complete control over user data in your own database. Clerk also offers self-hosted enterprise options. Control doesn't require building from scratch."
+
+**If "We have unique requirements for [specific flow]"**:
+> "What's the specific requirement? Most auth providers support custom flows:
+> - **Custom fields**: Clerk metadata, BetterAuth custom schema
+> - **Custom verification**: Email/SMS hooks available
+> - **Multi-tenancy**: Built into most providers
+> - **Custom UI**: All providers allow custom UI with their APIs
+>
+> Can you describe the unique flow? Let's verify it truly requires custom auth."
+
+**If "Auth services are too expensive"**:
+> "Let's compare costs:
+>
+> | Solution | Monthly Cost | Developer Time Saved |
+> |----------|--------------|---------------------|
+> | Clerk Free | $0 (up to 10k users) | 40+ hours initial + ongoing |
+> | BetterAuth | $0 (self-hosted) | 38 hours initial + reduced ongoing |
+> | Custom | $0 infrastructure | 0 saved, high ongoing risk |
+>
+> Even at $25/month, Clerk pays for itself in saved developer time within the first week. Security vulnerabilities in custom auth can cost far more in remediation and reputation damage."
+
+**If "I want to learn how auth works"**:
+> "Learning auth internals is valuable, but production systems aren't ideal learning environments. Consider:
+> 1. Build a learning project with custom auth to understand the concepts
+> 2. Read auth library source code (Lucia is excellent for this)
+> 3. Use a proven solution for production
+>
+> Auth mistakes in production can leak user data. The learning value isn't worth the security risk."
+
+**If "We're already partially built"**:
+> "How far along? If you're:
+> - **Week 1-2**: Still early enough to migrate to proven solution
+> - **Using bcrypt + JWT**: Most auth libraries support migration from existing password hashes
+> - **In production**: Assess security posture, plan migration timeline
+>
+> Migration is usually worth the cost to reduce security risk."
+
+### DOCUMENT: Record Decision
+
+**If proceeding with custom auth** (requires strong justification):
+
+```markdown
+## ADR: Custom Authentication System
+
+**Decision**: Build custom authentication system
+
+**Context**:
+- Requirement: [SPECIFIC UNIQUE REQUIREMENT THAT CANNOT BE MET BY EXISTING SOLUTIONS]
+- Constraints: [e.g., Regulatory requirement for specific implementation, air-gapped environment]
+- Team: Security expert [NAME] will review and maintain
+
+**Security Measures**:
+- [ ] Security audit by external firm before production
+- [ ] Penetration testing quarterly
+- [ ] Automated security scanning in CI/CD
+- [ ] Threat model documented
+- [ ] Incident response plan prepared
+- [ ] Rate limiting on all auth endpoints
+- [ ] Account enumeration prevention
+- [ ] Timing attack mitigation
+- [ ] Secure password reset flow
+- [ ] Session fixation prevention
+- [ ] CSRF protection
+- [ ] Brute force protection
+
+**Alternatives Considered**:
+- Clerk: Rejected because [specific reason]
+- BetterAuth: Rejected because [specific reason]
+- Lucia: Rejected because [specific reason]
+
+**Consequences**:
+- **Pros**: [specific benefits that justify the risk]
+- **Cons**: High maintenance burden, security liability, slower feature velocity
+- **Mitigation**: Dedicated security resources, regular audits
+
+**Review**: Security review required every 6 months or after any auth-related changes.
+
+**TODO**: Revisit if [specific constraint] is resolved - migrate to managed solution.
+```
+
+**If proceeding with BetterAuth** (likely outcome):
+
+```typescript
+// lib/auth.ts
+// Using BetterAuth for security-critical authentication.
+// Self-hosted for data control, but leverages battle-tested library to avoid
+// common auth vulnerabilities (timing attacks, token management, password reset flows).
+//
+// Migration from custom auth: BetterAuth supports importing existing bcrypt password hashes.
+// Review security: https://better-auth.com/docs/security
+
+import { betterAuth } from 'better-auth'
+
+export const auth = betterAuth({
+  database: db,
+  // ... configuration
+})
+```
+
+## Outcome
+
+**Result**: User agrees to use BetterAuth for self-hosted auth with data control.
+
+**Time saved**: 40+ hours initial implementation, countless hours of future security maintenance
+
+**Security risk avoided**: High - custom auth implementations frequently have vulnerabilities
+
+**Cost avoided**: Potential security breach, user data compromise, reputation damage
+
+## Key Lessons
+
+1. **Security-critical features favor proven solutions**: Auth, crypto, payments - use libraries
+2. **"Control" doesn't require "custom"**: Self-hosted solutions provide control without risk
+3. **Developer time is expensive**: Even "free" custom solutions have high hidden costs
+4. **Future liability matters**: Auth breaches can be company-ending events
+5. **Learning environments ≠ production**: Explore concepts in side projects, use proven solutions for users
+
+## Red Flags That Triggered Escalation
+
+- Security-critical system (◆◆ Hazard level)
+- Many edge cases requiring expertise
+- Proven alternatives exist
+- High ongoing maintenance burden
+- Potential for catastrophic failure
+- User data at risk
+
+## When Custom Auth Might Be Justified
+
+Rare scenarios where custom auth is appropriate:
+- Air-gapped military/government systems
+- Regulatory requirement for specific implementation (must verify with legal)
+- Integration with legacy enterprise auth system with no standard protocol
+- Research on authentication methods (non-production)
+
+Even then, build on top of secure primitives (Argon2, proven JWT libraries) rather than from scratch.
@@ -0,0 +1,173 @@
+# Example: Challenging Redux for Simple Form
+
+## Scenario
+
+User proposes using Redux + Redux Saga for managing a 3-field contact form (name, email, message).
+
+## Challenge Session
+
+### IDENTIFY: Framework Overkill
+
+**Proposal**: "I want to set up Redux with Redux Saga to manage the contact form state. We'll need actions for field updates, form submission, validation errors, and API status."
+
+**Complexity Smell Detected**: Framework Overkill
+- Redux + Saga = ~50 LOC boilerplate for 3 fields
+- Time-travel debugging not needed for contact form
+- No complex async orchestration required
+- Single form, no shared state across components
+
+**Escalation Level**: ◆ Caution
+
+### ALTERNATIVE: Propose Simpler Solutions
+
+**Response**:
+> ◆ **Caution**: Redux + Saga adds significant complexity for this use case. This pattern is typically used for complex apps with shared state across many components. For a single contact form, this will likely cause maintenance burden without clear benefits.
+>
+> Here are simpler alternatives that meet the requirements:
+
+**Option 1: React useState (Recommended)**
+
+```typescript
+function ContactForm() {
+  const [form, setForm] = useState({ name: '', email: '', message: '' })
+  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
+
+  const handleSubmit = async (e: FormEvent) => {
+    e.preventDefault()
+    setStatus('loading')
+    try {
+      await submitContact(form)
+      setStatus('success')
+    } catch (err) {
+      setStatus('error')
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={form.name}
+        onChange={e => setForm(prev => ({ ...prev, name: e.target.value }))}
+      />
+      {/* email, message fields ... */}
+      <button disabled={status === 'loading'}>Submit</button>
+    </form>
+  )
+}
+```
+
+**Option 2: React Hook Form (If validation is complex)**
+
+```typescript
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+
+function ContactForm() {
+  const { register, handleSubmit, formState: { isSubmitting, errors } } = useForm({
+    resolver: zodResolver(contactSchema)
+  })
+
+  const onSubmit = async (data) => {
+    await submitContact(data)
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+      {/* ... */}
+    </form>
+  )
+}
+```
+
+**Comparison**:
+
+| Approach | LOC | Dependencies | Learning Curve | Maintenance |
+|----------|-----|--------------|----------------|-------------|
+| Redux + Saga | ~150 | 2 libraries | High | High |
+| useState | ~30 | 0 | Low | Low |
+| React Hook Form | ~40 | 1 library | Medium | Low |
+
+### QUESTION: Investigate Constraints
+
+**Questions to ask**:
+1. "Will this form state need to be shared across multiple components or pages?"
+2. "Do you need time-travel debugging or state persistence for this form?"
+3. "Is there complex async orchestration (dependent requests, polling, retry logic)?"
+4. "Will the form scale to 20+ fields with complex validation rules?"
+5. "Does the team have existing Redux infrastructure this would integrate with?"
+
+### Likely Answers & Responses
+
+**If "We might add more forms later"**:
+> "Let's start with useState for this form. When we add the second form, we'll have concrete requirements and can decide if shared state management is needed. Adding Redux later is straightforward if justified."
+
+**If "I want to learn Redux"**:
+> "Learning Redux is valuable, but production code isn't the ideal learning environment. Consider building a Redux tutorial app separately, then apply it to work projects when requirements justify it. For this contact form, simpler patterns will ship faster and be easier to maintain."
+
+**If "We need the form data in the header component"**:
+> "If you need to lift state, you can pass it through props or use React Context. Here's how:
+>
+> ```typescript
+> const FormContext = createContext()
+>
+> function App() {
+>   const [contactData, setContactData] = useState(null)
+>   return (
+>     <FormContext.Provider value={{ contactData, setContactData }}>
+>       <Header />
+>       <ContactForm />
+>     </FormContext.Provider>
+>   )
+> }
+> ```
+>
+> This still avoids Redux boilerplate while enabling state sharing."
+
+### DOCUMENT: Record Decision
+
+**If proceeding with Redux** (unlikely after questioning):
+
+```markdown
+## ADR: Redux for Contact Form
+
+**Decision**: Use Redux + Redux Saga for contact form state management
+
+**Context**: Contact form requires state sharing with [specific component], complex async orchestration for [specific workflow], and integration with existing Redux store managing [other domain].
+
+**Consequences**:
+- **Pros**: Consistent state management pattern across app, debugging with Redux DevTools
+- **Cons**: Increased boilerplate (~150 LOC vs ~30 LOC), steeper learning curve for new contributors
+- **Mitigation**: Isolate form logic in dedicated slice, document with examples
+
+**Review**: Revisit if form remains isolated without cross-component state needs after 3 months.
+```
+
+**If proceeding with useState** (likely outcome):
+
+```typescript
+// ContactForm.tsx
+// Using useState for simplicity - form state is local and doesn't need sharing.
+// If requirements change (shared state, complex validation), consider React Hook Form or Zustand.
+
+function ContactForm() {
+  const [form, setForm] = useState({ name: '', email: '', message: '' })
+  // ...
+}
+```
+
+## Outcome
+
+**Result**: User agrees to start with `useState`, with plan to revisit if requirements evolve.
+
+**Time saved**: ~2 hours setup + ongoing maintenance burden avoided
+
+**Technical debt avoided**: Unnecessary abstraction that would confuse future maintainers
+
+## Key Lessons
+
+1. **Framework choice should match problem scale**: Redux excels at complex state; overkill for simple forms
+2. **Reversibility matters**: Starting simple → complex is easier than complex → simple
+3. **Concrete alternatives convince**: Code examples beat abstract arguments
+4. **Question assumptions**: "We might need it later" rarely justifies current complexity