Fix token handling, remove orchestrator API call, improve mobile responsive footer layout

2026-01-18 03:09:37 +00:00
parent d77fa4b817
commit 09fc949a06
50 changed files with 9991 additions and 4503 deletions
@@ -0,0 +1,75 @@
+# 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.