# Authorization and Data-Minimization Patterns

Use this reference only when the contract under review involves per-object access control, role-scoped fields, or a suspected Broken Object Level Authorization (BOLA) / Excessive Data Exposure concern (OWASP API Security Top 10, API1:2023 and API3:2023).

## What people get wrong

The common bad assumption is:

> "The client only asks for the objects it owns, so we don't need to check ownership server-side."

That is backwards. A client-supplied identifier — a URL path parameter, a query string, a request body field, or even a claim embedded in a bearer token that the caller can request to include — describes what the caller is *asking for*, not what the caller is *entitled to*. If the server returns whatever object matches the requested ID without independently checking it against the authenticated session, any caller can enumerate IDs and read (or in a mutating endpoint, write) other users' data. This is OWASP's #1 API risk category for a reason: it is the single most common real-world API vulnerability, and it is invisible in a UI walkthrough because the legitimate user's own ID always "just works."

A second bad assumption:

> "We'll just return the full object; the frontend only renders the fields it needs."

Returning the full object regardless of caller scope is Excessive Data Exposure. It shifts the trust boundary from the server (correct) to the client (wrong) — a browser DevTools Network tab, a proxy, or a modified client can see every field the server sent, whether or not the UI renders it. Internal fields (cost basis, internal flags, other users' identifiers embedded in nested objects, soft-deleted records) leak this way constantly.

## Non-negotiable design rules

### 1. Authorization is re-derived, not trusted

The server must independently determine "does the authenticated session have access to this object?" using the session's own identity (user ID, tenant ID, role claims from a verified token) — never by trusting that the requested ID implies ownership. Concretely: `SELECT * FROM orders WHERE id = :id AND account_id = :sessionAccountId`, not `SELECT * FROM orders WHERE id = :id` followed by returning the result unconditionally.

If the authorization check is a client-side redirect, a hidden form field, or a UI-only role gate with no matching server-side re-check, the finding is BOLA regardless of how the client behaves in the happy path.

### 2. Every field has a stated scope justification

Walk the response shape field by field. For each field, the reviewer (or the code's authorization logic) must be able to state: "this field is visible to caller scope X because Y." A field with no stated justification — "we just always send it" — is a data-minimization defect. This applies recursively to nested objects and arrays: a `user` object embedded inside an `order` response can leak another user's email or phone number even if the top-level `order` fields are all justified.

### 3. Scope-derived shape, not scope-derived filtering-after-the-fact

Prefer response shapes that are constructed per-scope (a query/serializer that only selects authorized fields for the caller's role) over constructing the full object and filtering fields out afterward in application code. Post-hoc filtering is fragile — a new field added to the full object later is exposed by default unless every filter call site is updated. Scope-derived construction fails closed; post-hoc filtering fails open.

### 4. List/collection endpoints get the same scrutiny as single-object endpoints

BOLA and data-minimization findings are not limited to `/resource/:id` endpoints. A `/resources?filter=...` list endpoint that does not scope the underlying query to the caller's authorized set — relying instead on the client to only ever request filters it "should" use — has the same defect, at higher blast radius (one request enumerates many objects instead of one).

### 5. Role/tier changes must invalidate cached authorization decisions

If authorization or field-visibility decisions are cached (a memoized permission check, a cached JWT-derived scope, a client-side cache key that doesn't include role), a role downgrade or tenant/session change must not leave stale broader access in effect. When reviewing a query-key or cache-key design for this kind of endpoint, confirm the key includes whatever identity/role dimension the response depends on — see the Context7-grounded query-key note in `SKILL.md`.

## Minimal safe review flow

1. Get the actual response shape (from code, not from a client-facing types file that may drift from what the server actually returns).
2. For each field, ask: which caller scope needs this, and where is that justified?
3. Find the authorization check in the route handler or its middleware. Confirm it reads the session's own identity, not a client-supplied value, to decide access.
4. Confirm the check runs before data is fetched/returned, not after (an after-the-fact check that still leaks partial data in an error path is still a finding).
5. For list/collection endpoints, confirm the underlying query itself is scoped, not just the individual-object path.
6. If a permission/role decision is cached, confirm the cache key includes the role/session dimension.

## Adversarial checklist

Before approving, answer these:

- If I change only the ID in the request (keeping the same session/token), do I get another caller's data? If untested and unverifiable from code alone, say so explicitly rather than assuming "probably fine."
- Is there any field in the response that exists only because "the ORM/serializer returns it by default"?
- Does a nested/embedded object carry fields belonging to a *different* principal than the top-level resource's owner?
- Is the authorization check duplicated per route, or centralized in a way that a new route can accidentally skip?
- Does a list endpoint's filter/query parameter influence which authorization scope is applied, instead of the scope being derived purely from the session?

If any answer is "unknown," the review's output must surface that as an open question, not an implicit pass.

## When to push back

Push back if the user says:

- "the frontend already filters it, so the API response doesn't matter"
- "nobody would guess another user's ID" (security by obscurity is not a mitigation)
- "we'll add the server-side check later, ship the endpoint now"
- "it's an internal-only field, the response just happens to include it"

Those are not acceptable trade-offs for a shipped contract. They are the two most common root causes (API1/API3) in the OWASP API Security Top 10.

# Error Shape, CORS, and Versioning

Use this reference only when reviewing error-handling code, CORS configuration, or a breaking/backward-compatible contract change with existing consumers.

## What people get wrong

> "Forwarding the upstream error makes debugging easier for us and for API consumers."

That reasoning optimizes for the wrong audience. A stack trace, an internal hostname, a database driver error message, or a raw vendor error payload (e.g., an unmodified error body from a third-party payment processor) is useful to the team operating the service — via server-side logs and traces — and actively harmful when returned to the client. It discloses internal topology, library versions, and sometimes query fragments or schema details to anyone who can call the endpoint, authenticated or not. Debuggability belongs in observability tooling, not in the HTTP response body.

> "CORS is just a browser annoyance; a wildcard origin gets people unblocked faster."

CORS is an authorization control at the browser layer, and it is meaningfully different from server-side authorization: a wildcard `Access-Control-Allow-Origin: *` says "any origin's script may read this response in the caller's browser." Combined with `Access-Control-Allow-Credentials: true` (cookies, HTTP auth, or client TLS certs sent automatically), this combination is invalid per the Fetch/CORS spec — browsers that implement the spec correctly reject wildcard-origin-plus-credentials at the browser level — and where a misconfigured server pairs a *reflected* origin (echoing back whatever `Origin` header the request sent, which is not a literal `*` but has the same effect) with credentials enabled, it functionally defeats the same-origin protections credentialed requests depend on.

## Officially grounded shape (MDN CORS)

- `Access-Control-Allow-Origin` must be a specific origin (or `null`) when the response is to be used with credentialed requests; the literal value `*` cannot be combined with `Access-Control-Allow-Credentials: true` per spec.
- A server that wants to support credentialed requests from multiple known origins must validate the incoming `Origin` header against an explicit allowlist and echo back only that validated value — not blindly reflect any `Origin` header received.
- Preflight (`OPTIONS`) responses must correctly declare `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers` for the actual methods/headers the real request will use; an overly broad preflight response (allowing methods/headers never actually used) is a smaller but related over-permissioning smell worth flagging alongside a wildcard-origin finding.

## Non-negotiable design rules

### 1. Error responses are shaped at the boundary, not passed through

Every upstream/backend error must be caught and mapped to a client-facing shape (a stable error code, a safe human-readable message, no internal detail) before it reaches the client. This mapping should happen at a consistent boundary (a shared error handler / middleware), not ad hoc per route, so a new route can't accidentally skip it.

### 2. CORS is an explicit allowlist wherever credentials are involved

If the endpoint accepts cookies, HTTP auth, or client certificates (`Access-Control-Allow-Credentials: true`, or the client sets `credentials: 'include'`), the allowed-origin policy must be an explicit, reviewed allowlist — validated against the `Origin` header, not a wildcard and not an unvalidated reflection of whatever origin asked.

### 3. Breaking changes require an identified consumer list and a stated migration path

A contract change is breaking if it removes a field, renames a field, narrows a previously-accepted input shape, changes the meaning of an existing status code, or changes the error response shape in a way an existing consumer's error-handling logic depends on. Before approving a breaking change:

- Identify existing consumers (search the codebase; ask the requester about out-of-repo/cross-team consumers if the contract is public).
- Require a stated plan: an additive-only change (preferred — add a new field/route instead of changing the old one), a versioned route (`/v2/...`), or a dual-write/deprecation window with a communicated sunset date.
- "Nothing should be calling this yet" is only acceptable when the reviewer has evidence (a search result, a service registry entry, an explicit statement from the requester with context) — not assumed by default.

### 4. Additive changes still get a data-minimization pass

A new field added to an existing response is not automatically safe just because it's additive — it still needs the same field-justification check as a net-new endpoint (see `authorization-and-data-minimization.md`).

## Minimal safe review flow

1. Find every place the route handler / BFF catches an error from an upstream call, a database, or an SDK.
2. Confirm each catch site maps to a sanitized client-facing error shape — check for accidental pass-through (`res.status(500).json(err)` or equivalent is a common accidental-leak pattern).
3. Find the CORS configuration for the route. Confirm it's an explicit allowlist if credentials are enabled; flag a wildcard-plus-credentials combination as blocking.
4. For a contract change, diff the old and new response/request shape field by field and status-code by status-code.
5. Search for existing consumers of any field/status-code/error-shape being removed or changed in a breaking way.
6. If consumers exist and the change is breaking, require the stated migration plan before approval.

## Safe command/code verification targets

- Grep the route handler and its shared error-handling middleware for direct pass-through of caught error objects into the response body.
- Grep the CORS configuration (framework middleware config, reverse-proxy config, or manual header-setting code) for a literal `*` origin alongside `credentials: true` / `Access-Control-Allow-Credentials: true`.
- Search the codebase for callers of the changed endpoint/field/status-code (import references, fetch/query-key usage, generated API client usage) to build the consumer list.

## When to push back

Push back if the user says:

- "just forward the error, it's faster to debug that way" — redirect them to server-side logging/tracing instead.
- "CORS is blocking my testing, just set it to `*`" for anything that also sets credentials — a scoped allowlist (including `localhost` explicitly for local dev) is the correct fix, not a wildcard shipped to production.
- "nothing should be calling the old shape" without having checked — require the search first.
- "we'll tell people about the breaking change after we ship it" — the deprecation window has to exist before the breaking change ships, not after.

# Contract Review Workflow and Verdict Contract

Use this reference for the step-by-step review procedure and the required output shape for every API integration contract review. Load the other two references only when the specific concern (authorization/data-minimization, or error-shape/CORS/versioning) is actually in scope for the endpoint under review.

## Workflow

1. **Identify the contract surface.** Is this a direct frontend-to-backend call, or a BFF route handler aggregating/proxying one or more upstream calls? Note every upstream system the response depends on.
2. **List every field in the response.** For each field, state which caller role(s)/scope(s) need it and why. Any field without a stated justification is a data-minimization finding.
3. **Trace the authorization path.** Find where the object/resource being requested is checked against the authenticated session. Confirm this check happens server-side, using the session's own identity — not merely by trusting a client-supplied ID as proof of ownership.
4. **Inspect error handling.** Find where upstream/backend errors are caught and confirm they are mapped to a sanitized client-facing shape before being returned, not forwarded as-is.
5. **Check CORS configuration.** Confirm the allowed-origin policy is an explicit allowlist (not a wildcard) whenever `Access-Control-Allow-Credentials: true` is set, and confirm the policy matches the actual trust boundary (not a blanket allowance for convenience during development left in place).
6. **For contract changes, identify existing consumers.** Search the codebase (and ask the user for out-of-repo consumers if the contract is public/cross-team) for callers of the changed field/status-code/error-shape. If any exist and the change is breaking, require a stated deprecation window (dual-write, versioned route, or additive-only change) before approval.
7. **Verify version-sensitive framework claims via Context7** (see `SKILL.md`'s Context7 Documentation Protocol) before relying on any claim about caching defaults, route-handler behavior, or query-key serialization.
8. **Issue a verdict** using the decision tree below.

## Decision tree

- Any response field lacks a stated authorization justification → **block** (excessive data exposure).
- Object-level authorization is not independently re-derived server-side from the authenticated session → **block** (BOLA risk; escalate as a security finding, not a style note).
- Error responses forward upstream detail (stack traces, internal hostnames, DB/vendor error bodies) → **block**.
- CORS is wildcard origin combined with credentialed requests → **block**.
- A breaking contract change has identified existing consumers with no deprecation plan → **block-with-conditions**, naming the required plan.
- All of the above are resolved, and any version-sensitive framework claim is Context7-verified or flagged unverified with the flag surfaced to the requester → **approve**, or **approve-with-conditions** if only non-blocking conditions (e.g., an unverified Context7 claim pending confirmation) remain.

## Output contract

Every response from this skill must include:

1. The endpoint/route handler and its consumer(s), stated explicitly.
2. A per-field data-minimization table or list: field → justified for which caller scope, or flagged unjustified.
3. The authorization enforcement mechanism found in the code, and whether it is independently server-verified (yes/no, with the file/line evidence).
4. Error-shape and CORS findings, each labeled by severity (blocking / non-blocking).
5. The versioning/deprecation status for any breaking change, including the consumer list found.
6. The verdict: approve / approve-with-conditions / block, with every unresolved condition listed explicitly (not implied).
7. Every version-sensitive framework claim labeled `Context7-verified` or `documentation-based — unverified this session`.
8. Open questions the review could not resolve from available evidence (e.g., "cannot confirm out-of-repo consumers without a service registry").

A response missing any of these eight elements is an incomplete review, not a shorter one.