Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
docs(security): record the first audit, its fixes and the open risks
spacesdrive94b04a9f76fd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1b87f70..8d4fcdf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -26,6 +26,13 @@ Twiligent now supports YouTube and Instagram only. What an instance owner must d### Security+- Connecting Instagram now finishes only for the person who started the sign-in: a consent link made by one Twiligent user and opened by someone else no longer connects that person's account (#148)+- The manual "publish due posts" trigger runs only your own posts, and no longer shows other users' failed posts (#148)+- HEAD requests count against the same rate limit as GET (#148)+- The GitHub Actions publisher removes addresses and tokens from Instagram's error messages before they reach the run log (#148)+- The app and the public site can no longer be framed by other sites, and send nosniff, referrer and permissions policies (#148)+- Every workflow's GitHub token can only read the repository (#148)+- Every GitHub Actions step is pinned to a full commit instead of a movable tag, so a compromised action release cannot reach the deploy secrets (#148)### Documentationdiff --git a/docs/architecture/backend/ROUTES.md b/docs/architecture/backend/ROUTES.mdindex 38c2a61..a9de5de 100644--- a/docs/architecture/backend/ROUTES.md+++ b/docs/architecture/backend/ROUTES.md@@ -38,7 +38,7 @@ Registered on `publicRoutes` in `routes/index.ts`.|---|---|---|---|| GET | `/api/health` | `healthController.getHealth` | Liveness: returns `{ status: 'ok', timestamp }` without touching the database || GET | `/api/health/ready` | `healthController.getReadiness` | Readiness: the Supabase secrets are set and one database read succeeds; returns `{ status: 'ready', databaseMs, timestamp }`, or `503 NOT_CONFIGURED` naming a missing secret, or `500 DATABASE_ERROR` |-| GET | `/api/auth/instagram/callback` | `instagramAuthController.handleInstagramCallback` | OAuth code exchange; always redirects the browser back to the accounts page with `ig_connected=true`, `ig_connected=reconnected` (the account was already connected and its token was renewed) or `ig_error=<reason>`, never a JSON error |+| GET | `/api/auth/instagram/callback` | `instagramAuthController.handleInstagramCallback` | Checks the signed state and redirects the browser to the accounts page with `#ig_code=<code>&ig_state=<state>` for the app to complete, or `?ig_error=<reason>`; never exchanges the code itself and never answers JSON || POST | `/api/auth/email-hook` | `authHookController.sendAuthEmail` (`routes/authHookRoutes.ts`) | Supabase Auth's Send Email hook: sends sign-up, password reset and other auth emails through Resend. Answers `{}` || GET | `/api/webhooks/instagram` | `instagramWebhookController.verifyInstagramWebhook` (`routes/instagramWebhookRoutes.ts`) | Meta's webhook check: answers the bare `hub.challenge` as text when `hub.mode=subscribe` and `hub.verify_token` matches `INSTAGRAM_WEBHOOK_VERIFY_TOKEN`; 403 otherwise, 503 when the token is not set || POST | `/api/webhooks/instagram` | `instagramWebhookController.receiveInstagramWebhook` | Instagram comment notifications and message events (messages and postbacks), signed by Meta. Stores the comments and a follow-up for each message that answers a followers-only reply, answers `{ success: true }`, then sends the matched replies and the follow-ups |@@ -106,6 +106,7 @@ Controllers call `YouTubeAnalyticsService` and `InstagramAnalyticsService`. Chan| Method | Path | File | Purpose ||---|---|---|---|| GET | `/api/auth/instagram/url` | `instagramAuthRoutes.ts`, `instagramAuthController.getInstagramAuthUrl` | Generates Instagram OAuth URL with HMAC-signed state. Returns `{ url }`; 503 when the Instagram app credentials are not set |+| POST | `/api/auth/instagram/complete` | `instagramAuthRoutes.ts`, `instagramAuthController.completeInstagramConnection` | Body `{ code, state }` from the callback. Exchanges the code and connects or renews the account only when the state was started by the caller: `{ success, outcome: "connected" or "reconnected" }`; 400 for an expired or changed state, 403 for a state another user started, 503 when the app credentials are not set. Counts against the quota rule |### Publishing@@ -130,7 +131,7 @@ Controllers call `ScheduledPostService` (`services/scheduledPostService.ts`).| PUT | `/api/scheduled-posts/:id` | `scheduledPostRoutes.ts`, `scheduledPostController.updateScheduledPost` | Edit a pending post (caption, scheduled time, media, etc.); 400 for a post that is not pending || DELETE | `/api/scheduled-posts/:id` | `scheduledPostRoutes.ts`, `scheduledPostController.deleteScheduledPost` | Delete a single post; 400 while it is publishing || DELETE | `/api/scheduled-posts` | `scheduledPostRoutes.ts`, `scheduledPostController.deleteAllScheduledPosts` | Delete all posts except those with `status: 'publishing'`; returns `{ deleted, kept }` |-| GET | `/api/process-scheduled` | `scheduledPostRoutes.ts`, `scheduledPostController.publishDuePosts` | Manual trigger - runs `scheduledPublisher.publishDue()` immediately for every user's due posts (dev/test) |+| GET | `/api/process-scheduled` | `scheduledPostRoutes.ts`, `scheduledPostController.publishDuePosts` | Manual trigger - runs `scheduledPublisher.publishDueForUser()` immediately for the caller's own due and stale posts only; the cron and the GitHub Actions publisher serve everyone || POST | `/api/process-scheduled` | `scheduledPostRoutes.ts`, `scheduledPostController.publishDuePosts` | Same as above |### Overviewdiff --git a/docs/architecture/backend/SERVICES.md b/docs/architecture/backend/SERVICES.mdindex 28f379a..8f00cbb 100644--- a/docs/architecture/backend/SERVICES.md+++ b/docs/architecture/backend/SERVICES.md@@ -97,7 +97,7 @@ Tracked content is YouTube videos only. `TrackedContentService.add` refuses any### Instagram OAuth (`instagramConnectService.ts`, `instagram/instagramOAuth.ts`)-`readInstagramOAuthConfig(env)` in `lib/config.ts` strips a leading byte order mark and whitespace from the app id, secret and URLs, drops a trailing slash from `BACKEND_URL`, and falls back to `http://localhost:8787` and `http://localhost:5173`. `authorizationUrl` throws `NotConfiguredError` (503) without the app credentials, and `buildAuthorizationUrl` signs the state with the app secret (`lib/oauthState.ts`). `connect` exchanges the code (stripping a trailing `#_`), upgrades to a long-lived token when Instagram allows it (otherwise keeps the short-lived token with no expiry), fetches the profile and returns `'already_added'` or `'connected'`. The callback controller turns those into the `ig_error` and `ig_connected` redirects.+`readInstagramOAuthConfig(env)` in `lib/config.ts` strips a leading byte order mark and whitespace from the app id, secret and URLs, drops a trailing slash from `BACKEND_URL`, and falls back to `http://localhost:8787` and `http://localhost:5173`. `authorizationUrl` throws `NotConfiguredError` (503) without the app credentials, and `buildAuthorizationUrl` signs the state with the app secret (`lib/oauthState.ts`). `connect` exchanges the code (stripping a trailing `#_`), upgrades to a long-lived token when Instagram allows it (otherwise keeps the short-lived token with no expiry), fetches the profile and returns `'reconnected'` or `'connected'`. The public callback only checks the state (`userIdFromState`) and hands the code to the app; `completeForUser(userId, code, state)` runs `connect` only when the state was started by that user, and throws `ForbiddenError` (403) otherwise, so a consent link sent by someone else connects nothing.### Auth emails (`authEmailService.ts`, `email/authEmails.ts`, `email/resendApi.ts`)diff --git a/docs/philosophy/SECURITY.md b/docs/philosophy/SECURITY.mdindex 93e3094..29f9252 100644--- a/docs/philosophy/SECURITY.md+++ b/docs/philosophy/SECURITY.md@@ -80,7 +80,8 @@ The Instagram OAuth flow uses a self-verifying HMAC state token to prevent CSRF:1. On OAuth start: state = `base64url(userId:timestamp)` + `.` + `HMAC-SHA256(secret, payload)`2. Nothing is stored server-side; the timestamp inside the signed payload expires the state after 10 minutes-3. On OAuth callback: verify HMAC before accepting the `code` parameter+3. On OAuth callback: verify HMAC, then hand `code` and `state` back to the app in the URL fragment, which never reaches a server or a referrer+4. The signed-in app posts them to `POST /api/auth/instagram/complete`, which connects the account only when the state's user id is the caller's; a consent link made by one person and opened by another connects nothing (security audit F1)If the HMAC check fails, the callback discards the code and redirects the browser back to the accounts page with `ig_error=invalid_state`. An attacker cannot forge a valid state without the `INSTAGRAM_APP_SECRET`.@@ -158,3 +159,7 @@ Risks found by a security review and left open on purpose, each with the reason| Risk | Why it stays | What would remove it ||---|---|---|| No automated secrets rotation | Rotation needs the owner in the Meta, Google and Supabase dashboards | A rotation runbook with a reminder, or provider APIs that rotate in place |+| With Supabase "Confirm email" off, someone could create a password account for another person's address before they sign up (audit L1) | Whether a later code or Google sign-in keeps that password is Supabase Auth behaviour, not visible in this code | The owner turns on email confirmation once the Send Email hook is set up, or turns off open sign-up for a private instance |+| An Instagram account connected by two Twiligent users routes comments to whichever user's rule wins, without checking that token still works (audit L2) | Needs two users who both connected the same account with working tokens | Route only to accounts whose last token check passed, and count send limits per Instagram identity |+| The shared YouTube API quota is counted per request, not per unit (audit L6) | The quota rule caps those routes at 30 per 10 minutes per user | The quota ledger that YouTube publishing adds |+| The daily token refresh has no subrequest budget, one user's due posts can use the shared publisher's run, and a subrequest overrun can open shared circuit breakers (audit L7 to L9) | Each needs many accounts or posts at once on the Free plan | Per-job subrequest budgets and a per-user cap per run, and not counting the Workers subrequest limit as a platform outage |diff --git a/docs/platform-v2/SECURITY_AUDIT.md b/docs/platform-v2/SECURITY_AUDIT.mdnew file mode 100644index 0000000..3b8cdff--- /dev/null+++ b/docs/platform-v2/SECURITY_AUDIT.md@@ -0,0 +1,81 @@+# Security audit++The security assessment for #148: what was run, what it found, what was fixed and what stays open. Every tool named here ran; each result is the tool's actual output. The workflow that keeps this going after v2 is `docs/workflows/SECURITY_REVIEW.md`.++This first audit covers the application as it stood on `main` at commit 7f35357 (2026-11-05), before the MCP server and YouTube publishing were built. Those parts get their own review as they are built and a second full audit before the platform v2 work closes (`IMPLEMENTATION_PLAN.md`, phase 11); this page gains a section for it.++---++## What ran++| Tool | Scope | Result |+|---|---|---|+| Cloudflare `security-audit` skill, full audit mode, quick profile | Worker, app, site, migrations and SQL functions, GitHub Actions, the scheduling script | 2 confirmed findings, 9 leads that need validation, 1 rejected; 25 coverage units (14 covered, 8 candidate, 3 deferred). Ten agents: 2 reconnaissance, 4 hunters, 1 critic, 3 independent verifiers. Source only: the machine has no OS sandbox, so no project code was run and nothing deployed was probed. Output, validated by the skill's own validators: `~/security-audit-skill/twiligent/run-1` (outside the repository) |+| Semgrep 1.174.0 (`p/typescript`, `p/javascript`, `p/secrets`, `p/github-actions`, `p/react`) | Every tracked file | Before fixes: 14 results (13 actions on movable tags, 1 `dangerouslySetInnerHTML`). After fixes: 1 result, the `dangerouslySetInnerHTML`, which is a false positive (see below) |+| `npm audit` | Root lockfile | 20 advisories in all (0 critical, 6 high, 13 moderate, 1 low), almost all in development tools; with `--omit=dev`, 12 (6 high), all reached through the `shadcn` CLI (see Dependencies) |++Coverage areas, each recorded in the audit's coverage ledger: authentication and sessions, access control, API and input validation, injection and deserialization, output encoding and XSS, CSRF, CORS, response headers, SQL functions and row level security, SSRF and path traversal, command injection, scheduling and publish-once logic, secrets and environment variables, rate limiting, dependencies, CI/CD, token handling, the Supabase Auth email hook, the Instagram webhook, cron jobs and the public site.++Deviations from the skill, recorded by the run: reconnaissance used 2 agents instead of 4; each verifier checked a batch of four candidates; the validators ran through a small shim because Windows Node has no `O_NOFOLLOW`; the run's own `REPORT.md` could not be written by the audit agent (its harness blocks report files), so this page is the report.++---++## Confirmed findings++| Id | Severity | Finding | Status |+|---|---|---|---|+| F1 | Medium (likelihood low, impact high) | **Instagram sign-in was not bound to the person who started it.** The public callback connected the account named by the signed state alone, so a consent link made by one Twiligent user and completed by another person connected that person's Instagram account, with publishing, messaging and insights access, to the first user's account. | Fixed: commit "finish Instagram sign-in only for the person who started it". The callback only checks the state and hands the code to the app in the URL fragment; the signed-in app posts it to `POST /api/auth/instagram/complete`, which refuses a state started by anyone else (403) before any call to Instagram. Regression tests: `backend/tests/routes/instagramAuthRoutes.test.ts` ("a consent link made by one person and completed by another connects nothing") |+| F2 | Low (likelihood medium, impact low) | **The manual publish trigger ran every user's due posts.** `GET` and `POST /api/process-scheduled` started the all-user publisher, so any signed-in user could settle other users' posts, spend their attempts, and read their failed post ids and error reasons. | Fixed: commit "limit the manual publish trigger to the caller's posts". The trigger now lists only the caller's due and stale posts; the cron and the GitHub Actions publisher still serve everyone. Regression test: `backend/tests/routes/scheduledPostRoutes.test.ts` ("runs only the caller's own due posts") |++Rejected by the verifiers: "deploy secrets are reachable from any branch". Running a deploy already needs write access to the repository, so no lower-trust person gains anything.++---++## Leads that need validation++Each depends on a fact outside the repository or on running code. None is a confirmed vulnerability; several were mitigated anyway because the fix is cheap.++| Id | Lead | Status |+|---|---|---|+| L1 | With "Confirm email" off, as the self-hosting guide advises, anyone can create a password account for someone else's address, and may keep access after the real owner signs in with a code or Google | Open, owner action. Depends on Supabase Auth's identity linking. Recorded in `docs/philosophy/SECURITY.md` (Known Risks) with the mitigation: turn on email confirmation once the email hook is set up, or turn off open sign-up |+| L2 | Comments on an Instagram account connected by two Twiligent users are routed to whichever user's rule wins, without checking that the account's token still works | Open. Only reachable when two users connected the same Instagram account with valid tokens. Planned: route only to accounts whose last token check passed, and limit sends per Instagram identity |+| L3 | The GitHub Actions publisher printed Instagram's error text unredacted, and the setup guide recommends a public fork whose run logs anyone can read | Fixed: commit "redact Instagram errors in the GitHub Actions publisher log". Errors go through the Worker's `redactSecrets`, the account id is no longer printed, and the guide and the app say what the logs contain |+| L4 | `HEAD /api/process-scheduled` skipped the quota rule because the matcher compared the raw method | Fixed: commit "count HEAD requests against the same rate limit rule as GET"; test in `rateLimit.test.ts` |+| L5 | A user-triggered publisher run under the 30 second request deadline could leave other users' posts claimed and spend their attempts | Mitigated by F2: the trigger now only touches the caller's own posts |+| L6 | The instance's shared YouTube API quota is counted per request, not per unit | Open, accepted for now: the quota rule caps quota-spending routes at 30 per 10 minutes per user. The YouTube publishing work adds a quota ledger per Pacific day (`ARCHITECTURE.md`, section 3) |+| L7 | The daily token refresh retries dead Instagram tokens with no subrequest budget and can starve the 90 day retention purge | Open. Planned: give the refresh its own subrequest budget and skip tokens marked as needing a reconnect |+| L8 | One user's many due posts can use the shared publisher's subrequests and delay others' posts | Open. Planned with the YouTube job runner: a per-user cap per run |+| L9 | One user's subrequest overrun can open the circuit breakers all users share | Open. Planned: do not count the Workers subrequest limit as a platform outage |++---++## Hardening done in the same work++| Change | Why |+|---|---|+| Every GitHub Actions step pinned to a full commit SHA | A movable tag lets whoever controls an action's repository change the code that runs with the deploy secrets (Semgrep `github-actions-mutable-action-tag`, 13 results) |+| `permissions: contents: read` in every workflow | The `GITHUB_TOKEN` a step receives can now only read; no workflow writes to the repository |+| `_headers` for the app and the site on Cloudflare Pages | `X-Frame-Options: DENY` and CSP `frame-ancestors 'none'` stop clickjacking; also `nosniff`, a referrer policy and a permissions policy. The Worker already sent strict headers on API responses |++---++## Not a finding++- `dangerouslySetInnerHTML` in `site/src/components/icons.tsx`: the markup is a constant generated at build time from the Solar icon set by `site/build/genIcons.ts`; no user input reaches it.+- Follow-ups sent after a person answers a followers-only reply are not counted by the hourly reply limits: they use Instagram's Send API inside the person's own 24 hour messaging window, at most one per comment, as `docs/architecture/data-flows/AUTOMATION.md` describes.++---++## Dependencies++- All 12 production advisories (`npm audit --omit=dev`: 6 high, 5 moderate, 1 low, in `body-parser`, `undici`, `systeminformation`, `zod`, `qs`, `fast-uri`, `minimatch`, `deepmerge` and `@shadcn/registry`) come through the `shadcn` package, which `frontend/package.json` lists under `dependencies`. The app only imports its stylesheet (`@import "shadcn/tailwind.css"` in `frontend/src/index.css`), which Vite inlines at build time, so none of the CLI's server-side packages reaches the browser bundle or the Worker. The exposure is to developers who run the shadcn CLI.+- Recommended, not yet applied: move `shadcn` to `devDependencies` at the same version (`npm install -D [email protected] --workspace frontend`), which states that it is build tooling and takes these advisories out of the production audit. The command was blocked by this session's permission checks, so it waits for the owner's approval.+- The development-only advisories (`typescript-eslint`'s `minimatch`, `wrangler`'s `miniflare` and `undici`) affect local tooling only; they are fixed by routine updates of those tools.++---++## Remaining risk++- Every check was source-only. Behaviour that depends on Supabase Auth, Meta or Google (L1, L2) and anything that needs running code was not reproduced.+- The deployed settings (Supabase "Confirm email" and sign-up, Cloudflare and GitHub settings) were not inspected.+- Open leads L1, L2, L6 to L9 are listed in `docs/philosophy/SECURITY.md` (Known Risks) with what would remove them.diff --git a/docs/workflows/TESTING.md b/docs/workflows/TESTING.mdindex 3368eb0..3848936 100644--- a/docs/workflows/TESTING.md+++ b/docs/workflows/TESTING.md@@ -336,7 +336,7 @@ After any change to `scripts/publish-scheduled.ts`, `backend/lib/scheduledPublis2. Watch the run output3. Verify: "No posts due for publishing" (if no scheduled posts) or successful publish-If you have a test post scheduled in the near future, use `GET /api/process-scheduled` to run the Worker's publisher (`scheduledPublisher.publishDue()`) manually.+If you have a test post scheduled in the near future, use `GET /api/process-scheduled` to run the Worker's publisher for your own due posts (`scheduledPublisher.publishDueForUser()`) manually.## Future Test Infrastructure