agent-skill-kit 3.9.135

package/.agent/skills/auth-patterns/rules/passkey.md

@@ -0,0 +1,243 @@
+---
+name: passkey
+description: WebAuthn/FIDO2 passkeys — registration, authentication, browser + server implementation
+title: "Passkeys (WebAuthn / FIDO2)"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: passkey
+---
+
+# Passkeys (WebAuthn / FIDO2)
+
+> Passwordless authentication using public-key cryptography.
+
+---
+
+## What Are Passkeys?
+
+| Aspect | Detail |
+|--------|--------|
+| Standard | WebAuthn (W3C) + FIDO2 (FIDO Alliance) |
+| Mechanism | Public-key cryptography (device holds private key) |
+| Phishing resistance | ✅ Origin-bound (can't be phished) |
+| UX | Biometric (fingerprint, Face ID) or PIN |
+| Syncing | iCloud Keychain, Google Password Manager, 1Password |
+
+---
+
+## Flow Overview
+
+```
+Registration:
+1. Server sends challenge + user info
+2. Browser calls navigator.credentials.create()
+3. User authenticates locally (biometric/PIN)
+4. Browser returns public key + signed challenge
+5. Server stores public key
+
+Authentication:
+1. Server sends challenge + allowed credential IDs
+2. Browser calls navigator.credentials.get()
+3. User authenticates locally
+4. Browser returns signed challenge
+5. Server verifies signature with stored public key
+```
+
+---
+
+## Server Implementation
+
+### Using @simplewebauthn/server
+
+```bash
+npm install @simplewebauthn/server @simplewebauthn/browser
+```
+
+### Registration
+
+```typescript
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+} from '@simplewebauthn/server';
+
+const rpName = 'Your App';
+const rpID = 'example.com';
+const origin = 'https://example.com';
+
+// Step 1: Generate options
+async function startRegistration(user: User) {
+  const options = await generateRegistrationOptions({
+    rpName,
+    rpID,
+    userID: user.id,
+    userName: user.email,
+    attestationType: 'none',     // Don't need hardware attestation
+    authenticatorSelection: {
+      residentKey: 'preferred',  // Discoverable credential (passkey)
+      userVerification: 'required',
+    },
+    excludeCredentials: user.credentials.map(c => ({
+      id: c.credentialId,
+      type: 'public-key',
+    })),
+  });
+
+  // Store challenge temporarily
+  await redis.setex(`webauthn:${user.id}`, 300, options.challenge);
+
+  return options;
+}
+
+// Step 2: Verify response
+async function finishRegistration(user: User, response: RegistrationResponse) {
+  const expectedChallenge = await redis.get(`webauthn:${user.id}`);
+
+  const verification = await verifyRegistrationResponse({
+    response,
+    expectedChallenge,
+    expectedOrigin: origin,
+    expectedRPID: rpID,
+  });
+
+  if (verification.verified && verification.registrationInfo) {
+    const { credentialPublicKey, credentialID, counter } =
+      verification.registrationInfo;
+
+    // Store credential
+    await db.credential.create({
+      data: {
+        userId: user.id,
+        credentialId: Buffer.from(credentialID),
+        publicKey: Buffer.from(credentialPublicKey),
+        counter,
+        deviceType: verification.registrationInfo.credentialDeviceType,
+        backedUp: verification.registrationInfo.credentialBackedUp,
+      },
+    });
+  }
+}
+```
+
+### Authentication
+
+```typescript
+import {
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse,
+} from '@simplewebauthn/server';
+
+// Step 1: Generate challenge
+async function startAuth(user?: User) {
+  const options = await generateAuthenticationOptions({
+    rpID,
+    userVerification: 'required',
+    // If user known, limit to their credentials
+    ...(user && {
+      allowCredentials: user.credentials.map(c => ({
+        id: c.credentialId,
+        type: 'public-key',
+      })),
+    }),
+  });
+
+  await redis.setex(`webauthn:auth:${options.challenge}`, 300, '1');
+  return options;
+}
+
+// Step 2: Verify
+async function finishAuth(response: AuthenticationResponse) {
+  const credential = await db.credential.findUnique({
+    where: { credentialId: response.id },
+    include: { user: true },
+  });
+
+  if (!credential) throw new Error('Credential not found');
+
+  const verification = await verifyAuthenticationResponse({
+    response,
+    expectedChallenge: storedChallenge,
+    expectedOrigin: origin,
+    expectedRPID: rpID,
+    authenticator: {
+      credentialPublicKey: credential.publicKey,
+      credentialID: credential.credentialId,
+      counter: credential.counter,
+    },
+  });
+
+  if (verification.verified) {
+    // Update counter (replay protection)
+    await db.credential.update({
+      where: { id: credential.id },
+      data: { counter: verification.authenticationInfo.newCounter },
+    });
+
+    return credential.user;
+  }
+}
+```
+
+---
+
+## Frontend (Browser)
+
+```typescript
+import {
+  startRegistration,
+  startAuthentication,
+} from '@simplewebauthn/browser';
+
+// Registration
+const regOptions = await fetch('/api/auth/passkey/register').then(r => r.json());
+const regResult = await startRegistration(regOptions);
+await fetch('/api/auth/passkey/register/verify', {
+  method: 'POST',
+  body: JSON.stringify(regResult),
+});
+
+// Authentication
+const authOptions = await fetch('/api/auth/passkey/login').then(r => r.json());
+const authResult = await startAuthentication(authOptions);
+await fetch('/api/auth/passkey/login/verify', {
+  method: 'POST',
+  body: JSON.stringify(authResult),
+});
+```
+
+---
+
+## Adoption Strategy
+
+| Phase | Action |
+|-------|--------|
+| 1 | Offer passkey as optional MFA |
+| 2 | Prompt existing users to add passkey |
+| 3 | Allow passkey-only login (passwordless) |
+| 4 | Keep password as fallback recovery |
+
+---
+
+## Browser Support (2025)
+
+| Browser | Passkey Support |
+|---------|-----------------|
+| Chrome 108+ | ✅ Full |
+| Safari 16+ | ✅ Full |
+| Firefox 122+ | ✅ Full |
+| Edge 108+ | ✅ Full |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [mfa.md](mfa.md) | MFA with passkeys as second factor |
+| [oauth2.md](oauth2.md) | OAuth alternative to passkeys |
+| [session.md](session.md) | Session after passkey auth |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/auth-patterns/rules/rbac-abac.md

@@ -0,0 +1,206 @@
+---
+name: rbac-abac
+description: Role-Based and Attribute-Based access control — Prisma schema, middleware, ABAC policy engine
+title: "RBAC & ABAC - Access Control"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: rbac, abac
+---
+
+# RBAC & ABAC — Access Control
+
+> Role-Based and Attribute-Based authorization patterns.
+
+---
+
+## Model Selection
+
+```
+How complex are your permissions?
+├── Simple (admin/user/viewer)
+│   └── RBAC (Role-Based)
+├── Medium (roles + resource ownership)
+│   └── RBAC + ownership checks
+├── Complex (context-dependent rules)
+│   └── ABAC (Attribute-Based)
+└── Enterprise (multi-tenant + compliance)
+    └── ABAC or hybrid RBAC+ABAC
+```
+
+---
+
+## RBAC (Role-Based Access Control)
+
+### Schema Design
+
+```typescript
+// Database models
+interface User {
+  id: string;
+  roles: Role[];         // Many-to-many
+}
+
+interface Role {
+  id: string;
+  name: string;          // "admin", "editor", "viewer"
+  permissions: Permission[];  // Many-to-many
+}
+
+interface Permission {
+  id: string;
+  resource: string;      // "posts", "users", "billing"
+  action: string;        // "create", "read", "update", "delete"
+}
+```
+
+### Prisma Schema
+
+```prisma
+model User {
+  id    String     @id @default(cuid())
+  roles UserRole[]
+}
+
+model Role {
+  id          String           @id @default(cuid())
+  name        String           @unique
+  permissions RolePermission[]
+  users       UserRole[]
+}
+
+model Permission {
+  id       String           @id @default(cuid())
+  resource String
+  action   String
+  roles    RolePermission[]
+  @@unique([resource, action])
+}
+
+model UserRole {
+  userId String
+  roleId String
+  user   User @relation(fields: [userId], references: [id])
+  role   Role @relation(fields: [roleId], references: [id])
+  @@id([userId, roleId])
+}
+
+model RolePermission {
+  roleId       String
+  permissionId String
+  role         Role       @relation(fields: [roleId], references: [id])
+  permission   Permission @relation(fields: [permissionId], references: [id])
+  @@id([roleId, permissionId])
+}
+```
+
+### Permission Check (Middleware)
+
+```typescript
+function requirePermission(resource: string, action: string) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const user = req.user;
+    const hasPermission = user.roles.some(role =>
+      role.permissions.some(p =>
+        p.resource === resource && p.action === action
+      )
+    );
+
+    if (!hasPermission) {
+      return res.status(403).json({ error: 'Insufficient permissions' });
+    }
+    next();
+  };
+}
+
+// Usage
+app.delete('/api/posts/:id', requirePermission('posts', 'delete'), deletePost);
+```
+
+---
+
+## ABAC (Attribute-Based Access Control)
+
+### When to Use
+
+| Scenario | Example |
+|----------|---------|
+| Context-dependent | "Editors can only edit posts they authored" |
+| Time-based | "Access only during business hours" |
+| Location-based | "Only from corporate network" |
+| Multi-tenant | "Users can only see their organization's data" |
+
+### Policy Pattern
+
+```typescript
+interface PolicyContext {
+  subject: { id: string; role: string; orgId: string; };
+  resource: { type: string; ownerId: string; orgId: string; };
+  action: string;
+  environment: { time: Date; ip: string; };
+}
+
+function evaluatePolicy(ctx: PolicyContext): boolean {
+  const policies: Policy[] = [
+    // Owners can do anything to their resources
+    {
+      effect: 'allow',
+      condition: (c) => c.subject.id === c.resource.ownerId,
+    },
+    // Admins can do anything in their org
+    {
+      effect: 'allow',
+      condition: (c) =>
+        c.subject.role === 'admin' &&
+        c.subject.orgId === c.resource.orgId,
+    },
+    // Editors can read/update (not delete) in their org
+    {
+      effect: 'allow',
+      condition: (c) =>
+        c.subject.role === 'editor' &&
+        c.subject.orgId === c.resource.orgId &&
+        ['read', 'update'].includes(c.action),
+    },
+  ];
+
+  // Default deny — allow only if at least one policy matches
+  return policies.some(p => p.effect === 'allow' && p.condition(ctx));
+}
+```
+
+---
+
+## Libraries & Services
+
+| Solution | Type | Best For |
+|----------|------|----------|
+| CASL | Library (JS) | Frontend + backend RBAC/ABAC |
+| Casbin | Library (multi-lang) | Policy engine |
+| Oso | Library | Application-embedded authz |
+| Auth0 FGA | Service | Fine-grained authorization |
+| Permit.io | Service | Managed RBAC/ABAC |
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|------|
+| Hardcode roles in if/else | Use permission table |
+| Check role name in code | Check permission (resource + action) |
+| Forget resource ownership | Always check `ownerId` |
+| Skip multi-tenant isolation | Always scope queries by `orgId` |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [jwt-deep.md](jwt-deep.md) | Role/permission claims in JWT |
+| [session.md](session.md) | Session-based permission checks |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/auth-patterns/rules/session.md

@@ -0,0 +1,183 @@
+---
+name: session
+description: Cookie sessions, Redis store, stateless vs stateful, session lifecycle and security
+title: "Session Management"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: session
+---
+
+# Session Management
+
+> Cookie-based sessions, Redis store, stateless vs stateful trade-offs.
+
+---
+
+## Stateless vs Stateful
+
+| Aspect | Stateless (JWT) | Stateful (Session) |
+|--------|-----------------|-------------------|
+| Storage | Token contains data | Server stores data |
+| Scalability | ✅ No shared state | ⚠️ Needs shared store |
+| Revocation | ❌ Hard (need blocklist) | ✅ Delete from store |
+| Size | Can grow large | Fixed session ID |
+| Best for | Microservices, API | Traditional web SSR |
+
+### Hybrid Approach (Recommended)
+
+```
+Use JWT for access (short-lived, stateless)
++ Session-based refresh (stateful, revocable in Redis)
+```
+
+---
+
+## Cookie-Based Session
+
+### Secure Cookie Configuration
+
+```typescript
+app.use(session({
+  name: '__session',                    // Avoid default 'connect.sid'
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,                     // No JS access
+    secure: true,                       // HTTPS only
+    sameSite: 'lax',                    // CSRF protection
+    maxAge: 24 * 60 * 60 * 1000,       // 24 hours
+    domain: '.example.com',            // Cross-subdomain if needed
+    path: '/',
+  },
+}));
+```
+
+### Cookie Security Flags
+
+| Flag | Purpose | Always Set? |
+|------|---------|-------------|
+| `httpOnly` | Prevent XSS token theft | ✅ |
+| `secure` | HTTPS only | ✅ (prod) |
+| `sameSite: lax` | Basic CSRF protection | ✅ |
+| `sameSite: strict` | Full CSRF protection | For sensitive ops |
+| `__Host-` prefix | Origin-bound | High security |
+
+---
+
+## Redis Session Store
+
+### Why Redis
+
+| Feature | Benefit |
+|---------|---------|
+| In-memory speed | < 1ms session lookup |
+| TTL support | Automatic expiry |
+| Cluster support | Horizontal scaling |
+| Pub/Sub | Session invalidation across nodes |
+
+### Setup
+
+```typescript
+import RedisStore from 'connect-redis';
+import { createClient } from 'redis';
+
+const redisClient = createClient({ url: process.env.REDIS_URL });
+await redisClient.connect();
+
+app.use(session({
+  store: new RedisStore({ client: redisClient }),
+  secret: process.env.SESSION_SECRET,
+  resave: false,
+  saveUninitialized: false,
+  cookie: { httpOnly: true, secure: true, sameSite: 'lax' },
+}));
+```
+
+### Session Data Structure
+
+```typescript
+// Keep session data minimal
+interface SessionData {
+  userId: string;
+  role: string;
+  orgId?: string;
+  loginAt: number;
+  lastActiveAt: number;
+  // DON'T store: full user profile, preferences, cart items
+}
+```
+
+---
+
+## Session Lifecycle
+
+### Login
+
+```typescript
+async function login(req: Request) {
+  const user = await authenticate(req.body);
+
+  // Regenerate session ID (prevent fixation)
+  req.session.regenerate(() => {
+    req.session.userId = user.id;
+    req.session.role = user.role;
+    req.session.loginAt = Date.now();
+  });
+}
+```
+
+### Logout
+
+```typescript
+async function logout(req: Request) {
+  const sessionId = req.sessionID;
+
+  // Destroy server-side session
+  req.session.destroy(() => {
+    // Clear cookie
+    res.clearCookie('__session');
+  });
+}
+```
+
+### Invalidate All Sessions (password change)
+
+```typescript
+async function invalidateAllSessions(userId: string) {
+  // Scan Redis for user's sessions
+  const keys = await redis.keys(`sess:*`);
+  for (const key of keys) {
+    const data = await redis.get(key);
+    if (data && JSON.parse(data).userId === userId) {
+      await redis.del(key);
+    }
+  }
+}
+```
+
+---
+
+## Session Security Checklist
+
+- [ ] Regenerate session ID after login
+- [ ] Set `httpOnly`, `secure`, `sameSite` on cookies
+- [ ] Use Redis/Memcached for distributed sessions
+- [ ] Implement idle timeout (30 min) + absolute timeout (24h)
+- [ ] Invalidate sessions on password change
+- [ ] Log session creation/destruction for audit
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [jwt-deep.md](jwt-deep.md) | JWT as stateless alternative |
+| [oauth2.md](oauth2.md) | OAuth sessions |
+| [mfa.md](mfa.md) | MFA with sessions |
+| [SKILL.md](../SKILL.md) | Auth strategy decision tree |
+
+---
+
+⚡ PikaKit v3.9.134