# v1.1.4 Handback — Outbound HTTP SDK & Cron Triggers

**Branch:** `feat/v1.1.4-http-cron` (off `main`)
**Commits:** 1 implementation commit (`feat(v1.1.4): outbound HTTP SDK + cron triggers`) + this HANDBACK commit.

> **Note on commit granularity:** the brief suggested split
> `feat(v1.1.4-http)` / `feat(v1.1.4-cron)` commits. The two features are
> interleaved across shared files (`Cargo.toml`, `crates/picloud/src/lib.rs`,
> `crates/manager-core/src/lib.rs`, `version.rs`, `services.rs`), so
> cleanly-*compiling* per-theme commits aren't separable without interactive
> hunk staging (unavailable in this environment). I chose one coherent,
> green commit over shipping broken intermediates. Squash/relabel as you see fit.

---

## Scope coverage

| # | Item | Status |
|---|------|--------|
| 1 | `http::*` SDK surface (get/post/put/patch/delete/head/post_form/request) | **Done** |
| 2 | SSRF deny-list (resolved-IP, DNS-rebinding defense, scheme/port, body caps, UA, timeouts, `PICLOUD_HTTP_ALLOW_PRIVATE`) | **Done** |
| 3 | http authz (`Capability::AppHttpRequest` → `script:write`, script-as-gate, no new Scope) | **Done** |
| 4 | `HttpService` trait + `HttpServiceImpl` + Services wiring | **Done** |
| 5 | Cron migration `0017` (Layout-E extension) | **Done** |
| 6 | Cron scheduler tokio task (catch-up = fire-once) | **Done** |
| 7 | `ctx.event.cron` shape + `TriggerEvent::Cron` | **Done** |
| 8 | Dispatcher routing extension (`… \| Cron`) | **Done** |
| 9 | Dashboard cron trigger UI (minimal) | **Done** |
| 10a | Redact `ModuleSourceError::Backend` at resolver boundary | **Done** |
| 10b | Pin `rhai = "=1.24"` | **Done** |
| 10c | CHANGELOG retroactive v1.1.3 cross-app-trigger security note | **Done** |
| 11 | Version bumps (workspace 1.1.4, SDK 1.5, dashboard 0.10.0) | **Done** |
| 12 | Tests (~50-70) | **Done** — 70 new |

---

## SSRF policy implementation notes

- **reqwest hook.** `crates/manager-core/src/ssrf.rs` defines `SsrfResolver`
  implementing `reqwest::dns::Resolve`, plugged in via
  `ClientBuilder::dns_resolver`. It delegates to the system resolver
  (injectable for tests — see DNS-rebinding test), then filters each `IpAddr`
  through `SsrfPolicy::check`. Because reqwest re-resolves at every connection
  (including each redirect hop), the policy applies post-redirect too.
- **`dns_resolver` is generic over a concrete `R: Resolve`** (stores `Arc<R>`),
  so the resolver is passed as `Arc<SsrfResolver>`, not `Arc<dyn Resolve>`.
- **Literal-IP gap closed.** reqwest only routes *hostnames* through the custom
  resolver — a URL with a literal-IP host (`http://127.0.0.1/`) bypasses it
  entirely. The impl therefore *also* runs `SsrfPolicy::check` on literal-IP
  hosts at URL-parse time (`validate_url`), on every hop. Both paths are tested.
- **IPv4-mapped IPv6 re-check.** `check_v6` calls `Ipv6Addr::to_ipv4_mapped()`;
  if `Some`, it re-runs the v4 deny-list against the embedded address
  (`::ffff:127.0.0.1` → denied as "loopback").
- **Applied before AND after redirects.** Redirects are followed *manually*
  (client built with `redirect(Policy::none())`) so per-request
  `follow_redirects`/`max_redirects` are honored; each hop re-validates
  scheme/port + literal-IP and re-resolves hostnames through the SSRF resolver.
- **Script-visible error format.** `"http: blocked by SSRF policy: <reason>"`
  where `<reason>` is a CIDR category (`loopback`, `private`, `link-local`,
  `carrier-grade-nat`, `multicast`, `reserved`, `unique-local`, `unspecified`).
  **The resolved IP is never included.** The all-addresses-denied case surfaces
  as `Ssrf` (not a generic DNS error) via a marker error the resolver emits and
  the impl detects by walking the reqwest error source chain.

## Cron scheduler implementation notes

- **Catch-up = fire-once.** Matches the brief; no deviation. `next_due` returns a
  single canonical scheduled-at (first slot after `last_fired_at`, or
  `created_at` if never fired); after firing, `last_fired_at = now`, so the next
  tick sees only future slots. **Verified live** against Postgres: an
  every-second (`* * * * * *`) trigger with a 2s tick advanced `last_fired_at`
  ~once per 2s, not once per second.
- **No ExecutionGate contention.** The scheduler only enqueues to the outbox
  (one row per due trigger per tick, in a `FOR UPDATE OF d SKIP LOCKED`
  transaction that also bumps `last_fired_at`). The existing dispatcher acquires
  the gate and delivers it identically to kv/docs/dead_letter — verified live
  (the cron outbox row was consumed, the script executed, the row deleted).
