|
|
|
|
@@ -0,0 +1,639 @@
|
|
|
|
|
# Phase 08: OAuth2.1 Authorization Server - Pattern Map
|
|
|
|
|
|
|
|
|
|
**Mapped:** 2026-09-23
|
|
|
|
|
**Files analyzed:** 40 concrete or logical new/modified targets
|
|
|
|
|
**Analogs found:** 34 / 40 (six protocol/security targets have no native Go analog)
|
|
|
|
|
|
|
|
|
|
## Scope Notes
|
|
|
|
|
|
|
|
|
|
- The target list comes from `08-CONTEXT.md` D-01 through D-21 and `08-RESEARCH.md`'s recommended structure, schema correction, Wave 0 gaps, and validation map.
|
|
|
|
|
- `wristband` is framework-only and must never import `fonoteka.go`, GORM, or app models.
|
|
|
|
|
- The PHP files are the byte/state source of truth. They are contract analogs, not Go structure analogs.
|
|
|
|
|
- Existing untracked `go.work.sum` and concurrently created phase artifacts were not touched.
|
|
|
|
|
- The current repository differs from two research assumptions: `ApiTokenManager` still hard-codes `inv_`, and `bonfire` supports scalar string flags only. Both gaps are included below.
|
|
|
|
|
|
|
|
|
|
## File Classification
|
|
|
|
|
|
|
|
|
|
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
| `wristband/server.go` | provider/controller | request-response | `surf/router.go`; `wire/response.go` | role-match |
|
|
|
|
|
| `wristband/stores.go` | provider/service | CRUD + transactional | `bouncer/registry.go` (interfaces); app `classes/active_collection.go` (transaction) | partial |
|
|
|
|
|
| `wristband/authorize.go` | controller/service | request-response + CRUD | PHP `OAuthAuthorizeController.php` | contract-exact; no Go analog |
|
|
|
|
|
| `wristband/token.go` | controller/service | request-response + transactional CRUD | PHP `OAuthTokenController.php`; `OAuthCodeManager.php` | contract-exact; no Go analog |
|
|
|
|
|
| `wristband/register.go` | controller/service | request-response + CRUD | PHP `OAuthRegisterController.php` | contract-exact; no Go analog |
|
|
|
|
|
| `wristband/crypto.go` | utility | transform | app `classes/auth/api_token_manager.go`; `token_guard.go` | role-match |
|
|
|
|
|
| `wristband/*_test.go` (including in-memory store) | test/provider | request-response + CRUD + concurrency | `bouncer/*_test.go`; app `classes/auth/api_token_manager_test.go` | role-match |
|
|
|
|
|
| `bonfire/command.go` | config/contract | command input | existing `bonfire/command.go` | modification; exact home |
|
|
|
|
|
| `bonfire/root.go` | provider | command parsing | existing `bonfire/root.go` | modification; exact home |
|
|
|
|
|
| `bonfire/output_test.go` | test | command parsing | `TestFlagAndArgumentParsing` in same file | exact |
|
|
|
|
|
| `scripts/check-phase8.sh` | config/test gate | batch | `scripts/check-phase3.sh` | exact family |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/config/config.yaml` | config | transform | user plugin `config/config.yaml` | exact |
|
|
|
|
|
| `../fonoteka.go/config/app.yaml` | config | transform | existing app config | exact home |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/models/oauth_client.go` | model | CRUD | same file + `models/api_token.go` | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/models/oauth_auth_code.go` | model | CRUD | same file + `models/api_token.go` | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/updates/12_oauth_schema_correction.go` (name discretionary) | migration | batch/DDL | `updates/11_secrets_slice.go` | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/updates/*oauth*_test.go` | test | batch/DDL | `classes/auth/postgres_test.go`; existing migration tests | role-match |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/classes/auth/oauth_store.go` | service/provider | transactional CRUD | `classes/active_collection.go`; `collection_write_service.go` | role-match; no row-lock analog |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/classes/auth/oauth_token_issuer.go` | service/adapter | CRUD | `classes/auth/api_token_manager.go` | exact seam |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/classes/auth/api_token_manager.go` | service | CRUD + transform | same file | modification; exact home |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/classes/auth/oauth_store_test.go` and issuer tests | test | transactional CRUD + concurrency | `classes/auth/postgres_test.go`; `api_token_manager_test.go` | exact harness |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/oauth_consent_controller.go` | controller | request-response + CRUD | `controllers/api/token_api_controller.go` | role/data-flow exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/connected_app_controller.go` | controller | request-response + CRUD | `controllers/api/token_api_controller.go` | role/data-flow exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/me_token_controller.go` | controller | request-response | `controllers/api/me_locale_controller.go`; PHP `MeTokenController.php` | role-match + contract-exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/*oauth*_test.go` and `me_token_controller_test.go` | test | request-response + CRUD | route/controller tests; PHP OAuth tests | role-match |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/console/oauth_client.go` | utility/command | CRUD | user plugin command registration; PHP `IssueOAuthClient.php` | role-match + contract-exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/console/oauth_client_test.go` | test | command + CRUD | user `console_test.go` | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/routes.go` | route | request-response | same file | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/plugin.go` | provider/config | event-driven bootstrap | same file; user `plugin.go` | exact |
|
|
|
|
|
| `../fonoteka.go/plugins/golem15/fonoteka/routes_*test.go` / `plugin_boot_test.go` | test | request-response + bootstrap | same files | exact |
|
|
|
|
|
| `../fonoteka.go/parity/oauth_flow_test.go` | test | request-response replay | `parity/nuxt_flow_test.go` | exact |
|
|
|
|
|
| `../fonoteka.go/parity/fixtures/mcp/mcp-lifecycle.yaml` | test fixture | request-response sequence | existing `mcp-oauth.yaml`, `mcp-tools.yaml` | exact family |
|
|
|
|
|
| `../fonoteka.go/parity/capture_clients.mjs` | utility/test client | event-driven + request-response | same file's `captureMcpOauth` | exact |
|
|
|
|
|
| `../fonoteka.go/parity/capture-rules.yaml` | config | transform/capture | existing OAuth capture rules | exact |
|
|
|
|
|
| `../fonoteka.go/parity/manifest.yaml` | config | batch/replay | existing nine pending entries | exact |
|
|
|
|
|
| `.planning/ROADMAP.md` | config/docs | transform | Phase 8 row/section in same file | exact |
|
|
|
|
|
| `.planning/REQUIREMENTS.md` | config/docs | transform | `AUTH-05` row in same file | exact |
|
|
|
|
|
| `.planning/notes/*oauth*.md` (exact name discretionary) | config/docs | transform | existing decision notes | role-match |
|
|
|
|
|
| `.planning/phases/08-oauth2-1-authorization-server/08-SECURITY-REVIEW.md` | test/audit | batch | Phase 6 `06-SECURITY-REVIEW.md` | exact template |
|
|
|
|
|
| Phase 6 supersession note (prefer Phase 8 plan/summary; do not silently rewrite locked history) | config/docs | transform | Phase 6 D-09 references | partial |
|
|
|
|
|
|
|
|
|
|
## Pattern Assignments
|
|
|
|
|
|
|
|
|
|
### `wristband/server.go`, `authorize.go`, `token.go`, `register.go`
|
|
|
|
|
|
|
|
|
|
**Structural analogs:** `surf/router.go`, `wire/response.go`
|
|
|
|
|
**Contract analogs:** PHP OAuth controllers and `OAuthCodeManager.php`
|
|
|
|
|
|
|
|
|
|
**Raw route behavior** (`surf/router.go:149-169`, `369-422`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func (r *Router) GroupRaw(prefix string, middleware []string, fn func(pact.Router)) {
|
|
|
|
|
r.openGroup(prefix, middleware, true, fn)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (r *Router) wrap(rt route) (http.Handler, error) {
|
|
|
|
|
h := constrain(rt.handler, rt.constraints)
|
|
|
|
|
// ... apply per-route middleware ...
|
|
|
|
|
if rt.raw {
|
|
|
|
|
h = recoverBare(h)
|
|
|
|
|
} else {
|
|
|
|
|
h = recoverJSON(h)
|
|
|
|
|
}
|
|
|
|
|
return h, nil
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Copy the `http.HandlerFunc` shape, but keep RFC response writing inside `wristband`; do not reuse house validation/envelopes. The server should expose handler methods suitable for direct `pact.Router` registration.
|
|
|
|
|
|
|
|
|
|
**Exact JSON writer convention** (`wire/response.go:10-23`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func WriteJSON(w http.ResponseWriter, status int, v any) {
|
|
|
|
|
var buf bytes.Buffer
|
|
|
|
|
enc := json.NewEncoder(&buf)
|
|
|
|
|
enc.SetEscapeHTML(false)
|
|
|
|
|
if err := enc.Encode(v); err != nil {
|
|
|
|
|
WriteOpaque500(w)
|
|
|
|
|
return
|
|
|
|
|
}
|
|
|
|
|
w.Header().Set("Content-Type", "application/json")
|
|
|
|
|
w.WriteHeader(status)
|
|
|
|
|
_, _ = w.Write(bytes.TrimSuffix(buf.Bytes(), []byte("\n")))
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Follow its no-trailing-newline and no-HTML-escaping technique, but use a wristband-local raw writer so encoding failures and protocol errors never acquire the house 500 envelope.
|
|
|
|
|
|
|
|
|
|
**Authorize validation order** (PHP `OAuthAuthorizeController.php:25-61`):
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
$client = $clientId !== '' ? OAuthClient::where('client_id', $clientId)->first() : null;
|
|
|
|
|
if ($client === null || !$client->isUsable()) {
|
|
|
|
|
return $this->localError('Unknown client.');
|
|
|
|
|
}
|
|
|
|
|
$redirectUri = (string) $request->query('redirect_uri', '');
|
|
|
|
|
if ($redirectUri === '' || !in_array($redirectUri, $client->redirectUris() ?? [], true)) {
|
|
|
|
|
return $this->localError('Unregistered redirect URI.');
|
|
|
|
|
}
|
|
|
|
|
// Only later failures redirect to the now-trusted URI.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Preserve this order exactly: client, exact redirect allow-list, response type, method, challenge, scopes/ceiling, resource, pending creation. Unknown client/redirect is local text 400 with no `Location`.
|
|
|
|
|
|
|
|
|
|
**Ordered redirect construction** (PHP `OAuthAuthorizeController.php:146-169`):
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
$params = [
|
|
|
|
|
'error' => $error,
|
|
|
|
|
'error_description' => $description,
|
|
|
|
|
'iss' => rtrim((string) config('app.url'), '/'),
|
|
|
|
|
];
|
|
|
|
|
if ($state !== null) {
|
|
|
|
|
$params['state'] = $state;
|
|
|
|
|
}
|
|
|
|
|
$query = http_build_query($params, '', '&', PHP_QUERY_RFC3986);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Implement one ordered-pair RFC 3986 helper. Do not use `url.Values.Encode()` because it sorts keys and uses form-style space encoding.
|
|
|
|
|
|
|
|
|
|
**Token dispatch/error pattern** (PHP `OAuthTokenController.php:21-63`, `143-151`):
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
if ($grantType === '') return $this->rfcError('invalid_request');
|
|
|
|
|
if ($grantType !== 'authorization_code' && $grantType !== 'refresh_token') {
|
|
|
|
|
return $this->rfcError('unsupported_grant_type');
|
|
|
|
|
}
|
|
|
|
|
// authenticate client, then dispatch grant
|
|
|
|
|
$response->header('WWW-Authenticate', 'Basic realm="OAuth"');
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Go-specific parser rule from D-02: reject JSON first, then `r.ParseForm()` and read `r.Form` (body wins over query). Basic credentials override form credentials. The only 401 challenge is exactly `Basic realm="OAuth"`.
|
|
|
|
|
|
|
|
|
|
**Registration body bound:** wrap only `/register` decoding with `http.MaxBytesReader` at 64 KiB and translate overflow to the ordinary `invalid_client_metadata` body. Raw routes are exempt from the house body-limit middleware (`surf/router.go:369-422`), so the bound belongs in wristband.
|
|
|
|
|
|
|
|
|
|
### `wristband/stores.go` and app `classes/auth/oauth_store.go`
|
|
|
|
|
|
|
|
|
|
**Closest Go transaction pattern:** `classes/active_collection.go:34-71`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func ResolveActiveCollection(ctx context.Context, gdb *gorm.DB, userID uint) (*models.Collection, error) {
|
|
|
|
|
var out *models.Collection
|
|
|
|
|
err := gdb.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
|
|
|
|
|
// every read/write uses tx
|
|
|
|
|
return nil
|
|
|
|
|
})
|
|
|
|
|
if err != nil {
|
|
|
|
|
return nil, err
|
|
|
|
|
}
|
|
|
|
|
return out, nil
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Use the same context-bound single closure on the app side, but expose only app-agnostic wristband interfaces:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
type Backend interface {
|
|
|
|
|
WithinTx(context.Context, func(Tx) error) error
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
type Tx interface {
|
|
|
|
|
ClientStore
|
|
|
|
|
AuthCodeStore
|
|
|
|
|
RefreshTokenStore
|
|
|
|
|
AccessTokenIssuer
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
There is **no existing Go row-lock analog**. The adapter must add `clause.Locking{Strength: "UPDATE"}` for code and refresh lookup. `wristband` must not import `gorm.io/gorm/clause`.
|
|
|
|
|
|
|
|
|
|
**Replay commit pattern** (PHP `OAuthCodeManager.php:163-232`):
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
$replayed = false;
|
|
|
|
|
$result = DB::transaction(function () use (&$replayed) {
|
|
|
|
|
$record = OAuthRefreshToken::where(...)->lockForUpdate()->first();
|
|
|
|
|
if ($record->rotated_to_id !== null) {
|
|
|
|
|
$this->revokeLineage($record);
|
|
|
|
|
$replayed = true;
|
|
|
|
|
return null;
|
|
|
|
|
}
|
|
|
|
|
// rotate normally
|
|
|
|
|
});
|
|
|
|
|
if ($replayed || $result === null) {
|
|
|
|
|
throw new OAuthInvalidGrantException();
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
In Go, record an outcome, return `nil` from `WithinTx` so lineage revocation commits, then return `ErrInvalidGrant` outside the transaction. Returning the OAuth error inside the GORM callback would roll back the security action.
|
|
|
|
|
|
|
|
|
|
### `wristband/crypto.go`
|
|
|
|
|
|
|
|
|
|
**Analog:** app `classes/auth/api_token_manager.go:23-44` and `token_guard.go:66-69`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
raw := make([]byte, 32)
|
|
|
|
|
if _, err := rand.Read(raw); err != nil {
|
|
|
|
|
return "", nil, err
|
|
|
|
|
}
|
|
|
|
|
secret := MintablePrefix + base64.RawURLEncoding.EncodeToString(raw)
|
|
|
|
|
|
|
|
|
|
func hashToken(secret string) string {
|
|
|
|
|
sum := sha256.Sum256([]byte(secret))
|
|
|
|
|
return hex.EncodeToString(sum[:])
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Reuse the primitives, not the app function: wristband opaque values have no `inv_` prefix. Client ID = 16 random bytes; client secret/code/refresh/request handle use their PHP byte lengths; encode with `base64.RawURLEncoding`; persist SHA-256 hex only. Add `crypto/subtle.ConstantTimeCompare` on fixed-length transformed values for both client secret and S256 PKCE.
|
|
|
|
|
|
|
|
|
|
### `wristband/*_test.go`
|
|
|
|
|
|
|
|
|
|
**Analog:** app `classes/auth/api_token_manager_test.go:13-51`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
secret, token, err := MintPersonalToken(1, "my token", nil, nil, nil)
|
|
|
|
|
if err != nil { t.Fatal(err) }
|
|
|
|
|
raw, err := base64.RawURLEncoding.DecodeString(strings.TrimPrefix(secret, "inv_"))
|
|
|
|
|
if err != nil || len(raw) != 32 { t.Fatalf(...) }
|
|
|
|
|
sum := sha256.Sum256([]byte(secret))
|
|
|
|
|
if token.TokenHash != hex.EncodeToString(sum[:]) { t.Fatalf(...) }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Keep tests as plain Go table tests with deterministic clock/random injection. The in-memory backend should hold one mutex for the full transaction closure so concurrency tests model the seam rather than individual map operations.
|
|
|
|
|
|
|
|
|
|
Required named families: metadata bytes/order; authorize validation and redirects; token parser asymmetry; Basic/post/none auth; PKCE syntax and comparison; code replay; refresh rotation/replay commit; DCR validation, cap and 64 KiB bound; expiry sweep; ordered URL encoding; no-sensitive-value logging.
|
|
|
|
|
|
|
|
|
|
### App OAuth models and schema correction
|
|
|
|
|
|
|
|
|
|
**Model analog:** `models/api_token.go:10-36`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
type ApiToken struct {
|
|
|
|
|
TokenHash string `gorm:"column:token_hash" json:"-"`
|
|
|
|
|
OAuthClientID *string `gorm:"column:oauth_client_id"`
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func (ApiToken) Hidden() []string { return []string{"token_hash"} }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Preserve `json:"-"` plus `Hidden()` for every secret hash. Change only the required OAuth fields:
|
|
|
|
|
|
|
|
|
|
- `OAuthClient.ClientSecretHash string` -> `*string`.
|
|
|
|
|
- `OAuthAuthCode.RequestID string` -> `*string`.
|
|
|
|
|
- `OAuthAuthCode.CodeHash string` -> `*string`.
|
|
|
|
|
- `OAuthAuthCode.UserID uint` -> `*uint`.
|
|
|
|
|
|
|
|
|
|
**Migration analog:** `updates/11_secrets_slice.go:47-109`, registered by `updates/registry.go:7-14`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
oauthTablesMigration = &gormigrate.Migration{
|
|
|
|
|
ID: "202609180010_create_oauth_tables",
|
|
|
|
|
Migrate: func(tx *gorm.DB) error {
|
|
|
|
|
return execStmts(tx, []string{/* ordered SQL */})
|
|
|
|
|
},
|
|
|
|
|
Rollback: func(tx *gorm.DB) error {
|
|
|
|
|
return execStmts(tx, []string{/* reverse-safe SQL */})
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func init() { Register(apiTokenMigration, oauthTablesMigration, credentialsTablesMigration) }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Add a new migration ID; do not edit the already-applied `202609180010` migration. `up` drops four `NOT NULL` constraints and adds PHP-equivalent operational indexes idempotently. `down` must refuse safely if null lifecycle rows exist rather than coercing or deleting data.
|
|
|
|
|
|
|
|
|
|
**Postgres test harness:** `classes/auth/postgres_test.go:37-52`, `122-156`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func TestMain(m *testing.M) {
|
|
|
|
|
if !testShort() { authPGErr = startAuthPostgres(ctx) }
|
|
|
|
|
code := m.Run()
|
|
|
|
|
stopAuthPostgres()
|
|
|
|
|
os.Exit(code)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func authDB(t testing.TB) *gorm.DB {
|
|
|
|
|
if testing.Short() { t.Skip("requires testcontainers postgres") }
|
|
|
|
|
// lagoon.Use, migrate user then fonoteka, register hooks
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Reuse this package harness. Add real-Postgres proofs for two simultaneous pending rows, pending-to-code nulling, public-client null secret, indexes, migration rollback refusal, `FOR UPDATE` code double-spend, concurrent refresh, replay lineage kill, and serialized DCR cap.
|
|
|
|
|
|
|
|
|
|
### App token issuer and `api_token_manager.go`
|
|
|
|
|
|
|
|
|
|
**Analog:** `classes/auth/api_token_manager.go:21-57`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func MintPersonalToken(userID uint, name string, scopes []string, expiresAt *time.Time, collectionIDs []uint) (string, *models.ApiToken, error) {
|
|
|
|
|
// generate inv_ secret and construct model; caller persists
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
func RevokeToken(db *gorm.DB, token *models.ApiToken) error {
|
|
|
|
|
now := time.Now()
|
|
|
|
|
if err := db.Model(token).Update("revoked_at", now).Error; err != nil { return err }
|
|
|
|
|
token.RevokedAt = &now
|
|
|
|
|
return nil
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The adapter should mint, set `OAuthClientID`, and persist through the transaction-scoped `*gorm.DB`. Revoke by access-token ID through the same transaction. Keep raw secret return one-way.
|
|
|
|
|
|
|
|
|
|
Repository drift to resolve: line 14 currently declares `const MintablePrefix = "inv_"`; D-11 says the prefix is config-backed with `inv_` as the fonoteka value. Preserve byte parity and update tests so no default path changes the emitted prefix.
|
|
|
|
|
|
|
|
|
|
### Consent and connected-app controllers
|
|
|
|
|
|
|
|
|
|
**Analog:** `controllers/api/token_api_controller.go`
|
|
|
|
|
|
|
|
|
|
**Imports/dependency pattern** (`:13-20`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
import (
|
|
|
|
|
"git.golem15.com/golem15/fonoteka/plugins/golem15/fonoteka/classes"
|
|
|
|
|
"git.golem15.com/golem15/fonoteka/plugins/golem15/fonoteka/classes/auth"
|
|
|
|
|
"git.golem15.com/golem15/fonoteka/plugins/golem15/fonoteka/models"
|
|
|
|
|
"git.golem15.com/golem15/summercms/backpack"
|
|
|
|
|
"git.golem15.com/golem15/summercms/bouncer"
|
|
|
|
|
"git.golem15.com/golem15/summercms/lagoon"
|
|
|
|
|
"git.golem15.com/golem15/summercms/wire"
|
|
|
|
|
"gorm.io/gorm"
|
|
|
|
|
)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**JWT dependency/auth pattern** (`:195-210`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func deps(w http.ResponseWriter, r *http.Request, app *backpack.App) (*gorm.DB, *bouncer.Principal, bool) {
|
|
|
|
|
gdb, ok := app.Lookup[*gorm.DB]()
|
|
|
|
|
user, ok := bouncer.User(r.Context())
|
|
|
|
|
if !ok || user == nil || user.ID == 0 {
|
|
|
|
|
writeOpaque500(w)
|
|
|
|
|
return nil, nil, false
|
|
|
|
|
}
|
|
|
|
|
return gdb, user, true
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Routes provide JWT auth. Controllers still derive the user from context and scope every pending/client/token query by ownership. Missing, stale, consumed, or foreign request handles collapse to the exact 404 contract.
|
|
|
|
|
|
|
|
|
|
**Validation and active collection** (`:35-67`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
errs, err := lagoon.Validate(r.Context(), gdb, models.ApiToken{}, rules, fields, nil)
|
|
|
|
|
if len(errs) > 0 {
|
|
|
|
|
writeValidation(w, errs)
|
|
|
|
|
return
|
|
|
|
|
}
|
|
|
|
|
active, err := classes.ResolveActiveCollection(r.Context(), gdb, user.ID)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For consent, validate `request_id` and each submitted scope, then intersect submitted ∩ pending requested ∩ `auth.MintableScopes`. Collection IDs come only from `ResolveActiveCollection`; never trust request collection IDs.
|
|
|
|
|
|
|
|
|
|
**Connected-app serialization/revocation** (`:90-113`, `117-172`):
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
err := gdb.WithContext(r.Context()).
|
|
|
|
|
Where("user_id = ? AND oauth_client_id IS NOT NULL AND revoked_at IS NULL", user.ID).
|
|
|
|
|
Order("created_at DESC").Find(&rows).Error
|
|
|
|
|
|
|
|
|
|
data = append(data, serializeToken(gdb, &rows[i]))
|
|
|
|
|
|
|
|
|
|
if err := auth.RevokeToken(gdb.WithContext(r.Context()), &token); err != nil { ... }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Reuse `serializeToken` rather than duplicating token fields, append sanitized `client_name`, count manual tokens separately, and call wristband lineage revocation in the same operation. Foreign/missing/manual IDs all return `{"error":"Token not found"}` with 404.
|
|
|
|
|
|
|
|
|
|
### `me_token_controller.go`
|
|
|
|
|
|
|
|
|
|
**Go handler analog:** `controllers/api/me_locale_controller.go:11-24`
|
|
|
|
|
**Exact response contract:** PHP `MeTokenController.php:22-37`
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
|
return response()->json(['data' => [
|
|
|
|
|
'scopes' => $token?->scopes ?? [],
|
|
|
|
|
'collection_ids' => $token?->collectionIds(),
|
|
|
|
|
'user_id' => $user?->id,
|
|
|
|
|
'name' => $token?->name,
|
|
|
|
|
]]);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `inv_token` guard already puts the matched `*models.ApiToken` in `bouncer.Credential` (`token_guard.go:32-64`). Read that credential and `bouncer.User`; do not perform a second bearer parse or database token lookup. Route it under `inv_token`, `throttle:fonoteka-api-token`, `inv.scope:read` and retain the existing backend 401 body/header behavior.
|
|
|
|
|
|
|
|
|
|
### `routes.go`, `plugin.go`, and OAuth config
|
|
|
|
|
|
|
|
|
|
**Route analog:** app `routes.go:10-43`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
r.Group("/_fonoteka/api/v1", surf.Use("jwt.auth", "locale.from-principal", "inv.must-change-password"), func(g pact.Router) {
|
|
|
|
|
// JWT-owned token/consent/connected-app handlers
|
|
|
|
|
})
|
|
|
|
|
r.Group("/api/v1/fonoteka", surf.Use("inv_token", "throttle:fonoteka-api-token", "inv.scope:read"), func(g pact.Router) {
|
|
|
|
|
// personal-token API including /me
|
|
|
|
|
})
|
|
|
|
|
r.GroupRaw("/", surf.Use(), func(g pact.Router) {
|
|
|
|
|
// RFC handlers; throttle only token and register per route
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Register `/token` and `/register` with variadic per-route middleware names, not group middleware. Do not attach `jwt.auth`, `inv_token`, `inv.scope`, or any house-tagged middleware to raw RFC routes.
|
|
|
|
|
|
|
|
|
|
**Plugin boot/provider analog:** app `plugin.go:44-83`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func (p *Plugin) Boot(app *backpack.App) error {
|
|
|
|
|
p.app = app
|
|
|
|
|
if gdb, ok := app.Lookup[*gorm.DB](); ok {
|
|
|
|
|
// construct/register app services
|
|
|
|
|
}
|
|
|
|
|
return nil
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Construct one wristband server from config, GORM store backend, and access-token issuer during boot; store it on `Plugin` for route factories and commands. Do not register an `oauth` guard.
|
|
|
|
|
|
|
|
|
|
**Config embedding analog:** user `plugin.go:41-43`, `165`; user `config/config.yaml:1-22`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
//go:embed config
|
|
|
|
|
var configFS embed.FS
|
|
|
|
|
|
|
|
|
|
func (p *Plugin) ConfigFS() fs.FS { return configFS }
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Add `pact.HasConfig`, plugin defaults for pending/code/access/refresh TTLs, DCR cap, stale-client age, resource, paths/scopes/metadata values, and 64 KiB register limit. `app.url` belongs in app config/environment and is trimmed once while constructing options. Never hard-code the issuer into wristband.
|
|
|
|
|
|
|
|
|
|
### `fonoteka:oauth-client` and the `bonfire` repeatable-flag gap
|
|
|
|
|
|
|
|
|
|
**Registration analog:** user `plugin.go:188-190`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func (p *Plugin) Commands() []bonfire.Command {
|
|
|
|
|
return []bonfire.Command{console.RequirePasswordChange(p.app)}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Command value analog:** example greeter plugin `plugin.go:78-118`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
return []bonfire.Command{{
|
|
|
|
|
Name: "greeter:hello",
|
|
|
|
|
Description: "Print the configured application name",
|
|
|
|
|
Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error {
|
|
|
|
|
out.Printf("name=%s\n", name)
|
|
|
|
|
return nil
|
|
|
|
|
},
|
|
|
|
|
}}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Exact required PHP signature/output:** `IssueOAuthClient.php:15-21`, `60-77`, `80-101`
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
fonoteka:oauth-client {name?}
|
|
|
|
|
--redirect-uri=* --scope=* --auth-method=client_secret_post
|
|
|
|
|
--client-id= --list
|
|
|
|
|
|
|
|
|
|
client_id=<id>
|
|
|
|
|
client_secret=<secret>
|
|
|
|
|
This secret is not recoverable and must be pasted into the connector now.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`--list` prints IDs, names, revocation, redirects, and ceiling but never a secret.
|
|
|
|
|
|
|
|
|
|
**Gap:** `bonfire/root.go:65-75` always calls Cobra `String`/`StringP`, and `bonfire.Input` exposes only `Flag(name) (string, bool)` (`command.go:40-45`). Repeatable PHP `=*` options therefore have no current analog. Extend the command contract/root wiring with an explicit string-slice flag shape and test repeated values in `bonfire/output_test.go`; do not parse `os.Args` inside the app command.
|
|
|
|
|
|
|
|
|
|
### Parity replay, lifecycle capture, and phase gate
|
|
|
|
|
|
|
|
|
|
**Replay analog:** `../fonoteka.go/parity/nuxt_flow_test.go:13-48`
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
db := parityDB(t)
|
|
|
|
|
applyPluginMigrations(t, db)
|
|
|
|
|
h, cfg := newConfiguredTarget(t, db)
|
|
|
|
|
srv := httptest.NewServer(h)
|
|
|
|
|
t.Cleanup(srv.Close)
|
|
|
|
|
|
|
|
|
|
flow, err := tide.LoadFlow(filepath.Join(dir, "nuxt-auth.yaml"))
|
|
|
|
|
store, err := tide.OpenStore("")
|
|
|
|
|
_, err = tide.ReplayFlow(t.Context(), flow, tide.ReplayConfig{
|
|
|
|
|
Target: srv.URL, Store: store, BaseDir: dir,
|
|
|
|
|
})
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Create `oauth_flow_test.go` with named projections for OAuth-relevant steps from `mcp-oauth` and `mcp-tools`, plus full `mcp-lifecycle`. Projection must fail if an expected step disappears; do not replay unrelated later-phase browser calls.
|
|
|
|
|
|
|
|
|
|
**Secret capture pattern:** `capture-rules.yaml:53-97`
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
- method: POST
|
|
|
|
|
path: /oauth/mcp/token
|
|
|
|
|
capture:
|
|
|
|
|
- from: request.form
|
|
|
|
|
name: code_verifier
|
|
|
|
|
as: pkce:mcp
|
|
|
|
|
category: pkce
|
|
|
|
|
- from: response.json
|
|
|
|
|
path: $.refresh_token
|
|
|
|
|
as: token:oauth-refresh
|
|
|
|
|
category: token
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Extend categories/rules for every new lifecycle secret. Keep private vars and `pkce.vars` mode 0600; committed fixtures contain placeholders only.
|
|
|
|
|
|
|
|
|
|
**Gate family:** `scripts/check-phase3.sh:6-63`
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
set -euo pipefail
|
|
|
|
|
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
|
|
|
APP="$(cd "$ROOT/../fonoteka.go" && pwd)"
|
|
|
|
|
|
|
|
|
|
run_module() {
|
|
|
|
|
local dir="$2"
|
|
|
|
|
(
|
|
|
|
|
cd "$dir"
|
|
|
|
|
go vet ./...
|
|
|
|
|
go test ./...
|
|
|
|
|
go test -race ./...
|
|
|
|
|
)
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Preserve fail-closed Docker checks, both-module vet/test/race, focused parity, corpus `--check-secrets`, and cleanup traps. Add real fonoteka-mcp startup with the three required environment variables and drive protected-resource discovery → AS metadata → DCR → PKCE authorize/login/consent → token → MCP tool → refresh. Do not modify the sibling MCP source.
|
|
|
|
|
|
|
|
|
|
### Planning and security artifacts
|
|
|
|
|
|
|
|
|
|
**Security review analog:** `06-SECURITY-REVIEW.md:1-18`, `30-64`
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
|
|
|
phase: 06
|
|
|
|
|
status: verified
|
|
|
|
|
threats_total: 34
|
|
|
|
|
threats_closed: 34
|
|
|
|
|
threats_open: 0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Copy the front matter, verdict summary, trust-boundary table, threat register, per-threat evidence, and command evidence structure. Phase 08 must map every `T-08-*` ID to a named failing-when-broken test and finish with zero unmapped threats.
|
|
|
|
|
|
|
|
|
|
Correct Phase 8's ROADMAP/REQUIREMENTS wording from zitadel/oidc to the direct standard-library wristband port and correct the resource-server/header ownership. Record D-01 in a decision note. For Phase 6 D-09, prefer an explicit supersession note in the Phase 8 plan/summary over rewriting locked historical context unless the planner is specifically authorized to update historical docs.
|
|
|
|
|
|
|
|
|
|
## Shared Patterns
|
|
|
|
|
|
|
|
|
|
### Framework/App Boundary
|
|
|
|
|
|
|
|
|
|
**Source:** `CLAUDE.md`; current package imports
|
|
|
|
|
**Apply to:** every `wristband/*` and app adapter file
|
|
|
|
|
|
|
|
|
|
`wristband` owns protocol records, parsing, policy, transitions, response shapes, and interfaces. `fonoteka.go` owns GORM, users, collections, token models, config, and controllers. Verify with an import-boundary test/grep: framework code must contain no `fonoteka` import.
|
|
|
|
|
|
|
|
|
|
### Authentication and Surface Isolation
|
|
|
|
|
|
|
|
|
|
**Source:** app `routes.go:12-21`, `token_guard.go:32-64`, `surf/router.go:369-422`
|
|
|
|
|
**Apply to:** routes and all controllers
|
|
|
|
|
|
|
|
|
|
- JWT group: consent and connected-app management only.
|
|
|
|
|
- Personal-token group: `/me` and resource APIs only, using existing `inv_token` and `inv.scope`.
|
|
|
|
|
- Raw group: metadata/authorize/token/register only; no auth guard and no house middleware.
|
|
|
|
|
- Never register the retired `oauth` guard.
|
|
|
|
|
|
|
|
|
|
### Response Serialization
|
|
|
|
|
|
|
|
|
|
**Source:** `wire/response.go:10-30`; app `token_api_controller.go:230-244`
|
|
|
|
|
**Apply to:** all handlers
|
|
|
|
|
|
|
|
|
|
- App controllers use `wire.WriteJSON` through the established `writeJSON` helper and keep PHP's `Cache-Control: no-cache, private` behavior where recorded.
|
|
|
|
|
- Wristband raw handlers use local exact writers and per-path cache headers; no `data` envelope, no generic house validation/error body.
|
|
|
|
|
- Backend token-surface 401 stays `{"error":"Invalid token"}` with no new Bearer challenge.
|
|
|
|
|
|
|
|
|
|
### Error Handling
|
|
|
|
|
|
|
|
|
|
**Source:** `token_api_controller.go:117-144`, PHP OAuth controllers
|
|
|
|
|
**Apply to:** app controllers and raw handlers
|
|
|
|
|
|
|
|
|
|
App ownership misses collapse to exact 404; unexpected storage/config/encoding failures are opaque. OAuth client/input/grant failures map to endpoint-native RFC bodies and statuses. Never expose storage errors or secrets in descriptions/logs.
|
|
|
|
|
|
|
|
|
|
### Database Transactions and Locking
|
|
|
|
|
|
|
|
|
|
**Source:** `active_collection.go:34-71`; PHP `OAuthCodeManager.php:97-232`
|
|
|
|
|
**Apply to:** code exchange, refresh rotation/replay, consent, revoke, DCR cap/sweep
|
|
|
|
|
|
|
|
|
|
Bind context once, run every operation on the passed transaction handle, acquire row locks before checking single-use state, and keep mint/revoke/link updates atomic. Commit replay lineage revocation before returning the protocol error.
|
|
|
|
|
|
|
|
|
|
### Testing
|
|
|
|
|
|
|
|
|
|
**Source:** `classes/auth/postgres_test.go`; `nuxt_flow_test.go`; Phase 6 security review
|
|
|
|
|
**Apply to:** all plans
|
|
|
|
|
|
|
|
|
|
Fast wristband behavior tests use the in-memory backend. Persistence/locking/migration and concurrency tests use the existing real-Postgres harness and skip only under `testing.Short()`. Route tests inspect the assembled surf route table, not a hand-built imitation. The final audit maps all 103 PHP OAuth test methods to named Go tests/subtests.
|
|
|
|
|
|
|
|
|
|
### Sensitive Values
|
|
|
|
|
|
|
|
|
|
**Source:** `capture-rules.yaml:53-97`; model `json:"-"`/`Hidden()` patterns
|
|
|
|
|
**Apply to:** stores, controllers, commands, capture, gates
|
|
|
|
|
|
|
|
|
|
Never log request IDs, codes, verifiers, client secrets, access tokens, or refresh tokens. Store only hashes except the one-time command/DCR response. Keep fixture vars private and run corpus secret scanning in the gate.
|
|
|
|
|
|
|
|
|
|
## No Native Go Analog Found
|
|
|
|
|
|
|
|
|
|
| File/Concern | Role | Data Flow | Reason / Required Reference |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `wristband/authorize.go` | controller/service | request-response + CRUD | No Go authorization-server state machine exists. Port validation order and bytes from PHP `OAuthAuthorizeController.php`, guided by RESEARCH patterns 3 and 5. |
|
|
|
|
|
| `wristband/token.go` refresh replay outcome | service | transactional CRUD | No Go lineage-rotation implementation exists. Port PHP `OAuthCodeManager.php:163-232`; ensure the replay kill commits before `invalid_grant`. |
|
|
|
|
|
| App `oauth_store.go` row locks | provider | transactional CRUD | Repository has GORM transactions but no `clause.Locking` use. Add app-only `FOR UPDATE` and real-Postgres contention tests. |
|
|
|
|
|
| `wristband/register.go` atomic cap | service | transactional CRUD | No atomic cap/sweep/create analog. Backend API must serialize the operation; test concurrent cap-1 registration. |
|
|
|
|
|
| Bonfire repeatable flags | config/provider | command parsing | Current `Flag` and `Input` are scalar-only. Extend bonfire with string-slice support before implementing exact `=*` options. |
|
|
|
|
|
| Ordered RFC 3986 query helper | utility | transform | Existing Go URL helpers do not preserve PHP insertion order/space bytes. Implement and fixture-test an ordered-pair encoder. |
|
|
|
|
|
|
|
|
|
|
## Planner Warnings
|
|
|
|
|
|
|
|
|
|
1. Schema correction is Wave 0. Handlers cannot model public clients or multiple pending requests until the four nullable fields and indexes are fixed.
|
|
|
|
|
2. Returning `ErrInvalidGrant` from inside the GORM callback rolls back replay revocation. Treat replay as a committed transaction outcome.
|
|
|
|
|
3. Validate the client and exact redirect URI before constructing any redirect.
|
|
|
|
|
4. Reject JSON `/token` requests before `ParseForm`; otherwise query parameters can make a JSON request succeed.
|
|
|
|
|
5. Keep rotated/revoked refresh rows until expiry; they are replay evidence.
|
|
|
|
|
6. Do not mount `/me`, consent, or connected apps on the wrong auth group.
|
|
|
|
|
7. Do not use `body.limit` on the raw registration route for D-21: its generic error shape would violate the endpoint-native `invalid_client_metadata` contract.
|
|
|
|
|
8. Do not claim D-14 until the real Node MCP starts, consumes `/api/v1/fonoteka/me`, completes a tool call, and refreshes against the Go backend.
|
|
|
|
|
|
|
|
|
|
## Metadata
|
|
|
|
|
|
|
|
|
|
**Analog search scope:** `summercms.go/{surf,wire,bouncer,bonfire,scripts}`, sibling `fonoteka.go/plugins/golem15/fonoteka`, sibling `fonoteka.go/parity`, canonical PHP OAuth implementation and unchanged MCP consumer
|
|
|
|
|
**Primary Go analogs:** `surf/router.go`, app `controllers/api/token_api_controller.go`, app `classes/auth/api_token_manager.go`, app `updates/11_secrets_slice.go`, app `parity/nuxt_flow_test.go`
|
|
|
|
|
**Contract sources:** PHP OAuth controllers/manager/client command and `MeTokenController.php`
|
|
|
|
|
**Pattern extraction date:** 2026-09-23
|
Jakub Zych