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