vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/back-up-my-code/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: back-up-my-code
+description: the builder's project is saved on GitHub so they never lose work. Use when the builder says something like: save my code; back up; put it on github.
+metadata:
+  vybekiit-generated: buyer-skill-stub
+---
+
+<!-- vybekiit:generated:buyer-skill-stub -->
+
+# Skill: back-up-my-code
+
+**Goal:** the builder's project is saved on GitHub so they never lose work.
+
+**Contract:** one action at a time · verify-before-advance · plain language (`language.md`) ·
+translate every error · celebrate. You handle git and GitHub; the builder only signs in or creates an account when asked.
+
+> (Under the hood — agent-only) Follow `github-vybekiit.md`. Use `gh` only — never say "git init" or "remote" to the builder.
+
+## Steps
+
+1. **Explain in one line.** *"I'll save your project online so you can't lose it."*
+
+2. **GitHub account.** If they don't have one, walk them through creating one at github.com — **one step at a time** in plain words. `gh` cannot create accounts for them.
+
+3. **Sign in.** If `vybekiit doctor` says GitHub isn't signed in, run `gh auth login --web` and have them click approve in the browser.
+   **Verify:** `gh auth status` shows signed in.
+
+4. **Save it.** Initialize the repo (if needed), commit all safe files (never `.env`), create a **private** GitHub repo, and push.
+   **Verify:** files visible on github.com.
+
+5. **Give them the link.** Share the repo URL in plain words — *"Your project is saved here."*
+   🎉 *Celebrate* — their work is backed up.
+
+6. **Later saves.** For ongoing checkpoints, use `ship-via-pr-vybekiit.md` — the **online checker** runs on all three operating systems before merge. Builder hears: *"Your latest work is saved and checked."*
+
+## If anything breaks
+
+Run `doctor`. Common fixes: not signed in to GitHub, repo name already taken (pick another), or `.env` accidentally staged (unstage — secrets stay local).
+
+## Definition of done
+
+Project pushed to a private GitHub repo, verified on github.com, builder has the link.
+
+## After completing this skill
+
+Append one entry to `checklist.md` Decision log using `formatChecklistEntry({ from, to, because })`.
+
+If MCP or first debug fails once, run `vybekiit doc-fallback <tech-id>` and tell the builder only: *"I'm double-checking the official setup guide for this — hang tight, I'll have the next step in a moment."*