- **Timezone handling.** `chrono-tz`. Invalid IANA names are rejected at the
  admin endpoint with a 422 (`TriggersApiError::Invalid`, message contains
  "timezone"); the repo re-validates defensively before insert.
- **Schema beyond the brief:** none. Followed the brief exactly — `schedule`,
  `timezone DEFAULT 'UTC'`, `last_fired_at`, `idx_cron_triggers_due`. **No**
  stored `next_scheduled_at` column (an exploration agent suggested one; the
  brief computes next-fire in-process, which I followed).

---

## Tests added (70 new)

- **SSRF policy + resolver (`ssrf.rs`, 20):** one per deny CIDR (127/8, 0/8,
  10/8, 172.16/12, 192.168/16, 169.254/16 incl. metadata, 100.64/10, 224/4,
  240/4, ::1, ::, fe80::/10, fc00::/7, ff00::/8); 172.x outside-range allowed;
  public v4/v6 allowed; IPv4-mapped re-check; `allow_private` disables all;
  resolver returns only allowed addrs; all-denied → SSRF marker; **DNS rebinding**
  (mock resolver: public then private — second denied); empty resolution ≠ SSRF.
- **HTTP client (`http_service.rs`, 16):** GET/POST round-trips vs a hand-rolled
  `TcpListener`; body dispatch + default UA; custom UA override; empty body;
  non-2xx no-error; response cap via Content-Length; response cap mid-stream
  (no Content-Length); request body cap pre-send; redirect-to-max-then-throw;
  scheme rejection (file/ftp/gopher); port rejection (22/25/465/587); SSRF
  literal-loopback; SSRF hostname-resolves-to-loopback; timeout; authz
  (anon skips / member forbidden / member-with-role allowed).
- **Bridge integration (`sdk_http.rs`, 15):** real Rhai engine under
  `spawn_blocking` vs a recording fake — status+JSON body, non-JSON string,
  empty→`()`, Map→JSON, String→text, `()`→no body, headers+timeout forwarded,
  unknown opt key throws, timeout>max throws, non-2xx no-throw, network error
  throws `http:`, `post_form` url-encoding, `request` arbitrary method,
  default-UA carries `script_id`, `cx.app_id` forwarded for attribution.
- **Cron scheduler (`cron_scheduler.rs`, 11):** 6-field schedule accept / 5-field
  + malformed reject; IANA tz accept / reject; due/not-due; never-fired uses
  created_at; **catch-up fires exactly once after 5 missed windows**; timezone
  affects fire time; bad schedule/tz → None.
- **Cron admin (`triggers_api.rs`, 6):** create succeeds; invalid schedule;
  unknown timezone; **module target rejected** (v1.1.3 regression); **cross-app
  target rejected** (v1.1.3 regression); member-without-role forbidden.
- **Module redaction (2):** `modules.rs` — backend error redacted from the
  script-visible error (no leak); `module_redaction_logging.rs` — original error
  **is** logged at ERROR level (captured via a global tracing subscriber).

---

## Decisions beyond the brief (every prompt-default deviation, flagged)

1. **Three-arg split `verb(url, body, opts)`** (user-approved during planning).
   Diverges from the brief's documented two-arg `(url, opts)` shape and
   generalizes the escape hatch to `request(method, url, body, opts)`. Resolves
   the brief's internal contradiction (its Slack example `http::post(url, #{text:...})`
   passed a bare body map, which would be an "unknown opt key" under the
   two-arg rule). The `opts` vocabulary is now exactly
   `{headers, timeout_ms, follow_redirects, max_redirects}` — **`body_raw` was
   dropped** (raw strings go through the positional body as a String). The
   Slack example works unchanged (`#{text:...}` is the body).
2. **Cron crate = `cron` (0.12), not `croner`.** The brief allowed either; `cron`
   handles the 6-field-with-seconds format and named weekdays (`MON-FRI`) used in
   the brief's example, and integrates with chrono `Schedule::after`.
3. **Catch-up = fire-once** — matches the brief; called out explicitly as
   requested. No deviation.
4. **`SdkCallCx` gained a `script_id` field.** The brief's default User-Agent is
   `picloud/<v> (script:<script_id>)`, but `SdkCallCx` didn't carry the script
   id. Adding it (sourced from `ExecRequest.script_id` in the engine) is the
   clean home and doubles as the audit-attribution key the brief emphasizes. All
   19 construction sites updated. The dead-letters admin cx uses a fresh sentinel
   id (no script executes there).
5. **SSRF also blocks IPv6 unspecified `::` and IPv4 `0.0.0.0`** with reason
   "unspecified". `0.0.0.0/8` is in the brief's list; `::` is not explicitly but
   is an obvious sibling hole, so I blocked it too (defensible superset).
