@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/better-auth/better-auth-security-best-practices/SKILL.MD

@@ -0,0 +1,432 @@
+---
+name: better-auth-security-best-practices
+description: Configure rate limiting, manage auth secrets, set up CSRF protection, define trusted origins, secure sessions and cookies, encrypt OAuth tokens, track IP addresses, and implement audit logging for Better Auth. Use when users need to secure their auth setup, prevent brute force attacks, or harden a Better Auth deployment.
+---
+
+## Secret Management
+
+### Configuring the Secret
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  secret: process.env.BETTER_AUTH_SECRET, // or via `BETTER_AUTH_SECRET` env
+});
+```
+
+Better Auth looks for secrets in this order:
+1. `options.secret` in your config
+2. `BETTER_AUTH_SECRET` environment variable
+3. `AUTH_SECRET` environment variable
+
+### Secret Requirements
+
+- Rejects default/placeholder secrets in production
+- Warns if shorter than 32 characters or entropy below 120 bits
+- Generate: `openssl rand -base64 32`
+- Never commit secrets to version control
+
+## Rate Limiting
+
+Enabled in production by default. Applies to all endpoints. Plugins can override per-endpoint.
+
+### Default Configuration
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  rateLimit: {
+    enabled: true, // Default: true in production
+    window: 10, // Time window in seconds (default: 10)
+    max: 100, // Max requests per window (default: 100)
+  },
+});
+```
+
+### Storage Options
+
+Options: `"memory"` (resets on restart, avoid on serverless), `"database"` (persistent), `"secondary-storage"` (Redis, default when available).
+
+```ts
+rateLimit: {
+  storage: "database",
+}
+```
+
+### Custom Storage
+
+Implement your own rate limit storage:
+
+```ts
+rateLimit: {
+  customStorage: {
+    get: async (key) => {
+      // Return { count: number, expiresAt: number } or null
+    },
+    set: async (key, data) => {
+      // Store the rate limit data
+    },
+  },
+}
+```
+
+### Per-Endpoint Rules
+
+Sensitive endpoints default to 3 requests per 10 seconds (`/sign-in`, `/sign-up`, `/change-password`, `/change-email`). Override:
+
+```ts
+rateLimit: {
+  customRules: {
+    "/api/auth/sign-in/email": {
+      window: 60, // 1 minute window
+      max: 5, // 5 attempts
+    },
+    "/api/auth/some-safe-endpoint": false, // Disable rate limiting
+  },
+}
+```
+
+## CSRF Protection
+
+Multi-layer protection: origin header validation, Fetch Metadata checks, and first-login protection.
+
+### Configuration
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  advanced: {
+    disableCSRFCheck: false, // Default: false (keep enabled)
+  },
+});
+```
+
+Only disable for testing or with an alternative CSRF mechanism.
+
+## Trusted Origins
+
+### Configuring Trusted Origins
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  baseURL: "https://api.example.com",
+  trustedOrigins: [
+    "https://app.example.com",
+    "https://admin.example.com",
+  ],
+});
+```
+
+The `baseURL` origin is automatically trusted. Also configurable via env: `BETTER_AUTH_TRUSTED_ORIGINS=https://app.example.com,https://admin.example.com`
+
+### Wildcard Patterns
+
+```ts
+trustedOrigins: [
+  "*.example.com", // Matches any subdomain
+  "https://*.example.com", // Protocol-specific wildcard
+  "exp://192.168.*.*:*/*", // Custom schemes (e.g., Expo)
+]
+```
+
+### Dynamic Trusted Origins
+
+Compute trusted origins based on the request:
+
+```ts
+trustedOrigins: async (request) => {
+  // Validate against database, header, etc.
+  const tenant = getTenantFromRequest(request);
+  return [`https://${tenant}.myapp.com`];
+}
+```
+
+Validates `callbackURL`, `redirectTo`, `errorCallbackURL`, `newUserCallbackURL`, and `origin` against trusted origins. Invalid URLs receive 403.
+
+## Session Security
+
+### Session Expiration
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days (default)
+    updateAge: 60 * 60 * 24, // Refresh session every 24 hours (default)
+  },
+});
+```
+
+### Session Caching Strategies
+
+Cache session data in cookies to reduce database queries:
+
+```ts
+session: {
+  cookieCache: {
+    enabled: true,
+    maxAge: 60 * 5, // 5 minutes
+    strategy: "compact", // Options: "compact", "jwt", "jwe"
+  },
+}
+```
+
+Strategies: `"compact"` (Base64url + HMAC, smallest), `"jwt"` (HS256, standard), `"jwe"` (encrypted, use when session has sensitive data).
+
+## Cookie Security
+
+Defaults: `secure: true` (HTTPS/production), `sameSite: "lax"`, `httpOnly: true`, `path: "/"`, prefix `__Secure-`.
+
+### Custom Cookie Configuration
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  advanced: {
+    useSecureCookies: true, // Force secure cookies
+    cookiePrefix: "myapp", // Custom prefix (default: "better-auth")
+    defaultCookieAttributes: {
+      sameSite: "strict", // Stricter CSRF protection
+      path: "/auth", // Limit cookie scope
+    },
+  },
+});
+```
+
+### Cross-Subdomain Cookies
+
+```ts
+advanced: {
+  crossSubDomainCookies: {
+    enabled: true,
+    domain: ".example.com", // Note the leading dot
+    additionalCookies: ["session_token", "session_data"],
+  },
+}
+```
+
+Only enable if you need authentication sharing and trust all subdomains.
+
+## OAuth / Social Provider Security
+
+PKCE is automatic for all OAuth flows. State tokens are 32-char random strings expiring after 10 minutes.
+
+### State Parameter Storage
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  account: {
+    storeStateStrategy: "cookie", // Options: "cookie" (default), "database"
+  },
+});
+```
+
+### Encrypting OAuth Tokens
+
+```ts
+account: {
+  encryptOAuthTokens: true, // Uses AES-256-GCM
+}
+```
+
+Enable if storing OAuth tokens for API access on behalf of users. Use `skipStateCookieCheck: true` only for mobile apps that cannot maintain cookies.
+
+## IP-Based Security
+
+### IP Address Configuration
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  advanced: {
+    ipAddress: {
+      ipAddressHeaders: ["x-forwarded-for", "x-real-ip"], // Headers to check
+      disableIpTracking: false, // Keep enabled for rate limiting
+    },
+  },
+});
+```
+
+Set `ipv6Subnet` (128, 64, 48, 32; default 64) to group IPv6 addresses. Enable `trustedProxyHeaders: true` only if behind a trusted reverse proxy.
+
+## Database Hooks for Security Auditing
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  databaseHooks: {
+    session: {
+      create: {
+        after: async ({ data, ctx }) => {
+          await auditLog("session.created", {
+            userId: data.userId,
+            ip: ctx?.request?.headers.get("x-forwarded-for"),
+            userAgent: ctx?.request?.headers.get("user-agent"),
+          });
+        },
+      },
+      delete: {
+        before: async ({ data }) => {
+          await auditLog("session.revoked", { sessionId: data.id });
+        },
+      },
+    },
+    user: {
+      update: {
+        after: async ({ data, oldData }) => {
+          if (oldData?.email !== data.email) {
+            await auditLog("user.email_changed", {
+              userId: data.id,
+              oldEmail: oldData?.email,
+              newEmail: data.email,
+            });
+          }
+        },
+      },
+    },
+    account: {
+      create: {
+        after: async ({ data }) => {
+          await auditLog("account.linked", {
+            userId: data.userId,
+            provider: data.providerId,
+          });
+        },
+      },
+    },
+  },
+});
+```
+
+Return `false` from a `before` hook to prevent an operation.
+
+## Background Tasks
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  advanced: {
+    backgroundTasks: {
+      handler: (promise) => {
+        // Platform-specific handler
+        // Vercel: waitUntil(promise)
+        // Cloudflare: ctx.waitUntil(promise)
+        waitUntil(promise);
+      },
+    },
+  },
+});
+```
+
+Ensures operations like sending emails don't affect response timing.
+
+## Account Enumeration Prevention
+
+Built-in: consistent response messages, dummy operations on invalid requests, background email sending. Return generic error messages ("Invalid credentials") rather than specific ones ("User not found").
+
+## Complete Security Configuration Example
+
+```ts
+import { betterAuth } from "better-auth";
+
+export const auth = betterAuth({
+  secret: process.env.BETTER_AUTH_SECRET,
+  baseURL: "https://api.example.com",
+  trustedOrigins: [
+    "https://app.example.com",
+    "https://*.preview.example.com",
+  ],
+  
+  // Rate limiting
+  rateLimit: {
+    enabled: true,
+    storage: "secondary-storage",
+    customRules: {
+      "/api/auth/sign-in/email": { window: 60, max: 5 },
+      "/api/auth/sign-up/email": { window: 60, max: 3 },
+    },
+  },
+  
+  // Session security
+  session: {
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+    updateAge: 60 * 60 * 24, // 24 hours
+    freshAge: 60 * 60, // 1 hour for sensitive actions
+    cookieCache: {
+      enabled: true,
+      maxAge: 300,
+      strategy: "jwe", // Encrypted session data
+    },
+  },
+  
+  // OAuth security
+  account: {
+    encryptOAuthTokens: true,
+    storeStateStrategy: "cookie",
+  },
+  
+  
+  // Advanced settings
+  advanced: {
+    useSecureCookies: true,
+    cookiePrefix: "myapp",
+    defaultCookieAttributes: {
+      sameSite: "lax",
+    },
+    ipAddress: {
+      ipAddressHeaders: ["x-forwarded-for"],
+      ipv6Subnet: 64,
+    },
+    backgroundTasks: {
+      handler: (promise) => waitUntil(promise),
+    },
+  },
+  
+  // Security auditing
+  databaseHooks: {
+    session: {
+      create: {
+        after: async ({ data, ctx }) => {
+          console.log(`New session for user ${data.userId}`);
+        },
+      },
+    },
+    user: {
+      update: {
+        after: async ({ data, oldData }) => {
+          if (oldData?.email !== data.email) {
+            console.log(`Email changed for user ${data.id}`);
+          }
+        },
+      },
+    },
+  },
+});
+```
+
+## Security Checklist
+
+Before deploying to production:
+
+- [ ] **Secret**: Use a strong, unique secret (32+ characters, high entropy)
+- [ ] **HTTPS**: Ensure `baseURL` uses HTTPS
+- [ ] **Trusted Origins**: Configure all valid origins (frontend, mobile apps)
+- [ ] **Rate Limiting**: Keep enabled with appropriate limits
+- [ ] **CSRF Protection**: Keep enabled (`disableCSRFCheck: false`)
+- [ ] **Secure Cookies**: Enabled automatically with HTTPS
+- [ ] **OAuth Tokens**: Consider `encryptOAuthTokens: true` if storing tokens
+- [ ] **Background Tasks**: Configure for serverless platforms
+- [ ] **Audit Logging**: Implement via `databaseHooks` or `hooks`
+- [ ] **IP Tracking**: Configure headers if behind a proxy

package/dist/skills/frameworks/effect/effect-authoring/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: effect-authoring
+description: >-
+  Use when asked to plan, write, build, fix, refactor, or review Effect-TS
+  code. Apply before editing so the first implementation follows repo
+  conventions for Effect primitives, branded IDs, observability, error design,
+  `@effect/vitest`, and Effect-Atom, especially in `packages/api`.
+---
+
+# Effect-TS Authoring Guide
+
+Use this skill before edits. Optimize for correct code on first pass, not a scorecard after the fact.
+
+## Workflow
+
+### Step 1: Classify the Task Before Writing
+
+Sort the requested change into the smallest relevant set:
+
+- **Backend Effect code**: Effect services, procedures, repositories, layers, schemas, domain actions
+- **Test code**: `.test.ts` files, test layers, failure-path coverage
+- **UI / Effect-Atom code**: `.tsx` files using Effect-Atom, RPC, HttpApi clients
+
+Skip config/docs unless they change the implementation contract.
+
+### Step 2: Load Only the References Needed for the Task
+
+Read the minimum reference set before editing:
+
+- **Backend Effect code**: `references/effect-primitives.md`, `references/branded-types.md`, `references/otel-patterns.md`, `references/error-patterns.md`
+- **Test code**: `references/test-patterns.md`
+- **UI / Effect-Atom code**: `references/effect-atom-patterns.md`
+
+If uncertain about Effect library behavior, run `opensrc path effect` or `opensrc path Effect-TS/effect` to resolve the local checkout path, then inspect there instead of guessing.
+
+### Step 3: Build a Pre-Write Checklist
+
+Turn the loaded references into a short implementation checklist for the exact files/functions being changed.
+
+For backend Effect work, check for these constraints up front:
+
+- Make dependencies visible as Effect requirements or `Effect.Service` dependencies; do not hide them behind concrete imports
+- Provide implementations with `Layer`s; avoid call-site `Effect.provide` except at runner/test boundaries
+- Use Effect primitives over native patterns where the repo expects them: `Array`, `Match`, `Option`, `Schema`, `Effect.forEach`, `Layer`
+- Avoid `try/catch`, `async/await`, `console.log`, ad-hoc validation, and plain `Error` classes in Effect code
+- Carry branded IDs through boundaries; do not fall back to raw `string` / `number`
+- Use named `Effect.fn("Service.method")` wrappers for named effectful functions
+- Annotate spans with essential IDs and business context only
+- Prefer `Schema.TaggedError` and `catchTag` with rich context over generic failures
+
+For test work, check for these constraints up front:
+
+- Use `@effect/vitest`, not plain `vitest`
+- Prefer `it.layer(...)` and `it.scoped(...)`
+- Replace Effect services with test layers, not `vi.mock`
+- Test failures with `Effect.either` / tagged errors, not `try/catch`
+
+For UI work, check for these constraints up front:
+
+- Prefer Effect-Atom typesafe clients for first-party Effect backends
+- Avoid `useEffect` + `fetch` state machines when an atom/query should own the data flow
+
+### Step 4: Inspect Local Patterns Before Editing
+
+Read adjacent modules before writing:
+
+- existing tagged error names
+- local branded type definitions
+- layer composition style
+- service/action boundaries
+- trace naming conventions
+- nearby test harness patterns
+
+Prefer repo-local patterns over generic examples from the references.
+
+### Step 5: Write the Code Against the Checklist
+
+Implement directly against the pre-write checklist. Treat the references as authoring constraints, not post-hoc review criteria.
+
+If a reference conflicts with established local conventions, follow the local convention and call out the mismatch briefly in the final response.
+
+Do not start with a review-style `git diff` workflow when the task is code generation or refactoring. Start from the requested change and the target files.
+
+### Step 6: Validate Immediately After Editing
+
+Run the narrowest useful validation for the touched area:
+
+- targeted tests
+- relevant typecheck
+- lint if the changed surface is lint-sensitive
+- any repo-specific command that proves the new behavior
+
+If validation fails, fix the code before moving on.
+
+### Step 7: Switch to Review Mode Only When Needed
+
+Use review-style findings only when:
+
+- the user explicitly asks for a review, audit, or score
+- the task is read-only
+- a final spot-check is needed after implementation
+
+In review mode, use the same references, but report findings instead of treating them as a pre-write checklist.
+
+Do not default to spawning review subagents during authoring. That adds latency and pushes correctness to the end of the workflow.
+
+## Reference Files
+
+Load on demand:
+
+- `references/effect-primitives.md` — Effect Array, Match, Option, Schema, `Effect.forEach`, Layer
+- `references/branded-types.md` — branded IDs and boundary consistency
+- `references/otel-patterns.md` — `Effect.fn`, span annotations, structured logging
+- `references/error-patterns.md` — `Schema.TaggedError`, `catchTag`, error context
+- `references/test-patterns.md` — `@effect/vitest`, `it.layer`, failure-path testing
+- `references/effect-atom-patterns.md` — Effect-Atom queries, mutations, client patterns

package/dist/skills/frameworks/effect/effect-authoring/references/branded-types.md

@@ -0,0 +1,98 @@
+# Branded Types Checklist
+
+## Core Rule
+
+All entity IDs MUST use branded types via `Schema.brand()`. Never use plain `string` or `number` for IDs. This prevents mixing up IDs of different entity types at compile time.
+
+## How to Define Branded Types
+
+```typescript
+import { Schema } from "effect"
+
+// Integer IDs
+export const UserId = Schema.Int.pipe(Schema.brand("@myorg/schema/UserId"))
+export type UserId = Schema.Schema.Type<typeof UserId>
+
+// String IDs
+export const ApiKey = Schema.String.pipe(Schema.brand("@myorg/schema/ApiKey"))
+export type ApiKey = Schema.Schema.Type<typeof ApiKey>
+
+// FromString variants (for URL params that arrive as strings)
+export const UserIdFromString = Schema.NumberFromString.pipe(
+  Schema.brand("@myorg/schema/UserId")
+)
+```
+
+Define branded types for every entity ID in your domain (e.g., `UserId`, `OrganizationId`, `ProjectId`, `OrderId`, `ProductId`, etc.) and colocate them in a shared branded types module.
+
+## Checklist
+
+### 1. Function Parameters Use Branded Types Directly
+
+```typescript
+// GOOD
+const findById = (userId: UserId, organizationId: OrganizationId) => ...
+
+// BAD
+const findById = (userId: number, organizationId: number) => ...
+```
+
+### 2. No `as` Casting for IDs
+
+```typescript
+// GOOD
+import { Schema } from "effect"
+const id = Schema.decodeSync(UserId)(rawValue)
+// or use the branded constructor
+const id = UserId.make(rawValue)
+
+// BAD
+const id = rawValue as UserId
+const id = someNumber as unknown as UserId
+```
+
+### 3. *FromString Variants for URL/Route Params
+
+URL params arrive as strings. Use `*FromString` schemas to decode them.
+
+```typescript
+// GOOD
+const params = Schema.Struct({
+  userId: UserIdFromString,
+  projectId: ProjectIdFromString,
+})
+
+// BAD
+const userId = parseInt(req.params.userId) as UserId
+```
+
+### 4. Database Schema Alignment
+
+When a database column uses a branded type, all code accessing that column must use the same branded type throughout. Check that:
+- Repository method params match column types
+- Service method params propagate branded types (not plain numbers)
+- API handler params decode to branded types before passing to services
+
+### 5. No Plain string/number in Domain Types
+
+```typescript
+// GOOD
+interface OrderConfig {
+  orderId: OrderId
+  userId: UserId
+}
+
+// BAD
+interface OrderConfig {
+  orderId: number
+  userId: number
+}
+```
+
+## Where to Check
+
+- Function signatures (params and return types)
+- Interface/type definitions containing IDs
+- Schema definitions for API input/output
+- Database query `.where()` clauses
+- Variable declarations storing IDs