55 lines
3.8 KiB
Markdown
55 lines
3.8 KiB
Markdown
# AUTH — User Authentication
|
|
|
|
Bearer-token user authentication: JWT issuance, client-side token storage, HTTP + SignalR transport bindings, per-tag SignalR dispatch authorization, and security hardening.
|
|
|
|
> **Architectural authority:** [`../adr/0001-user-bearer-token-flow.md`](../adr/0001-user-bearer-token-flow.md). This README is the consumer-facing recipe; the ADR captures rationale and decision history.
|
|
|
|
## Status
|
|
|
|
⚠️ **Pre-implementation.** ADR 0001 specifies the architecture; framework code not yet landed. This README is a scaffold — the "Consumer recipe" section fills in as implementation progresses (per ADR 0001 Follow-up "Implementation" series).
|
|
|
|
## Scope
|
|
|
|
| Concern | Decision |
|
|
|---|---|
|
|
| Token issuance | JWT (HS256, 24h fixed lifetime, configurable per consumer); refresh-flow deferred to ADR 0002 |
|
|
| Client-side storage | `IAcTokenStore` framework abstraction; consumer-supplied platform impls (MAUI / WASM) |
|
|
| HTTP transport | Framework-provided delegating handler injects bearer header automatically |
|
|
| SignalR transport | Framework hub-builder extension wires access-token provider; WASM uses query-string fallback |
|
|
| Server-side validation | Standard ASP.NET Core JwtBearer pipeline via framework DI bundle |
|
|
| Per-tag authorization | Hub-class `[Authorize]` default + explicit allowlist attribute for unauth tags (login, ping) |
|
|
| Security hardening | Startup options validation (key length, issuer/audience), HTTPS metadata required outside Development |
|
|
|
|
## Out of scope (per ADR 0001)
|
|
|
|
Refresh-token flow (→ ADR 0002), role/claims authorization, multi-tenant claims, OAuth2 / external IdP, token revocation, logout server-side invalidation.
|
|
|
|
## Files in this folder
|
|
|
|
- [`README.md`](README.md) — this file (scope + consumer recipe).
|
|
- [`AUTH_ISSUES.md`](AUTH_ISSUES.md) — known issues, security observations, edge cases.
|
|
- [`AUTH_TODO.md`](AUTH_TODO.md) — planned work derived from ADR 0001 Follow-ups.
|
|
|
|
## Consumer recipe
|
|
|
|
> Placeholder — populated as implementation progresses.
|
|
|
|
Sections to come (mirrors ADR 0001 Follow-up "Implementation" + "Consumer wiring"):
|
|
- DI registration bundle examples (MAUI + WASM + Server)
|
|
- `IAcTokenStore` consumer implementation skeletons
|
|
- Hub allowlist attribute usage
|
|
- `appsettings.json` `AyCode:Jwt` section reference
|
|
- HTTPS / Kestrel / proxy notes (especially WASM `access_token` URL-param redaction)
|
|
|
|
## Security: Never log secrets
|
|
|
|
JWT signing keys, access tokens, refresh tokens, password hashes, and OAuth client secrets MUST NEVER appear in log output. Logged secrets leak via the same channels as the logs themselves (file system, retention archives, screenshots, bug reports). For diagnostics, log only metadata (user ID, expiry, issuer) or hash prefixes — never the raw value.
|
|
|
|
This guideline emerged from `ACCORE-LOG-I-P5W3` and `ACCORE-LOG-I-K1Z7` (both `Closed (2026-04-25)` via `#if DEBUG` gating per ADR 0001 pre-flight). A pending TODO (forthcoming entry in `LOGGING_TODO.md`, no ID assigned yet) proposes a generalized framework-level guideline section in [`LOGGING/README.md`](../../AyCode.Core/docs/LOGGING/README.md); when it lands, this section trims to a cross-ref.
|
|
|
|
## Cross-references
|
|
|
|
- **ADR**: [`../adr/0001-user-bearer-token-flow.md`](../adr/0001-user-bearer-token-flow.md) — architectural decision.
|
|
- **Topic registry**: `AUTH` row in [`TOPIC_CODES.md`](../../.github/skills/docs-check/references/TOPIC_CODES.md) (added in `LLMP-DEC-49`).
|
|
- **Sibling pre-migration**: `ACCORE-LOG-I-P5W3` / `ACCORE-LOG-I-K1Z7` in [`LOGGING_ISSUES.md`](../../AyCode.Core/docs/LOGGING/LOGGING_ISSUES.md) — currently homed in LOGGING; ADR 0001 Follow-up "Status migration on AUTH topic creation" lists these as candidates for relocation here as `AUTH-I-N` with `Superseded by` cross-refs in LOGGING. Migration NOT yet performed — separate user-approved follow-up.
|