docs(security): narrow x-no-account-id guidance and JWT notes
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user