@basictech/react 0.8.0-beta.4 → 0.9.0-beta.0

package/AUTH_IMPLEMENTATION_GUIDE.md

@@ -1,2011 +0,0 @@
-# Authentication Implementation Guide
-
-This guide provides comprehensive REST API specifications and requirements for implementing authentication with Basic PDS Server. 
-
----
-
-## Table of Contents
-
-1. [PDS Authentication](#pds-authentication)
-   - [Account Registration](#account-registration)
-   - [Account Login](#account-login)
-   - [OAuth Authorization](#oauth-authorization)
-   - [Session Management](#session-management)
-   - [Password Management](#password-management)
-   - [Email Verification](#email-verification)
-   - [Handle Availability](#handle-availability)
-   - [DID Resolution](#did-resolution)
-2. [OAuth2 Implementation](#oauth2-implementation)
-   - [Discovery & Configuration](#discovery--configuration)
-   - [Scopes](#scopes) 
-   - [Authorization Code Flow](#authorization-code-flow)
-   - [Token Management](#token-management)
-   - [User Information](#user-information)
-3. [Scopes & Authorization](#scopes--authorization)
-   - [Scope System](#scope-system)
-   - [Available Scopes Reference](#available-scopes-reference)
-   - [Action Implications](#action-implications)
-   - [Admin Scope Behavior](#admin-scope-behavior)
-   - [Authorization Errors](#authorization-errors)
-   - [Best Practices](#best-practices)
-4. [PKCE Extension](#pkce-extension-optional)
-5. [DPoP Extension](#dpop-extension-optional)
-6. [Security Requirements](#security-requirements)
-
----
-
-## PDS Authentication
-
-PDS authentication provides handle/password-based authentication with email verification, password reset, and decentralized identifiers (DIDs). This is meant for clients of the PDS server, usually a front-end.
-
----
-
-### Account Registration
-
-**Endpoint:** `POST /auth/signup`
-
-Create a new user account with handle and password.
-
-#### Request
-
-```http
-POST /auth/signup HTTP/1.1
-Content-Type: application/json
-
-{
-  "type": "password",
-  "handle": "john_doe",
-  "password": "securepassword123",
-  "email": "john@example.com",
-  "name": "John Doe"
-}
-```
-
-#### Request Body Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `type` | string | Yes | Authentication type. Must be `"password"` |
-| `handle` | string | Yes | Unique handle (alphanumeric, 2-30 chars) |
-| `password` | string | Yes | User password (minimum 3 characters) |
-| `email` | string | No | User email address (for verification) |
-| `name` | string | No | User's display name |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "data": {
-    "id": "acc_12345",
-    "handle": "john_doe.basic.id",
-    "email": "john@example.com",
-    "name": "John Doe",
-    "created_at": "2025-09-29T10:00:00Z"
-  }
-}
-```
-
-**Error (400):**
-```json
-{
-  "error": "Email already verified",
-  "message": "This email address is already verified with another account"
-}
-```
-
-#### Email Verification
-
-If an email is provided during signup, a verification email is automatically sent containing a verification link:
-```
-https://your-app.com/login?verify_email_token={token}&email={email}
-```
-
-The verification token is valid for **24 hours**.
-
----
-
-### Account Login
-
-**Endpoint:** `POST /auth/login`
-
-Authenticate with handle and password to receive access and refresh tokens.
-
-#### Request
-
-```http
-POST /auth/login HTTP/1.1
-Content-Type: application/json
-
-{
-  "handle": "john_doe",
-  "password": "securepassword123"
-}
-```
-
-#### Request Body Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `handle` | string | Yes | User's handle or email |
-| `password` | string | Yes | User's password |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "auth": {
-    "account_id": "acc_12345",
-    "ok": true
-  },
-  "token": {
-    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "token_type": "Bearer",
-    "expires_in": 60,
-    "refresh_token": "3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef123456..."
-  }
-}
-```
-
-**Error (401):**
-```json
-{
-  "error": "Unauthorized - Invalid credentials"
-}
-```
-
-#### Token Details
-
-- **Access Token**: JWT signed with RS256, valid for 1 minute
-- **Refresh Token**: Cryptographically random opaque token stored in database, valid for 30 days
-- **Token Type**: Always `"Bearer"`
-
-The access token payload contains:
-```json
-{
-  "userId": "acc_12345",
-  "clientId": "self",
-  "scope": "admin",
-  "sid": "sess_abc123",
-  "iat": 1727606400,
-  "exp": 1727606460
-}
-```
-
-**Token Claims:**
-- `userId` - Account ID
-- `clientId` - Always `"self"` for login
-- `scope` - Always `"admin"` for login (grants full account access)
-- `sid` - Session ID
-- `iat` - Issued at timestamp
-- `exp` - Expiration timestamp
-
-**The `admin` scope:**
-- Grants access to all account features
-- Can view/manage all sessions
-- Can access data from all connected apps
-- Only available via login (not OAuth apps)
-
----
-
-### OAuth Authorization
-
-**Endpoint:** `POST /auth/authorize`
-
-After a user logs in with PDS authentication, they can authorize OAuth applications to access their account.
-
-#### Request
-
-```http
-POST /auth/authorize HTTP/1.1
-Host: auth.example.com
-Authorization: Bearer {user_access_token}
-Content-Type: application/json
-
-{
-  "client_id": "app_123",
-  "redirect_uri": "https://app.example.com/callback",
-  "scope": "profile email",
-  "state": "xyz123",
-  "code_challenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
-  "code_challenge_method": "S256"
-}
-```
-
-#### Request Headers
-
-| Header | Required | Description |
-|--------|----------|-------------|
-| `Authorization` | Yes | Bearer token with `admin` scope (from login) |
-
-**Note:** Only users logged in via `/auth/login` can authorize apps (have admin scope)
-
-#### Request Body Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `client_id` | string | Yes | Application identifier |
-| `redirect_uri` | string | Yes | Callback URI |
-| `scope` | string | Yes | Requested scopes |
-| `state` | string | No | State parameter from initial request |
-| `code_challenge` | string | No | PKCE code challenge |
-| `code_challenge_method` | string | No | Must be `"S256"` if challenge provided |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "code": "auth_abc123def456",
-  "redirect": "https://app.example.com/callback?code=auth_abc123def456&state=xyz123",
-  "connect": {
-    "id": "conn_789",
-    "account_id": "acc_12345",
-    "project_id": "app_123",
-    "status": "connected",
-    "scope": "profile email"
-  },
-  "pkce_supported": true
-}
-```
-
-**Error (401):**
-```json
-{
-  "error": "access_denied",
-  "error_description": "User authentication failed"
-}
-```
-
-#### Authorization Code Properties
-
-- **Format**: Opaque string (e.g., `abc123def456`)
-- **Validity**: Single use only
-- **Expiration**: Short-lived (typically 10 minutes)
-- **Storage**: Includes redirect_uri, scope, PKCE challenge if provided
-
----
-
-### Session Management
-
-Sessions track authenticated devices and provide security features like device management and refresh token family tracking.
-
-#### Session Creation
-
-Sessions are automatically created during:
-1. **PDS Login** (`POST /auth/login`)
-2. **OAuth2 Token Exchange** (`POST /auth/token` with authorization code)
-
-Each session includes:
-- **Session ID**: Unique identifier
-- **Device Instance ID**: Unique device identifier
-- **User Agent**: Browser/application information
-- **Platform**: Device platform (Web, Mobile, etc.)
-- **IP Address**: Connection IP
-- **Last Seen**: Timestamp of last activity
-
-#### Session Properties
-
-```json
-{
-  "id": "sess_abc123",
-  "account_connection_id": "conn_789",
-  "account_id": "acc_12345",
-  "project_id": "app_123",
-  "device_instance_id": "device_1727606400_abc",
-  "label": "OAuth Client Session",
-  "user_agent": "Mozilla/5.0...",
-  "platform": "Web",
-  "ip_inet": "192.168.1.1",
-  "last_seen_at": "2025-09-29T10:30:00Z",
-  "created_at": "2025-09-29T10:00:00Z"
-}
-```
-
-#### Refresh Token Chain
-
-Each session maintains a **refresh token family**:
-- All refresh tokens in a session belong to the same family
-- Token rotation creates new tokens in the same family
-- Reuse detection revokes the entire family
-- Session termination revokes all family tokens
-
----
-
-### Password Management
-
-#### Request Password Reset
-
-**Endpoint:** `POST /auth/forgot-password`
-
-Request a password reset link to be sent via email.
-
-#### Request
-
-```http
-POST /auth/forgot-password HTTP/1.1
-Content-Type: application/json
-
-{
-  "identifier": "john@example.com"
-}
-```
-
-#### Request Body Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `identifier` | string | Yes | User's email or handle |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "success": true,
-  "message": "If an account with that email/handle exists, a password reset link has been sent"
-}
-```
-
-**Note:** For security, the response is always the same whether the account exists or not.
-
-#### Reset Token
-
-The reset link sent via email has the format:
-```
-https://your-app.com/login?reset_token={token}&email={email}
-```
-
-The reset token is valid for **15 minutes**.
-
----
-
-#### Reset Password with Token
-
-**Endpoint:** `POST /auth/reset-password`
-
-Reset the password using a valid reset token.
-
-#### Request
-
-```http
-POST /auth/reset-password HTTP/1.1
-Content-Type: application/json
-
-{
-  "reset_token": "abc123def456...",
-  "password": "newSecurePassword456"
-}
-```
-
-#### Request Body Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `reset_token` | string | Yes | Valid reset token from email |
-| `password` | string | Yes | New password (minimum 3 characters) |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "success": true,
-  "message": "Password has been successfully reset"
-}
-```
-
-**Error (400):**
-```json
-{
-  "error": "Invalid or expired reset token"
-}
-```
-
----
-
-#### Verify Reset Token
-
-**Endpoint:** `POST /auth/verify-reset-token`
-
-Check if a password reset token is valid before showing the reset form.
-
-#### Request
-
-```http
-POST /auth/verify-reset-token HTTP/1.1
-Content-Type: application/json
-
-{
-  "reset_token": "abc123def456..."
-}
-```
-
-#### Response
-
-```json
-{
-  "valid": true
-}
-```
-
----
-
-### Email Verification
-
-#### Send Verification Email
-
-**Endpoint:** `POST /auth/verify-email`
-
-Request a verification email to be sent.
-
-#### Request
-
-```http
-POST /auth/verify-email HTTP/1.1
-Content-Type: application/json
-
-{
-  "email": "john@example.com"
-}
-```
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "success": true,
-  "message": "If an account with that email exists, a verification link has been sent",
-  "verification_link": "https://your-app.com/login?verify_email_token=..."
-}
-```
-
-**Already Verified (200):**
-```json
-{
-  "success": true
-}
-```
-
----
-
-#### Verify Email with Token
-
-**Endpoint:** `POST /auth/verify-email-token`
-
-Complete email verification using the token from the verification link.
-
-#### Request
-
-```http
-POST /auth/verify-email-token HTTP/1.1
-Content-Type: application/json
-
-{
-  "token": "abc123def456..."
-}
-```
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "success": true,
-  "message": "Email has been successfully verified"
-}
-```
-
-**Error (400):**
-```json
-{
-  "error": "Invalid or expired verification token"
-}
-```
-
----
-
-### Handle Availability
-
-**Endpoint:** `GET /auth/check-handle`
-
-Check if a handle is available for registration.
-
-#### Request
-
-```http
-GET /auth/check-handle?handle=john_doe HTTP/1.1
-```
-
-> **Backward compatibility:** The legacy `GET /auth/check-username` endpoint redirects to `/auth/check-handle`.
-
-#### Query Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `handle` | string | Yes | Handle to check |
-
-#### Response
-
-```json
-{
-  "available": true
-}
-```
-
----
-
-### DID Resolution
-
-**Endpoint:** `GET /auth/resolve`
-
-Resolve a decentralized identifier (DID) to its document. Further DID support coming soon.
-
-#### Request
-
-```http
-GET /auth/resolve?did=did:pds:base64url_encoded_data HTTP/1.1
-```
-
-#### Query Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `did` | string | Yes | DID to resolve (format: `did:pds:{base64url}`) |
-
-#### Response
-
-```json
-{
-  "did": "decoded_did_data"
-}
-```
-
-#### DID Format
-
-DIDs follow the format: `did:pds:{base64url_encoded_data}`
-
-- Must start with `did:`
-- Method must be `pds`
-- Body is base64url encoded data
-
----
-
-## OAuth2 Implementation
-
-OAuth2 endpoints are meant for client applications who want to connect to a user's PDS.
-OAuth2 provides secure delegated access using the **Authorization Code Flow** with optional PKCE support. This implementation follows RFC 6749 (OAuth 2.0) and RFC 6750 (Bearer Token).
-
-### Discovery & Configuration
-
-#### OpenID Connect Discovery
-
-**Endpoint:** `GET /.well-known/openid-configuration`
-
-Provides metadata about the OAuth2/OIDC server capabilities.
-
-#### Request
-
-```http
-GET /.well-known/openid-configuration HTTP/1.1
-Host: auth.example.com
-```
-
-#### Response
-
-```json
-{
-  "issuer": "https://auth.example.com",
-  "authorization_endpoint": "https://auth.example.com/auth/authorize",
-  "token_endpoint": "https://auth.example.com/auth/token",
-  "userinfo_endpoint": "https://auth.example.com/auth/userinfo",
-  "jwks_uri": "https://auth.example.com/auth/.well-known/jwks.json",
-  "response_types_supported": ["code"],
-  "grant_types_supported": ["authorization_code", "refresh_token"],
-  "subject_types_supported": ["public"],
-  "id_token_signing_alg_values_supported": ["RS256"],
-  "scopes_supported": [
-    "openid:read",
-    "profile:read",
-    "email:read",
-    "account:read",
-    "account:write",
-    "account:update",
-    "account:app:read",
-    "account:app:write",
-    "account:app:delete",
-    "account:session:read",
-    "account:session:write",
-    "account:session:update",
-    "account:session:delete",
-    "app:db:read",
-    "app:db:write",
-    "app:db:update",
-    "app:db:delete",
-    "admin"
-  ],
-  "token_endpoint_auth_methods_supported": [
-    "client_secret_post",
-    "client_secret_basic",
-    "none"
-  ],
-  "code_challenge_methods_supported": ["S256"],
-  "claims_supported": [
-    "sub",
-    "iss",
-    "aud",
-    "exp",
-    "iat",
-    "email",
-    "email_verified",
-    "name",
-    "given_name",
-    "family_name",
-    "picture"
-  ]
-}
-```
-
----
-
-#### JWKS Endpoint
-
-**Endpoint:** `GET /.well-known/jwks.json`
-
-Provides the public keys for JWT verification in JSON Web Key Set (JWKS) format.
-
-#### Request
-
-```http
-GET /.well-known/jwks.json HTTP/1.1
-Host: auth.example.com
-```
-
-#### Response
-
-```json
-{
-  "keys": [
-    {
-      "kty": "RSA",
-      "use": "sig",
-      "kid": "1",
-      "n": "xGOr-H7A...",
-      "e": "AQAB",
-      "alg": "RS256"
-    }
-  ]
-}
-```
-
-**Response Headers:**
-```
-Content-Type: application/json
-Cache-Control: public, max-age=3600
-Access-Control-Allow-Origin: *
-```
-
----
-
-### Authorization Code Flow
-
-The authorization code flow is a three-step process:
-1. Client redirects user to authorization endpoint
-2. User authenticates and authorizes the application
-3. Client exchanges authorization code for access token
-
-#### Step 1: Authorization Request
-
-**Endpoint:** `GET /auth/authorize`
-
-Initiate the OAuth2 authorization flow.
-
-#### Request
-
-```http
-GET /auth/authorize?client_id=app_123&redirect_uri=https://app.example.com/callback&response_type=code&scope=profile%20email&state=xyz123 HTTP/1.1
-Host: auth.example.com
-```
-
-#### Query Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `client_id` | string | Yes | Application/project identifier |
-| `redirect_uri` | string | Yes | URI to redirect after authorization |
-| `response_type` | string | Yes | Must be `"code"` |
-| `scope` | string | No | Space-separated list of scopes (default: `"profile"`) |
-| `state` | string | Yes | CSRF protection token (opaque value) |
-| `code_challenge` | string | No | PKCE code challenge (see PKCE section) |
-| `code_challenge_method` | string | No | Must be `"S256"` if PKCE is used |
-
-#### Redirect URI Validation
-
-The `redirect_uri` must:
-- Be a valid URL format
-- Match the registered redirect URI in the project profile (exact match)
-- If no redirect URI is registered, fallback rules apply:
-  - Localhost URIs (`localhost`, `127.0.0.1`) are allowed
-  - URIs matching the project's website hostname are allowed
-
-#### Response
-
-The server redirects the user to the authorization UI:
-
-```http
-HTTP/1.1 302 Found
-Location: https://basic.id/authorize?client_id=app_123&redirect_uri=https://app.example.com/callback&response_type=code&scope=profile%20email&state=xyz123
-```
-
-#### Error Handling
-
-If validation fails, the server responds based on the error:
-
-**Invalid redirect_uri (400):**
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Invalid redirect_uri: does not match registered value"
-}
-```
-
-**For other errors, redirect to client:**
-```http
-HTTP/1.1 302 Found
-Location: https://app.example.com/callback?error=invalid_request&error_description=Missing+client_id&state=xyz123
-```
-
----
-
-#### Step 2: Token Exchange
-
-**Endpoint:** `POST /auth/token`
-
-Exchange authorization code for access and refresh tokens.
-
-#### Request
-
-```http
-POST /auth/token HTTP/1.1
-Host: auth.example.com
-Content-Type: application/json
-
-{
-  "grant_type": "authorization_code",
-  "code": "auth_abc123def456",
-  "redirect_uri": "https://app.example.com/callback",
-  "client_id": "app_123",
-  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
-}
-```
-
-#### Request Body Parameters (JSON)
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `grant_type` | string | Yes | Must be `"authorization_code"` |
-| `code` | string | Yes | Authorization code from previous step |
-| `redirect_uri` | string | Yes* | Must match the authorization request |
-| `client_id` | string | No | Application identifier (validated if provided) |
-| `code_verifier` | string | No** | PKCE code verifier |
-
-\* Required if `redirect_uri` was used in authorization request  
-\** Required if PKCE code challenge was used
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "token_type": "Bearer",
-  "expires_in": 60,
-  "refresh_token": "789abc123def456789abc123def456789abc456def789abc123def456...",
-  "scope": "profile email"
-}
-```
-
-**Error (400):**
-```json
-{
-  "error": "invalid_grant",
-  "error_description": "Invalid or expired authorization code"
-}
-```
-
-#### Token Properties
-
-**Access Token (JWT):**
-- Algorithm: RS256
-- Expiration: 60 seconds (1 minute)
-- Claims:
-  ```json
-  {
-    "clientId": "app_123",
-    "userId": "acc_12345",
-    "scope": "profile email",
-    "iat": 1727606400,
-    "exp": 1727610000
-  }
-  ```
-
-**Refresh Token:**
-- Format: Opaque cryptographic token
-- Storage: Database with hashed value
-- Expiration: 30 days
-- Properties: Linked to session, supports rotation
-
----
-
-### Token Management
-
-#### Refresh Access Token
-
-**Endpoint:** `POST /auth/token`
-
-Obtain a new access token using a refresh token.
-
-#### Request
-
-```http
-POST /auth/token HTTP/1.1
-Host: auth.example.com
-Content-Type: application/json
-
-{
-  "grant_type": "refresh_token",
-  "refresh_token": "789abc123def456789abc123def456789abc456def789abc123def456...",
-  "client_id": "app_123"
-}
-```
-
-#### Request Body Parameters (JSON)
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `grant_type` | string | Yes | Must be `"refresh_token"` |
-| `refresh_token` | string | Yes | Valid refresh token |
-| `client_id` | string | No | Application identifier (validated if provided) |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
-  "token_type": "Bearer",
-  "expires_in": 60,
-  "refresh_token": "456def789abc123def456789abc123def456abc123def456789abc...",
-  "scope": "profile email"
-}
-```
-
-**Error (400):**
-```json
-{
-  "error": "invalid_grant",
-  "error_description": "Invalid or expired refresh token"
-}
-```
-
-#### Refresh Token Rotation
-
-The server implements **automatic refresh token rotation** for security:
-
-1. Each refresh token use generates a new refresh token
-2. The old refresh token is marked as "used" but kept in grace period
-3. **Grace Period**: 60 seconds window where old token can be reused
-   - Prevents issues with network retries
-   - Multiple requests return the same new token
-4. **Reuse Detection**: If a revoked token is used → entire chain is revoked
-
-#### Validation Checks
-
-Before issuing new tokens, the server validates:
-- Refresh token is active and not expired
-- Account connection is still active (`status = 'connected'`)
-- Client ID matches (if provided)
-- Token hasn't been revoked
-
----
-
-### User Information
-
-**Endpoint:** `GET /auth/userinfo`
-
-Retrieve user information using an access token (OpenID Connect UserInfo endpoint).
-
-#### Request
-
-```http
-GET /auth/userinfo HTTP/1.1
-Host: auth.example.com
-Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-#### Request Headers
-
-| Header | Required | Description |
-|--------|----------|-------------|
-| `Authorization` | Yes | Bearer token with `profile` or `admin` scope |
-
-#### Response
-
-**Success (200):**
-```json
-{
-  "sub": "acc_12345",
-  "id": "acc_12345",
-  "name": "John Doe",
-  "email": "john@example.com",
-  "handle_bare": "john_doe"
-}
-```
-
-**Error (401):**
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Invalid or expired access token"
-}
-```
-
-**Error (403):**
-```json
-{
-  "error": "invalid_scope",
-  "error_description": "Requires 'profile:read' permission. No grant found for 'profile:read'..."
-}
-```
-
-#### Scope Requirements
-
-The access token must have:
-- `profile:read` scope - Standard user information access
-- OR `admin` scope - Full access (includes all scopes)
-
----
-
-## Scopes & Authorization
-
-### Scope System
-
-The server uses a hierarchical scope-based authorization system for fine-grained permission control.
-
-**Scope Format:** `resource:child:action`
-
-**Examples:**
-- `account:read` or `account` - Read account information (read is default)
-- `app:db:write` - Write to app database
-- `account:session:delete` - Delete sessions
-- `admin` - Super scope (grants everything)
-
-**Default Action:**
-- If no action is specified, defaults to `read`
-- `profile` = `profile:read`
-- `email` = `email:read`
-- `account` = `account:read`
-
-**Key Principles:**
-- ✅ **Hierarchical:** Resources can have children (`account:app:read`)
-- ✅ **Action Implications:** Higher actions grant lower ones
-- ✅ **Default Action:** Omitted action defaults to `read`
-- ✅ **Validated:** Invalid scopes rejected at creation
-- ✅ **Clear Errors:** Detailed permission messages
-
----
-
-### Available Scopes Reference
-
-#### OpenID Connect Scopes
-
-| Scope | Description |
-|-------|-------------|
-| `profile:read` | User profile information (name, handle) |
-| `email:read` | User's email address |
-| `openid:read` | OpenID Connect authentication |
-
-#### Account Management
-
-| Scope | Description | Implied Actions |
-|-------|-------------|-----------------|
-| `account:read` | View account details | - |
-| `account:write` | Full write access | read, create, update, delete |
-| `account:update` | Update account information | - |
-| `account:admin` | Full account control | write + all sub-actions |
-
-#### Connected Apps
-
-| Scope | Description | Implied Actions |
-|-------|-------------|-----------------|
-| `account:app:read` | List connected applications | - |
-| `account:app:write` | Full app management | read, create, update, delete |
-| `account:app:update` | Update app connections | - |
-| `account:app:delete` | Disconnect applications | - |
-| `account:app:admin` | Full app control | write + all sub-actions |
-
-#### Session Management
-
-| Scope | Description | Implied Actions |
-|-------|-------------|-----------------|
-| `account:session:read` | View active device sessions | - |
-| `account:session:write` | Full session management | read, create, update, delete |
-| `account:session:update` | Update session metadata | - |
-| `account:session:delete` | Revoke sessions | - |
-| `account:session:admin` | Full session control | write + all sub-actions |
-
-#### App Database
-
-| Scope | Description | Implied Actions |
-|-------|-------------|-----------------|
-| `app:db:read` | Query database tables | - |
-| `app:db:write` | Full database access | read, create, update, delete |
-| `app:db:create` | Create new records | - |
-| `app:db:update` | Update existing records | - |
-| `app:db:delete` | Delete records | - |
-| `app:db:admin` | Full database control | write + all sub-actions |
-
-#### App Profiles
-
-| Scope | Description | Implied Actions |
-|-------|-------------|-----------------|
-| `app:profile:read` | View user profiles in app | - |
-| `app:profile:write` | Full profile access | read, create, update, delete |
-| `app:profile:update` | Update user profiles | - |
-| `app:profile:delete` | Delete user profiles | - |
-| `app:profile:admin` | Full profile control | write + all sub-actions |
-
----
-
-### Action Implications
-
-**Automatic Permission Grants:**
-
-```
-admin → write → read, create, update, delete
-```
-
-**How It Works:**
-When you have a higher-level action, you automatically get all lower-level actions.
-
-**Example 1: Database Write**
-```
-Granted: app:db:write
-Automatically includes:
-  ✅ app:db:read
-  ✅ app:db:create
-  ✅ app:db:update
-  ✅ app:db:delete
-```
-
-**Example 2: Admin Scope**
-```
-Granted: admin
-Automatically includes:
-  ✅ Every scope in the system
-  ✅ Bypasses all restrictions
-```
-
-**Best Practice:** Request the highest action you need, not every individual permission.
-
----
-
-### Admin Scope Behavior
-
-**The `admin` scope is special:**
-
-**Availability:**
-- ✅ Only via `/auth/login` (client_id='self')
-- ❌ OAuth apps cannot request it
-
-**Permissions:**
-- ✅ Grants ALL scopes
-- ✅ Bypasses ownership checks
-- ✅ Access to all apps' data
-- ✅ Full account administration
-
-**Use Cases:**
-- User managing their own account
-- Viewing data across all connected apps
-- Account administration and debugging
-
-**Security:**
-```http
-Third-party app requests admin:
-GET /auth/authorize?scope=admin&client_id=my-app
-→ ERROR: "Admin scopes can only be granted to the self client"
-```
-
----
-
-### Authorization Errors
-
-#### 1. Insufficient Scope (403)
-
-**Cause:** Missing required scope
-
-**Response:**
-```json
-{
-  "error": "insufficient_permissions",
-  "message": "Requires 'app:db:write' permission",
-  "required": "app:db:write",
-  "reason": "No grant found for 'app:db:write'. Available: profile:read"
-}
-```
-
-**Solution:** Request additional scopes via incremental authorization
-
----
-
-#### 2. Resource Ownership (403)
-
-**Cause:** Accessing another app's data
-
-**Response:**
-```json
-{
-  "error": "forbidden",
-  "message": "Cannot access data for a different application",
-  "type": "ownership",
-  "hint": "Your access token is scoped to a different application."
-}
-```
-
-**Solution:** Use correct project_id or get admin scope
-
----
-
-#### 3. Invalid Scope (400)
-
-**Cause:** Requesting non-existent scope
-
-**Response:**
-```json
-{
-  "error": "invalid_scope",
-  "error_description": "Invalid scopes: unknown:scope"
-}
-```
-
-**Solution:** Use valid scopes from reference
-
----
-
-### Best Practices
-
-**1. Request Minimum Scopes**
-```javascript
-// ✅ Good
-scope: 'profile:read app:db:write'
-
-// ❌ Bad (redundant)
-scope: 'profile:read app:db:read app:db:write app:db:create app:db:update'
-```
-
-**2. Handle Errors Gracefully**
-```javascript
-if (response.status === 403) {
-  const error = await response.json();
-  if (error.required) {
-    // Guide user to re-authorize with needed scope
-    requestAdditionalScope(error.required);
-  }
-}
-```
-
-**3. Use Incremental Authorization**
-```javascript
-// Start with basic scopes
-initialScopes: 'profile:read'
-
-// Request more later when needed
-additionalScopes: 'app:db:write'
-// Result: User has both scopes
-```
-
-**4. Test with Real Scopes**
-- Don't use admin in development
-- Test with actual OAuth scopes
-- Validate error handling
-
----
-
-### Scope Format Rules
-
-**Valid Formats:**
-- Full format: `resource:action` (e.g., `profile:read`)
-- Shorthand: `resource` (e.g., `profile` - defaults to `read`)
-- Hierarchical: `resource:child:action` (e.g., `account:app:read`)
-
-**Examples:**
-```
-✅ Valid:
-- profile (defaults to profile:read)
-- email (defaults to email:read)  
-- account:read
-- app:db:write
-- account:session:delete
-
-❌ Invalid:
-- account.read (wrong separator)
-- app/db (wrong separator)
-- app::read (consecutive colons)
-```
-
-**OAuth Standard Compatibility:**
-- OpenID Connect scopes: `profile`, `email`, `openid` (read action implied)
-- Custom scopes: Use full format or shorthand for read
-
----
-
-## PKCE Extension (Optional)
-
-**Proof Key for Code Exchange (PKCE)** enhances security for public clients that cannot securely store client secrets. This follows RFC 7636.
-
-### PKCE Flow Overview
-
-1. Client generates code verifier (random string)
-2. Client creates code challenge (SHA256 hash of verifier)
-3. Authorization request includes code challenge
-4. Token request includes code verifier
-5. Server validates: `SHA256(code_verifier) === code_challenge`
-
-### Implementation Steps
-
-#### Step 1: Generate Code Verifier
-
-Create a cryptographically random string:
-
-```javascript
-// Generate 32-byte random string
-const verifier = base64url(randomBytes(32))
-// Example: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
-```
-
-**Requirements:**
-- Length: 43-128 characters
-- Character set: `[A-Z]`, `[a-z]`, `[0-9]`, `-`, `.`, `_`, `~`
-- Encoding: Base64url without padding
-
----
-
-#### Step 2: Generate Code Challenge
-
-Create SHA256 hash of the code verifier:
-
-```javascript
-const challenge = base64url(sha256(verifier))
-// Example: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
-```
-
-**Algorithm:** `S256` (SHA256) - Only supported method
-
----
-
-#### Step 3: Authorization Request with PKCE
-
-```http
-GET /auth/authorize?client_id=app_123&redirect_uri=https://app.example.com/callback&response_type=code&state=xyz123&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256 HTTP/1.1
-```
-
-**Additional Parameters:**
-
-| Parameter | Value | Description |
-|-----------|-------|-------------|
-| `code_challenge` | Base64url string | SHA256 hash of verifier |
-| `code_challenge_method` | `"S256"` | Always use SHA256 |
-
----
-
-#### Step 4: Token Exchange with PKCE
-
-```http
-POST /auth/token HTTP/1.1
-Content-Type: application/json
-
-{
-  "grant_type": "authorization_code",
-  "code": "auth_abc123",
-  "redirect_uri": "https://app.example.com/callback",
-  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
-}
-```
-
-**Additional Parameter:**
-
-| Parameter | Value | Description |
-|-----------|-------|-------------|
-| `code_verifier` | Original random string | Used to verify challenge |
-
----
-
-### PKCE Validation
-
-The server validates PKCE as follows:
-
-1. **If code challenge was provided in authorization:**
-   - `code_verifier` is **required** in token request
-   - Server computes: `SHA256(code_verifier)`
-   - Must match stored `code_challenge`
-   - Mismatch → `400 invalid_grant`
-
-2. **If no code challenge in authorization:**
-   - PKCE is optional
-   - `code_verifier` is ignored if provided
-
-### Error Responses
-
-**Missing code_verifier:**
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Missing required parameter: code_verifier (PKCE validation required)"
-}
-```
-
-**Invalid code_verifier:**
-```json
-{
-  "error": "invalid_grant",
-  "error_description": "Invalid code_verifier - PKCE validation failed"
-}
-```
-
-**Unsupported challenge method:**
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Invalid code_challenge_method. Only S256 is supported"
-}
-```
-
----
-
-## DPoP Extension (Optional)
-
-**Demonstrating Proof-of-Possession (DPoP)** binds tokens to specific clients using public key cryptography. This follows [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449).
-
-### DPoP Overview
-
-DPoP prevents token theft by binding tokens to a client's private key:
-1. Client generates key pair
-2. Client creates DPoP proof (signed JWT)
-3. Server binds token to key thumbprint
-4. All requests require valid DPoP proof
-
-### DPoP Proof Format
-
-A DPoP proof is a JWT with specific claims:
-
-```json
-{
-  "typ": "dpop+jwt",
-  "alg": "ES256",
-  "jwk": {
-    "kty": "EC",
-    "crv": "P-256",
-    "x": "...",
-    "y": "..."
-  }
-}
-```
-
-**Payload:**
-```json
-{
-  "jti": "unique-request-id",
-  "htm": "POST",
-  "htu": "https://auth.example.com/auth/token",
-  "iat": 1727606400,
-  "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"
-}
-```
-
-### DPoP Claims
-
-| Claim | Required | Description |
-|-------|----------|-------------|
-| `typ` | Yes | Must be `"dpop+jwt"` |
-| `alg` | Yes | Signing algorithm (ES256, RS256) |
-| `jwk` | Yes | Public key in JWK format |
-| `jti` | Yes | Unique identifier (prevents replay) |
-| `htm` | Yes | HTTP method (uppercase) |
-| `htu` | Yes | HTTP URI (without query/fragment) |
-| `iat` | Yes | Issued at timestamp |
-| `ath` | No | Hash of access token (for resource requests) |
-
-### Implementation Steps
-
-#### Step 1: Generate Key Pair
-
-```javascript
-// Generate ES256 key pair
-const keyPair = await crypto.subtle.generateKey(
-  { name: "ECDSA", namedCurve: "P-256" },
-  true,
-  ["sign", "verify"]
-)
-
-// Export public key as JWK
-const publicJwk = await crypto.subtle.exportKey("jwk", keyPair.publicKey)
-```
-
----
-
-#### Step 2: Create DPoP Proof
-
-```javascript
-// Create proof header
-const header = {
-  typ: "dpop+jwt",
-  alg: "ES256",
-  jwk: publicJwk
-}
-
-// Create proof payload
-const payload = {
-  jti: crypto.randomUUID(),
-  htm: "POST",
-  htu: "https://auth.example.com/auth/token",
-  iat: Math.floor(Date.now() / 1000)
-}
-
-// Sign JWT
-const dpopProof = await signJWT(header, payload, privateKey)
-```
-
----
-
-#### Step 3: Token Request with DPoP
-
-```http
-POST /auth/token HTTP/1.1
-Host: auth.example.com
-Content-Type: application/json
-DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik...
-
-{
-  "grant_type": "authorization_code",
-  "code": "auth_abc123",
-  "redirect_uri": "https://app.example.com/callback"
-}
-```
-
-**Headers:**
-```
-Content-Type: application/json
-DPoP: {dpop_proof_jwt}
-```
-
----
-
-#### Step 4: DPoP-Bound Token Response
-
-```json
-{
-  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...",
-  "token_type": "DPoP",
-  "expires_in": 60,
-  "refresh_token": "xyz789abc123def456789abc123def456789def456abc123def789abc...",
-  "scope": "profile email"
-}
-```
-
-**Key Differences:**
-- `token_type` is `"DPoP"` (not `"Bearer"`)
-- Access token contains `cnf` claim with key thumbprint:
-  ```json
-  {
-    "cnf": {
-      "jkt": "0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
-    }
-  }
-  ```
-
----
-
-#### Step 5: Resource Request with DPoP
-
-```http
-GET /account/profile HTTP/1.1
-Host: api.example.com
-Authorization: DPoP eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9...
-DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik...
-```
-
-**DPoP Proof includes `ath` claim:**
-```json
-{
-  "jti": "unique-request-id-2",
-  "htm": "GET",
-  "htu": "https://api.example.com/account/profile",
-  "iat": 1727606500,
-  "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"
-}
-```
-
-`ath` = Base64url(SHA256(access_token))
-
----
-
-### DPoP Validation
-
-The server validates DPoP proofs:
-
-1. **Signature Validation:**
-   - Verify JWT signature using `jwk` in header
-   - Algorithm must match `alg` claim
-
-2. **Claim Validation:**
-   - `typ` must be `"dpop+jwt"`
-   - `htm` must match HTTP method
-   - `htu` must match request URI (scheme + authority + path)
-   - `iat` must be recent (within acceptable skew)
-
-3. **Token Binding:**
-   - Compute `jkt` = Base64url(SHA256(JWK))
-   - Must match `cnf.jkt` in access token
-
-4. **Replay Protection:**
-   - `jti` must be unique
-   - Store recent `jti` values (cache)
-
-### Error Responses
-
-**Invalid DPoP Proof:**
-```
-HTTP/1.1 401 Unauthorized
-WWW-Authenticate: DPoP error="invalid_dpop_proof"
-```
-
-**Missing DPoP Proof:**
-```
-HTTP/1.1 401 Unauthorized
-WWW-Authenticate: DPoP error="invalid_token", error_description="DPoP proof required"
-```
-
----
-
-## Security Requirements
-
-### Token Security
-
-#### Access Token
-- **Format:** JWT with RS256 signature
-- **Lifetime:** 1 minute (60 seconds)
-- **Transmission:** HTTPS only, in Authorization header
-
-#### Token Validation with JWKS
-
-To verify access tokens, clients should use the public keys provided by the JWKS endpoint.
-
-**Step 1: Fetch JWKS**
-
-```javascript
-// Fetch and cache the JWKS
-async function getJWKS() {
-  const response = await fetch('https://auth.example.com/auth/.well-known/jwks.json');
-  const jwks = await response.json();
-  return jwks;
-}
-```
-
-**Step 2: Verify JWT Signature**
-
-Using the `jose` library (recommended):
-
-```javascript
-import { createRemoteJWKSet, jwtVerify } from 'jose';
-
-// Create JWKS instance (cache this)
-const JWKS = createRemoteJWKSet(
-  new URL('https://auth.example.com/auth/.well-known/jwks.json')
-);
-
-// Verify token
-async function verifyAccessToken(token) {
-  try {
-    const { payload, protectedHeader } = await jwtVerify(token, JWKS, {
-      algorithms: ['RS256'],
-      issuer: 'https://auth.example.com',  // Optional: validate issuer
-    });
-    
-    // Token is valid
-    return {
-      valid: true,
-      userId: payload.userId,
-      clientId: payload.clientId,
-      scope: payload.scope,
-      exp: payload.exp
-    };
-  } catch (error) {
-    // Token is invalid or expired
-    return {
-      valid: false,
-      error: error.message
-    };
-  }
-}
-```
-
-**Step 3: Validate Claims**
-
-```javascript
-async function validateToken(token) {
-  // Verify signature and decode
-  const result = await verifyAccessToken(token);
-  
-  if (!result.valid) {
-    throw new Error('Invalid token: ' + result.error);
-  }
-  
-  // Additional claim validation
-  const now = Math.floor(Date.now() / 1000);
-  
-  // Check expiration
-  if (result.exp < now) {
-    throw new Error('Token expired');
-  }
-  
-  // Check scope (recommended approach)
-  const tokenScopes = result.scope.split(',').map(s => s.trim());
-  
-  // Check for required scope or admin (which grants everything)
-  const hasRequiredScope = tokenScopes.includes('profile:read') || tokenScopes.includes('admin');
-  
-  if (!hasRequiredScope) {
-    throw new Error('Insufficient scope: requires profile:read');
-  }
-  
-  return result;
-}
-```
-
-**Best Practices:**
-
-1. **Cache JWKS**: Cache the JWKS response for at least 1 hour (check `Cache-Control` header)
-2. **Key Rotation**: Support multiple keys in JWKS for seamless rotation
-3. **Algorithm Validation**: Always specify `algorithms: ['RS256']` to prevent algorithm confusion attacks
-4. **Clock Skew**: Allow 60-second clock skew for `exp` and `iat` validation
-5. **Error Handling**: Distinguish between expired, invalid signature, and malformed tokens
-
-**Manual Verification (without library):**
-
-```javascript
-import crypto from 'crypto';
-
-async function manualVerifyToken(token) {
-  // Split JWT into parts
-  const [headerB64, payloadB64, signatureB64] = token.split('.');
-  
-  // Decode header and payload
-  const header = JSON.parse(Buffer.from(headerB64, 'base64url').toString());
-  const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString());
-  
-  // Fetch JWKS and find matching key
-  const jwks = await getJWKS();
-  const key = jwks.keys.find(k => k.kid === header.kid);
-  
-  if (!key) {
-    throw new Error('Key not found in JWKS');
-  }
-  
-  // Convert JWK to PEM format (requires jwk-to-pem library)
-  const publicKey = jwkToPem(key);
-  
-  // Verify signature
-  const verify = crypto.createVerify('RSA-SHA256');
-  verify.update(`${headerB64}.${payloadB64}`);
-  
-  const signature = Buffer.from(signatureB64, 'base64url');
-  const isValid = verify.verify(publicKey, signature);
-  
-  if (!isValid) {
-    throw new Error('Invalid signature');
-  }
-  
-  // Validate claims
-  const now = Math.floor(Date.now() / 1000);
-  if (payload.exp < now) {
-    throw new Error('Token expired');
-  }
-  
-  return payload;
-}
-```
-
-**Token Validation Response:**
-
-```javascript
-// Valid token
-{
-  "valid": true,
-  "userId": "acc_12345",
-  "clientId": "app_123",
-  "scope": "profile email",
-  "exp": 1727606460
-}
-
-// Invalid token
-{
-  "valid": false,
-  "error": "signature verification failed"
-}
-```
-
-#### Refresh Token
-- **Format:** Cryptographically random string (256-bit)
-- **Storage:** Database with SHA256 hash
-- **Lifetime:** 30 days
-- **Rotation:** Automatic on each use
-- **Grace Period:** 60 seconds for network retries
-- **Reuse Detection:** Entire chain revoked on reuse
-
----
-
-### CSRF Protection
-
-**State Parameter:**
-- Required in authorization flow
-- Minimum 128-bit entropy
-- Single-use (bound to session)
-- Verified on callback
-
-**Implementation:**
-```javascript
-// Generate state
-const state = base64url(randomBytes(32))
-// Store in session/cookie
-session.oauthState = state
-// Include in authorization URL
-const authUrl = `...&state=${state}`
-// Verify on callback
-if (callbackState !== session.oauthState) {
-  throw new Error('Invalid state')
-}
-```
-
----
-
-### Redirect URI Security
-
-**Validation Rules:**
-1. **Exact Match:** Must match registered URI
-2. **No Wildcards:** Wildcards not supported
-3. **HTTPS Only:** In production (HTTP allowed for localhost)
-4. **No Fragments:** Fragment identifiers not allowed
-5. **Validation Timing:** Before showing authorization UI
-
-**Error Handling:**
-- Invalid redirect_uri → Do not redirect (return 400)
-- Other errors → Redirect with error parameter
-
----
-
-### Password Requirements
-
-**Minimum Requirements:**
-- Length: 3 characters (update this for production)
-- Storage: Hashed with bcrypt (cost factor 10)
-- Transmission: HTTPS only
-- Reset tokens: 15-minute expiration
-- Verification tokens: 24-hour expiration
-
----
-
-
-### Error Handling
-
-**Error Response Format (OAuth2):**
-```json
-{
-  "error": "invalid_request",
-  "error_description": "Missing required parameter: client_id",
-  "error_uri": "https://docs.example.com/errors/invalid_request"
-}
-```
-
-**Standard Error Codes:**
-- `invalid_request` - Malformed request
-- `invalid_client` - Invalid client credentials
-- `invalid_grant` - Invalid/expired code or token
-- `unauthorized_client` - Client not authorized
-- `unsupported_grant_type` - Grant type not supported
-- `invalid_scope` - Requested scope invalid
-- `access_denied` - User denied authorization
-- `server_error` - Internal server error
-
-**Error Response Rules:**
-- Never leak sensitive information
-- Log detailed errors server-side
-- Return generic errors to client
-- Include `state` parameter in redirects
-
----
-
-## Complete Flow Examples
-
-### Example 1: Simple Web App Login
-
-**Step 1 - User clicks "Login":**
-```javascript
-const authUrl = new URL('https://auth.example.com/auth/authorize')
-authUrl.searchParams.set('client_id', 'webapp_123')
-authUrl.searchParams.set('redirect_uri', 'https://myapp.com/callback')
-authUrl.searchParams.set('response_type', 'code')
-authUrl.searchParams.set('scope', 'profile email')
-authUrl.searchParams.set('state', generateState())
-
-window.location.href = authUrl.toString()
-```
-
-**Step 2 - User authenticates and authorizes**
-
-**Step 3 - Callback receives code:**
-```javascript
-// https://myapp.com/callback?code=auth_abc123&state=xyz789
-
-// Validate state
-if (params.state !== session.state) throw new Error('Invalid state')
-
-// Exchange code for tokens
-const response = await fetch('https://auth.example.com/auth/token', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    grant_type: 'authorization_code',
-    code: params.code,
-    redirect_uri: 'https://myapp.com/callback'
-  })
-})
-
-const tokens = await response.json()
-// Store tokens securely
-session.accessToken = tokens.access_token
-session.refreshToken = tokens.refresh_token
-```
-
-**Step 4 - Use access token:**
-```javascript
-const userInfo = await fetch('https://auth.example.com/auth/userinfo', {
-  headers: {
-    'Authorization': `Bearer ${session.accessToken}`
-  }
-})
-```
-
----
-
-### Example 2: Mobile App with PKCE
-
-**Step 1 - Generate PKCE values:**
-```javascript
-// Generate code verifier
-const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)))
-
-// Generate code challenge
-const encoder = new TextEncoder()
-const data = encoder.encode(verifier)
-const hash = await crypto.subtle.digest('SHA-256', data)
-const challenge = base64url(new Uint8Array(hash))
-
-// Store verifier for later
-storage.set('pkce_verifier', verifier)
-```
-
-**Step 2 - Authorization request:**
-```javascript
-const authUrl = new URL('https://auth.example.com/auth/authorize')
-authUrl.searchParams.set('client_id', 'mobile_app_456')
-authUrl.searchParams.set('redirect_uri', 'myapp://callback')
-authUrl.searchParams.set('response_type', 'code')
-authUrl.searchParams.set('scope', 'profile email')
-authUrl.searchParams.set('state', generateState())
-authUrl.searchParams.set('code_challenge', challenge)
-authUrl.searchParams.set('code_challenge_method', 'S256')
-
-// Open browser
-openBrowser(authUrl.toString())
-```
-
-**Step 3 - Token exchange with verifier:**
-```javascript
-// Deep link: myapp://callback?code=auth_abc123&state=xyz789
-
-const response = await fetch('https://auth.example.com/auth/token', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    grant_type: 'authorization_code',
-    code: params.code,
-    redirect_uri: 'myapp://callback',
-    code_verifier: storage.get('pkce_verifier')
-  })
-})
-
-const tokens = await response.json()
-```
-
----
-
-### Example 3: Token Refresh
-
-**Automatic token refresh:**
-```javascript
-async function getValidAccessToken() {
-  // Check if current token is expired
-  const decodedToken = jwt.decode(session.accessToken)
-  const expiresAt = decodedToken.exp * 1000
-  const now = Date.now()
-  
-  // Refresh if token expires in less than 5 minutes
-  if (expiresAt - now < 5 * 60 * 1000) {
-    const response = await fetch('https://auth.example.com/auth/token', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        grant_type: 'refresh_token',
-        refresh_token: session.refreshToken
-      })
-    })
-    
-    if (!response.ok) {
-      // Refresh token is invalid, need to re-authenticate
-      redirectToLogin()
-      return null
-    }
-    
-    const tokens = await response.json()
-    session.accessToken = tokens.access_token
-    session.refreshToken = tokens.refresh_token
-  }
-  
-  return session.accessToken
-}
-
-// Use in API calls
-async function apiRequest(url) {
-  const token = await getValidAccessToken()
-  return fetch(url, {
-    headers: { 'Authorization': `Bearer ${token}` }
-  })
-}
-```
-
----
-
-## Additional Resources
-
-### RFCs and Standards
-
-- [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) - OAuth 2.0 Authorization Framework
-- [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750) - OAuth 2.0 Bearer Token Usage
-- [RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) - Proof Key for Code Exchange (PKCE)
-- [RFC 7662](https://datatracker.ietf.org/doc/html/rfc7662) - Token Introspection
-- [RFC 9449](https://datatracker.ietf.org/doc/html/rfc9449) - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP)
-- [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html)
-- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)
-
-### Security Best Practices
-
-- [OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics)
-- [OAuth 2.0 for Browser-Based Apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps)
-- [OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
-
----
-
-## Support
-
-For implementation questions or issues:
-- Review the Swagger documentation at `/docs`
-- OpenAPI available at /docs/json
-
----
-
----
-
-**Last Updated:** October 1, 2025  
-**Version:** 2.0.0 - With Scope-Based Authorization