guardlink: Cursor rule for Windsurf

GuardLink Security Annotations

This project carries a GuardLink threat model.

Where annotations go

Annotation mode: inline. Annotations live in source-file comments, in the comment syntax of the file you are editing — the doc-block of the function or module they describe.

/**
 * @exposes #api to #sqli [critical] cwe:CWE-89 -- "email concatenated into SQL"
 * @mitigates #api against #sqli using #prepared-stmts -- "parameterized via pg"
 */
export function login(email: string) { … }

Do not create .gal sidecars under .guardlink/annotations/ in this mode; a repo with both is a mixed repo, and that is the failure this section exists to prevent.

Core Requirement

Every time you write or modify code that touches security-relevant behavior, you MUST add GuardLink annotations in the same change. This includes: new endpoints, auth logic, data validation, database queries, file I/O, external API calls, crypto, process spawning, user input handling, config parsing. Do NOT annotate code that never touches a security boundary — formatters, UI components, pure helpers. Business logic that makes an authorization or ownership decision IS in scope: an IDOR or a missing tenant check lives in business logic.

Key Rules

• ANNOTATE NEW CODE. When you add a function or endpoint that handles user input, accesses data, or crosses a trust boundary — add @exposes, @mitigates, @flows, @handles, or at minimum @comment. This is not optional.
• NEVER write @accepts — that is a human-only governance decision. For risks with no mitigation: write @exposes + @audit + @comment suggesting potential controls.
• NEVER write @entitles either — propose it with guardlink entitle --propose and a human's acceptance writes it, under their name. It claims a privilege is supposed to have this effect, so an over-grant closes a real escalation as by-design. Cite the authz code as file:line or the claim is inert. Never propose one for an ownership question (IDOR, tenant isolation).
• Use @confirmed for verified exploits. When pentest/scanning/manual reproduction proves a threat is exploitable: @confirmed #threat on Asset [severity] -- "evidence". Distinct from @exposes (theoretical) — @confirmed means real, verified, no false positives. Without evidence in hand, @exposes stands and you do not promote it — reading the code is not reproduction. To get evidence: bugb intake "<brief>" builds a plan an operator approves, never you.
• Preserve existing annotations — do not delete or mangle them.
• Definitions (@asset, @threat, @control with (#id)) live in .guardlink/definitions.ts. Reuse IDs — never redefine. Add new definitions there first, then reference in source files.
• Source files use relationship verbs: @mitigates, @exposes, @confirmed, @flows, @handles, @boundary, @comment, @validates, @audit, @owns, @assumes, @transfers, @feature. (@actor is a definition — it lives with @asset/@threat/@control. @entitles is proposed, not written.)
• Triggers for the four verbs everyone forgets: wrote a test that pins a control → @validates #control for Asset. Code trusts a caller/library/platform to hold a property it never checks → @assumes Asset -- "what must hold". A threat becomes a vendor's or another team's responsibility → @transfers #threat from Source to Target (both ends must be declared assets; a vendor needs an External.* asset first). You know the accountable team → @owns team-id for Asset (bare token — no quotes, no #).
• Write coupled annotation blocks: risk + control (or audit) + data flow + context note — plus @boundary when that flow crosses a trust change, and @handles when the asset touches classified data.
• Avoid @shield unless a human explicitly asks to hide code from AI.