Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
2454a6a
feat(data-sharing): schema, capture triggers and delivery queue for o…
9thLevelSoftware Nov 6, 2026
2dc2b4b
fix(data-sharing): prove capture never aborts a write; close completi…
9thLevelSoftware Nov 6, 2026
32ad07e
feat(data-sharing): webhook-endpoints Edge Function with SSRF guard a…
9thLevelSoftware Nov 6, 2026
9f6c1a4
feat(data-sharing): deliver-webhooks worker and payload builder
9thLevelSoftware Nov 6, 2026
0361508
feat(data-sharing): portal settings UI, privacy policy and receiver g…
9thLevelSoftware Nov 6, 2026
361454f
docs(data-sharing): dated addendum pointing the 2026-03 audit at the …
9thLevelSoftware Nov 6, 2026
008c77f
test(data-sharing): build signing-secret fixtures at runtime
9thLevelSoftware Nov 6, 2026
5913b4d
Merge branch 'feat/webhook-endpoints-function' into feat/deliver-webh…
9thLevelSoftware Nov 6, 2026
db3ff97
test(data-sharing): build the worker test's signing secrets at runtime
9thLevelSoftware Nov 6, 2026
0257dd0
Merge branch 'feat/deliver-webhooks-worker' into feat/data-sharing-ui
9thLevelSoftware Nov 6, 2026
5a8787f
test(data-sharing): drop secret-shaped fixtures from the portal tests
9thLevelSoftware Nov 6, 2026
227a3be
fix(data-sharing): close gaps found in review of the schema PR
9thLevelSoftware Nov 6, 2026
69d403f
Merge branch 'feat/webhook-data-sharing-schema' into feat/webhook-end…
9thLevelSoftware Nov 6, 2026
ccd9229
Merge branch 'feat/webhook-endpoints-function' into feat/deliver-webh…
9thLevelSoftware Nov 6, 2026
81fa00f
Merge branch 'feat/deliver-webhooks-worker' into feat/data-sharing-ui
9thLevelSoftware Nov 6, 2026
be4e9cc
Merge remote-tracking branch 'origin/main' into feat/webhook-data-sha…
9thLevelSoftware Nov 6, 2026
5b31015
Merge branch 'feat/webhook-data-sharing-schema' into feat/webhook-end…
9thLevelSoftware Nov 6, 2026
225bedc
fix(data-sharing): act on review of the webhook-endpoints PR
9thLevelSoftware Nov 6, 2026
2d7e672
Merge remote-tracking branch 'origin/main' into feat/webhook-endpoint…
9thLevelSoftware Nov 6, 2026
66f7549
Merge branch 'feat/webhook-endpoints-function' into feat/deliver-webh…
9thLevelSoftware Nov 6, 2026
ca76974
Merge remote-tracking branch 'origin/main' into feat/deliver-webhooks…
9thLevelSoftware Nov 6, 2026
1eef6fc
Merge branch 'feat/deliver-webhooks-worker' into feat/data-sharing-ui
9thLevelSoftware Nov 6, 2026
b0aa56a
Merge remote-tracking branch 'origin/main' into feat/data-sharing-ui
9thLevelSoftware Nov 6, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
206 changes: 206 additions & 0 deletions docs/data-sharing-webhooks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
# Data sharing webhooks

Phoenix Portal can push a user's own training data to an HTTPS endpoint the
user controls. This page is for whoever builds the **receiver**, and for
operators. For the rules the code must keep, see `CLAUDE.md` → "Data sharing
(outbound webhooks)".

- Available on **Flame and above**. Set up in the portal under
**Profile → Settings → Data Sharing**.
- Up to **3 endpoints** per account. Each endpoint chooses which kinds of
data it receives.
- Only the account owner can configure it, and an endpoint only ever receives
its owner's data.

## Requirements for an endpoint

| | |
|---|---|
| Scheme | `https` only, with a certificate a normal client would trust |
| Host | A public DNS name or public IP. Private, loopback, link-local and reserved addresses are refused, when the endpoint is saved and again before every delivery |
| Port | 443, or 1024–65535 |
| Credentials | Not in the URL. Use the signature, or the optional custom header |
| Redirects | Never followed. A `3xx` answer is a failed delivery |
| Timeout | 10 seconds |
| Success | Any `2xx` status. The response body is ignored and never stored |

