75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# 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. |