docs(security): narrow x-no-account-id guidance and JWT notes

This commit is contained in:
Scott Idem
2026-05-01 13:59:07 -04:00
parent d5e5cb7ada
commit 19822c4eaf
4 changed files with 34 additions and 2 deletions

View File

@@ -86,6 +86,18 @@ site_access_code_kv: {
}
```
### `x-no-account-id` — Narrow Transport Exception
`x-no-account-id` is a transport-level escape hatch that strips account context before the request leaves the frontend. It is not a permission grant and it is not a replacement for JWT or `x-account-id`.
Use it only when the request truly cannot be made account-scoped. Current legitimate cases should stay narrow:
1. Bootstrap / site-domain discovery before the account is known.
2. Explicit public or guest endpoints that do not have an account context.
3. Helper paths that intentionally need a global-default fallback.
If a request already has a valid account context, prefer `x-account-id` and let the JWT carry session identity. Treat any new `x-no-account-id` use as temporary until it is reviewed and either replaced or justified.
---
## Utility Functions
@@ -154,6 +166,11 @@ Returns `1` if `level_a` is higher, `-1` if lower, `0` if equal. Useful for thre
- Security model: API key is one layer; JWT + `x-account-id` scoping provides the primary auth.
- Do not introduce new usages. Prefer `PUBLIC_AE_BOOTSTRAP_KEY` for unauthenticated lookups.
### JWT usage guidance
- JWTs are the preferred proof of an established session. Keep them attached to authenticated flows instead of leaning on transport-level bypasses.
- If a route or helper can work with a JWT and an account ID, it should not need `x-no-account-id`.
- If a helper still needs the bypass today, document the reason and add a removal target.
### Email Display
Non-trusted users must never see a full email address. Obscure using:
```typescript