## The request

Every delivery is a `POST` with a JSON body and these headers:

| Header | Value |
|---|---|
| `content-type` | `application/json` |
| `user-agent` | `PhoenixPortal-Webhooks/1.0` |
| `webhook-id` | The delivery id. **The same on every retry** of that delivery: use it to deduplicate |
| `webhook-timestamp` | Unix seconds when this attempt was signed |
| `webhook-signature` | One or more space-separated `v1,<base64>` signatures |
| *(your custom header)* | Only if you configured one, e.g. `Authorization` |

Body:

```json
{
"type": "workout.updated",
"timestamp": "2026-11-06T12:00:00.000Z",
"data": {
"apiVersion": "2026-11-01",
"endpointId": "…",
"entity": "workout",
"id": "…",
"loadConvention": "per_cable_kg",
"record": { "id": "…", "name": "…", "started_at": "…", "total_volume": 1200 },
"children": {
"exercises": [{ "id": "…", "session_id": "…", "name": "Row", "cable_count": 2 }],
"sets": [{ "id": "…", "exercise_id": "…", "set_number": 1, "weight_kg": 40, "actual_reps": 8 }],
"rep_summaries": [{ "id": "…", "set_id": "…", "rep_number": 1 }]
}
}
}
```

A deletion carries the id and nothing else:

```json
{
"type": "routine.deleted",
"timestamp": "2026-11-06T12:05:00.000Z",
"data": { "apiVersion": "2026-11-01", "endpointId": "…", "entity": "routine", "id": "…" }
}
```

### Loads are per cable

Every weight and volume is **per cable**, exactly as the phone shows it and as
it is stored. Nothing is doubled. `exercises.cable_count` is `1`, `2` or
`null`; `null` means the machine did not report it, so do not assume two.

## Verifying a delivery

