124 lines
4.7 KiB
Markdown
124 lines
4.7 KiB
Markdown
---
|
|
phase: 07-user-plugin-and-authentication
|
|
plan: 04
|
|
subsystem: auth
|
|
tags: [fonoteka, api-token, locale, parity]
|
|
|
|
requires:
|
|
- phase: 07-user-plugin-and-authentication
|
|
provides: JWT guard, locale.from-principal, inv.must-change-password
|
|
provides:
|
|
- MintPersonalToken and RevokeToken
|
|
- POST/GET/DELETE /_fonoteka/api/v1/tokens
|
|
- GET/PUT /_fonoteka/api/v1/me/locale
|
|
- route-table proof that me/locale is the 423 exemption
|
|
affects: [07-05, 07-06]
|
|
|
|
tech-stack:
|
|
added: []
|
|
patterns: [inv_ prefix plus sha256 hex shared with TokenGuard, me/locale group without the password lock]
|
|
|
|
key-files:
|
|
created:
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/classes/auth/api_token_manager.go
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/token_api_controller.go
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/controllers/api/me_locale_controller.go
|
|
modified:
|
|
- ../fonoteka.go/plugins/golem15/fonoteka/routes.go
|
|
- ../fonoteka.go/parity/manifest.yaml
|
|
|
|
key-decisions:
|
|
- "Personal token secrets are inv_ plus raw url-safe base64, hashed the same way TokenGuard verifies"
|
|
- "me/locale is the only /_fonoteka/api/v1 route without inv.must-change-password"
|
|
- "Empty preferred_locale is JSON null"
|
|
|
|
patterns-established:
|
|
- "Pattern: token list and locale responses send Cache-Control no-cache, private"
|
|
- "Pattern: a missing or foreign token id is the same 404"
|
|
|
|
requirements-completed: []
|
|
|
|
duration: 75min
|
|
completed: 2026-09-22
|
|
---
|
|
|
|
# Phase 7 Plan 04: Personal tokens and locale Summary
|
|
|
|
**Personal API tokens can be minted, listed, and revoked, and `me/locale` stays reachable while the password-change lock returns 423 everywhere else on `/_fonoteka/api/v1`.**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 75 min
|
|
- **Started:** 2026-09-22T14:50:00Z
|
|
- **Completed:** 2026-09-22T16:05:00Z
|
|
- **Tasks:** 3
|
|
- **Files modified:** 16
|
|
|
|
## Accomplishments
|
|
|
|
- `MintPersonalToken` returns an `inv_` secret whose sha256 hex matches `TokenGuard`. Revoke stamps `revoked_at`.
|
|
- `POST /tokens` rejects a scope outside `read`, `write`, and `ai` before insert. `GET /tokens` omits the secret. `DELETE /tokens/{id}` is owner-scoped.
|
|
- `GET/PUT /me/locale` persist `pl` or `en`. A locked user can still change locale and gets 423 on genres.
|
|
- The five routes replay as `status: ported`. The corpus is 7 ported and 147 pending out of 154.
|
|
|
|
## Task Commits
|
|
|
|
1. **Task 1: Mint and revoke** — `3c53bf8` in `fonoteka.go`
|
|
2. **Task 2: Token and locale HTTP** — `58fcb45` in `fonoteka.go`
|
|
3. **Task 3: Exempt-route proof and parity flip** — `fa95534` in `fonoteka.go`
|
|
|
|
## Files Created/Modified
|
|
|
|
- `plugins/golem15/fonoteka/classes/auth/api_token_manager.go` — mint and revoke
|
|
- `plugins/golem15/fonoteka/controllers/api/token_api_controller.go` — store, index, destroy
|
|
- `plugins/golem15/fonoteka/controllers/api/me_locale_controller.go` — show and update
|
|
- `plugins/golem15/fonoteka/routes.go` — locale middleware placement
|
|
- `parity/manifest.yaml` — five routes marked ported
|
|
|
|
## Decisions Made
|
|
|
|
The captured `POST /tokens` body was a debug HTML 500 from an empty name. The Go handler returns 422 `{"error":"Validation failed","errors":{"name":["The name field is required."]}}`, and the fixture now records that.
|
|
|
|
`GET /tokens` was a capture of a live `parity-mcp` row. Replay uses the genres seed token `Parity MCP` with scope `read`, and the fixture follows that seed.
|
|
|
|
## Deviations from Plan
|
|
|
|
### Auto-fixed Issues
|
|
|
|
**1. [Rule 1 - Bug] Nil validation map panicked on a bad scope**
|
|
- **Found during:** Task 2
|
|
- **Issue:** `lagoon.Validate` returns a nil map when `name` is valid, and assigning `errs["scopes"]` panicked into an opaque 500.
|
|
- **Fix:** Allocate the map before recording the scope error.
|
|
- **Files modified:** `controllers/api/token_api_controller.go`
|
|
- **Committed in:** `58fcb45`
|
|
|
|
**2. [Rule 1 - Bug] `created_at` used a `Z` suffix**
|
|
- **Found during:** Task 3
|
|
- **Issue:** Tide accepts only Carbon `+00:00` timestamps. `time.RFC3339` emits `Z`.
|
|
- **Fix:** Format token timestamps as `2006-01-02T15:04:05-07:00`.
|
|
- **Files modified:** `controllers/api/token_api_controller.go`
|
|
- **Committed in:** `fa95534`
|
|
|
|
---
|
|
|
|
**Total deviations:** 2 auto-fixed
|
|
**Impact on plan:** Bad scopes stay 422. Token timestamps match the parity normalizer.
|
|
|
|
## Issues Encountered
|
|
|
|
None
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
Ready for 07-05, which starts by recording the isolated PHP instance. AUTH-03 and AUTH-04 stay unchecked until the phase requirement is signed off.
|
|
|
|
## Self-Check: PASSED
|
|
|
|
- `TestMintPersonalToken`, `TestTokenApi`, `TestMeLocale`, and `TestRequirePasswordChangeExemptSet` passed.
|
|
- `go test ./parity/ -run 'TestParityCorpus|TestParityContract'` passed with 7 ported routes.
|
|
- Commits `3c53bf8`, `58fcb45`, and `fa95534` are on `fonoteka.go` master.
|