json-rest-api 1.0.10 → 1.0.11

package/docs/GUIDE/GUIDE_4_Authentication_And_Permissions.md

@@ -1,155 +1,201 @@
-# Permissions and Authentication Guide
+# Authentication and Permissions Guide
 
-The JWT Authentication Plugin provides a powerful declarative permission system that makes it easy to secure your REST API resources. This guide shows you how to use authentication and define permissions using the book catalog example.
+This guide shows you how to add authentication to your REST API using the JWT Authentication Plugin. The plugin validates JWT tokens from any auth provider (Supabase, Auth0, Firebase, etc.) and enforces permissions on your resources.
 
 ## Table of Contents
-- [Overview](#overview)
-- [Quick Start](#quick-start)
-- [Getting Tokens from Auth Providers](#getting-tokens-from-auth-providers)
-  - [Supabase](#supabase)
-  - [Auth0](#auth0)
-  - [Custom JWT](#custom-jwt)
-- [Installation and Setup](#installation-and-setup)
-- [Declarative Permissions](#declarative-permissions)
-- [Built-in Auth Checkers](#built-in-auth-checkers)
-- [Making Authenticated API Calls Directly](#making-authenticated-api-calls-directly)
-- [Using Auth Helpers](#using-auth-helpers)
+- [How It Works - The Architecture](#how-it-works---the-architecture)
+- [Quick Start - Get Running in 5 Minutes](#quick-start---get-running-in-5-minutes)
+- [Frontend: Getting Auth Tokens](#frontend-getting-auth-tokens)
+  - [Supabase Setup](#supabase-setup)
+  - [Auth0 Setup](#auth0-setup)
+  - [Google OAuth Login](#google-oauth-login)
+- [Backend: Validating Tokens](#backend-validating-tokens)
+- [Using Built-in Checkers](#using-built-in-checkers)
+- [Progressive Examples](#progressive-examples)
+- [Advanced: Custom Authorization](#advanced-custom-authorization)
 - [Token Management](#token-management)
-- [Custom Auth Checkers](#custom-auth-checkers)
-- [Examples](#examples)
-- [Best Practices](#best-practices)
+- [Migration Guide](#migration-guide)
 
-## Overview
+## How It Works - The Architecture
 
-The JWT Auth Plugin provides two main features:
+The JWT plugin is a **backend/server-side** tool that validates tokens. Here's the complete flow:
 
-1. **Authentication** - Validates JWT tokens and populates `context.auth`
-2. **Authorization** - Declarative permission rules on resources
+```
+┌─────────────┐      ┌─────────────┐      ┌──────────────┐
+│   Browser   │      │  Supabase/  │      │  Your API    │
+│  (Frontend) │ ───> │    Auth0    │      │  (Backend)   │
+└─────────────┘      └─────────────┘      └──────────────┘
+      │                     │                      │
+      │ 1. Login with       │                      │
+      │    email/Google     │                      │
+      │ ─────────────────>  │                      │
+      │                     │                      │
+      │ 2. Get JWT token    │                      │
+      │ <─────────────────  │                      │
+      │                     │                      │
+      │ 3. API request with Bearer token           │
+      │ ──────────────────────────────────────>    │
+      │                                            │
+      │                                   4. JWT Plugin validates
+      │                                      token with Supabase
+      │                                            │
+      │ 5. Response (allowed or denied)            │
+      │ <──────────────────────────────────────    │
+```
 
-The plugin validates tokens from any JWT provider (Supabase, Auth0, your own auth server) and enforces permissions you define on your resources.
+**Key Points:**
+- **Frontend**: Handles user login (email/password, Google, etc.) and gets JWT token
+- **Auth Provider**: Issues and manages JWT tokens (Supabase, Auth0, etc.)
+- **Backend (Your API)**: Uses JWT plugin to validate tokens and enforce permissions
+- **JWT Plugin**: Does NOT handle login/signup - only validates existing tokens
 
-## Quick Start
+## Quick Start - Get Running in 5 Minutes
 
-Here's how to get authentication working in 3 steps:
+### Step 1: Install the Plugin
 
-### 1. Get JWT tokens from your auth provider
-```javascript
-// Example with Supabase (in your frontend)
-import { createClient } from '@supabase/supabase-js'
+```bash
+npm install jose
+```
 
-const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY)
+### Step 2: Configure Your Backend API
 
-// User login
-const { data: { session } } = await supabase.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'password'
-})
+```javascript
+import { Api } from 'hooked-api';
+import { RestApiPlugin, RestApiKnexPlugin } from 'json-rest-api';
+import { JwtAuthPlugin } from 'json-rest-api/plugins/core/jwt-auth-plugin.js';
 
-const token = session.access_token // This is your JWT token!
-```
+// Create your API
+const api = new Api();
+await api.use(RestApiPlugin);
+await api.use(RestApiKnexPlugin, { knex });
 
-### 2. Configure the plugin in your API
-```javascript
-// In your API server
+// Add JWT authentication (example with Supabase)
 await api.use(JwtAuthPlugin, {
-  // For Supabase
-  jwksUrl: `${SUPABASE_URL}/auth/v1/.well-known/jwks.json`,
-  rolesField: 'app_metadata.roles'
-})
-```
+  jwksUrl: 'https://your-project.supabase.co/auth/v1/.well-known/jwks.json'
+});
 
-### 3. Define permissions on resources
-```javascript
+// Add a protected resource
 await api.addResource('posts', {
-  schema: { /* ... */ },
+  schema: {
+    id: { type: 'id' },
+    title: { type: 'string', required: true },
+    content: { type: 'text' },
+    user_id: { type: 'string' }  // Automatically set to current user
+  },
   
+  // Simple auth rules using built-in checkers
   auth: {
-    query: ['public'],         // Anyone can read
-    post: ['authenticated'],   // Must be logged in
-    patch: ['is_owner'],       // Must own the post
-    delete: ['is_owner', 'admin'] // Owner or admin
+    query: ['public'],         // Anyone can read posts
+    post: ['authenticated'],   // Must be logged in to create
+    patch: ['owns'],          // Can only edit your own posts
+    delete: ['owns']          // Can only delete your own posts
   }
-})
+});
+```
+
+### Step 3: Test It
+
+```javascript
+// From your frontend (after user logs in)
+const response = await fetch('http://localhost:3000/api/posts', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${token}`,  // Token from Supabase/Auth0
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    data: {
+      type: 'posts',
+      attributes: {
+        title: 'My First Post',
+        content: 'Hello world!'
+      }
+    }
+  })
+});
 ```
 
-That's it! Your API now requires authentication and enforces permissions.
+That's it! You now have authenticated API endpoints.
+
+## Frontend: Getting Auth Tokens
+
+The JWT plugin validates tokens from any provider. Here's how to get tokens from popular services:
 
-## Getting Tokens from Auth Providers
+### Supabase Setup
 
-The plugin doesn't generate tokens - it validates them. Here's how to get tokens from popular providers:
+#### 1. Create a Supabase Project
+Go to [supabase.com](https://supabase.com) and create a new project. You'll get:
+- Project URL: `https://your-project.supabase.co`
+- Anon Key: `eyJhbGc...` (public key for frontend)
 
-### Supabase
+#### 2. Frontend: Email/Password Login
 
-#### Step 1: Set up Supabase Auth
 ```javascript
-// In your frontend app
+// In your React/Vue/etc app
 import { createClient } from '@supabase/supabase-js'
 
 const supabase = createClient(
   'https://your-project.supabase.co',
   'your-anon-key'
 )
-```
 
-#### Step 2: User Registration/Login
-```javascript
 // Sign up new user
-const { data, error } = await supabase.auth.signUp({
-  email: 'user@example.com',
-  password: 'secure-password'
-})
+async function signUp(email, password) {
+  const { data, error } = await supabase.auth.signUp({
+    email,
+    password
+  })
+  if (error) throw error
+  return data.session.access_token  // This is your JWT!
+}
 
 // Sign in existing user
-const { data: { session } } = await supabase.auth.signInWithPassword({
-  email: 'user@example.com',
-  password: 'secure-password'
-})
-
-// The JWT token is in session.access_token
-const token = session.access_token
-```
+async function signIn(email, password) {
+  const { data, error } = await supabase.auth.signInWithPassword({
+    email,
+    password
+  })
+  if (error) throw error
+  return data.session.access_token  // This is your JWT!
+}
 
-#### Step 3: Use token with your API
-```javascript
-// Make authenticated requests to your API
-const response = await fetch('https://your-api.com/api/posts', {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${token}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    data: {
-      type: 'posts',
-      attributes: {
-        title: 'My Post',
-        content: 'Hello world'
+// Use the token for API calls
+async function createPost(token, title, content) {
+  const response = await fetch('http://localhost:3000/api/posts', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      data: {
+        type: 'posts',
+        attributes: { title, content }
       }
-    }
+    })
   })
-})
+  return response.json()
+}
 ```
 
-#### Step 4: Configure plugin for Supabase
+#### 3. Backend Configuration
+
 ```javascript
+// Your API server
 await api.use(JwtAuthPlugin, {
-  // Supabase JWKS URL - replace with your project URL
-  jwksUrl: `${process.env.SUPABASE_URL}/auth/v1/.well-known/jwks.json`,
-  
-  // Supabase stores roles in app_metadata
-  rolesField: 'app_metadata.roles',
-  
-  // Optional: Add these for extra security
-  audience: 'authenticated',
-  issuer: process.env.SUPABASE_URL
+  jwksUrl: 'https://your-project.supabase.co/auth/v1/.well-known/jwks.json'
 })
 ```
 
-### Auth0
+### Auth0 Setup
+
+#### 1. Create an Auth0 Application
+Go to [auth0.com](https://auth0.com) and create a new Single Page Application.
+
+#### 2. Frontend: Auth0 Login
 
-#### Step 1: Set up Auth0
 ```javascript
-// In your frontend
+// In your React/Vue/etc app
 import { createAuth0Client } from '@auth0/auth0-spa-js'
 
 const auth0 = await createAuth0Client({
@@ -157,808 +203,505 @@ const auth0 = await createAuth0Client({
   clientId: 'your-client-id',
   authorizationParams: {
     redirect_uri: window.location.origin,
-    audience: 'https://your-api.com'
+    audience: 'https://your-api.com'  // Your API identifier
   }
 })
-```
 
-#### Step 2: User Login
-```javascript
-// Redirect to Auth0 login
-await auth0.loginWithRedirect()
+// Login
+async function login() {
+  await auth0.loginWithRedirect()
+}
 
-// After redirect back, get token
-const token = await auth0.getAccessTokenSilently()
+// After redirect, get token
+async function getToken() {
+  const token = await auth0.getAccessTokenSilently()
+  return token  // Your JWT!
+}
 ```
 
-#### Step 3: Configure plugin for Auth0
+#### 3. Backend Configuration
+
 ```javascript
+// Your API server
 await api.use(JwtAuthPlugin, {
-  jwksUrl: `https://${AUTH0_DOMAIN}/.well-known/jwks.json`,
-  audience: process.env.AUTH0_AUDIENCE,
-  issuer: `https://${AUTH0_DOMAIN}/`,
-  
-  // Auth0 uses custom claims
-  rolesField: 'https://your-app.com/roles'
+  jwksUrl: 'https://your-domain.auth0.com/.well-known/jwks.json',
+  audience: 'https://your-api.com',
+  issuer: 'https://your-domain.auth0.com/'
 })
 ```
 
-### Custom JWT
+### Google OAuth Login
 
-If you're generating your own JWTs:
+Google login works through your auth provider (Supabase/Auth0), not directly. The user logs in with Google, but you still get a JWT from Supabase/Auth0.
+
+#### Supabase + Google
+
+##### 1. Enable Google in Supabase Dashboard
+- Go to Authentication → Providers → Google
+- Add your Google Client ID and Secret (from Google Cloud Console)
+
+##### 2. Frontend: Google Login Button
 
-#### Step 1: Generate tokens in your auth server
 ```javascript
-// In your auth server
-import jwt from 'jsonwebtoken'
-
-const token = jwt.sign(
-  {
-    sub: user.id,           // User ID
-    email: user.email,
-    roles: ['user', 'editor'],
-    jti: generateUniqueId(), // For revocation
-    iat: Math.floor(Date.now() / 1000),
-    exp: Math.floor(Date.now() / 1000) + 3600 // 1 hour
-  },
-  process.env.JWT_SECRET,
-  { algorithm: 'HS256' }
-)
+// React component example
+function GoogleLoginButton() {
+  const handleGoogleLogin = async () => {
+    const { data, error } = await supabase.auth.signInWithOAuth({
+      provider: 'google',
+      options: {
+        redirectTo: 'http://localhost:3000/auth/callback'
+      }
+    })
+    if (error) throw error
+    // User will be redirected to Google, then back to your app
+  }
+  
+  return (
+    <button onClick={handleGoogleLogin}>
+      Sign in with Google
+    </button>
+  )
+}
+
+// After redirect, get the session
+useEffect(() => {
+  supabase.auth.getSession().then(({ data: { session } }) => {
+    if (session) {
+      const token = session.access_token  // JWT from Supabase!
+      // Use this token for API calls
+    }
+  })
+}, [])
 ```
 
-#### Step 2: Configure plugin with secret
+##### 3. Backend: Same Configuration!
+
 ```javascript
+// No change needed - same as email/password
 await api.use(JwtAuthPlugin, {
-  secret: process.env.JWT_SECRET,
-  
-  // Your token structure
-  userIdField: 'sub',
-  rolesField: 'roles'
+  jwksUrl: 'https://your-project.supabase.co/auth/v1/.well-known/jwks.json'
 })
 ```
 
-## Installation and Setup
+The beauty is that your backend doesn't care HOW users logged in (email, Google, Facebook) - it just validates the JWT from Supabase.
 
-```javascript
-import { JwtAuthPlugin } from 'json-rest-api/plugins/core/jwt-auth-plugin.js';
+## Backend: Validating Tokens
+
+### Basic Configuration Options
 
-// Install the plugin
+```javascript
 await api.use(JwtAuthPlugin, {
-  // Required: Choose one authentication method
-  secret: 'your-secret-key',              // For HS256 tokens
-  // OR
-  publicKey: '-----BEGIN PUBLIC KEY...', // For RS256 tokens  
-  // OR
-  jwksUrl: 'https://your-auth-provider.com/.well-known/jwks.json', // For external auth
-  
-  // Optional: Token configuration
-  audience: 'your-api-audience',
-  issuer: 'https://your-auth-provider.com',
+  // Option 1: For external auth providers (Supabase, Auth0)
+  jwksUrl: 'https://.../.well-known/jwks.json',
   
-  // Optional: Field mappings
-  userIdField: 'sub',        // Where to find user ID in token (default: 'sub')
-  rolesField: 'roles',       // Where to find roles (default: 'roles')
-  ownershipField: 'user_id', // Field in resources for ownership (default: 'user_id')
+  // Option 2: For symmetric key (your own auth)
+  secret: process.env.JWT_SECRET,
   
-  // Optional: Revocation settings
-  revocation: {
-    enabled: true,           // Enable token revocation (default: true)
-    storage: 'database',     // 'database' or 'memory' (default: 'database')
-  },
+  // Option 3: For asymmetric key (your own auth)
+  publicKey: '-----BEGIN PUBLIC KEY-----...',
   
-  // Optional: Endpoints
-  endpoints: {
-    logout: '/auth/logout',   // Add logout endpoint
-    session: '/auth/session'  // Add session check endpoint
-  }
-});
+  // Optional settings
+  audience: 'your-api-audience',  // Required for Auth0
+  issuer: 'https://issuer.com',   // Validate token issuer
+  userIdField: 'sub',              // Where to find user ID (default: 'sub')
+  emailField: 'email',            // Where to find email (default: 'email')
+  ownershipField: 'user_id'       // Field for ownership checks (default: 'user_id')
+})
 ```
 
-## How Auth Rules Work
+### Understanding JWKS Configuration (Recommended)
 
-**Important**: Auth rules must be defined in the same configuration object as your schema when calling `addResource`:
+When you use `jwksUrl` (the recommended approach for Supabase/Auth0), here's what actually happens behind the scenes:
 
+#### What is JWKS?
+JWKS (JSON Web Key Set) is a URL that provides public keys for verifying JWT signatures. Instead of hardcoding keys, your API fetches them dynamically.
+
+#### The Automatic Process
 ```javascript
-await api.addResource('resource-name', {
-  schema: { ... },        // Your field definitions
-  relationships: { ... }, // Optional relationships
-  auth: {                 // Permission rules go here!
-    query: ['public'],
-    get: ['public'],
-    post: ['authenticated'],
-    patch: ['is_owner', 'has_role:editor', 'admin'],
-    delete: ['is_owner', 'has_role:moderator', 'admin']
-  }
+await api.use(JwtAuthPlugin, {
+  jwksUrl: 'https://your-project.supabase.co/auth/v1/.well-known/jwks.json'
 });
 ```
 
-The JWT plugin will automatically extract these rules and enforce them on all operations.
-
-### Common Permission Patterns
-
-```javascript
-// Public read, authenticated write
-auth: {
-  query: ['public'],
-  get: ['public'],
-  post: ['authenticated'],
-  patch: ['authenticated'],
-  delete: ['admin']
-}
-
-// Private resource with role-based access
-auth: {
-  query: ['authenticated'],
-  get: ['authenticated'],
-  post: ['has_role:author', 'has_role:editor'],
-  patch: ['is_owner', 'has_role:editor'],
-  delete: ['is_owner', 'has_role:moderator', 'admin']
-}
-
-// Admin-only resource
-auth: {
-  query: ['admin'],
-  get: ['admin'],
-  post: ['admin'],
-  patch: ['admin'],
-  delete: ['admin']
-}
-
-// User profiles (self-service)
-auth: {
-  query: ['admin'],                    // Only admins can list all users
-  get: ['is_owner', 'admin'],         // Users can see their own profile
-  post: ['admin'],                     // Only admins create users
-  patch: ['is_owner', 'admin'],       // Users can edit their own profile
-  delete: ['admin']                    // Only admins can delete users
+This single line sets up:
+
+1. **Automatic Key Fetching**: On first request, downloads Supabase's current public keys
+2. **Smart Caching**: Caches keys for 10 minutes to avoid repeated downloads
+3. **Key Rotation Handling**: When Supabase rotates keys, your API automatically gets the new ones
+4. **Multiple Key Support**: Handles multiple keys during rotation periods
+
+#### What the JWKS URL Returns
+```json
+{
+  "keys": [
+    {
+      "kid": "abc123",    // Key ID - matches 'kid' in JWT header
+      "kty": "RSA",       // Key type
+      "use": "sig",       // Usage: signature verification
+      "n": "xGOr-H7A...", // RSA public key modulus
+      "e": "AQAB"         // RSA public key exponent
+    },
+    {
+      "kid": "def456",    // Another key (during rotation)
+      "n": "yKPq-J8B...",
+      "e": "AQAB"
+    }
+  ]
 }
 ```
 
-## Declarative Permissions
-
-Instead of writing permission checks in hooks, you declare permissions directly on your resources:
-
-```javascript
-await api.addResource('books', {
-  schema: {
-    id: { type: 'id' },
-    title: { type: 'string', required: true },
-    content: { type: 'text' },
-    user_id: { type: 'string' },
-    country_id: { type: 'number', belongsTo: 'countries', as: 'country' },
-    published: { type: 'boolean', default: false }
-  },
-  
-  // Declare permissions for each operation
-  auth: {
-    query: ['public'],                    // Anyone can list books
-    get: ['public'],                      // Anyone can read a book
-    post: ['authenticated'],              // Must be logged in to create
-    patch: ['is_owner', 'has_role:editor', 'admin'], // Owner, editor, or admin
-    delete: ['is_owner', 'admin']         // Only owner or admin
-  }
-});
-```
-
-The permission rules are checked automatically - no manual hook writing needed!
-
-## Built-in Auth Checkers
+#### Performance Impact
+- **First request**: ~50-100ms (downloads keys from Supabase)
+- **Next 10 minutes**: ~1-2ms (uses cached keys)
+- **After cache expires**: Re-downloads automatically
+- **On verification failure**: Attempts to refresh keys
 
-The plugin includes these auth checkers out of the box:
+#### Why This is Superior to Hardcoded Keys
+- **Zero Maintenance**: Keys update automatically when provider rotates them
+- **Always Secure**: You never handle or store private keys
+- **No Downtime**: Key rotation happens seamlessly
+- **No Code Changes**: Provider can change keys without you knowing
 
-### `public`
-Anyone can access, no authentication required.
+### What Happens During Validation
 
-```javascript
-auth: {
-  query: ['public']  // Anyone can list resources
-}
-```
+1. **Token Extraction**: Plugin extracts token from `Authorization: Bearer <token>` header
+2. **Key Selection**: Matches token's `kid` (key ID) with cached JWKS keys
+3. **Signature Verification**: Validates JWT signature using the matching public key
+4. **Claims Validation**: Checks audience, issuer, expiration
+5. **Context Population**: Sets `context.auth`:
+   ```javascript
+   context.auth = {
+     userId: '123',              // From 'sub' claim
+     email: 'user@example.com',  // From 'email' claim
+     token: { /* full JWT */ },  // All token data
+     tokenId: 'jti-123'          // For revocation
+   }
+   ```
 
-### `authenticated`
-User must be logged in (have a valid token).
+## Using Built-in Checkers
 
-```javascript
-auth: {
-  post: ['authenticated']  // Must be logged in to create
-}
-```
+The plugin provides only THREE built-in authorization checkers:
 
-### `is_owner`
-User must own the resource (their ID matches the ownership field).
+### 1. `public` - No Authentication Required
 
 ```javascript
 auth: {
-  patch: ['is_owner'],  // Only owner can update
-  delete: ['is_owner']  // Only owner can delete
+  query: ['public'],  // Anyone can read, even without token
+  get: ['public']
 }
-
-// The plugin checks: record.user_id === context.auth.userId
-// The ownership field is configurable (default: 'user_id')
 ```
 
-### `admin`
-User must have the 'admin' role.
+### 2. `authenticated` - Must Be Logged In
 
 ```javascript
 auth: {
-  delete: ['admin']  // Only admins can delete
+  post: ['authenticated'],   // Must have valid JWT token
+  patch: ['authenticated']
 }
 ```
 
-### `has_role:X`
-User must have a specific role.
+### 3. `owns` - Must Own the Resource
 
 ```javascript
 auth: {
-  patch: ['has_role:editor'],        // Must be editor
-  delete: ['has_role:moderator']     // Must be moderator
+  patch: ['owns'],  // Can only edit records where user_id matches
+  delete: ['owns']  // Can only delete your own records
 }
 ```
 
-### `has_permission:X`
-User must have a specific permission (for fine-grained control).
-
-```javascript
-auth: {
-  patch: ['has_permission:posts:write'],
-  delete: ['has_permission:posts:delete']
-}
-```
+The `owns` checker compares the `user_id` field in the database record with the current user's ID from the token.
 
-## Making Authenticated API Calls Directly
+## Progressive Examples
 
-When using the API programmatically (not through HTTP), you can pass authentication context as the second parameter to any API method:
+Let's build up from simple to complex:
 
-### Direct API Usage
+### Example 1: Public API (No Auth)
 
 ```javascript
-// Import your configured API
-import { api } from './your-api-setup.js';
-
-// Make authenticated calls by passing auth context as second parameter
-const authContext = {
-  auth: {
-    userId: 'user-123',
-    email: 'user@example.com',
-    role: 'admin',
-    // Any other auth data your app needs
-  }
-};
-
-// Query with auth
-const books = await api.resources.books.query({
-  filters: { published: true },
-  include: ['author'],
-  page: { size: 10 }
-}, authContext);
-
-// Get single resource with auth
-const book = await api.resources.books.get({
-  id: 123
-}, authContext);
-
-// Create with auth
-const newBook = await api.resources.books.post({
-  inputRecord: {
-    data: {
-      type: 'books',
-      attributes: {
-        title: 'My New Book',
-        isbn: '978-3-16-148410-0'
-      }
-    }
-  }
-}, authContext);
-
-// Update with auth
-const updated = await api.resources.books.patch({
-  id: 123,
-  inputRecord: {
-    data: {
-      type: 'books',
-      id: '123',
-      attributes: {
-        title: 'Updated Title'
-      }
-    }
+await api.addResource('articles', {
+  schema: {
+    title: { type: 'string', required: true },
+    content: { type: 'text' }
   }
-}, authContext);
-
-// Delete with auth
-await api.resources.books.delete({
-  id: 123
-}, authContext);
+  // No auth property = completely open
+})
 ```
 
-### Multi-tenancy Example
-
-If using the MultiHome plugin for multi-tenancy:
+### Example 2: Read-Only Public, Write Requires Login
 
 ```javascript
-// Tenant-specific context
-const tenantContext = {
+await api.addResource('articles', {
+  schema: {
+    title: { type: 'string', required: true },
+    content: { type: 'text' },
+    user_id: { type: 'string' }
+  },
+  
   auth: {
-    userId: 'user-123',
-    multihome_id: 'tenant-a'  // Required for multihome
+    query: ['public'],         // Anyone can read
+    get: ['public'],
+    post: ['authenticated'],   // Must be logged in to create
+    patch: ['authenticated'],
+    delete: ['authenticated']
   }
-};
-
-// All operations will be scoped to tenant-a
-const tenantProjects = await api.resources.projects.query({}, tenantContext);
+})
 ```
 
-### Script/Admin Usage
-
-For administrative scripts or background jobs:
+### Example 3: Users Can Only Edit Their Own Content
 
 ```javascript
-// Admin context with elevated privileges
-const adminContext = {
+await api.addResource('articles', {
+  schema: {
+    title: { type: 'string', required: true },
+    content: { type: 'text' },
+    user_id: { type: 'string' }  // Auto-set on create
+  },
+  
   auth: {
-    userId: 'system',
-    role: 'superadmin',
-    isSystem: true
+    query: ['public'],
+    get: ['public'],
+    post: ['authenticated'],
+    patch: ['owns'],  // Only edit your own
+    delete: ['owns']  // Only delete your own
   }
-};
+})
 
-// Batch operations
-async function processAllBooks() {
-  const books = await api.resources.books.query({
-    page: { size: 100 }
-  }, adminContext);
-  
-  for (const book of books.data) {
-    // Process each book with admin privileges
-    await api.resources.books.patch({
-      id: book.id,
-      inputRecord: { /* ... */ }
-    }, adminContext);
+// Also enable auto-ownership
+await api.use(JwtAuthPlugin, {
+  jwksUrl: '...',
+  autoOwnership: {
+    enabled: true,  // Auto-set user_id on create
+    filterByOwner: true  // Users only see their own records in queries
   }
-}
+})
 ```
 
-### Testing Example
-
-In tests, you can easily simulate different users:
+### Example 4: Adding Admin Override (Custom Checker)
 
 ```javascript
-// Test different permission scenarios
-const contexts = {
-  anonymous: {},  // No auth
-  regular: { auth: { userId: 'user-1', role: 'member' } },
-  editor: { auth: { userId: 'user-2', role: 'editor' } },
-  admin: { auth: { userId: 'user-3', role: 'admin' } }
-};
-
-// Test that regular users can't delete
-await assert.rejects(
-  api.resources.books.delete({ id: 1 }, contexts.regular),
-  /Forbidden/
-);
-
-// Test that editors can update
-await api.resources.books.patch({
-  id: 1,
-  inputRecord: { /* ... */ }
-}, contexts.editor);
-```
-
-## Using Auth Helpers
-
-While declarative permissions handle most cases, you can also use auth helpers in custom hooks:
+// Register a custom role checker
+api.helpers.auth.registerChecker('role', async (context, { param }) => {
+  // In real app, query your users table
+  const user = await api.resources.users.get(context.auth.userId)
+  return user.role === param
+})
 
-```javascript
-// In any hook, you have access to helpers.auth
-api.addHook('beforeCreate', async ({ context, inputRecord, helpers }) => {
-  // Require authentication
-  helpers.auth.requireAuth(context);
-  
-  // Require specific roles
-  helpers.auth.requireRoles(context, ['editor', 'admin']);
-  
-  // Check ownership (multiple ways)
-  helpers.auth.requireOwnership(context);              // Uses context.existingRecord
-  helpers.auth.requireOwnership(context, record);      // Pass record
-  helpers.auth.requireOwnership(context, '123');       // Pass user ID
+await api.addResource('articles', {
+  schema: { /* ... */ },
   
-  // Set owner on new records
-  inputRecord.user_id = context.auth.userId;
-});
-```
-
-## Token Management
-
-### Context Population
-
-When a valid JWT token is provided, the plugin populates `context.auth`:
-
-```javascript
-context.auth = {
-  userId: '123',                    // From token 'sub' claim
-  email: 'user@example.com',        // From token 'email' claim
-  roles: ['user', 'editor'],        // From token 'roles' claim
-  permissions: ['posts:write'],     // From token 'permissions' claim
-  token: { /* full JWT payload */ },
-  tokenId: 'jti-value'              // For revocation
-}
-```
-
-### Token Revocation and Logout
-
-The plugin supports token revocation for logout and security. Here's how it works:
-
-#### Frontend Logout Flow
-```javascript
-// 1. Call your API's logout endpoint
-await fetch('/api/auth/logout', {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${token}`
+  auth: {
+    query: ['public'],
+    get: ['public'],
+    post: ['authenticated'],
+    patch: ['owns', 'role:admin'],  // Owner OR admin
+    delete: ['owns', 'role:admin']   // Owner OR admin
   }
-});
-
-// 2. Clear local storage
-localStorage.removeItem('supabase.auth.token');
-
-// 3. Sign out from Supabase (optional but recommended)
-await supabase.auth.signOut();
+})
 ```
 
-#### API-Side Token Management
-```javascript
-// The plugin provides these methods:
-
-// In your custom endpoints
-await helpers.auth.logout(context);  // Revokes current token
-
-// Revoke specific token (e.g., from webhook)
-await helpers.auth.revokeToken(jti, userId, expiresAt);
+## Advanced: Custom Authorization
 
-// Check current session
-GET /api/auth/session
-// Returns: { authenticated: true/false, user: {...} }
-```
-
-#### Handling Auth Provider Webhooks
+The plugin is designed to be minimal. For complex authorization, you create custom checkers:
 
-If your auth provider supports webhooks, you can sync logouts:
+### Database-Driven Roles
 
 ```javascript
-// Handle Supabase auth events
-api.addRoute('POST', '/webhooks/supabase-auth', async ({ body }) => {
-  if (body.event === 'SIGNED_OUT') {
-    // Revoke the token in your API too
-    await helpers.auth.revokeToken(
-      body.logout_token_id,
-      body.user_id,
-      body.token_exp
-    );
+// Store roles in your database
+await api.addResource('user_roles', {
+  schema: {
+    user_id: { type: 'string', required: true },
+    role: { type: 'string', required: true }
   }
-});
-```
-
-### Working with Different Auth Providers
+})
 
-The plugin works with any JWT provider. Here are the common configurations:
+// Create role checker
+api.helpers.auth.registerChecker('role', async (context, { param }) => {
+  const roles = await api.resources.user_roles.query({
+    filter: { user_id: context.auth.userId }
+  })
+  return roles.some(r => r.role === param)
+})
 
-#### Supabase Configuration
-```javascript
-await api.use(JwtAuthPlugin, {
-  jwksUrl: `${SUPABASE_URL}/auth/v1/.well-known/jwks.json`,
-  rolesField: 'app_metadata.roles',     // Supabase stores custom data here
-  
-  // Add roles in Supabase Dashboard:
-  // Authentication > Users > Select User > Edit User Metadata
-  // Add to app_metadata: { "roles": ["admin", "editor"] }
-});
+// Use it
+auth: {
+  delete: ['role:admin']  // Must have admin role in database
+}
 ```
 
-#### Auth0 Configuration
-```javascript
-await api.use(JwtAuthPlugin, {
-  jwksUrl: `https://${AUTH0_DOMAIN}/.well-known/jwks.json`,
-  audience: AUTH0_AUDIENCE,
-  issuer: `https://${AUTH0_DOMAIN}/`,
-  rolesField: 'https://your-app.com/roles',  // Auth0 uses namespaced claims
-  
-  // Add roles in Auth0:
-  // Create a Rule or Action that adds roles to the token
-});
-```
+### Subscription Tiers
 
-#### Firebase Auth Configuration
 ```javascript
-await api.use(JwtAuthPlugin, {
-  jwksUrl: 'https://www.googleapis.com/robot/v1/metadata/x509/securetoken@system.gserviceaccount.com',
-  audience: process.env.FIREBASE_PROJECT_ID,
-  issuer: `https://securetoken.google.com/${process.env.FIREBASE_PROJECT_ID}`,
-  rolesField: 'custom_claims.roles'
-});
-```
+api.helpers.auth.registerChecker('plan', async (context, { param }) => {
+  const user = await api.resources.users.get(context.auth.userId)
+  const plans = ['free', 'basic', 'pro', 'enterprise']
+  const requiredLevel = plans.indexOf(param)
+  const userLevel = plans.indexOf(user.subscription_plan)
+  return userLevel >= requiredLevel
+})
 
-## Custom Auth Checkers
+// Premium features
+auth: {
+  post: ['plan:pro']  // Need pro plan or higher
+}
+```
 
-You can create domain-specific auth checkers:
+### Team Membership
 
 ```javascript
-// Register a custom checker
-helpers.auth.registerChecker('is_team_member', async (context, { existingRecord }) => {
-  if (!context.auth?.userId) return false;
-  
-  // Check if user is part of the team
-  const team = await api.resources.teams.get({ 
-    id: existingRecord.team_id 
-  });
-  
-  return team.member_ids.includes(context.auth.userId);
-});
+api.helpers.auth.registerChecker('team', async (context, { param }) => {
+  const membership = await api.resources.team_members.query({
+    filter: { 
+      user_id: context.auth.userId,
+      team_id: param
+    }
+  })
+  return membership.length > 0
+})
 
-// Use in a resource
-await api.addResource('team_documents', {
-  schema: { /* ... */ },
-  
-  auth: {
-    query: ['is_team_member'],
-    get: ['is_team_member'],
-    patch: ['is_team_member', 'admin']
-  }
-});
+// Team resources
+auth: {
+  query: ['team:engineering']  // Must be on engineering team
+}
 ```
 
-## Complete Example: Book Catalog API
-
-Let's build a complete authenticated book catalog API:
+### Multi-Tenant Permissions
 
 ```javascript
-import { Api } from 'hooked-api';
-import { RestApiPlugin, RestApiKnexPlugin, HttpPlugin } from 'json-rest-api';
-import { JwtAuthPlugin } from 'json-rest-api/plugins/core/jwt-auth-plugin.js';
-
-// 1. Create and configure API
-const api = new Api();
-
-await api.use(RestApiPlugin);
-await api.use(RestApiKnexPlugin, { knex });
-
-// 2. Configure JWT Auth for Supabase
-await api.use(JwtAuthPlugin, {
-  jwksUrl: `${process.env.SUPABASE_URL}/auth/v1/.well-known/jwks.json`,
-  rolesField: 'app_metadata.roles',
-  ownershipField: 'user_id'
-});
-
-// 3. Define authenticated resources
-await api.addResource('books', {
-  schema: {
-    id: { type: 'id' },
-    title: { type: 'string', required: true },
-    isbn: { type: 'string' },
-    user_id: { type: 'string' },        // Owner
-    country_id: { type: 'number', belongsTo: 'countries' },
-    published: { type: 'boolean', default: false }
-  },
-  
-  auth: {
-    query: ['public'],                  // Anyone can browse
-    get: ['public'],                    // Anyone can read
-    post: ['authenticated'],            // Must be logged in
-    patch: ['is_owner', 'has_role:librarian'], // Owner or librarian
-    delete: ['is_owner', 'admin']       // Owner or admin
-  }
-});
-
-// 4. Auto-set ownership on create
-api.addHook('beforeCreate', async ({ context, inputRecord, scopeName }) => {
-  if (scopeName === 'books' && context.auth) {
-    inputRecord.user_id = context.auth.userId;
-  }
-});
-
-// 5. Filter unpublished books for anonymous users
-api.addHook('beforeQuery', async ({ context, queryParams, scopeName }) => {
-  if (scopeName === 'books' && !context.auth) {
-    queryParams.filter = { ...queryParams.filter, published: true };
-  }
-});
-
-// 6. Start HTTP server
-await api.use(HttpPlugin, { port: 3000, basePath: '/api' });
+api.helpers.auth.registerChecker('tenant_role', async (context, { param }) => {
+  const tenantId = context.request.headers['x-tenant-id']
+  const membership = await api.resources.tenant_members.query({
+    filter: { 
+      tenant_id: tenantId,
+      user_id: context.auth.userId
+    }
+  })
+  return membership[0]?.role === param
+})
 
-// Frontend usage:
-// const { data: { session } } = await supabase.auth.signIn(...)
-// const token = session.access_token
-// 
-// fetch('/api/books', {
-//   headers: { 'Authorization': `Bearer ${token}` }
-// })
+// Tenant-specific permissions
+auth: {
+  delete: ['tenant_role:admin']  // Admin in current tenant
+}
 ```
 
-## More Examples
+## Token Management
 
-### Public Blog with Private Drafts
+### Accessing Token Data
 
 ```javascript
-await api.addResource('posts', {
-  schema: {
-    id: { type: 'id' },
-    title: { type: 'string', required: true },
-    content: { type: 'text' },
-    user_id: { type: 'string' },
-    published: { type: 'boolean', default: false }
+// After validation, you have access to:
+context.auth = {
+  userId: '123',                    // From 'sub' claim
+  email: 'user@example.com',        // From 'email' claim
+  token: {                          // Full JWT payload
+    sub: '123',
+    email: 'user@example.com',
+    iat: 1234567890,
+    exp: 1234567890,
+    // Any custom claims from your auth provider
+    app_metadata: { /* ... */ },
+    user_metadata: { /* ... */ }
   },
-  
-  auth: {
-    query: ['public'],           // Anyone can list
-    get: ['public'],             // Anyone can read
-    post: ['authenticated'],     // Must be logged in to create
-    patch: ['is_owner'],         // Only owner can edit
-    delete: ['is_owner', 'admin'] // Owner or admin can delete
-  }
-});
-
-// Add custom filtering for drafts
-api.addHook('beforeQuery', async ({ context, queryParams }) => {
-  // Non-owners only see published posts
-  if (!context.auth || context.auth.userId !== queryParams.filter?.user_id) {
-    queryParams.filter = { ...queryParams.filter, published: true };
-  }
-});
+  tokenId: 'jti-123'               // For revocation
+}
 ```
 
-### Multi-Author Books
+### Token Revocation / Logout
 
 ```javascript
-await api.addResource('books', {
-  schema: {
-    id: { type: 'id' },
-    title: { type: 'string', required: true },
-    publisher_id: { type: 'number', belongsTo: 'publishers' }
-  },
-  
-  relationships: {
-    authors: { hasMany: 'authors', through: 'book_authors' }
+// Enable revocation
+await api.use(JwtAuthPlugin, {
+  jwksUrl: '...',
+  revocation: {
+    enabled: true,
+    storage: 'database'  // Survives restarts
   },
-  
-  auth: {
-    query: ['public'],
-    get: ['public'],
-    post: ['has_role:author', 'has_role:editor'],
-    patch: ['is_book_author', 'has_role:editor'],
-    delete: ['admin']
+  endpoints: {
+    logout: '/auth/logout'  // Add logout endpoint
   }
-});
+})
 
-// Custom checker for multi-author books
-helpers.auth.registerChecker('is_book_author', async (context, { existingRecord }) => {
-  if (!context.auth?.userId || !existingRecord) return false;
-  
-  const bookAuthors = await api.resources.book_authors.query({
-    queryParams: {
-      filter: {
-        book_id: existingRecord.id,
-        author_id: context.auth.userId
-      }
+// Frontend logout
+async function logout(token) {
+  // 1. Revoke token on your API
+  await fetch('http://localhost:3000/auth/logout', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`
     }
-  });
-  
-  return bookAuthors.length > 0;
-});
-```
-
-### Admin Panel
-
-```javascript
-await api.addResource('users', {
-  schema: {
-    id: { type: 'id' },
-    email: { type: 'string', required: true },
-    role: { type: 'string' },
-    banned: { type: 'boolean', default: false }
-  },
+  })
   
-  auth: {
-    query: ['admin', 'has_role:user_manager'],
-    get: ['admin', 'has_role:user_manager', 'is_self'],
-    post: ['admin'],
-    patch: ['admin', 'has_role:user_manager', 'is_self'],
-    delete: ['admin']
-  }
-});
-
-// Users can view/edit their own profile
-helpers.auth.registerChecker('is_self', (context, { existingRecord }) => {
-  return context.auth?.userId === existingRecord?.id;
-});
+  // 2. Clear Supabase session
+  await supabase.auth.signOut()
+}
 ```
 
-## Best Practices
+### Direct API Usage (No HTTP)
 
-### 1. Use Declarative Permissions
+For testing or server-side operations:
 
-Instead of:
 ```javascript
-// ❌ Manual permission checks in hooks
-api.addHook('checkPermissions', async ({ context, operation }) => {
-  if (operation === 'post' && !context.auth) {
-    throw new Error('Must be authenticated');
+// Create auth context manually
+const authContext = {
+  auth: {
+    userId: 'user-123',
+    email: 'user@example.com'
   }
-});
-```
-
-Do this:
-```javascript
-// ✅ Declarative permissions
-auth: {
-  post: ['authenticated']
 }
-```
 
-### 2. Combine Rules with OR Logic
+// Use API methods directly
+const posts = await api.resources.posts.query({
+  filter: { published: true }
+}, authContext)  // Pass context as second parameter
 
-Multiple rules in an array work as OR conditions:
-```javascript
-auth: {
-  patch: ['is_owner', 'has_role:moderator', 'admin']
-  // Can update if: owner OR moderator OR admin
-}
+const newPost = await api.resources.posts.post({
+  inputRecord: { /* ... */ }
+}, authContext)
 ```
 
-### 3. Set Ownership on Create
+## Common Issues and Solutions
 
+### Issue: "Access denied" on all requests
+**Solution**: Check that your token is being sent correctly:
 ```javascript
-api.addHook('beforeCreate', async ({ context, inputRecord, scopeName }) => {
-  // Set owner for user-owned resources
-  if (scopeName === 'posts' && context.auth) {
-    inputRecord.user_id = context.auth.userId;
-  }
-});
-```
-
-### 4. Use Appropriate Checkers
-
-- `public` - For truly public data
-- `authenticated` - When you just need a logged-in user
-- `is_owner` - For user-owned resources
-- `has_role:X` - For role-based access
-- `admin` - For administrative functions
+// Correct
+headers: { 'Authorization': `Bearer ${token}` }
 
-### 5. Handle Unauthenticated Users Gracefully
+// Wrong
+headers: { 'Authorization': token }  // Missing "Bearer "
+```
 
+### Issue: Token validation fails
+**Solution**: Ensure your JWKS URL matches your auth provider:
 ```javascript
-// Filter data for unauthenticated users instead of denying access
-api.addHook('beforeQuery', async ({ context, queryParams, scopeName }) => {
-  if (scopeName === 'posts' && !context.auth) {
-    // Only show published posts to anonymous users
-    queryParams.filter = { ...queryParams.filter, published: true };
-  }
-});
+// Supabase: Check your project URL
+jwksUrl: 'https://YOUR-PROJECT.supabase.co/auth/v1/.well-known/jwks.json'
+
+// Auth0: Check your domain
+jwksUrl: 'https://YOUR-DOMAIN.auth0.com/.well-known/jwks.json'
 ```
 
-### 6. Create Semantic Custom Checkers
+### Issue: Google login token not working
+**Solution**: Remember that Google login still goes through your auth provider:
+- User logs in with Google → Supabase/Auth0 → Get Supabase/Auth0 JWT
+- Your API validates the Supabase/Auth0 JWT, not Google's token
 
+### Issue: Ownership not working
+**Solution**: Ensure your schema has a `user_id` field:
 ```javascript
-// ✅ Good: Semantic name that explains the permission
-helpers.auth.registerChecker('can_moderate_content', (context) => {
-  return context.auth?.roles?.includes('moderator') || 
-         context.auth?.roles?.includes('admin');
-});
-
-// ❌ Bad: Technical implementation detail
-helpers.auth.registerChecker('has_mod_or_admin', (context) => {
-  // Same logic but less clear intent
-});
+schema: {
+  user_id: { type: 'string' }  // Required for 'owns' checker
+}
 ```
 
 ## Summary
 
-The JWT Auth Plugin provides a clean, declarative way to handle authentication and authorization in your REST API. By defining permissions directly on resources, you eliminate boilerplate code and create a more maintainable, secure API.
-
-Key benefits:
-- **No manual hook writing** for common permission patterns
-- **Clear, readable** permission declarations
-- **Flexible** enough for complex scenarios
-- **Secure by default** with deny-by-default behavior
-- **Extensible** with custom checkers
+The JWT Authentication Plugin provides:
+1. **Token validation** from any JWT provider (Supabase, Auth0, etc.)
+2. **Three built-in checkers**: `public`, `authenticated`, `owns`
+3. **Framework for custom authorization** via `checker:parameter` pattern
 
-Whether you're building a simple blog or a complex multi-tenant application, the declarative permission system scales with your needs while keeping your code clean and maintainable.
+Remember:
+- **Frontend**: Handles login (email, Google, etc.) and gets JWT
+- **Backend**: Validates JWT and enforces permissions
+- **Start simple**: Use built-in checkers, add custom logic as needed