Admin Control Plane · Phase 2b 15 · JWT + approval store backing + TTL enforcement + audit sink boundary · additive on top of Phase 2a · 24/24 parity preserved

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

Phase 2a shipped a runnable policy engine that answered access / mask / assist / view-as / sensitive questions deterministically — but it trusted any non-empty approval_ref at face value, accepted only dev X-PTT-* headers, and had no audit envelope. Phase 2b closes four honest gaps without crossing into write-path territory:

• · A Bearer JWT resolver so the wire contract matches what IdP integration will eventually need — without claiming verification is live.
• · A file-backed approval store with rows grounded 1:1 in approval_queue_model.queue_shape.item_fields.
• · TTL / expiry semantics that honour sla_due_at and dual-signer rules — consumed by new endpoints that do NOT alter Phase 2a behaviour.
• · An audit sink BOUNDARY — a preview endpoint that renders an envelope matching audit_event_model.base_shape without delivering to Kafka or WORM.

This moves Admin one honest step closer to production while keeping every phase-2a guarantee intact.

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

Scope vs non-scope ขอบเขต

JWT / verified-auth boundary rationale ทำไมต้องมี JWT boundary

Phase 2a reserved auth_strategy.phase_2b_plan (RS256 · JWKS · claims per role_registry.jwt_claim_shape). Implementing the Bearer resolver now — even in decode-only mode — means:

• · The wire format is locked. When IdP integration lands, only the verification flag flips · no request shape change.
• · Sibling services (FF 2b) already issue-aware; Admin can accept the same JWT and pick up sub/role/tenant_id.
• · Fallback X-PTT-* is explicit and labeled dev_headers in service.auth_source so grep on a log tells operators which path was taken.
• · Unverified responses carry warnings: ['auth_not_verified'] · impossible to silently confuse dev with prod.

Verification conditions (all three required): PyJWT installed · POLICY_JWT_VERIFY=true · POLICY_JWT_PUBLIC_KEY or POLICY_JWKS_URL. Any missing precondition keeps the service in honest dev mode.

Approval store rationale ทำไมต้องมี store backing

Phase 2a's sensitive_check relied on _active_approval() which trusts any non-empty string. That is fine for contract testing but cannot honour dual-signer rules, TTL, withdrawn/rejected states, or matrix_row cross-checks. A file-backed store is the minimum-viable concrete representation matching exactly the queue_shape.item_fields Phase 2c will persist in Postgres.

Row shape authority: docs/runtime/admin-control-plane/approval_queue_model.json#queue_shape.item_fields is canonical. approval_store_schema.json mirrors it field-for-field; any divergence is a bug.

Read-only stance: no create / sign / withdraw endpoints in this phase. Mutation is Phase 2c. The store is loaded once at startup; no hot reload. Store writes stay blocked even if the file is edited — the running process sees only the snapshot taken at boot.

TTL / expiry rationale ทำไมต้องมี TTL semantics ชัด

sla_due_at doubles as the TTL deadline — it is the single source of truth for "still consumable". The engine computes ttl_remaining at read time rather than relying on a background sweeper flipping state. This is intentional for Phase 2b:

• · No scheduler infrastructure is required. Any request that arrives after sla_due_at receives expired=true.
• · Consistency with access_policy.precedence_rules.prec-8: "Any unmask without active approval_ref OR expired TTL → masked".
• · Honest mirror of approval_queue_model.expiration_rules: expired items cannot auto-revive; resubmit is Phase 2c.

Dual-signer rule: state='signed_partial' is valid only when required_signer_count=1. Dual rows (=2) require signed_full. The reason code dual_signers_required is emitted on the boundary so callers see exactly why.

Audit sink boundary rationale ทำไมต้องมี audit boundary ก่อน

The full audit pipeline needs Kafka SASL, WORM bucket, hash-chain keys, and a query API — all Phase 2b+ infra. But downstream runtimes already want to see the exact envelope shape they will eventually need to emit. POST /api/policy/audit/preview answers that:

• · Returns an envelope matching audit_event_model.base_shape populated from request context.
• · sink_status: 'deferred' on every response · impossible to mistake for real delivery.
• · Stdout also logs the envelope as NDJSON · operators can tail the service log.
• · Accepts any of the 20 event_types · warnings if the type is not in the model.

Audit read access control, hash-chain signing, and the real producer wait for Phase 2c.

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

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

// Phase 2b request flow (admin-control-plane-service)

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

Bearer resolver:
    verify (PyJWT + flag + key + aud) → auth_source='jwt'
    else decode-only                  → auth_source='jwt_unverified' + warning
    else                               → skip

Context merge: claims > headers > body > query > defaults

IF endpoint == /api/policy/approvals/{id}:
    store lookup → 404 if absent
    → validate_approval_row(row, now) → {valid, expired, ttl_remaining, reasons}

IF endpoint == /api/policy/approvals/validate (POST):
    for each approval_id in body.approval_refs:
        store lookup
        validate_approval_row → per_ref entry
    return {per_ref[], any_valid, any_expired, all_valid}

IF endpoint == /api/policy/sensitive.check.2b (POST):
    compute required_approvers from mask_row
    for each approval_ref:
        validate_approval_row → expired / state check
    decision = allow iff any_valid AND matrix_row matches
    writes by platform_role still denied (same as Phase 2a)

IF endpoint == /api/policy/audit/preview (POST):
    render envelope matching audit_event_model.base_shape
    sink_status='deferred' · stdout NDJSON mirror
    NEVER contacts Kafka

IF endpoint in Phase 2a set (access · mask · assist · viewas · sensitive · batch · health):
    → Phase 2a policy_engine functions (unchanged · 24/24)

client ← JSON envelope {ok, data, error, service{auth_source, warnings}}

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

• · Runtime surfaces under /runtime/admin-control-plane-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 under /planning/admin-control-plane-phase-2b.html, sibling to admin-control-plane.html.
• · No new main-console button, no new Ops Portal button — discoverability via Index Portal + banners + back-links.

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

• · New planning entry idx-planning-admin-2b at 03.15.00.00
• · New runtime entry idx-runtime-admin-service-2b at 04.03.10.00
• · New appendix entries at 04.03.10.01..04 (contract · approval schema · approval examples · audit contract · audit examples)
• · Admin planning page banner appended Phase 2b line
• · Phase 2a service debug footer appended "Phase 2b ↗"
• · Phase 1 admin runtime index banner appended Phase 2b link
• · Fulltext index rebuilt · target search terms: admin control plane phase 2b · admin 2b · approval store · approval ttl · admin jwt · policy verified auth · audit sink boundary · expired approval · row sensitive override · approval validity

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

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

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