task: harden the third-party script path for the docs assistant (no SRI, no crossorigin, no CSP)
- Dominant language
- MDX
- Stars
- 90
- Forks
- 382
- Avg merge
- 3d 9h
- Merged PRs (30d)
- 35
Description
Follow-up from the review of #2286. Not a blocker for that PR — the branded host has landed and the loader is scoped — but the hardening gap it identified is still open and now has no home.
## What is true today
`assistant.js` injects a third-party script onto every published page with no integrity or origin controls:
```js
// assistant.js:16-20
var script = document.createElement('script');
script.src = WIDGET_SRC; // https://docs-assistant.celo.org/widget.js
script.dataset.apiUrl = 'https://docs-assistant.celo.org/api/chat';
script.referrerPolicy = 'strict-origin';
```
- No `integrity` attribute and no `crossOrigin` — verified: `grep -c "integrity\|crossOrigin" assistant.js` returns `0`.
- No CSP anywhere in the repo to fall back on — there is no `vercel.json`, no `_headers`, no middleware, and `docs.json` has no `headers` key (verified by loading `docs.json` and checking for the key).
Per AGENTS.md §1, any `.js` under the content root runs on **every** published page with full same-origin DOM access — including the pages that print contract addresses and RPC endpoints.
## Impact
Whoever controls `docs-assistant.celo.org` can execute arbitrary JS on every docs page. That is currently us, which is why this is a follow-up and not a blocker. The residual risk is a compromise or misconfiguration of that host silently becoming a compromise of the docs, with no second control to catch it. A reader copying a contract address has no way to tell.
## Why this is not simply "add SRI"
`widget.js` is first-party and expected to change on its own deploy cadence. An `integrity` hash pins one build, so adding SRI naively breaks the widget on the next widget deploy. Options worth weighing:
- Pin SRI and add a release step that updates the hash in `assistant.js` (couples two repos, but fails closed).
- Add `crossOrigin="anonymous"` now — cheap, no downside, and a prerequisite for SRI later.
- Ask Mintlify whether response headers (CSP with `script-src`) are configurable on the current plan; if so, an allowlist for `docs-assistant.celo.org` is stronger than SRI and does not break on deploy.
## Acceptance criteria
- [ ] Decision recorded on which of the three controls apply, with the reasoning
- [ ] `crossOrigin` set on the injected script unless there is a stated reason not to
- [ ] If SRI is adopted, a documented release step keeps the hash current
- [ ] If CSP is available on the Mintlify plan, `script-src` restricted to the known hosts
- [ ] ANALYTICS.md/AGENTS.md note the control that ended up in place
Refs #2250, #2286.
Contributor guide
Research direction
Start with assistant.js lines 16-20 and inspect docs.json, ANALYTICS.md, and AGENTS.md for the current script and documentation conventions. Confirm which controls Mintlify supports, then record the selected decision and reasoning. Done means the applicable script control is in place and the referenced documentation and release steps are updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, security
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100