# Universal Auth Module

## Overview
This module provides a standardized, immutable authentication and token management system for any web project using PocketBase and Microsoft Graph. It supports user and agent tokens, delegated and app-only flows, and a consistent popup UI for login prompts.

## Features
- Pattern-based: Choose 'pb-user', 'pb-agent', 'graph-user', 'graph-agent', or any combination (e.g., 'pb-user+graph-agent') for your project needs
- Supports both user and agent tokens for PocketBase and Microsoft Graph
- Special handling for Valkey/Redis agent login and token storage (for backend/automation flows)
- Single source of truth for token storage, retrieval, and refresh
- Consistent, hidden popup for all user login prompts
- Extracts user info (display name, email) from PocketBase
- Works in any frontend project with PocketBase

## Usage

### 1. Include in your project
```html
<script src="https://cdn.jsdelivr.net/npm/pocketbase@0.26.5/dist/pocketbase.umd.js"></script>
<script src="auth/auth-universal.js"></script>
```

### 2. Initialize the pattern
```js
// Choose your pattern:
// 'pb-user'         - PocketBase user login
// 'pb-agent'        - PocketBase agent/service login
// 'graph-user'      - Microsoft Graph delegated (user) login
// 'graph-agent'     - Microsoft Graph agent/app-only (client credentials)
// Combine as needed: 'pb-user+graph-agent', 'pb-agent+graph-user', etc.
Auth.use('pb-user+graph-agent');
```

### 3. Get and use tokens
```js
const pbToken = await Auth.ensureToken('pb');
const graphToken = await Auth.ensureToken('graph');
const userInfo = Auth.getUserInfo();
```

### 4. Handle reauthentication
- If a token is missing or expired, Auth will automatically show a popup for login.
- The popup is hidden at all other times.

### 5. Clear tokens (for testing or logout)
```js
Auth.clearToken('pb');
Auth.clearToken('graph');
```

## Secrets and Environment
- For frontend, all secrets are handled by PocketBase OAuth (no client secrets exposed).
- For backend/agent flows, use environment variables and server-side code to store secrets securely.
- The module does not expose or require secrets in the frontend.

## Example Test Page
See `auth-test.html` for a safe way to test all flows without affecting your main app.

## Rules for Copilot Instructions
- Always use Auth.use() to set the pattern before requesting tokens. Supported types: 'pb-user', 'pb-agent', 'graph-user', 'graph-agent', or any combination.
- Always use Auth.ensureToken(type) to get a valid token; it will handle refresh and prompt if needed.
- Never store secrets in frontend code; use PocketBase OAuth for user login.
- All login prompts must use the provided popup, never custom dialogs.
- Token keys are immutable: 'pbUserToken', 'pbAgentToken', 'graphUserToken', 'graphAgentToken'.
- User info extraction must use Auth.getUserInfo().
- For agent/app-only tokens, use backend code, environment variables, and optionally Valkey/Redis for secure storage and retrieval.

## FAQ
- **Can I use this in any project?** Yes, as long as you include PocketBase and this module.
- **Does it work for both user and agent tokens?** Yes, with the correct pattern and backend support for agent tokens (including Valkey/Redis for automation).
- **Is the popup customizable?** The style can be changed, but the flow must remain consistent for all projects.
- **How are secrets handled?** Only via backend environment variables for agent tokens; never exposed in frontend.

---
For further integration, see the comments in `auth-universal.js` and the example test page.