387 lines
16 KiB
Markdown
387 lines
16 KiB
Markdown
# PROJECT: Site Passcode Security — API-Verified Auth
|
||
|
||
**Last updated:** 2026-04-10
|
||
**Status:** Backend work in progress — frontend pending backend completion
|
||
**Priority:** High — passcodes for trusted/administrator access currently in localStorage plaintext
|
||
|
||
---
|
||
|
||
## Problem Statement
|
||
|
||
When a user loads the Aether frontend, the site bootstrap response includes `access_code_kv_json` — a JSON object containing all passcodes for all access levels (administrator, trusted, public, authenticated). The frontend stores this verbatim in `$ae_loc.site_access_code_kv`, which is persisted in localStorage.
|
||
|
||
**Result:** Anyone with DevTools → Application → Local Storage can see every passcode for every access level on any Aether site. For public/authenticated this is low risk, but for trusted and administrator this is a real exposure — these passcodes can grant control over event data, badge printing, edit mode, etc.
|
||
|
||
The passcode check (`handle_check_access_type_passcode` in `e_app_access_type.svelte`) is entirely local — it reads the cached values and compares directly. No API call is made. The backend already has a `/authenticate_passcode` endpoint that verifies server-side, but it needs the fixes described below before the frontend can rely on it.
|
||
|
||
### Source of Truth
|
||
|
||
`site.access_code_kv_json` is the single source of truth for all passcodes. The `v_site_domain` DB view joins this field from the site table — there is no separate copy. Both the bootstrap response and `/authenticate_passcode` read from the same data.
|
||
|
||
---
|
||
|
||
## Threat Model
|
||
|
||
| Threat | Current | After Fix |
|
||
|---|---|---|
|
||
| Attacker inspects localStorage | Sees all passcodes in plaintext | Sees a JWT (opaque, no passcode) |
|
||
| Attacker uses stolen trusted passcode | Trivial if they have localStorage access | Still possible if they enter the passcode — unavoidable |
|
||
| Attacker replays an old passcode after it changes | Works forever (cached value never refreshes) | Fails — API verifies against current DB value |
|
||
| Attacker tampers with `access_type` in localStorage | Grants apparent permission but API calls still fail | Same — `access_type` is still persisted separately |
|
||
| Passcode reuse across sessions | Works indefinitely | JWT TTL enforces session expiry per role |
|
||
| Offline / API-unavailable entry | Works (local cache) | **Blocked** — requires API to verify |
|
||
|
||
### The fundamental constraint
|
||
|
||
Passcode-based access is inherently weaker than username/password login with a hashed credential. The system's security model layers passcode access below user login, and API calls themselves are still gated by `x-aether-api-key` + `x-account-id`. The passcode primarily controls **what the frontend shows** and some API-level permission gates for trusted routes.
|
||
|
||
---
|
||
|
||
## Proposed Solution: API-Verified Passcode + JWT Session
|
||
|
||
### Core idea
|
||
|
||
1. **Never send passcodes to the client.** The frontend stops reading/storing `access_code_kv_json` from the bootstrap response.
|
||
2. **Passcode entry triggers an API call** to `/authenticate_passcode`. API verifies server-side against the DB.
|
||
3. **On success, the API returns a JWT** — the JWT contains the role, account context, and expiry.
|
||
4. **Store the JWT in `$ae_loc.jwt`** (already a field, already wired into `$ae_api`).
|
||
5. **On page reload**, check the JWT's `eat` (expires-at) claim locally (base64 decode, no signature verification needed client-side). If expired, drop to anonymous. If valid, `access_type` is already persisted in `$ae_loc`.
|
||
|
||
### Session restore on reload
|
||
|
||
- `access_type` still persists in localStorage (no change here)
|
||
- The JWT is the **proof** that the access was legitimately granted and is still valid
|
||
- On page load: decode JWT payload (base64 the middle segment), check `eat` vs `Date.now()/1000`
|
||
- If JWT expired → reset `access_type` to anonymous, clear JWT
|
||
- If JWT valid → no action needed, `access_type` is already correct
|
||
|
||
This gives session expiry without a network call on every page load.
|
||
|
||
---
|
||
|
||
## TTL Per Role — Decided
|
||
|
||
| Access Level | JWT TTL | Notes |
|
||
|---|---|---|
|
||
| `super` | 8 hours | Highest privilege |
|
||
| `manager` | 24 hours | |
|
||
| `administrator` | 48 hours | |
|
||
| `trusted` | 48 hours | Onsite staff — covers multi-day events |
|
||
| `public` | 24 hours | |
|
||
| `authenticated` | 12 hours | |
|
||
| `anonymous` | N/A | No passcode |
|
||
|
||
---
|
||
|
||
## Caching Decision
|
||
|
||
**No passcode caching.** Every passcode entry makes one API call. The JWT handles session persistence — no passcode ever touches localStorage. Performance impact is only at the moment of entry (~50–150ms), which is acceptable for a once-per-session action.
|
||
|
||
---
|
||
|
||
## Backend Changes Required
|
||
|
||
**Note:** The backend fixes described below have been implemented and tested in the `aether_api_fastapi` repository (the `/authenticate_passcode` endpoint now uses explicit role priority, returns a full passcode JWT with `auth_type: 'passcode'`, applies per-role TTLs, and validates passcode length). Frontend changes can proceed once the backend deployment with these fixes is available.
|
||
|
||
**Phase 2 status:** Not started — removing `access_code_kv_json` from the public site model remains pending.
|
||
|
||
**File:** `aether_api_fastapi/app/routers/api.py`
|
||
|
||
The `/authenticate_passcode` endpoint exists and is structurally correct but has four issues that must be fixed before the frontend migrates to using it.
|
||
|
||
### Fix 1: Passcode matching must use explicit priority order
|
||
|
||
**Current (wrong):**
|
||
```python
|
||
for role, code in access_codes.items(): # dict insertion order — not guaranteed
|
||
if str(code) == str(passcode):
|
||
matched_role = role
|
||
break
|
||
```
|
||
|
||
**Required:**
|
||
```python
|
||
ROLE_PRIORITY = ['super', 'manager', 'administrator', 'trusted', 'public', 'authenticated']
|
||
|
||
matched_role = None
|
||
for role in ROLE_PRIORITY:
|
||
code = access_codes.get(role)
|
||
if code and str(code) == str(passcode):
|
||
matched_role = role
|
||
break
|
||
```
|
||
|
||
This ensures that if a config mistake causes two roles to share a passcode, the higher-privilege role always wins. It also makes the intent explicit and independent of JSON storage order.
|
||
|
||
### Fix 2: JWT payload must include all six role flags
|
||
|
||
**Current (incomplete):**
|
||
```python
|
||
payload = {
|
||
'account_id': account_id_random,
|
||
'administrator': (matched_role == 'administrator'),
|
||
'manager': (matched_role == 'manager'),
|
||
'super': (matched_role == 'super'),
|
||
# trusted / public / authenticated missing
|
||
...
|
||
}
|
||
```
|
||
|
||
**Required:**
|
||
```python
|
||
payload = {
|
||
'account_id': account_id_random,
|
||
'super': (matched_role == 'super'),
|
||
'manager': (matched_role == 'manager'),
|
||
'administrator': (matched_role == 'administrator'),
|
||
'trusted': (matched_role == 'trusted'),
|
||
'public': (matched_role == 'public'),
|
||
'authenticated': (matched_role == 'authenticated'),
|
||
'json_str': json.dumps({
|
||
'auth_type': 'passcode', # distinguishes from user login JWTs
|
||
'site_id': site_id,
|
||
'role': matched_role # canonical role string — frontend uses this
|
||
})
|
||
}
|
||
```
|
||
|
||
The `auth_type: 'passcode'` marker is critical — it allows the frontend and any future backend consumers to distinguish a passcode JWT from a user login JWT.
|
||
|
||
### Fix 3: Per-role TTL
|
||
|
||
**Current:**
|
||
```python
|
||
token = sign_jwt(
|
||
secret_key=settings.JWT_KEY,
|
||
ttl=3600 * 24, # hardcoded 24h for all roles
|
||
**payload
|
||
)
|
||
```
|
||
|
||
**Required:**
|
||
```python
|
||
ROLE_TTL = {
|
||
'super': 8 * 3600, # 8 hours
|
||
'manager': 24 * 3600, # 24 hours
|
||
'administrator': 48 * 3600, # 48 hours
|
||
'trusted': 48 * 3600, # 48 hours
|
||
'public': 24 * 3600, # 24 hours
|
||
'authenticated': 12 * 3600, # 12 hours
|
||
}
|
||
|
||
token = sign_jwt(
|
||
secret_key=settings.JWT_KEY,
|
||
ttl=ROLE_TTL[matched_role],
|
||
**payload
|
||
)
|
||
```
|
||
|
||
### Fix 4: Add minimum length validation to `passcode` field
|
||
|
||
**Current:**
|
||
```python
|
||
passcode: str = Field(..., description="The passcode to verify")
|
||
```
|
||
|
||
**Required:**
|
||
```python
|
||
passcode: str = Field(..., min_length=5, description="The passcode to verify")
|
||
```
|
||
|
||
This matches the frontend's 5-character trigger and prevents empty/trivial submissions.
|
||
|
||
### Complete corrected endpoint (for reference)
|
||
|
||
```python
|
||
ROLE_PRIORITY = ['super', 'manager', 'administrator', 'trusted', 'public', 'authenticated']
|
||
|
||
ROLE_TTL = {
|
||
'super': 8 * 3600,
|
||
'manager': 24 * 3600,
|
||
'administrator': 48 * 3600,
|
||
'trusted': 48 * 3600,
|
||
'public': 24 * 3600,
|
||
'authenticated': 12 * 3600,
|
||
}
|
||
|
||
class PasscodeAuthRequest(BaseModel):
|
||
"""Request model for site-based passcode authentication."""
|
||
site_id: str = Field(..., description="Random string ID of the site")
|
||
passcode: str = Field(..., min_length=5, description="The passcode to verify")
|
||
|
||
@router.post('/authenticate_passcode', response_model=Resp_Body_Base)
|
||
async def authenticate_passcode(
|
||
auth_req: PasscodeAuthRequest,
|
||
response: Response = Response,
|
||
):
|
||
"""
|
||
Passcode-to-JWT Endpoint.
|
||
Verifies a passcode against site.access_code_kv_json (single source of truth —
|
||
v_site_domain joins from the same site record).
|
||
Returns a signed JWT with the site's account context, full role flags, and
|
||
a per-role TTL. The jwt.json_str.auth_type='passcode' field distinguishes
|
||
this token from a user login JWT.
|
||
"""
|
||
site_id = auth_req.site_id
|
||
passcode = auth_req.passcode
|
||
|
||
# 1. Look up the site record
|
||
search_data = {'id_random': site_id}
|
||
if record := sql_select(table_name='site', data=search_data):
|
||
# 2. Parse access codes
|
||
access_codes_raw = record.get('access_code_kv_json')
|
||
access_codes = {}
|
||
if access_codes_raw:
|
||
try:
|
||
access_codes = json.loads(access_codes_raw) if isinstance(access_codes_raw, str) else access_codes_raw
|
||
except Exception as e:
|
||
log.error(f"Failed to parse access_code_kv_json for site {site_id}: {e}")
|
||
|
||
# 3. Verify passcode in explicit priority order (highest privilege wins)
|
||
matched_role = None
|
||
for role in ROLE_PRIORITY:
|
||
code = access_codes.get(role)
|
||
if code and str(code) == str(passcode):
|
||
matched_role = role
|
||
break
|
||
|
||
if matched_role:
|
||
log.info(f"Auth Success: Verified '{matched_role}' passcode for site {site_id}")
|
||
|
||
# 4. Resolve account context
|
||
account_id_random = record.get('account_id_random')
|
||
if not account_id_random:
|
||
if account_id_int := record.get('account_id'):
|
||
account_id_random = get_id_random(record_id=account_id_int, table_name='account')
|
||
|
||
# 5. Mint JWT with complete role flags and per-role TTL
|
||
payload = {
|
||
'account_id': account_id_random,
|
||
'super': (matched_role == 'super'),
|
||
'manager': (matched_role == 'manager'),
|
||
'administrator': (matched_role == 'administrator'),
|
||
'trusted': (matched_role == 'trusted'),
|
||
'public': (matched_role == 'public'),
|
||
'authenticated': (matched_role == 'authenticated'),
|
||
'json_str': json.dumps({
|
||
'auth_type': 'passcode',
|
||
'site_id': site_id,
|
||
'role': matched_role
|
||
})
|
||
}
|
||
|
||
token = sign_jwt(
|
||
secret_key=settings.JWT_KEY,
|
||
ttl=ROLE_TTL[matched_role],
|
||
**payload
|
||
)
|
||
|
||
return mk_resp(
|
||
data={'jwt': token, 'account_id': account_id_random, 'role': matched_role},
|
||
response=response
|
||
)
|
||
else:
|
||
log.warning(f"Auth Failed: Invalid passcode for site {site_id}")
|
||
return mk_resp(data=False, status_code=401, response=response, status_message="Invalid passcode.")
|
||
else:
|
||
log.warning(f"Auth Failed: Site {site_id} not found.")
|
||
return mk_resp(data=False, status_code=404, response=response, status_message="Site not found.")
|
||
```
|
||
|
||
### Backend Phase 2 (follow-up — not blocking frontend)
|
||
|
||
**Remove `access_code_kv_json` from the `Site_Domain_Base` response model** (`site_domain_models.py`). This ensures passcodes are never sent to the client even if future code reads from the bootstrap. Requires confirming no other endpoint consumers rely on `access_code_kv_json` being in the base response before making this change.
|
||
|
||
---
|
||
|
||
## Frontend Changes Required
|
||
|
||
**These depend on the backend fixes above being deployed first.**
|
||
|
||
### 1a. `src/lib/app_components/e_app_access_type.svelte`
|
||
|
||
Replace `handle_check_access_type_passcode` entirely. The new version:
|
||
|
||
- Is `async`
|
||
- Adds `auth_pending: boolean = $state(false)` and `auth_error: string | null = $state(null)`
|
||
- Uses a direct `fetch` call (NOT `post_object` — avoids triggering the session-expired banner on a 401)
|
||
- On success: sets `$ae_loc.access_type = data.role`, stores `$ae_loc.jwt = data.jwt`, triggers `process_permission_check` as before
|
||
- On 401: shows inline error, clears `entered_passcode`, resets `checked_passcode = null` to allow retry
|
||
- On network error: shows inline connection error
|
||
- Clears `auth_error` when `entered_passcode` changes
|
||
|
||
API call shape:
|
||
```http
|
||
POST /authenticate_passcode
|
||
Content-Type: application/json
|
||
x-aether-api-key: <from $ae_api.headers['x-aether-api-key']>
|
||
Body: { site_id: $ae_loc.site_id, passcode: entered_passcode }
|
||
```
|
||
|
||
Add to template (near the passcode input):
|
||
```svelte
|
||
{#if auth_pending}
|
||
<Loader size="1em" class="animate-spin text-gray-400" />
|
||
{/if}
|
||
{#if auth_error}
|
||
<span class="text-error-500 text-xs">{auth_error}</span>
|
||
{/if}
|
||
```
|
||
|
||
### 1b. `src/routes/+layout.ts`
|
||
|
||
**Stop caching passcodes from bootstrap** — remove line ~394:
|
||
```ts
|
||
// ae_loc_init['site_access_code_kv'] = json_data.access_code_kv_json || {};
|
||
```
|
||
|
||
**Add passcode JWT expiry check** — after the block around line 84 where `ae_loc_json.jwt` is read, add:
|
||
```ts
|
||
// Enforce passcode JWT TTL on page load.
|
||
// Decodes the JWT payload (base64, no secret needed) and resets access to anonymous if expired.
|
||
// User login JWTs (auth_type !== 'passcode') are left untouched.
|
||
if (ae_loc_json?.jwt) {
|
||
try {
|
||
const parts = ae_loc_json.jwt.split('.');
|
||
if (parts.length === 3) {
|
||
const jwt_payload = JSON.parse(atob(parts[1]));
|
||
const json_str = typeof jwt_payload.json_str === 'string'
|
||
? JSON.parse(jwt_payload.json_str)
|
||
: jwt_payload.json_str;
|
||
if (json_str?.auth_type === 'passcode' && jwt_payload.eat < Date.now() / 1000) {
|
||
// Passcode JWT has expired — revoke access
|
||
ae_loc_json.jwt = null;
|
||
ae_loc_json.access_type = 'anonymous';
|
||
}
|
||
}
|
||
} catch {
|
||
// Malformed JWT — leave untouched, let existing handling deal with it
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1c. `src/lib/stores/ae_stores__auth_loc_defaults.ts` (cleanup)
|
||
|
||
Remove `site_access_code_kv` from the `AuthLocState` interface and the `auth_loc_defaults` object. The field is unused after 1a. Confirm no other component reads from it first (current grep: only `e_app_access_type.svelte` uses it — confirmed).
|
||
|
||
---
|
||
|
||
## Migration Notes
|
||
|
||
- Users with existing localStorage will still have `site_access_code_kv` cached — this is harmless after the frontend stops reading it. No forced cache clear needed.
|
||
- Existing persisted `access_type` is unaffected — users keep their current session level until their JWT expires or they manually clear storage.
|
||
- The `$ae_loc.jwt` field is already used by the user login flow. The `auth_type: 'passcode'` marker in `json_str` ensures the expiry logic only targets passcode sessions, not user login sessions.
|
||
|
||
---
|
||
|
||
## Files Affected
|
||
|
||
| File | Repo | Change |
|
||
| --- | --- | --- |
|
||
| `app/routers/api.py` | `aether_api_fastapi` | **Backend — do first.** Priority ordering, full JWT payload, per-role TTL, min_length on passcode |
|
||
| `app/models/site_domain_models.py` | `aether_api_fastapi` | Phase 2: remove `access_code_kv_json` from public model |
|
||
| `src/lib/app_components/e_app_access_type.svelte` | `aether_app_sveltekit` | Replace local check with async API call; loading/error UI |
|
||
| `src/routes/+layout.ts` | `aether_app_sveltekit` | Stop caching passcodes; add JWT expiry check |
|
||
| `src/lib/stores/ae_stores__auth_loc_defaults.ts` | `aether_app_sveltekit` | Cleanup: remove `site_access_code_kv` |
|
||
| `documentation/AE__Permissions_and_Security.md` | `aether_app_sveltekit` | Update passcode auth section to reflect new flow |
|