docs(security): add SECURITY.md and discoverable disclosure links #192
Labels
No labels
agent:implement
agent:ready
backend
bug
cannot-reproduce
confirmed
desktop
docs
documentation
duplicate
enhancement
feature
frontend
good first issue
help wanted
high-risk
in-review
invalid
mobile
needs-triage
P0-critical
P1-high
P2-medium
P3-low
qa
QA
question
ready
report
responsive
security
security-escalate
smart-contract
solana
tablet
test-pass
ux
wallet-issue
wallet:keplr
wallet:metamask
wallet:station
wallet:walletconnect
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
code/cl8y-bridge-monorepo#192
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
The bridge monorepo has no root
SECURITY.mdand no easy-to-find user disclosure path. CL8Y DEX already ships that surface: root policy, README / docs-index pointers, a structured security-report issue template, and a dApp footer link. Mirror that pattern here so a user who sees a stuck or unexpected transfer, a wrong amount or recipient, a misleading UI state, or a suspected vulnerability can find how to report it without digging through the watchtower threat-model doc.Bundle (do not split):
SECURITY.md— contact, responsible disclosure, response window, in-scope / out-of-scope.docs/README.md, anddocs/security-model.mdmust link it (same job as DEXREADME.md“Security reports” anddocs/security-model.md§ User security contact)..gitlab/and no.forgejo/issue templates today).packages/frontendso retail users do not have to find the git tree.Pattern to follow (different repo, already shipped): cl8y-dex-terraclassic#392 and that repo’s
SECURITY.md. Do not copy GitLab-only URLs. This repo’s tracker is Forgejo (git.cl8y.com/code/cl8y-bridge-monorepo).Current state
SECURITY.md404onmain)README.mdDocumentation tabledocs/README.mdSecurity sectionsecurity-model.mdand Terra gap analysis onlydocs/security-model.mddocs/qa-onboarding.md.gitlab/, no.forgejo/templates;.github/is workflow/reference leftoverLayout.tsxfooter is version / git SHA / theme only. Legal clickwrap (INV-FE-CLICKWRAP-1 / #134) is terms signing, not vulnerability reportingSECURITY.md/ disclosure playbook (DEX hasskills/AGENTS_SECURITY_CONTACT.md)Readers who need this: retail users on
bridge.cl8y.com, researchers, and agents verifying pre-launch disclosure. They currently land on operator-facing threat-model prose or QA onboarding, neither of which is a disclosure policy.Why the new documentation is needed
SECURITY.mdat the repo root. Without it, the file browser and any host “Security” tab have nothing to show.docs/security-model.mdexplains how cancelers stop a badapproveWithdraw. It does not tell a user where to send a report or that they must not paste exploit steps into a public issue.Constraints / guardrails
contact@ceramicliberty.comunless product updates it in-repo. Do not invent a second mailbox, Telegram handle, or Discord. Keep email + template URL in sync acrossSECURITY.md, template, footer constants, and docs.code/cl8y-bridge-monorepowith thesecuritylabel via a template under.forgejo/issue_template/(or.gitea/issue_template/if that is what this Forgejo version reads). Do not revive GitLab template URLs. Do not point the footer at DEX’s GitLabsecurity_reporttemplate.docs/METAMASK_BLOCKAID_EVM.md/ INV-BLK1), general product bugs (normal issues, nosecuritylabel), and operator runbooks (docs/runbook-cancelers.md) — those stay internal.TermsGateor send reporters toterms.cl8y.com. Footer / legal strip only.z-50or eat the first tap on Connect.docs/security-model.mdthreat model. Add a short “User security contact” section + link, same as DEX § User security contact.Relevant files
SECURITY.md(new, repo root)README.mddocs/README.mddocs/security-model.mddocs/qa-onboarding.md.forgejo/issue_template/security_report.yaml(or.md)securitylabel, impact, chain, tx hash, UTC time. Confirm the directory this Forgejo actually renderspackages/frontend/src/components/Layout.tsxpackages/frontend/src/components/(small legal copy helper if needed)packages/frontendunit test next to the footerhref,target="_blank",rel="noopener noreferrer"docs/FRONTEND_BRIDGE_INVARIANTS.mdskills/agent-security-contact.md(new)AGENTS_SECURITY_CONTACT.mdwith Forgejo URLsRecommended direction
SECURITY.mdwith the DEX section set, rewritten for bridge: How to report (Forgejo template first, email second), what to include (tx hash, src/dest chain, token, amount, wallet, screenshots, UTC time, whether funds look stuck or at risk), Responsible disclosure, Response window, Scope table (contracts / operator-canceler / frontend).security. Prompt for reproduction, impact, affected component (EVM, Terra, Solana, frontend, operator). Tell reporters not to paste exploit PoCs.README.mdDocumentation (or a one-line “Security reports: seeSECURITY.md”),docs/README.mdSecurity list,docs/security-model.mdnew section with a table of policy / template / footer.docs/qa-onboarding.mdone subsection so QA does not file user vulns as ordinary UX bugs.Layout.tsx(desktop and any mobile legal strip): “Report suspicious activity” → Forgejo new-issue URL with the security template (orSECURITY.mdonmainif the template URL is not stable for anonymous users).target="_blank"rel="noopener noreferrer". Do not usewindow.location.href. Constants in one module.maketarget that greps the files and runs the footer unit test.Acceptance criteria
SECURITY.mdexists at the repository root onmainafter merge. It names the email, the Forgejo structured-report path, responsible disclosure (no public exploit write-ups before contact), and a 48–72 hour acknowledgement window.README.md, anddocs/README.mdcan reach that file in one click each (relative markdown links, not a hostname buried in prose).docs/security-model.mdhas a user-contact section that points atSECURITY.md; the watchtower model is unchanged.securityand does not use a generic bug template.hrefis the canonical template orSECURITY.mdURL. New tab,noopener noreferrer. Clickwrap / Connect header behavior unchanged (INV-FE-CLICKWRAP-1, INV-FE-WC-MOBILE-1).test -f SECURITY.md, greps for contact email / response window / “Do not”, footer test green.Test plan (functional paths)
SECURITY.mdlisted; file has contact + window + disclosureREADME.mdSecurity reports linkSECURITY.mddocs/README.mdSecurity listsecuritylabel; fields for chain / tx / impactmake devfooter, desktopTermsGate; report link is not inside the gateVerification criteria
test -f SECURITY.mdfrom repo root.grepcontact email,48–72 hours(or the agreed window), and a responsible-disclosure “Do not” inSECURITY.md.README.mdanddocs/README.mdare relative and resolve in the Forgejo blob view.packages/frontend.SECURITY.md;make dev→ footer → new tab is this repo’s report path, not DEX GitLab and notterms.cl8y.com.Out of scope
docs/METAMASK_BLOCKAID_EVM.md).SECURITY.mdverbatim (GitLab URLs and DEX scope table would be wrong).Definition of Ready
Given a public clone of
code/cl8y-bridge-monorepoand the live bridge UI footer,When a user looks for how to report a suspicious transfer, wrong payout, misleading status, or suspected vulnerability,
Then they find root
SECURITY.mdfrom the repo and docs index, a Forgejo security-report template, and a footer link to that path, with the same contact email and response window as the published DEX policy, without a clickwrap or wallet-connect regression.purpose=docs
First-pass model recommendation
Recommendation: grok-high
Rationale: Docs/chrome only and low/medium product risk, but the change is not a single-subsystem three-file edit. It spans root policy, docs index + threat-model cross-links, a new Forgejo issue template (this repo has no GitLab templates), frontend footer constants/tests, and a skill/invariant so URLs stay Forgejo rather than leftover GitLab. Contact and disclosure wording must stay consistent with the already-shipped DEX policy. That fails the Composer “at most three production files / one subsystem” bar. Verification is greps, one footer unit test, and a manual footer click-through — no Kimi, no contract tests.
cl8y-agent-control: queued
implementjobd5392bb5-34a5-453d-ad05-b2b4c6b7ee01(not executed; no Hetzner VM).