6. **No reqwest feature additions needed** — `dns_resolver` and `Response::chunk()`
   compile under the existing `default-features = false, features = ["json","rustls-tls"]`.
   No cookie jar (cookies feature is off, so there's no jar to disable). Added
   `url` as an executor-core dep (for `form_urlencoded` in `post_form`).

---

## How to verify locally (§8 attestation — run on this exact HEAD)

All four gates were run on the handback HEAD (the `feat(v1.1.4)` commit, before
this markdown commit):

```
cargo fmt --all -- --check                               → exit 0
cargo clippy --all-targets --all-features -- -D warnings → exit 0
cargo test --workspace                                   → 427 passed, 0 failed
(cd dashboard && npm run check)                          → 0 errors, 0 warnings (369 files)
```

This HANDBACK commit is pure markdown (no gate-relevant files), so the numbers
above hold for the final HEAD.

**Migrations — verified against a real Postgres (dev stack, port 15432):**
- Fresh-DB replay: the `#[sqlx::test]` schema-snapshot test applies all
  migrations on a fresh ephemeral DB and matches the (re-blessed) golden — passes.
- On-top-of-prior-state: booting `picloud` against a dev DB pinned at migration
  `0006` applied `0007…0017` cleanly (`"migrations applied"`); `_sqlx_migrations`
  max is now `17`; `cron_trigger_details` + widened CHECKs present.

**Live smoke performed:**
- Boot logged the `PICLOUD_HTTP_ALLOW_PRIVATE` warning and started the cron
  scheduler + HTTP service without panic.
- Seeded an every-second cron trigger → scheduler set `last_fired_at`, dispatcher
  consumed the outbox row and ran the script (row deleted on success), and
  `last_fired_at` advanced at the tick cadence (fire-once confirmed). Smoke data
  cleaned up afterward.
- HTTP GET / SSRF-block / body-dispatch behaviors are covered by the automated
  integration tests (real `TcpListener` round-trips + loopback/hostname SSRF
  blocks) rather than a manual curl flow, since a live SSRF-block smoke
  conflicts with the `PICLOUD_HTTP_ALLOW_PRIVATE` a local-server smoke requires.

To re-run the schema snapshot:
```
docker compose up -d postgres
DATABASE_URL=postgres://picloud:picloud@127.0.0.1:15432/picloud \
  cargo test -p picloud-manager-core --test schema_snapshot -- --include-ignored
```

---

## ⚠️ Latent issue found: stale schema-snapshot golden

`crates/manager-core/tests/expected_schema.txt` was **significantly stale** — the
committed golden was missing many tables from prior releases
(`abandoned_executions`, `dead_letters`, `dead_letter_trigger_details`,
`docs_*`, etc.). The `schema_snapshot` test is `#[ignore]` (needs a DB), so it
was apparently never re-blessed across v1.1.1–v1.1.3 and silently drifted.

I re-blessed it, so the diff is large (+217 lines) but **only `cron_trigger_details`
+ the two widened CHECK constraints are v1.1.4-new** — the rest is pre-existing
drift correction. The blessed golden now matches a clean replay (verified).
Recommend the reviewer skim the diff to confirm, and consider whether the
`#[ignore]` should be lifted in CI (with a DB service) so the golden can't drift
again.

---

## Latent security findings

None new beyond the (already-known, already-closed-in-v1.1.3) cross-app trigger
gap, which §10c now documents in the CHANGELOG. The SSRF surface is the main
security mechanism in this release; see the SSRF notes above for the
defense-in-depth layering (resolver hook + literal-IP check + per-hop
re-validation + IP-never-leaked errors).

One thing for the reviewer to weigh: the SSRF policy is a hardcoded deny-list
with no per-app allow-list (deferred to v1.2 per the brief). An operator who
needs a script to reach a private service has only the all-or-nothing
`PICLOUD_HTTP_ALLOW_PRIVATE` global escape hatch today.

## Open questions for the reviewer

1. **Three-arg HTTP shape** (decision #1) — confirm you're happy with
   `verb(url, body, opts)` + dropping `body_raw`, vs the brief's documented
   two-arg form. This is the one user-facing API-shape divergence.
2. **Stale schema golden** — OK to land the full re-bless in this PR, or would
   you prefer the drift correction split out?

## Deferred items (per the brief's OUT list — not built)

WebSocket/SSE, streaming responses, HTTP/3, per-app outbound allow/deny lists,
per-app rate limits, mTLS, request signing, cookie jar, cron backfill replay,
cron next-fire preview, cron schedule history, drift compensation,
module-import-over-HTTP, files/pubsub/secrets/email/users/queue.

## Known limitations / rough edges

- The dashboard Triggers tab lists all trigger kinds but only *creates* cron
  triggers (kv/docs creation remains API-only, unchanged from before). No
  next-fire-at preview (deferred to v1.2).
- `post_form` / body field order follows Rhai map iteration order
  (`BTreeMap`-backed, so sorted/deterministic; not insertion order).
- The cron scheduler tick is floored at 1s; sub-second schedules effectively
  fire at the tick cadence (by design — see the fire-once policy).
- The stale REVIEW.md at repo root is the v1.1.3 reviewer's artifact; the
  v1.1.4 reviewer should overwrite it.