security-prompts-auth

What this skill does

# Auth & Authorization Security Templates

## Purpose

This skill provides authentication and authorization prompt templates for implementing secure access control systems. Use these templates to set up role-based access control (RBAC), granular permissions, ownership verification, and comprehensive authorization testing.

## Available Templates

### 01: RBAC Implementation
**File**: `01_rbac_implementation.md`
**When to use**: First time adding roles (user, premium, admin)
**Time**: 60 minutes

**Implementation Coverage**:
- Server-side role storage
- Clerk publicMetadata integration
- Webhook-based role assignment
- Role-based route protection
- Middleware enforcement
- Role checking utilities

**Roles Implemented**:
- **user** (default) - Basic authenticated access
- **premium** (paid) - Enhanced features via Clerk Billing
- **admin** (staff) - Full system access

**Trigger keywords**: "RBAC", "role-based access", "user roles", "implement roles", "setup roles", "add roles", "role system"

**Use case**: Initial authorization setup, multi-tier application, SaaS with subscription tiers

**Output**: Complete RBAC system with Clerk integration

---

### 02: Permissions System
**File**: `02_permissions.md`
**When to use**: Granular permission system beyond basic roles
**Time**: 90 minutes

**Implementation Coverage**:
- Fine-grained permissions
- Permission groups
- Resource-level access
- Permission inheritance
- Dynamic permission checks
- Permission management UI

**Permission Examples**:
- `users.read`, `users.write`, `users.delete`
- `posts.create`, `posts.edit`, `posts.publish`
- `admin.dashboard`, `admin.settings`

**Trigger keywords**: "permissions", "permission system", "granular access", "fine-grained permissions", "permission management", "resource permissions"

**Use case**: Enterprise applications, complex access requirements, team collaboration tools

**Output**: Comprehensive permission system with management interface

---

### 03: Ownership Verification
**File**: `03_ownership.md`
**When to use**: Resource ownership checks (users can only modify their own data)
**Time**: 30 minutes

**Implementation Coverage**:
- Ownership validation
- User-resource relationship checks
- Authorization errors
- Multi-owner scenarios
- Delegation patterns

**Security Focus**:
- Prevent horizontal privilege escalation
- Verify user owns the resource
- Handle shared resources
- Team/organization ownership

**Trigger keywords**: "ownership", "ownership check", "resource ownership", "user owns", "own data only", "verify ownership", "prevent user accessing others data"

**Use case**: Profile editing, document management, any user-specific resources

**Output**: Ownership verification utilities and endpoint protection

---

### 04: Authorization Testing
**File**: `04_auth_testing.md`
**When to use**: Comprehensive authorization testing
**Time**: 60 minutes

**Test Coverage**:
- Role-based access tests
- Permission verification tests
- Ownership check tests
- Negative authorization tests
- Cross-user access prevention
- Privilege escalation tests

**Test Scenarios**:
- User cannot access admin routes
- User cannot modify other users' data
- Premium features blocked for free users
- Unauthenticated requests rejected
- Invalid role assignments rejected

**Trigger keywords**: "auth testing", "authorization tests", "test permissions", "test RBAC", "test access control", "authorization test suite"

**Use case**: Continuous testing, CI/CD integration, security validation

**Output**: Complete authorization test suite

---

## Usage Pattern

### 1. Identify Authorization Need

**First-time setup** (no auth beyond Clerk):
→ 01_rbac_implementation.md

**Need granular control**:
→ 02_permissions.md

**User-specific resources**:
→ 03_ownership.md

**Verify authorization**:
→ 04_auth_testing.md

### 2. Sequential Implementation

**Recommended order**:
```markdown
Step 1: RBAC (Foundation)
→ Use: 01_rbac_implementation.md

Step 2: Ownership (User Resources)
→ Use: 03_ownership.md

Step 3: Permissions (If Needed)
→ Use: 02_permissions.md

Step 4: Testing (Always)
→ Use: 04_auth_testing.md
```

### 3. Load Template

