Feature Flags · Phase 2b 14 · JWT-aware context + file-backed override store + sensitive-flag precheck · additive on top of Phase 2a+

Phase statement ข้อกำหนดเฟส

Phase 2a+ shipped a runnable HTTP boundary for the Phase 2a evaluator, authenticated by X-PTT-* dev headers only, with inline-only override support. Phase 2b closes three honest gaps without crossing into write-path territory:

• · A Bearer JWT resolver so the wire contract is already in the shape IdP integration will need — without claiming verification is live.
• · A file-backed override store so tenants/users have non-inline overrides that layer beneath inline ones — without a database.
• · A sensitive-flag precheck endpoint that reports the sensitivity profile + required approvers locally — without cross-calling the admin policy service (the cross-runtime demo remains the place for that).

The intent is to move FF service one honest step closer to production without overclaiming any of the underlying infrastructure.

Delta from Phase 2a+ ความเปลี่ยนแปลงจาก 2a+

Scope vs non-scope ขอบเขต

JWT boundary rationale ทำไมต้องมี JWT boundary ตอนนี้

The Phase 2a+ contract already reserved auth_strategy.phase_2b_plan (RS256 · JWKS · claims shape). Actually implementing the Bearer reader now — even without verification — means:

• · The wire format is locked in. When IdP integration lands, only the verification flag flips; no request shape change.
• · Runtimes that already issue JWTs (eg. the Admin Phase 2b path) can start sending them now and get their claims picked up honestly.
• · The fallback to X-PTT-* headers is explicit and labeled dev_headers, so operators can grep logs for which requests are actually using which path.
• · warnings: ['auth_not_verified'] travels with every unverified response — impossible to silently mistake dev mode for prod.

Verification becomes live only when ALL three conditions hold simultaneously: PyJWT installed · POLICY_JWT_VERIFY=true · POLICY_JWT_PUBLIC_KEY or POLICY_JWKS_URL present. Any missing precondition keeps the service in honest dev mode.

Override store rationale ทำไมต้องมี override store

Inline overrides (request.overrides.user / tenant) were the only path in Phase 2a+. That is fine for contract testing but unusable for tenants who want persistent opt-in/opt-out without round-tripping every request with a payload. A file-backed store is the minimum-viable concrete representation that preserves the data model required by Phase 2c's Postgres work, without actually committing us to a database.

Precedence (top wins):

1. inline request.overrides.user[flag_key]
2. inline request.overrides.tenant[flag_key]
3. store user-row matching (flag_key, user_id) · non-expired
4. store tenant-row matching (flag_key, tenant_id) · non-expired
5. evaluator staged bucketing / rollout_stage_map / default

Expired rows (expires_at in the past) are treated as absent but kept in the file for inspection. approval_ref on a row is display-only in this phase — the admin approval store is not consulted. The operator can read the ref and cross-check manually via the Admin policy-engine service if needed.

Importantly, the evaluator's own 9-step logic (Phase 2a) is unchanged. The service merges store-backed overrides into the request.overrides field before calling evaluator.evaluate(), so precedence rules like deps before overrides (step 3 before step 5) still hold — an override cannot activate a flag whose dependencies are unsatisfied. This is a fail-safe feature, not a bug.

Sensitive-flag gating rationale ทำไมต้องมี precheck endpoint ใหม่

The evaluator already blocks flags whose audit.last_approval_ref is null and requires_approval is true (step 4, approval_missing). But from the client's perspective, that's a terse source=approval_missing with no guidance. Phase 2b's POST /api/flags/sensitive-eval returns a richer, operator-friendly response:

• · sensitivity_profile — sensitive_flag, requires_approval, rollout_stage, policy_precheck_required.
• · policy_hint — a local computation from registry fields: decision (allow / deny-needs-approval / skipped), required_approvers, approval_matrix_row, approvals_present, plus an honest_note explicitly stating this does NOT call the admin service.
• · can_proceed_to_eval — (NOT policy_precheck_required) OR approvals_present.
• · flag_result — populated only when can_proceed=true. Even then, the evaluator may still return approval_missing because the flag-level gate (audit.last_approval_ref) is a separate check. Surfacing both is the honest double-gate.

For a REAL policy-first / eval-second chain against the admin policy service (with actual HTTP calls, trace interleaving, and deny-path short-circuiting), operators should continue using the cross-runtime integration demo. Keeping that orchestration out of this service preserves the decision-service safety profile and avoids tight coupling between the two runtimes.

A-owned vs B-owned boundary เส้นแบ่ง ownership

Sequence overview ลำดับการทำงาน

// Request arrives at FF service (Phase 2b extended)

client → FF service
    headers: Authorization: Bearer <jwt>   (optional)
    headers: X-PTT-* (optional · legacy)

Bearer resolver:
    if can_verify (PyJWT+flag+key) → verified claims · auth_source='jwt'
    else if bearer present           → decoded only    · auth_source='jwt_unverified' + warning
    else                             → skip

Context merge: bearer claims > X-PTT-* > query > defaults

IF endpoint == /api/flags/sensitive-eval:
    sensitivity_profile  ← registry.flag (sensitive_flag · requires_approval · rollout_stage)
    policy_hint          ← LOCAL computation (NOT admin service)
    can_proceed_to_eval   = (NOT precheck_required) OR approvals_present
    IF can_proceed:
        merge store overrides UNDER inline overrides (store_user < store_tenant < inline)
        → evaluator.evaluate(registry, merged_ctx)    // unchanged Phase 2a
        → flag_result (evaluator may still gate via step 4 approval_missing)
    ELSE:
        flag_result = null

IF endpoint == /api/flags/eval (existing 2a+ path):
    → evaluator.evaluate(registry, ctx)       // unchanged · parity 19/19

IF endpoint == /api/flags/overrides/by-flag/{key}:
    → return all store rows for {key} with active=bool    // read-only

client ← FF service JSON envelope {ok, data, error, service}

Route rationale เหตุผลของ path

• · Runtime surfaces under /runtime/feature-flags-service/ — sibling to phase_2b_contract.json, the existing service.html, README.md, and the new phase-2b.html. The word Dashboard is not used (reserved per IA hard rule #5).
• · Planning document under /planning/feature-flags-phase-2b.html, sibling to feature-flags.html (the existing Phase 1/2a/2a+ banner).
• · No new main-console button, no new Ops Portal button — discoverability via Index Portal + banners + back-links only.

Discoverability impact ผลกระทบต่อ discoverability

• · New planning entry idx-planning-flags-2b at 03.14.00.00
• · New runtime entry idx-runtime-flags-service-2b at 04.01.10.00
• · New appendix entries at 04.01.10.01/02/03 (phase_2b_contract.json · override_store_schema.json · override_examples.json) and 04.01.10.04 (phase-2b.html if kept in idx)
• · FF planning page banner gains a Phase 2b line
• · FF service README gains a "Phase 2b additions" section
• · FF Phase 2a+ service.html footer gains a "Phase 2b →" link
• · Fulltext index rebuilt to include the new surfaces
• · Target search terms: feature flags phase 2b · ff 2b · jwt feature flags · override store · tenant override · user override · sensitive flag gating · policy aware flags · feature flag auth boundary · feature flags runtime 2b

Deferred matrix รายการที่ยังไม่ทำ

Definition of Done · Phase 2b only เกณฑ์จบรอบนี้

What Phase 2b is NOT สิ่งที่รอบนี้ไม่ใช่