28 KiB
28 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 05-data-layer-full-fidelity | 03 | execute | 3 |
|
|
true |
|
|
Purpose: this is the phase's other named security-load-bearing surface (mass assignment was Plan 02) — encryption key handling, redaction discipline, and the fact that Organisations land in the user plugin's migration set even though only Fonoteka's credential tables reference them this phase.
Output: lagoon.Encrypted, lagoon.KeyGenerateCommand, a Laravel-decrypt helper; golem15_user_organisations; ApiToken, OAuthClient, OAuthAuthCode, OAuthRefreshToken, UserAiCredential, OrgAiCredential, UserDiscogsCredential, OrgDiscogsCredential models and their 3 migrations.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/phases/05-data-layer-full-fidelity/05-CONTEXT.md @.planning/phases/05-data-layer-full-fidelity/05-RESEARCH.md @.planning/phases/05-data-layer-full-fidelity/05-01-SUMMARY.mdFrom summercms.go/lagoon/fill.go (Plan 05-01):
type HasHidden interface { Hidden() []string }
From fonoteka.go/plugins/golem15/fonoteka/models/registry.go and updates/registry.go, and the equivalent in plugins/golem15/user (Plan 05-01):
func Register(models ...any) // package models
func All() []any // package models
func Register(ms ...*gormigrate.Migration) // package updates
func All() []*gormigrate.Migration // package updates
From summercms.go/bouncer/jwt.go Verify (the fail-loud-on-empty-secret shape to copy for app.key):
func Verify(tokenString, secret string) (string, error) {
if strings.TrimSpace(secret) == "" {
return "", fmt.Errorf("bouncer: jwt secret is empty")
}
...
}
From summercms.go/lagoon/commands.go RuntimeCommands (the command-trio shape key:generate joins):
func RuntimeCommands(app *backpack.App, plugins []party.Plugin) []bonfire.Command {
return []bonfire.Command{ {Name: "migrate", ...}, {Name: "migrate:rollback", ...}, {Name: "migrate:status", ...} }
}
From summercms.go/compass/config.go (dot-path config access app.key/app.previous_keys will use):
func (c *Config) String(path string) string
func (c *Config) Lookup(path string) (any, bool)
In `lagoon/keygen.go`: implement `func KeyGenerateCommand() bonfire.Command` returning `bonfire.Command{Name: "key:generate", Description: "Print a fresh 32-byte base64 app.key", Run: func(ctx context.Context, in bonfire.Input, out bonfire.Output) error { ... }}` using `crypto/rand.Read` on a 32-byte buffer, `out.Success(base64.StdEncoding.EncodeToString(key))` — never `math/rand`. Append `KeyGenerateCommand()` to the slice `RuntimeCommands` returns in `lagoon/commands.go` (one new line in the existing slice literal — a framework-owned file no other plan in this phase touches).
In `lagoon/laravel_decrypt.go`: implement `func DecryptLaravelPayload(payloadJSON string, appKey []byte) ([]byte, error)` — base64-JSON-decode `{iv, value, mac}` per Laravel's `encrypted` cast format, verify the HMAC-SHA256 `mac` over `iv+value` using `appKey` (raw bytes — Laravel uses the raw `APP_KEY` directly for both cipher and MAC key, verify against the RESEARCH.md-cited Laravel docs), then AES-256-CBC-decrypt `value` with `iv`, unpadding PKCS#7. Doc-comment it "cutover-import-only; never called from `Encrypted`'s live Scan/Value path" (D-10).
Create `models/organisation.go` (package `models`, in `plugins/golem15/user`) with `type Organisation struct { ID uint; Name string; CreatedAt time.Time; UpdatedAt time.Time }`, `func (Organisation) TableName() string { return "golem15_user_organisations" }`, `func init() { models.Register(Organisation{}) }` — structure only, no `Fillable`/`Rules`/relations beyond the FK target Fonoteka's credential models need (Phase 7 owns roles/membership behavior).
Add an `app.key: ""` entry to `fonoteka.go/config/app.yaml` as a documented placeholder — following `config/database.yaml`'s "Set SUMMER_..." comment-header convention: "# Set SUMMER_APP__KEY to a 32-byte base64 value (summer key:generate). Empty fails boot once any encrypted-cast model runs." Do not set a real value.
Create the 8 model files (package `models`), each following the exact struct/tag shape from RESEARCH.md's per-model inventory rows and the D-10..D-13 code example: `ApiToken` (row 4: `UserID`, `Name *string`, `TokenHash string` `json:"-"`, `Scopes lagoon.Jsonable[[]string]`, `CollectionIDs lagoon.Jsonable[[]uint]`, `ExpiresAt`/`RevokedAt`/`LastUsedAt *time.Time`, `LastUsedIP *string`, `OAuthClientID *string`; `Hidden()` returns `{"token_hash"}`); `OAuthClient` (row 14, `ClientSecretHash string` `json:"-"`, `Hidden()` `{"client_secret_hash"}`); `OAuthAuthCode` (row 13, `CodeHash string` `json:"-"`, `Hidden()` `{"code_hash"}`); `OAuthRefreshToken` (row 15, `TokenHash string` `json:"-"`, `Hidden()` `{"token_hash"}`); `UserAiCredential`/`OrgAiCredential` (rows 21/16, `APIKey lagoon.Encrypted` `gorm:"column:api_key"` `json:"-"`, `Hidden()` `{"api_key"}`, exactly matching the code example in RESEARCH.md's "Pattern: Encrypted-at-rest cast" section); `UserDiscogsCredential`/`OrgDiscogsCredential` (rows 23/17, `Token lagoon.Encrypted` `gorm:"column:token"` `json:"-"`, `Hidden()` `{"token"}`). Every file's `init()` calls `models.Register(TheType{})`.
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| app.key config -> Encrypted column key | a misconfigured or absent key must never silently fall back to a weak/default key |
| stored ciphertext -> old key holder | key rotation must not lock out legitimately-encrypted-under-the-old-key rows, nor allow decrypting with a key that was never a real primary |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-05-08 | Information Disclosure | lagoon.Encrypted accidental serialization |
mitigate | json:"-" backstop plus MarshalJSON/String/GoString all hardcoded to redact; Hidden() on every credential model names the same column (D-13) |
| T-05-09 | Information Disclosure / Denial of Service | key rotation | mitigate | Versioned ciphertext (key-id prefix) plus app.previous_keys decrypt-only fallback prevents both silent data loss and indefinite reuse of a retired key (D-12) |
| T-05-10 | Tampering | app.key missing/weak |
mitigate | LoadAppKey fails boot loudly on empty/short/undecodable input, no default value path exists (D-11) |
| T-05-11 | Tampering (supply chain) | HKDF key derivation for lagoon.Encrypted |
accept | Uses the Go 1.27 standard library crypto/hkdf package — no new dependency is introduced (this corrects an earlier draft of this plan that proposed golang.org/x/crypto/hkdf; Go 1.24+ ships HKDF in stdlib, so CLAUDE.md's stdlib-first rule applies directly and there is nothing for a package-legitimacy checkpoint to review) |
| T-05-12 | Repudiation | api_tokens/oauth_refresh_tokens store only *_hash columns, never raw secrets |
accept | Matches PHP's own design; raw tokens are never persisted anywhere, hashed only, consistent with the Hidden() backstop |
| </threat_model> |
<success_criteria>
lagoon.Encryptedround-trips, redacts on every marshal path, supports key rotation viaapp.previous_keys, fails boot loudly on a badapp.key, and derives its column key using only the Go 1.27 standard library (no new dependency).key:generateand the standalone Laravel decrypt helper exist and are tested.golem15_user_organisationsexists, owned by the user plugin; nowiden_usersmigration ships this phase.- All 3 secrets-slice migrations and 8 models exist, self-register, and have correct
Hidden()/json:"-"/lagoon.Encryptedtyping. </success_criteria>