household-bot/docs/specs/HOUSEBOT-031-secure-scheduler-endpoint.md

HOUSEBOT-031: Secure Scheduler Endpoint and Idempotent Reminder Dispatch

Summary

Add authenticated reminder job endpoints to the bot runtime with deterministic deduplication and dry-run support.

Goals

• Accept reminder job calls through dedicated HTTP endpoints.
• Reject unauthorized or malformed scheduler requests.
• Prevent duplicate reminder dispatch for the same household, period, and reminder type.
• Emit structured outcomes for local validation and future monitoring.

Non-goals

• Full Cloud Scheduler IaC setup.
• Final Telegram reminder copy or topic routing.
• OIDC verification in v1 of this runtime slice.

Scope

• In: shared-secret auth, request validation, dry-run mode, dedupe persistence, structured logs.
• Out: live Telegram send integration and scheduler provisioning.

Interfaces and Contracts

• Endpoint family: /jobs/reminder/<type>
• Allowed types:
  • utilities
  • rent-warning
  • rent-due
• Request body:
  • period?: YYYY-MM
  • jobId?: string
  • dryRun?: boolean
• Auth:
  • x-household-scheduler-secret: <secret> or Authorization: Bearer <secret>

Domain Rules

• Dedupe key format: <period>:<reminderType>
• Persistence uniqueness remains household-scoped.
• dryRun=true never persists a dispatch claim.

Data Model Changes

• None. Reuse processed_bot_messages as the idempotency ledger for scheduler reminder claims.

Security and Privacy

• Scheduler routes are unavailable unless SCHEDULER_SHARED_SECRET is configured.
• Unauthorized callers receive 401.
• Request errors return 400 without leaking secrets.

Observability

• Successful and failed job handling emits structured JSON logs.
• Log payload includes:
  • jobId
  • dedupeKey
  • outcome
  • reminderType
  • period

Edge Cases and Failure Modes

• Empty body defaults period to the current UTC billing month.
• Invalid period format is rejected.
• Replayed jobs return duplicate without a second dispatch claim.

Test Plan

• Unit: reminder job service dry-run and dedupe results.
• Integration-ish: HTTP handler auth, route validation, and response payloads.

Acceptance Criteria

• Unauthorized scheduler requests are rejected.
• Duplicate scheduler calls return a deterministic duplicate outcome.
• Dry-run mode skips persistence and still returns a structured payload.
• Logs include jobId, dedupeKey, and outcome.