package/dist/global-skills/better-auth-best-practices/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: better-auth-best-practices
+description: Configure Better Auth server and client, set up database adapters, manage sessions, add plugins, and handle environment variables. Use when users mention Better Auth, betterauth, auth.ts, or need to set up TypeScript authentication with email/password, OAuth, or plugin configuration.
+---
+
+# Better Auth Integration Guide
+
+**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
+
+---
+
+## Setup Workflow
+
+1. Install: `npm install better-auth`
+2. Set env vars: `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL`
+3. Create `auth.ts` with database + config
+4. Create route handler for your framework
+5. Run migrations:
+   - **Built-in adapter:** `npx @better-auth/cli@latest migrate`
+   - **Drizzle:** `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
+   - **Prisma:** `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
+6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`
+
+---
+
+## Quick Reference
+
+### Environment Variables
+- `BETTER_AUTH_SECRET` - Encryption secret (min 32 chars). Generate: `openssl rand -base64 32`
+- `BETTER_AUTH_URL` - Base URL (e.g., `https://example.com`)
+
+Only define `baseURL`/`secret` in config if env vars are NOT set.
+
+### File Location
+CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.
+
+### CLI Commands
+- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
+- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
+- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
+
+**Re-run after adding/changing plugins.**
+
+---
+
+## Core Config Options
+
+| Option | Notes |
+|--------|-------|
+| `appName` | Optional display name |
+| `baseURL` | Only if `BETTER_AUTH_URL` not set |
+| `basePath` | Default `/api/auth`. Set `/` for root. |
+| `secret` | Only if `BETTER_AUTH_SECRET` not set |
+| `database` | Required for most features. See adapters docs. |
+| `secondaryStorage` | Redis/KV for sessions & rate limits |
+| `emailAndPassword` | `{ enabled: true }` to activate |
+| `socialProviders` | `{ google: { clientId, clientSecret }, ... }` |
+| `plugins` | Array of plugins |
+| `trustedOrigins` | CSRF whitelist |
+
+---
+
+## Database
+
+**Direct connections:** Pass `pg.Pool`, `mysql2` pool, `better-sqlite3`, or `bun:sqlite` instance. For Postgres, also supports `postgres` (postgres.js) and `@neondatabase/serverless`.
+
+**ORM adapters:** Import from `better-auth/adapters/drizzle`, `better-auth/adapters/prisma`, `better-auth/adapters/mongodb`.
+
+**Drizzle provider values:** `"pg"` (PostgreSQL), `"mysql"` (MySQL), `"sqlite"` (SQLite). Must match the driver used.
+
+**Critical:** Better Auth uses adapter model names, NOT underlying table names. If Prisma model is `User` mapping to table `users`, use `modelName: "user"` (Prisma reference), not `"users"`.
+
+---
+
+## Session Management
+
+**Storage priority:**
+1. If `secondaryStorage` defined → sessions go there (not DB)
+2. Set `session.storeSessionInDatabase: true` to also persist to DB
+3. No database + `cookieCache` → fully stateless mode
+
+**Cookie cache strategies:**
+- `compact` (default) - Base64url + HMAC. Smallest.
+- `jwt` - Standard JWT. Readable but signed.
+- `jwe` - Encrypted. Maximum security.
+
+**Key options:** `session.expiresIn` (default 7 days), `session.updateAge` (refresh interval), `session.cookieCache.maxAge`, `session.cookieCache.version` (change to invalidate all sessions).
+
+---
+
+## User & Account Config
+
+**User:** `user.modelName`, `user.fields` (column mapping), `user.additionalFields`, `user.changeEmail.enabled` (disabled by default), `user.deleteUser.enabled` (disabled by default).
+
+**Account:** `account.modelName`, `account.accountLinking.enabled`, `account.storeAccountCookie` (for stateless OAuth).
+
+**Required for registration:** `email` and `name` fields.
+
+---
+
+## Email Flows
+
+- `emailVerification.sendVerificationEmail` - Must be defined for verification to work
+- `emailVerification.sendOnSignUp` / `sendOnSignIn` - Auto-send triggers
+- `emailAndPassword.sendResetPassword` - Password reset email handler
+
+---
+
+## Security
+
+**In `advanced`:**
+- `useSecureCookies` - Force HTTPS cookies
+- `disableCSRFCheck` - ⚠️ Security risk
+- `disableOriginCheck` - ⚠️ Security risk  
+- `crossSubDomainCookies.enabled` - Share cookies across subdomains
+- `ipAddress.ipAddressHeaders` - Custom IP headers for proxies
+- `database.generateId` - Custom ID generation or `"serial"`/`"uuid"`/`false`
+
+**Rate limiting:** `rateLimit.enabled`, `rateLimit.window`, `rateLimit.max`, `rateLimit.storage` ("memory" | "database" | "secondary-storage").
+
+---
+
+## Hooks
+
+**Endpoint hooks:** `hooks.before` / `hooks.after` - Array of `{ matcher, handler }`. Use `createAuthMiddleware`. Access `ctx.path`, `ctx.context.returned` (after), `ctx.context.session`.
+
+**Database hooks:** `databaseHooks.user.create.before/after`, same for `session`, `account`. Useful for adding default values or post-creation actions.
+
+**Hook context (`ctx.context`):** `session`, `secret`, `authCookies`, `password.hash()`/`verify()`, `adapter`, `internalAdapter`, `generateId()`, `tables`, `baseURL`.
+
+---
+
+## Plugins
+
+**Import from dedicated paths for tree-shaking:**
+```
+import { twoFactor } from "better-auth/plugins/two-factor"
+```
+NOT `from "better-auth/plugins"`.
+
+**Popular plugins:** `twoFactor`, `organization`, `passkey`, `magicLink`, `emailOtp`, `username`, `phoneNumber`, `admin`, `apiKey`, `bearer`, `jwt`, `multiSession`, `sso`, `oauthProvider`, `oidcProvider`, `openAPI`, `genericOAuth`.
+
+Client plugins go in `createAuthClient({ plugins: [...] })`.
+
+---
+
+## Client
+
+Import from: `better-auth/client` (vanilla), `better-auth/react`, `better-auth/vue`, `better-auth/svelte`, `better-auth/solid`.
+
+Key methods: `signUp.email()`, `signIn.email()`, `signIn.social()`, `signOut()`, `useSession()`, `getSession()`, `revokeSession()`, `revokeSessions()`.
+
+---
+
+## Type Safety
+
+Infer types: `typeof auth.$Infer.Session`, `typeof auth.$Infer.Session.user`.
+
+For separate client/server projects: `createAuthClient<typeof auth>()`.
+
+---
+
+## Common Gotchas
+
+1. **Model vs table name** - Config uses ORM model name, not DB table name
+2. **Plugin schema** - Re-run CLI after adding plugins
+3. **Secondary storage** - Sessions go there by default, not DB
+4. **Cookie cache** - Custom session fields NOT cached, always re-fetched
+5. **Stateless mode** - No DB = session in cookie only, logout on cache expiry
+6. **Change email flow** - Sends to current email first, then new email
+7. **Drizzle: db not initialized** - `drizzleAdapter(db, ...)` requires a `db` instance from `drizzle()`. See `create-auth` skill for setup examples (node-postgres, postgres.js, Neon).
+8. **Drizzle: missing drizzle.config.ts** - `drizzle-kit` commands require a `drizzle.config.ts` pointing to the generated schema file and DB credentials.
+
+---
+
+## Resources
+
+- [Docs](https://better-auth.com/docs)
+- [Options Reference](https://better-auth.com/docs/reference/options)
+- [LLMs.txt](https://better-auth.com/llms.txt)
+- [GitHub](https://github.com/better-auth/better-auth)
+- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)

package/dist/global-skills/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