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.)

---

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.