Cursor rule

1---
2description:
3globs: **/*.{openapi.yaml}
4alwaysApply: false
5---
6# Standard Headers
7 
8pattern: Accept
9description: Specify the response format accepted by the client.
10when:
11   - request: true
12    - required: false
13   - response: false
14   - methods: ALL
15examples:
16  - 'Accept: application/vnd.guardia.v1+json'
17 
18pattern: Accept-Language
19description: Specify the client's preferred language.
20when:
21   - request: true
22    - required: false
23   - response: false
24   - methods: ALL
25examples:
26  - 'Accept-Language: pt-BR'
27  - 'Accept-Language: es'
28  - 'Accept-Language: en'
29actions:
30  - include:
31    - Use `en` as default value.
32 
33pattern: Content-Language
34description: Specify the response language.
35when:
36  - request: false
37  - response: true
38    - condition: always
39  - methods: ALL
40  - status codes: ALL
41examples:
42  - 'Content-Language: pt-BR'
43  - 'Content-Language: es'
44  - 'Content-Language: en'
45actions:
46  - include:
47    - Use same value requested through the Accept-Language header of the request.
48 
49pattern: Cache-Control
50description: Controls caching behavior for HTTP responses.
51when:
52  - request: false
53  - response: true
54    - required: true
55    - condition: always
56  - methods: POST, PATCH
57  - status codes: 2xx
58examples:
59  - 'Cache-Control: public, max-age=<timestamp>'
60  - 'Cache-Control: private, max-age=<timestamp>'
61  - 'Cache-Control: no-store'
62actions:
63  - include:
64     - Use `no-store` for sensitive data or error response.
65     - Use includes `public` for all success response that not return sentitive data and cache can be shared.
66     - Use includes `private` for all success response that not return sentitive data and cache can not be shared.
67     - Use `max-age=<timestamp>` for all success response that no return sentitive data.
68  - validate:
69     - If using `max-age`, value must be numeric in seconds.
70  - follow:
71     - ./docs/specifications/restful/http-headers.md#cache-control
72     - RFC 9111, Section 5.2 Cache-Control
73 
74pattern: Link
75description: Provides pagination or resource navigation links using HATEOAS.
76when:
77  - request: false
78  - response: true
79    - required: true
80    - condition: when listing or navigating entities
81  - methods: POST, PATCH
82  - status codes: 2xx
83examples:
84  - link:\
85  <https://{tenant_id}.guardia.finance/api/v1/ledgers?page_token={first_page_token}>; rel="first",\
86  <https://{tenant_id}.guardia.finance/api/v1/ledgers?page_token={previous_page_token}>; rel="previous",\
87  <https://{tenant_id}.guardia.finance/api/v1/ledgers?page_token={next_page_token}>; rel="next",\
88  <https://{tenant_id}.guardia.finance/api/v1/ledgers?page_token={last_page_token}>; rel="last"
89 
90actions:
91  - include: Use HATEOAS links when listing or navigating entities.
92  - follow: https://restfulapi.net/hateoas
93 
94pattern: Idempotency-Key
95description: Identifies a request that should not be processed more than once.
96when:
97  - request: true
98    - required: true
99  - response: true
100    - required: true
101    - condition: when success response
102  - methods: POST, PATCH
103  - status codes: 2xx
104examples:
105  - 'Idempotency-Key: 5f47ab1e-7b0a-4bfb-a2a4-623bd242b31c'
106actions:
107  - validate:
108    - Ensure uniqueness for sensitive methods (e.g., POST, PATCH).
109  - follow:
110    - ./docs/specifications/restful/http-headers.md#idempotency-key
111    - ./docs/specifications/idempotency.md#implementação-em-apis
112    - draft-ietf-httpapi-idempotency-key-header-01, Internet Engineering Task Force (IETF), 8 May 2022.
113 
114pattern: Content-Digest
115description: Hash of the payload used to guarantee integrity for idempotent requests.
116when:
117  - request: false
118  - response: true
119    - required: true
120    - condition: when received Idempotency-Key in request
121  - methods: POST, PATCH
122  - status codes: 2xx
123examples:
124  - 'Content-Digest: sha-256=<hash>'
125actions:
126  - validate:
127    - Hash must be a sha-265 valid.
128    - Hash must match the actual request body.
129  - follow:
130    - ./docs/specifications/restful/http-headers.md#idempotency-key
131    - ./docs/specifications/idempotency.md#implementação-em-apis
132    - draft-ietf-httpapi-idempotency-key-header-01, Internet Engineering Task Force (IETF), 8 May 2022.
133 
134pattern: Last-Modified
135description: Indicates the last modification date of a given entity.
136when:
137  - request: false
138  - response: true
139    - required: true
140    - condition: only if received Idempotency-Key in request
141  - methods: POST, PATCH
142  - status codes: 2xx
143examples:
144  - 'Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT'
145actions:
146  - validate:
147    - Must follow  date format.
148  - follow:
149    - ./docs/specifications/restful/http-headers.md#idempotency-key
150    - ./docs/specifications/idempotency.md#implementação-em-apis
151    - draft-ietf-httpapi-idempotency-key-header-01, Internet Engineering Task Force (IETF), 8 May 2022.
152    - RFC 7232, Section 2.2. Last-Modified
153 
154pattern: Retry-After
155description: Informs how long (in seconds) the client should wait before retrying after a 429 error.
156when:
157  - request: false
158  - response: true
159    - required: true
160    - condition: when return 429
161  - methods: ALL
162  - status codes: 429
163examples:
164  - 'Retry-After: <timestamp>'
165actions:
166  - validate:
167    - Must be a positive integer in seconds.
168  - follow:
169    - ./docs/specifications/restful/http-headers.md#retry-after
170 
171# Custom Headers (X-Grd-* by Guardia)
172 
173pattern: X-Grd-Debug
174description: Enables extended debug information in the response payload.
175when:
176  - request: false
177  - response: true
178    - required: true
179    - condition: only if received X-Grd-Debug in request
180  - methods: ALL
181  - status codes: ALL
182examples:
183  - 'X-Grd-Debug: true'
184actions:
185  - validate:
186    - Only accepts "true" or "false" (case-insensitive). Other values trigger a 400 error.
187  - security:
188    - Apply limits — 10 requests per minute, minimum 1-minute interval, 10-minute max duration.
189  - follow:
190    - ./docs/specifications/http-response-payloads.md#em-caso-de-debug
191    - ./docs/specifications/restful/http-headers.md#x-grd-debug
192 
193pattern: X-Grd-Trace-Id
194description: Unique request identifier generated by Guardia infrastructure.
195when:
196  - request: false
197  - response: true
198    - required: true
199    - condition: always
200  - methods: ALL
201  - status codes: ALL
202examples:
203  - 'X-Grd-Trace-Id: <uuid>'
204actions:
205  - validate:
206    - Must be a valid UUIDv7 (RFC 9562).
207  - enforce:
208    - Always include in all responses, including errors.
209  - follow:
210    - ./docs/specifications/restful/http-headers.md#x-grd-trace-id
211 
212pattern: X-Grd-Correlation-Id
213description: Correlates external calls in a distributed trace context.
214when:
215  - request: true
216    - required: false
217  - response: true
218    - required: true
219    - condition: only if received X-Grd-Correlation-Id in request
220  - methods: ALL
221  - status codes: ALL
222examples:
223  - 'X-Grd-Correlation-Id: 018f74a6-e3b2-70cc-bf24-8a4b012f5f3e'
224actions:
225  - enforce: if-present, propagate to logs and events.
226  - validate: If invalid, ignore and generate a new one.
227 
228# Security Considerations
229 
230pattern: header validation
231description: General rules for header validation.
232actions:
233  - sanitize: Headers must never contain PII, secrets, credentials, or sensitive business data.
234  - enforce: Limit maximum header size and total number per request.
235  - isolate: Custom headers prefixed with `X-Grd-*` must be validated in isolation.
236  - follow: RFC 9110 and OWASP secure headers best practices.
237 
238 
239 
240 
241 
242 
243