Auth Login Patterns

Selector: Set this once per project.

ACTIVE_LOGIN_METHOD=pb-oauth-via-microsoft

(Other methods can be added; only one should be active.)

---

Environment Variables

Required Variables

Azure AD / Microsoft Authentication:

• CLIENT_ID - Azure AD Application Client ID
• CLIENT_SECRET - Azure AD Application Client Secret
• TENANT_ID - Azure AD Tenant ID
• REDIRECT_URI - OAuth redirect URI

PocketBase:

• PB_DB - PocketBase database URL (e.g., https://pocketbase.ccllc.pro)
• PB_COLLECTION - Collection name for job data (e.g., Job_Info_TestEnv)
• PB_AUTH_COLLECTION - Collection name for user authentication (e.g., Users)

Redis/Valkey (Caching & Search):

• REDIS_URL - Redis/Valkey connection URL (e.g., redis://localhost:6379 or redis://redis-server:6379)
  • If not provided, defaults to redis://localhost:6379
  • For production, connect to the same Redis/Valkey instance as Job-Info-Prod

Optional:

• PORT - Server port (default: 3025)

---

Caching & Search

This application uses Redis/Valkey for:

1. Data Caching: Job records are cached for 5 minutes (300 seconds) to reduce PocketBase queries
2. Search Results Caching: Search results are cached for 3 minutes (180 seconds)
3. Cache Invalidation: Automatically clears cache when data is updated

API Endpoints

Get All Jobs (with caching):

GET /api/jobs
Headers: X-PocketBase-Token: <user_token>

Search Jobs (with caching):

GET /api/jobs/search?q=<query>
Headers: X-PocketBase-Token: <user_token>

Searches across: Job_Number, Job_Full_Name, Job_Name, Company_Client, Contact_Person, Estimator, Job_Status, Project_Manager, Notes

Clear Cache (admin):

POST /api/cache/clear
Headers: X-PocketBase-Token: <user_token>

Cache Strategy

• Source of Truth: PocketBase remains the source of truth for updates
• Read Operations: Check cache first, fallback to PocketBase if cache miss
• Write Operations: Update PocketBase, then invalidate cache
• Future: Will switch to Job-Info-Prod for production data synchronization

---

Shared Rules (All Methods)

• Serve frontend from the project’s frontend folder; show login UI only when not authenticated.
• Secrets come from .env; never hardcode or log secrets/tokens.
• Token storage: use in-memory auth store (avoid localStorage/sessionStorage unless explicitly required).
• On logout, clear the auth store and hide the protected UI.
• Log only context + message; exclude raw tokens or secrets.

---

Method: pb-oauth-via-microsoft (PocketBase + Microsoft)

Frontend

• Use PocketBase SDK OAuth (provider: 'microsoft').
• Show login button when !pb.authStore.isValid; hide the form until valid.
• On success: keep token in pb.authStore; display user email; show logout.
• On logout: pb.authStore.clear(); hide protected UI.

Backend

• Endpoints expecting auth (e.g., /api/submit) must receive pbToken.
• Call setUserPocketBaseAuth(pbToken) before PocketBase operations.
• Required .env keys: CLIENT_ID, CLIENT_SECRET, TENANT_ID, REDIRECT_URI, PB_DB, PB_COLLECTION, PB_AUTH_COLLECTION.
• Validate token via PocketBase client; reject if missing/invalid.
• Do not log tokens; log context and error message only.

UI States

• Logged out: show login UI only.
• Logged in: hide login UI, show form/app content.
• Errors: show a visible error container; avoid alert loops.

Security

• Enforce CORS as needed; HTTPS in production.
• Keep .env out of version control; use deploy-time secrets.

---

Method: pb-and-graph-via-microsoft (PocketBase + Microsoft Graph)

Frontend

• Same UI pattern as pb-oauth-via-microsoft (PocketBase OAuth provider: 'microsoft').
• Show login when !pb.authStore.isValid; hide protected UI until valid.
• On success: keep token in pb.authStore; display user email; show logout; on logout clear auth store.

Backend

• Expect pbToken on protected endpoints; call setUserPocketBaseAuth(pbToken) before PB operations.
• Acquire Graph token via client credentials for Excel sync.
• Required .env keys:
  • Azure AD: CLIENT_ID, CLIENT_SECRET, TENANT_ID, REDIRECT_URI
  • PocketBase: PB_DB, PB_COLLECTION, PB_AUTH_COLLECTION
  • Graph/Excel: DRIVE_ID, ITEM_ID, EXCEL_TABLE, EXCEL_TABLE_WRITEBACK (if used)
• Use Graph scope: https://graph.microsoft.com/.default
• Do not log tokens; log context + message only.

Token Handling

• PocketBase token (user): stored in memory via pb.authStore; sent to backend as pbToken.
• Graph token (app): obtained server-side via client credentials; never exposed to frontend; short-lived, fetched on demand.

UI States

• Logged out: show login UI only.
• Logged in: hide login UI, show form/app content.
• Errors: show visible error container; avoid alert loops.

Security

• Enforce CORS as needed; HTTPS in production.
• Keep .env out of version control; use deploy-time secrets.
• Do not log raw tokens or secrets.

---

Method: PBandGraphOauth (PocketBase + Microsoft Graph OAuth)

Frontend

• Use PocketBase SDK OAuth (provider: 'microsoft').
• Show login button when !pb.authStore.isValid; hide protected UI until valid.
• On success: keep token in pb.authStore; display user email; show logout.
• On logout: pb.authStore.clear(); hide protected UI.

Backend

• Endpoints expecting auth (e.g., /api/submit) must receive pbToken from the frontend.
• Call setUserPocketBaseAuth(pbToken) before PocketBase operations.
• Obtain a Microsoft Graph access token using Azure AD app credentials.
• Required .env keys (exactly from current .env):
  • Azure AD: CLIENT_ID, CLIENT_SECRET, TENANT_ID, REDIRECT_URI
  • PocketBase: PB_DB, PB_COLLECTION, PB_AUTH_COLLECTION
• Graph token scope: https://graph.microsoft.com/.default.
• Never log raw tokens or secrets; log only context + messages.

Token Handling

• PocketBase token (user): stored in memory via pb.authStore; sent to backend as pbToken on protected calls.
• Graph token (app): acquired server-side via client credentials using CLIENT_ID/CLIENT_SECRET/TENANT_ID; never exposed to the frontend.

UI States

• Logged out: show login UI only.
• Logged in: hide login UI; show protected UI.
• Errors: show a visible error container; avoid alert loops.

Security

• Enforce CORS as needed; HTTPS in production.
• Keep .env out of version control; use deploy-time secrets.
• Do not log raw tokens or secrets.

---

Adding Another Method (Template)

# Example selector
ACTIVE_LOGIN_METHOD=custom-sso

Frontend:
- Describe SDK/flow
- Show/hide rules
- Token storage rules

Backend:
- How tokens are validated
- Required .env keys
- How errors are logged/returned

Security:
- CORS/HTTPS rules
- Logging redactions

---

How to Use

1. Copy this folder into a new project (outside your app code) or reference it as the canonical auth guide.
2. Set ACTIVE_LOGIN_METHOD to the one in use.
3. Follow only the active method; do not mix flows.
4. Keep .env values in deploy-time secrets; never commit them.