docs(adr): add ADR-004 (portal key storage) + ADR-005 (CORS deny-cache TTL)#105
Merged
Conversation
…e TTL) Locks in two v0.2.0 audit decisions that were marked 'worth recording' in the reviewer agent's punch list. Both are pure documentation — behaviour was already shipped in PRs #101 and #104. ADR-004 — Portal Signing Key Storage: - Plaintext varchar(64) at rest, mirroring the existing SigningSecret column. No application-level encryption; relies on operator's Postgres deployment posture. - Instant invalidation on rotate / disable. No grace window for overlapping old + new key validity. - One-shot reveal on enable / rotate; subsequent reads return only portalEnabled bool + rotated-at + origins (never the key). - Documents alternatives (pgcrypto, rotation grace, external KMS) and revisit triggers (compliance regimes, host-integration friction, key reuse beyond JWT verification). ADR-005 — Portal CORS Preflight Deny-Cache TTL: - 60s default (LookupCacheTtlSeconds reuse); cache both allow and deny outcomes; key is lowercased-origin scoped. - No synchronous invalidation hook from PUT /portal/origins: cache key is origin-scoped, operator action is app-scoped — bookkeeping cost outweighs the <=60s staleness. - Documents alternatives (per-app invalidation, shorter/longer TTL, negative-only cache) and revisit triggers (operator UX complaints, memory pressure via origin enumeration).
voyvodka
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tur 5 of the v0.2.0 portal audit follow-up. Locks in two decisions the reviewer agent flagged as "worth recording as ADRs" — both are pure documentation; the behaviour was already shipped in PR #101 (ADR-004 surface) and PR #104 (ADR-005 surface).
ADRs
ADR-004 — Portal Signing Key Storage: Plaintext + Instant Invalidation, No Rotation Grace
varchar(64)at rest, mirroring the existingSigningSecretcolumn.enable/rotate.pgcrypto(defers, doesn't solve the underlying compromise scenario), rotation grace (doubles blast radius of leaked key), external KMS (out of scope for self-hosted reference).ADR-005 — Portal CORS Preflight Deny-Cache TTL
LookupCacheTtlSecondsreuse); both allow and deny cached.PUT /portal/origins— cache key is origin-scoped, operator action is app-scoped; the bookkeeping cost outweighs the ≤60s staleness.Test plan
adr-NNN-kebab-slug.md).