Design note: signed single-use action links (/act)¶
- Issue: #38 (Human-led, security, M3). Threats T13, T14, T16 (and T15 with #41) in docs/security.md; asset A3; story updates in §10.
- Status: Accepted: the maintainer accepted all ten recommendations (PR #115). Implemented on the same branch; schemas decision 54 records the result and what the implementation decided beyond this note.
- Sources: PLAN §3.5 (
/act/<signed-token>, single use, 24 h, key from env), §4 (plugin-ntfy"Done" / "Snooze" buttons,obsidian://deep links), §7 (only/act/outside SSO), §9 ("a stolen/acttoken"); ADR 0002 and its #17 amendment; schemas decisions 25, 30, 34 (apply, journal, compare-and-swap), 43 H (secret length);src/horae/contracts/intents.py(TaskUpdateStatus),src/horae/secrets/, thetaskstable (migration 2). Depends on #37 (FastAPI app); the SSO exemption test is #41's.
Goal and non-goals¶
A tap on a notification button (or a link in the daily note) changes one task in one
predefined way, once, within 24 h, without SSO. The token is the only credential, so it must be
unforgeable, bound, single use, short-lived and unreadable as a capability anywhere but /act.
Acceptance criteria: (AC1) a token works once, reuse and expiry are refused; (AC2) no secrets and no
free-form URLs in tokens; (AC3) rate limiting; (AC4, T14) GET consumes nothing, POST applies;
(AC5, T16) dedicated key, rotation invalidates every outstanding token.
Non-goals: minting links inside LLM text (the action guard stays as is); undo of task changes (not journalled as undoable, decision 34 D7); the ntfy plugin and its iOS behaviour (#72, #65); Traefik configuration (#41).
A. What a link can do¶
The token carries an action kind from a closed set, never an intent document:
| Kind | Applies | Bound to |
|---|---|---|
task.done |
task.update_status {status: done} |
fingerprint, expected state |
task.snooze |
task.update_status {status: snoozed, until} |
fingerprint, expected state, a duration from a closed set |
until is computed by the core at POST time from the duration (question 6). Adding a kind is a
code change in the core, like adding an intent (ADR 0002). notify.push, http.post and note.*
can never be reached through /act.
Minting. Only the core holds the key. A notifier never builds a URL: the notify.push contract
gains an optional actions list (at most 3, ntfy's limit) of {label, kind, task, duration?}; the
core checks task like any task target (decision 30: a fingerprint the run collected), mints the
URLs at apply time and passes them to the notifier with the call. This is a schema change
(schemas/ is sensitive, question 2). Daily-note links reuse the same minting from the
daily-brief renderer, in a follow-up (question 3).
B. Token format¶
Recommendation: a fixed binary layout, HMAC-SHA256, base64url without padding, one segment.
token = b64url( payload || tag )
payload = ver(1) kid(4) kind(1) exp(8, unix s, big-endian) nonce(16)
state(8) dur(1) fp_len(1) fingerprint(1..128, decision 3 alphabet)
tag = HMAC-SHA256(key, "horae-act/v1\0" || payload) (32 bytes, not truncated)
- At most 168 + 32 = 200 bytes, at most 267 characters. The route accepts
^[A-Za-z0-9_-]{98,267}$and nothing else; the decoder is strict (re-encoding must give the same string, so one token has one spelling), checks lengths,ver, a knownkindand the fingerprint alphabet after the tag is verified withhmac.compare_digest. stateis the first 8 bytes of SHA-256 over the task's current(status, due, snoozed_until)at mint time: the compare-and-swap value (section F).duris 0 fortask.done.- No secrets, no URLs, no titles: only a kind, a fingerprint, numbers and random bytes (AC2).
The base URL comes from trusted configuration (
http.public_urlinhorae.yaml), never from the token or the request (Host/X-Forwarded-Hostare ignored). - The payload is signed, not encrypted: whoever sees the link can decode the fingerprint
(e.g.
github:issue:123). Question 4 weighs a server-side row instead.
Alternatives: canonical JSON + .-separated MAC (readable, but a second parser and canonicalisation
rules); JWT/PASETO (algorithm agility and libraries we do not need); an opaque random id with
everything in a store row (smallest exposure, but a write per minted button and a lookup before
the MAC can reject garbage).
C. The key¶
- A dedicated secret,
HORAE_ACT_KEY, resolved bySecretResolver(so it is redacted everywhere, decision 25 / #53), never shared with another use. At least 32 bytes (256 bits); shorter is refused at startup and ahorae doctorerror; docs sayopenssl rand -base64 48. Missing key:/actanswers 503, the core mints no actions and the notification is sent without buttons (logged once). - Key id
kid = HMAC-SHA256(key, "horae-act/kid")[:4]: derived, no configuration, changes with the key, reveals nothing about it. It lets a token minted under another key be refused before anything else. - Rotation invalidates every outstanding token, no grace window (AC5). One key is loaded;
a token whose
kiddiffers is refused. Since a token lives at most 24 h, a grace window (HORAE_ACT_KEY_PREVIOUS) buys little and contradicts the criterion; rotating after a suspected leak must kill all links at once. The consumed-nonce rows of the old key are kept until they expire (harmless).
D. Single use and replay¶
New table (migration 8):
CREATE TABLE act_consumed (
nonce BLOB PRIMARY KEY CHECK (length(nonce) = 16),
kid BLOB NOT NULL,
expires_at INTEGER NOT NULL, -- the token's exp
consumed_at TEXT NOT NULL,
run_id TEXT REFERENCES runs (id) ON DELETE SET NULL,
outcome TEXT NOT NULL -- applied | stale | failed
) STRICT;
- Consume first, in the transaction that journals the change.
POST: verify the token, take the apply lock (decision 34 D6, waiting at most a few seconds, else 503 and the token stays usable), then oneBEGIN IMMEDIATEthat inserts the nonce (a primary-key conflict means "already used") and appends the journal entry; commit; thenSink.apply; then mark the outcome. A crash after the commit leaves the token used and the change journalled as not applied: at most once, never twice. A sink failure or a stale target also leaves it used (single use means a single attempt); the page says so. - Each
POSTis a small run of the reserved pipeline_act(pipeline names never start with_), so the change has a run id, a record and a journal like any other. - Cleanup: rows with
expires_at < now - 1 hare deleted opportunistically on eachPOST(one boundedDELETE) and byprune_runs. Dropping them is safe because expiry already refuses those tokens; the extra hour covers a backward clock step.
E. Expiry and clocks¶
exp = mint time + 24 h, refused when now >= exp. Minting and checking run on the same host and
clock, so there is no skew leeway. A token whose exp is more than 24 h + 5 min in the future
is refused too (guards a clock that jumped forward at mint, or a bug). The nonce row outliving the
token by an hour (section D) covers small backward steps.
F. Binding to ADR 0002 and compare-and-swap¶
POST never trusts the token for more than which task and which kind: the core builds the
task.update_status intent itself, plans it through the normal path (permission of the sink that
owns the task, decision 30 routing, journal) and applies it with the sink's compare-and-swap.
Before that it recomputes state from the current task row: a different value (task already done,
snoozed again, due date moved, task gone) is refused as stale, nothing is applied, and the
page says "this task changed since the notification". Binding the whole state, not just
status, means a button can never act on a task the user has edited in the meantime. Repeated
re-collection that leaves those three fields unchanged does not make the link stale.
G. GET shows, POST applies¶
GET /act/<token>: rate limit, verify (format, tag, kid, expiry, not yet consumed, read only), then render a confirmation page with one<form method="post">button. It writes nothing (no nonce, no run, no log line with the token), so link previews, prefetchers and security scanners leave the token usable (AC4).POST /act/<token>: the same checks, then section D. A notificationhttpaction button posts directly (one tap); aviewlink or a daily-note link opens the page first (question 1).- CSRF: the token in the path is the credential and is unguessable, so a cross-site form cannot
post without already holding it. In addition: if
Originis present it must equalhttp.public_url's origin, andSec-Fetch-Site, if present, must besame-originornone(the ntfy app's native client sends neither). No cookies are set or read, so there is no session to ride. - Headers on every
/actresponse:Content-Security-Policy: default-src 'none'; style-src 'sha256-<inline>'; form-action 'self'; frame-ancestors 'none'; base-uri 'none',Cache-Control: no-store,Referrer-Policy: no-referrer,X-Content-Type-Options: nosniff,X-Robots-Tag: noindex. No JavaScript, no external fonts, images or styles, no Open Graph tags (so previews show nothing useful).
What the page shows: the action ("Mark as done", "Snooze until tomorrow 09:00") and the task
title from the tasks table, escaped and cut to 120 characters, plus the due date if any. It
never shows note content, the fingerprint, the target path or anything else from the vault.
Anyone holding a valid token (including a previewer) sees that title; that is the price of the
user being able to check what they confirm (question 5).
H. Rate limiting¶
In process, before any decoding or store access, for GET and POST: a token bucket per client
IP (10 requests/min, burst 5) and a global one (60/min), both answered 429 with
Retry-After. A request with an invalid token costs 3. The per-IP table is an LRU of at most 4096
entries. The client IP is the peer address, or the last X-Forwarded-For hop only when the peer
is a configured trusted proxy (Traefik); otherwise the header is ignored. Assumes one worker
process (the reference deployment); several workers would each have their own buckets, documented.
I. SSO exemption¶
Only the /act/ prefix is outside SSO (#41 tests the rendered Traefik template). In the app, the
/act router depends on no SSO header and reads none (no X-Forwarded-User trust); the router
matches exactly /act/{token} with the pattern above, so %2F, .. or a trailing path cannot
reach /runs or /healthz through the exempt prefix (tested in the app as well).
J. Logging and redaction¶
- The token never reaches a log, the run record or an error: uvicorn's access log is replaced, for
/act, by one lineact <kind> <ref> <outcome>whererefis the first 8 hex digits of SHA-256(nonce), only for tokens whose tag verified (an unverified string is logged asinvalidwith its length). - The run record of
_actkeeps the intent and theref, not the token. - The operator guide (#41) tells the operator to turn off Traefik access logs for the
/actrouter or drop its path, since Traefik logs paths before Horae sees them.
K. Failure responses¶
Every pre-authorisation failure (bad format, bad tag, unknown kid, expired, already used, unknown
task) gives the same page with the same status (404, "This link is not valid any more"),
after the same work (the tag is always computed over a fixed-size buffer), so the response does not
say which check failed. Distinct answers only where they leak nothing about the token: 429 (rate
limit), 503 (no key, apply lock busy). After a successful POST consume, the holder of a valid
token gets the real outcome: applied, stale (changed since) or failed.
Test plan (one test file per concern, tests/test_act_*.py)¶
| Criterion | Tests |
|---|---|
| AC1 single use, expiry | test_a_token_applies_once_and_is_refused_after, test_two_concurrent_posts_apply_once (two threads, one apply), test_an_expired_token_is_refused, test_a_token_expiring_too_far_ahead_is_refused, test_a_crash_after_consume_never_applies_twice, test_cleanup_keeps_unexpired_nonces |
| AC2 no secrets or URLs | test_a_token_decodes_to_kind_fingerprint_numbers_only (property test over minted tokens: no key bytes, no ://, length ≤ 267), test_the_base_url_comes_from_config_not_the_host_header |
| AC3 rate limit | test_per_ip_limit_returns_429, test_global_limit_returns_429, test_forwarded_for_is_ignored_from_an_untrusted_peer, test_invalid_tokens_cost_more |
| AC4 GET / POST | test_a_get_leaves_the_token_usable (GET twice, then POST applies), test_get_writes_nothing_to_the_store, test_a_cross_origin_post_is_refused, test_the_page_has_no_script_or_external_asset_and_strict_csp |
| AC5 key | test_rotating_the_key_refuses_every_outstanding_token, test_a_short_or_missing_key_disables_act, test_a_forged_or_tampered_token_is_refused (every byte flipped) |
| Binding, CAS | test_a_stale_task_is_refused_and_consumes_the_token, test_the_intent_is_built_by_the_core_from_the_kind, test_a_link_cannot_reach_another_intent_type |
| Failures, logs | test_every_invalid_token_gets_the_same_response, test_the_token_never_appears_in_logs_or_the_store (scan DB + WAL and caplog), test_the_page_shows_the_title_only |
| Routing | test_only_the_exact_act_route_is_served_without_sso (%2F, .., trailing segments) |
Risks¶
- A leaked link (shoulder, screenshot, shared phone) acts once within 24 h: bounded by kind and CAS; the user sees the result in the vault.
- Previewers see the task title (question 5).
- Fingerprints are visible in the link (question 4).
- Multiple workers weaken the in-process rate limit (documented; single worker by default).
Questions for the maintainer¶
- One tap or always confirm? Should a notification
httpaction buttonPOSTdirectly (one tap, the ntfy app sends it), whileviewlinks and daily-note links open the confirmation page? Recommendation: yes; previews neverPOST, and #72 checks the iOS behaviour first. - Contract change. Add
notify.push.actions(at most 3{label, kind, task, duration?}), with the core minting URLs at apply time and the notifier never seeing the key? Recommendation: yes, in this story (one schema change,schemas/reviewed). - Daily-note links. Same minting from the daily-brief renderer in this story, or a follow-up? A link written to a note lives in the vault (and LiveSync) after it has expired. Recommendation: follow-up story; #38 ships notification buttons only.
- Signed payload or server-side row? Keep the stateless signed payload (fingerprint visible in the link), or mint an opaque random id stored with its action (nothing readable, a write per button)? Recommendation: signed payload; fingerprints are identifiers, not secrets, and the issue asks for HMAC-signed tokens. Revisit if a source puts personal data in fingerprints.
- Confirmation page content. Task title (escaped, 120 characters) and due date, nothing else? Recommendation: yes; a generic "mark a task done?" page would make the confirmation useless.
- Snooze durations. A closed set resolved at
POSTtime:1h,3h,tomorrow(09:00 in the instance time zone)? Recommendation: yes, these three. - Consume on failure. A stale target or a sink failure uses the token up (single attempt), but a busy apply lock (503) does not? Recommendation: yes.
- Rotation grace window. None, as the criterion says? Recommendation: none.
- Rate limits. 10/min per IP (burst 5), 60/min global, invalid tokens cost 3? Recommendation: yes, as constants first, configurable later if needed.
- Expected-state binding. Bind
(status, due, snoozed_until), so an edited task makes its link stale, rather thanstatusalone? Recommendation: the three fields.