Signatures follow the [Standard Webhooks](https://www.standardwebhooks.com)
format, so an existing library will verify them. With the reference Node
library:

```js
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.PHOENIX_SIGNING_SECRET); // "whsec_…"

export async function handler(request) {
const body = await request.text(); // the raw body, before any JSON parsing
let event;
try {
event = webhook.verify(body, {
"webhook-id": request.headers.get("webhook-id"),
"webhook-timestamp": request.headers.get("webhook-timestamp"),
"webhook-signature": request.headers.get("webhook-signature"),
});
} catch {
return new Response("invalid signature", { status: 401 });
}
// event.type, event.data …
return new Response(null, { status: 204 });
}
```

By hand:

1. The signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`.
2. The key is the **base64-decoded** bytes after the `whsec_` prefix (not the
text of the secret).
3. Compute HMAC-SHA256 and base64-encode it. Accept the delivery if it equals
the value after `v1,` in **any** entry of `webhook-signature`, compared in
constant time.
4. Reject a `webhook-timestamp` more than a few minutes from your clock, to
stop replays.

Verify against the raw bytes you received. Re-serialising the JSON first
changes the bytes and the signature will not match.

### The custom header

For receivers that cannot verify a signature (some no-code tools), an endpoint
can carry one extra header, for example `Authorization: Bearer …`. It is sent
on every delivery and stored encrypted. It proves the caller knows the value;
unlike the signature it does not protect the body from being altered, so
prefer the signature where you can.

### Replacing the secret

"Replace secret" creates a new secret and shows it once. For the next
**24 hours** each delivery carries two signatures, new secret first, so a
receiver holding either secret keeps verifying. After that only the new one is
used.

## Events

`<entity>.updated` is sent when an item is created or changed and carries its
current state. `<entity>.deleted` is sent when it is removed. `ping` is the
test delivery from the portal's "Send test" button.

| Scope (chosen per endpoint) | Entity | `record` is a row of | `children` |
|---|---|---|---|
| Workouts | `workout` | `workout_sessions` | `exercises`, `sets`, `rep_summaries` |
| Personal records | `personal_record` | `personal_records` | — |
| Routines | `routine` | `routines` | `routine_exercises` |
| Training cycles | `cycle` | `training_cycles` | `cycle_days` |
| Goals | `goal` | `user_goals` | — |
| Exercise progress | `exercise_progress` | `exercise_progress` | — |
| Achievements | `badge`, `gamification_stats`, `rpg_attributes` | `earned_badges`, `gamification_stats`, `rpg_attributes` | — |
| Imported activities | `external_activity` | `external_activities` (never Strava-sourced rows) | — |
| Profile | `profile`, `local_profile` | `profiles`, `local_profiles` | — |

Field names are the database column names, the same ones the "Download All My
Data" export uses. The account's internal user id is not included.

**Never sent this way:** raw force-curve telemetry, the Inferno biomechanics
tables, activities imported from Strava, community content, billing data, or
anything belonging to another user.

## Delivery behaviour

- **At least once.** A delivery can arrive more than once (a retry after your
`2xx` was lost, or "Resend all"). Deduplicate on `webhook-id`, or simply
upsert by `data.id`.
- **Current state, not a change log.** The payload is built when it is sent.
Several quick edits to one item arrive as one delivery with the final state;
an item edited and then deleted arrives as a deletion.
- **No ordering guarantee** between items. Because each delivery carries the
current state, applying them in any order converges.
- **Timing.** Changes are picked up within about a minute, after a 20-second
settle delay.
- **Retries.** Any answer other than `2xx`, a timeout or a connection failure
is retried after about 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h and 24 h
(nine attempts over roughly two days). `429` and `503` honour `Retry-After`
up to one hour.
- **Switched off automatically.** If a delivery uses up all its attempts, or
the endpoint answers `410 Gone`, the endpoint is switched off and the portal
says why. Switching it back on sends one test delivery first and only
succeeds if that is accepted.
- **Paused with the plan.** If the account drops below Flame the endpoint is
paused and nothing is sent until the plan returns and the owner switches it
back on.
- **Size.** A payload over 1 MB is not sent and is shown as "too large" in the
delivery log.
- **Resend all** queues one delivery for every existing item in the endpoint's
selected data. Use it to load history into a new receiver.

The portal keeps a 30-day delivery log per endpoint: status, attempt count,
HTTP status and a fixed reason code. It never records your endpoint's response
body.

## Security notes for operators

- The only code that fetches a user-chosen URL is
`supabase/functions/_shared/webhookTarget.ts`. Its header documents one
**residual risk that is not closed**: the runtime cannot pin a connection to
the address it validated, so DNS rebinding can still aim a request at an
internal address. It is bounded by https with certificate validation, by the
request carrying no Supabase credential, by redirects not being followed, and
by nothing of the response being kept beyond its status code.
- Signing secrets and custom header values are encrypted with
`OAUTH_TOKEN_ENCRYPTION_KEY` in `webhook_endpoint_secrets`, which no browser
role can read. Rotating that key without re-encrypting makes every endpoint
fail with `internal_error` until its secret is replaced.
- Operating steps (switching deliveries on and off, reading the queue) are in
`docs/runbooks/operations.md` → "Data Sharing Webhooks".
23 changes: 23 additions & 0 deletions docs/edge-functions-security-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,29 @@ try {

---

## Addendum: functions added after this audit

> **Added 2026-11-06. Not part of the 2026-03-28 audit.** The functions below
> did not exist when this report was written and were not reviewed by its
> auditor. This is a pointer to where their security model is stated, not a
> finding.

#### `webhook-endpoints` and `deliver-webhooks` (data sharing)

| Topic | Where it is decided |
| --- | --- |
| Authentication | `webhook-endpoints`: gateway JWT plus `auth.getUser()`; the user id comes only from the token. `deliver-webhooks`: `x-cron-secret` or service-role bearer, stated above its `verify_jwt = false` block in `supabase/config.toml` |
| User isolation | Every query carries the JWT user id (`webhook-endpoints/index.ts`). Payload reads use the claimed delivery's owner id (`_shared/webhookPayload.ts`). A composite foreign key ties each delivery to its endpoint's owner (`20261106120000`) |
| Tier | FLAME in `requireSubscription`, and again in SQL when deliveries are claimed |
| Secrets | Generated server-side, returned once, AES-GCM at rest in a table no browser role can read (`webhook_endpoint_secrets`) |
| Outbound requests (SSRF) | `_shared/webhookTarget.ts` is the only code that fetches a user-chosen URL. **Its header states a residual risk that is not closed:** DNS rebinding, bounded but not eliminated |
| Rate limiting | General key, plus a tighter key for the actions that contact a user-chosen host |

Tests that fail if these break are named in `CLAUDE.md` under "Data sharing
(outbound webhooks)" and in `docs/data-sharing-webhooks.md`.

---

## Recommendations Summary

### High Priority (Address Soon)
Expand Down
83 changes: 83 additions & 0 deletions docs/runbooks/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -1737,6 +1737,89 @@ no reopen path, because auto-reopening would let a records edit un-achieve a
goal.
---

## 15. Data Sharing Webhooks

A Flame+ user's own data is pushed to endpoints they register (Profile >
Settings > Data Sharing). Receiver-facing behaviour is in
[`docs/data-sharing-webhooks.md`](../data-sharing-webhooks.md).

### Switch deliveries on, and the kill switch

The `deliver-webhooks` pg_cron job is **created inactive**. Activate it only
after the `deliver-webhooks` Edge Function is deployed:

```sql
SELECT cron.alter_job(
(SELECT jobid FROM cron.job WHERE jobname = 'deliver-webhooks'),
active := true);
```

Setting `active := false` stops every delivery for every user. Changes keep
being captured (one waiting row per item, so the queue does not grow without
bound) and are sent when the job is switched back on. Nothing is lost by
pausing.

It uses the same Vault secret (`edge_cron_secret`) and Edge secret
(`CRON_SECRET`) as the other cron-invoked functions; there is nothing extra to
set.

### Is it working?

```sql
-- The worker's own responses: 200 = a pass ran; 401 = the Vault secret and
-- CRON_SECRET differ; 404 = the function is not deployed.
SELECT id, status_code, timed_out, error_msg, created
FROM net._http_response ORDER BY created DESC LIMIT 20;

-- Queue depth and what is failing.
SELECT status, last_error_code, count(*)
FROM public.webhook_deliveries
WHERE created_at > now() - interval '24 hours'
GROUP BY 1, 2 ORDER BY 3 DESC;

-- Endpoints that are not active, and why.
SELECT status, disabled_reason, count(*)
FROM public.webhook_endpoints GROUP BY 1, 2;
```

| `last_error_code` | Meaning |
| --- | --- |
| `http_error`, `timeout`, `connection_failed`, `dns_failed`, `redirect_not_followed` | The receiver's side. Retried on the backoff schedule. |
| `target_not_allowed` | The stored URL now resolves to a private or reserved address, or is one of our own hosts. Not sent. |
| `internal_error` | Ours: the endpoint's secret could not be read or decrypted, or a payload read failed. Check `OAUTH_TOKEN_ENCRYPTION_KEY` and the function logs (`[DELIVER_WEBHOOKS]`). |
| `subscription_lapsed` | The owner dropped below Flame; the endpoint was paused. Expected. |
| `superseded`, `scope_removed`, `endpoint_inactive`, `not_shareable` | Closed without sending, by design. |

A row stuck in `delivering` is a worker that died mid-send; it is reclaimed
after its 3-minute lease with no action needed.

### A user reports an endpoint "switched itself off"

`webhook_endpoints.disabled_reason` says why: `too_many_failures` (a delivery
used all nine attempts), `endpoint_gone` (the receiver answered 410), or
`subscription_lapsed`. The user switches it back on in the portal, which sends
one test delivery first. Do not set `status = 'active'` by hand: the table
requires `disabled_reason` to be cleared in the same statement, and skipping
the test delivery hides the fault that switched it off.

### Stop one user's sharing immediately

```sql
UPDATE public.webhook_endpoints
SET status = 'paused', disabled_reason = 'user_paused'
WHERE user_id = '<user id>' AND status = 'active';
```

Account deletion removes endpoints, secrets and the delivery log by cascade.

### What must never be logged or pasted into a ticket

An endpoint's URL path or query (it may itself be a credential), a signing
secret, a custom header value, or a payload. The functions log ids, status
codes and fixed reason codes only.

---

## Related Runbooks

- [Billing Incident Response](billing-incident-response.md) -- manual fixes,
Expand Down
Loading
Loading