```markdown
Read: .claude/skills/security/security-prompts/auth-authorization/[number]_[name].md
```

### 4. Customize for Application

Replace in template:
- `[role names]` with your roles
- `[permission names]` with your permissions
- `[resource types]` with your data models
- `[access matrix]` with your requirements

### 5. Present Implementation Plan

```markdown
I'll implement [AUTHORIZATION_TYPE] using the auth template.

**What we'll set up**:
- [List from template]

**How it integrates with Clerk**:
- [Clerk-specific details]

**Testing strategy**:
- [Testing approach]

**Estimated time**: [From template]

Let me customize the template for your application...
```

## Common Authorization Patterns

### Pattern 1: Basic RBAC
```markdown
Application: Blog with user/admin roles

Implementation:
→ 01_rbac_implementation.md

Role Matrix:
- user: Read posts, comment, manage own comments
- admin: All user access + create/edit/delete posts, moderate comments

Testing:
→ 04_auth_testing.md
```

### Pattern 2: SaaS with Tiers
```markdown
Application: SaaS tool with free/premium/enterprise

Implementation:
→ 01_rbac_implementation.md

Role Matrix:
- free: Basic features, 10 projects limit
- premium: Advanced features, unlimited projects
- enterprise: All features + team management

Integration:
→ Clerk Billing webhooks set role based on subscription

Testing:
→ 04_auth_testing.md
```

### Pattern 3: User Resources
```markdown
Application: Profile management

Implementation:
Step 1: RBAC for basic roles
→ 01_rbac_implementation.md

Step 2: Ownership for profile editing
→ 03_ownership.md

Verification:
- User A cannot edit User B's profile
- Admins can edit any profile
- Users can edit their own profile

Testing:
→ 04_auth_testing.md
```

### Pattern 4: Enterprise Permissions
```markdown
Application: Team collaboration tool

Implementation:
Step 1: RBAC for base roles
→ 01_rbac_implementation.md

Step 2: Granular permissions
→ 02_permissions.md

Step 3: Ownership for resources
→ 03_ownership.md

Permission Matrix:
- Owner: All permissions
- Admin: Most permissions, cannot delete workspace
- Member: View and edit, cannot manage team
- Guest: View only

Testing:
→ 04_auth_testing.md
```

## Integration with Feature Templates

### Authenticated Endpoints

```markdown
Step 1: Setup RBAC
→ auth-authorization/01_rbac_implementation.md

Step 2: Implement feature with auth
→ prompt-engineering/02_authenticated_endpoint.md

Step 3: Add ownership checks
→ auth-authorization/03_ownership.md

Step 4: Test authorization
→ auth-authorization/04_auth_testing.md
```

### Admin Features

```markdown
Step 1: Setup RBAC (if not exists)
→ auth-authorization/01_rbac_implementation.md

Step 2: Implement admin endpoints
→ prompt-engineering/04_admin_action.md

Step 3: Test admin access
→ auth-authorization/04_auth_testing.md

Step 4: Review security
→ threat-modeling/04_code_review.md
```

## Clerk Integration

All templates integrate with Clerk:

**Role Storage**: `publicMetadata.role`
```typescript
// Read from session
const { sessionClaims } = auth();
const role = sessionClaims?.publicMetadata?.role;
```

**Webhook Assignment**:
```typescript
// In convex/http.ts or app/api/webhooks/clerk/route.ts
await clerkClient.users.updateUserMetadata(userId, {
  publicMetadata: { role: "user" }
});
```

**Middleware Protection**:
```typescript
// In middleware.ts
const role = auth().sessionClaims?.publicMetadata?.role;
if (role !== "admin" && pathname.startsWith("/admin")) {
  return Response.redirect("/unauthorized");
}
```

**Permission Storage** (if using 02_permissions.md):
```typescript
publicMetadata: {
  role: "user",
  permissions: ["posts.read", "posts.create", "comments.create"]
}
```

## Best Practices

### 1. Server-Side Only

**Always verify on server**:
```typescript
// ✅ Good - serve