rsc-universal 0.1.1

package/skills/angular/scripts/verify.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+#
+# verify.sh — Angular modern-baseline copy-banlist (heuristic lint, NOT a compiler).
+#
+# USAGE
+#   bash scripts/verify.sh [PATH ...]
+#   Run from your Angular project root. With no args it scans ./src (falling back
+#   to the current dir). Pass explicit paths to scope it to just-edited files:
+#     bash scripts/verify.sh src/app/users
+#
+# WHAT IT DOES
+#   Greps Angular .ts/.html sources for legacy patterns this skill bans, so the
+#   agent can self-correct toward standalone + signals + built-in control flow:
+#     - @NgModule in new code
+#     - legacy structural directives  *ngIf / *ngFor / *ngSwitch
+#     - decorator I/O  @Input() / @Output()
+#     - @for blocks missing a `track` expression
+#     - constructor-based DI (constructor(private x: X)) where inject() is the rule
+#   Each hit prints file:line. It is a best-effort heuristic, not a parser, so it
+#   may have false positives/negatives — treat it as a hint.
+#
+# GUARANTEES
+#   - Read-only: never writes, fixes, installs, or hits the network.
+#   - Exits 0 on an empty/clean target (no sources, or no hits) — no false failure.
+#   - Exits 1 only when at least one banned pattern is found, so it can gate a loop.
+#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).
+
+set -u
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+hits=0
+ok() { printf '%s\n' "${GREEN}ok${RESET}  $1"; }
+
+# --- resolve scan roots -----------------------------------------------------
+roots=""
+if [ "$#" -gt 0 ]; then
+  roots="$*"
+elif [ -d ./src ]; then
+  roots="./src"
+else
+  roots="."
+fi
+
+# Collect candidate Angular source files (.ts/.html), skipping vendor/build dirs
+# and *.spec.ts / *.d.ts. Newline-delimited list; empty if nothing matches.
+files="$(
+  find $roots \
+    \( -name node_modules -o -name dist -o -name .angular -o -name .git -o -name coverage \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.html' \) \
+    ! -name '*.spec.ts' ! -name '*.d.ts' -print 2>/dev/null
+)"
+
+if [ -z "$files" ]; then
+  printf '%s\n' "${YELLOW}skip${RESET} no Angular .ts/.html sources under: $roots"
+  exit 0
+fi
+
+# Grep a pattern across all files, reporting each match as "file:line: text".
+# $1 = ERE pattern, $2 = human label. Counts hits into the global $hits.
+scan() {
+  pattern="$1"; label="$2"
+  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE "$pattern" "$f" 2>/dev/null | sed "s|^|$f:|"
+  done)"
+  if [ -n "$out" ]; then
+    printf '%s\n' "$out" | while IFS= read -r m; do
+      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} $label  $m"
+    done
+    n="$(printf '%s\n' "$out" | grep -c . )"
+    hits=$((hits + n))
+  else
+    ok "no $label"
+  fi
+}
+
+# @for openers that do NOT contain `track` on the same line — track is required.
+scan_for_track() {
+  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -nE '@for[[:space:]]*\(' "$f" 2>/dev/null | grep -v 'track' | sed "s|^|$f:|"
+  done)"
+  if [ -n "$out" ]; then
+    printf '%s\n' "$out" | while IFS= read -r m; do
+      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} @for without track (track is required)  $m"
+    done
+    n="$(printf '%s\n' "$out" | grep -c . )"
+    hits=$((hits + n))
+  else
+    ok "no @for without track"
+  fi
+}
+
+printf '=== Angular banlist (%s files under %s) ===\n' "$(printf '%s\n' "$files" | grep -c .)" "$roots"
+
+# 1. NgModule in new code.
+scan '@NgModule' '@NgModule (use standalone components)'
+
+# 2. Legacy structural directives.
+scan '\*ng(If|For|Switch)\b' 'legacy *ngIf/*ngFor/*ngSwitch (use @if/@for/@switch)'
+
+# 3. Decorator I/O.
+scan '@(Input|Output)\(' '@Input()/@Output() decorator (use input()/output())'
+
+# 4. @for blocks missing the required `track` expression.
+scan_for_track
+
+# 5. Constructor-based DI.
+scan 'constructor[[:space:]]*\([^)]*(private|public|protected|readonly)[[:space:]]+[A-Za-z_]+[[:space:]]*:' 'constructor DI (use inject())'
+
+printf '\n'
+if [ "$hits" -gt 0 ]; then
+  printf '%sFAIL%s %d banned-pattern hit(s) — migrate toward standalone + signals.\n' "$RED" "$RESET" "$hits"
+  exit 1
+fi
+printf '%sPASS%s clean — no banned legacy Angular patterns found.\n' "$GREEN" "$RESET"
+exit 0

package/skills/api-connector-builder/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: api-connector-builder
+description: "Use when writing a client against a third-party REST or GraphQL API and the boring-but-critical parts keep biting — token refresh mid-run, only-the-first-page results, random 429s, banned keys. Covers auth flow selection (API key, Bearer, OAuth2 client-credentials, auth-code+PKCE, device), pagination to exhaustion (offset, cursor/keyset, Link header, Relay connections), retry-with-jitter on transient failures only, and rate-limit-aware throttling. Triggers: 'write a connector for the Linear/Shopify API', 'this API keeps 429-ing us', 'paginate through all results', 'token expires mid-run add refresh', 'wrap this REST API as a typed SDK', 'conector para una API que nos limita', 'recórreme totes les pàgines'. NOT receiving inbound callbacks (that is webhooks), NOT chaining many services into a flow (that is automation-flows), NOT designing your own API surface (that is api-design)."
+tags: [api, rest, graphql, oauth, pagination, retries, rate-limiting, http-client, connector]
+recommends: [webhooks, automation-flows, api-design, data-scraper, secure-coding, error-handling, structured-extraction]
+origin: risco
+---
+
+# API connector builder — auth, pagination, retries, rate limits
+
+You are writing a client for **someone else's** HTTP API. You do not own the
+contract; you obey it. The deliverable is one typed connector module per vendor
+that authenticates, walks the whole result set, retries only transient failures
+with backoff, and stays under the rate limit without getting the key banned.
+
+Four pillars, every time: **auth, pagination, retries, rate limits.** If your
+connector skips any one of them it works in the demo and breaks in production —
+on page 2, on token expiry, on the first 429, or on a flaky network.
+
+This skill goes **outbound** (you call them). Receiving their callbacks is the
+inverse and lives in `webhooks`.
+
+## Operating posture
+
+- **Read the vendor docs before writing a line.** Invented endpoints and guessed
+  field names 404 in prod. Find the real base URL, version, and error envelope.
+- **Secrets come from env or a secret store, never source.** Hardcoded keys leak
+  through git history and screenshots and you cannot rotate them cleanly.
+- **One connector = one vendor.** Mixed clients tangle two auth schemes and two
+  rate-limit budgets into one tangle no one can reason about.
+- **Every request gets a timeout.** A hung socket with no timeout stalls the
+  whole run forever; the default in most clients is "wait indefinitely".
+- **Log request id + status + attempt, never the token.** Logs get shipped to
+  third parties; a logged bearer token is a leaked credential.
+
+## Step 0 — read the contract
+
+Before any code, extract these from the vendor's docs. Each one changes what you
+write, so missing one means a rewrite.
+
+| Find in their docs        | Why it changes your code                                  |
+| ------------------------- | --------------------------------------------------------- |
+| Auth scheme + token TTL   | Picks the flow below; TTL decides if you need refresh     |
+| Base URL **and version**  | Wrong version = silent 404s or deprecated field shapes    |
+| Rate-limit header names   | You cannot throttle to a budget you cannot read           |
+| Pagination style          | Cursor vs offset vs Link vs Relay = different loop         |
+| Error envelope shape      | Where the real error code lives (body, not always status) |
+| Idempotency support       | Decides whether POST is safe to retry (key header?)       |
+
+If a fact is not in the docs, probe one real call and read the response headers
+and body — do not assume.
+
+## Auth — pick the flow, then store the secret right
+
+OAuth 2.1 is the current baseline. Three deltas you must honor: **PKCE is
+mandatory for every authorization-code client**, the **Implicit** and
+**Resource-Owner-Password** grants are **removed**, and **bearer tokens may not
+travel in query strings** (header only) — query strings end up in logs and
+referrers. (oauth.net/2.1, accessed 2026-06-02.)
+
+| Flow                          | Pick it when                                | Secret lives        | Refresh strategy                       |
+| ----------------------------- | ------------------------------------------- | ------------------- | -------------------------------------- |
+| **API key in header**         | Simple server-to-server, vendor issues key  | env / secret store  | none; rotate manually                  |
+| **Bearer static token**       | Personal access token, long-lived           | env / secret store  | none; treat as a key                   |
+| **OAuth2 Client Credentials** | Machine-to-machine, no end user             | client_id + secret  | re-mint on 401; cache until expiry     |
+| **OAuth2 Auth-Code + PKCE**   | Acting on behalf of a user                  | refresh token       | rotate on every refresh (see below)    |
+| **Device flow**               | CLI / TV / input-constrained device         | refresh token       | poll then rotate as auth-code          |
+
+**Refresh-token rule (public clients):** refresh tokens must be **sender-
+constrained or one-time-use** — rotated on every refresh, with the old one
+invalidated. Keep access tokens short-lived. Never log a raw token; log a partial
+or hash if you must correlate. (OAuth 2.0 Security BCP / RFC 9700, accessed
+2026-06-02.) Full per-flow walkthroughs, token storage, and a DPoP note are in
+`references/auth-flows.md`.
+
+## Retries + backoff
+
+Retry **only transient failures**, and only when the operation is safe to repeat.
+
+| Status / error                       | Retry? | Note                                          |
+| ------------------------------------ | ------ | --------------------------------------------- |
+| 429 Too Many Requests                | yes    | honor `Retry-After` (see rate limits)         |
+| 502 / 503 / 504                      | yes    | server-side transient                         |
+| Connection reset / timeout / DNS     | yes    | network transient                             |
+| 400 / 401 / 403 / 404 / 409 / 422    | **no** | replay returns the same error — fix the call  |
+| 2xx                                  | n/a    | success                                       |
+
+**Idempotency gate.** GET/PUT/DELETE are idempotent by semantics and safe to
+retry. **POST is not** — only retry it if you send a stable **idempotency key**
+so the server dedupes the duplicate. (AWS Builders' Library, accessed 2026-06-02.)
+
+**Backoff with jitter.** Use `delay = min(cap, base * 2^attempt) + random_jitter`.
+The jitter is not optional: without it, every client that failed at the same
+instant retries at the same instant — a synchronized thundering herd that DDoSes
+the recovering server. Full or decorrelated jitter is preferred. Always set stop
+conditions: **max attempts 3–5, a total deadline, and a per-attempt timeout.**
+(AWS Builders' Library, accessed 2026-06-02.)
+
+```python
+# Bad: retries everything, flat sleep, no jitter, no cap, no deadline.
+for _ in range(10):
+    r = httpx.get(url)
+    if r.status_code == 200:
+        return r.json()
+    time.sleep(1)  # 4xx will never recover; herds synchronize on flat 1s
+```
+
+```python
+# Good: transient-only, exponential backoff WITH jitter, bounded.
+import random, time, httpx
+
+RETRYABLE = {429, 502, 503, 504}
+
+def get(url, *, attempts=5, base=0.5, cap=20.0, deadline=60.0):
+    started = time.monotonic()
+    for attempt in range(attempts):
+        try:
+            r = httpx.get(url, timeout=10.0)  # per-attempt timeout
+        except (httpx.ConnectError, httpx.ReadTimeout):
+            pass  # network transient -> fall through to backoff
+        else:
+            if r.status_code == 200:
+                return r.json()
+            if r.status_code not in RETRYABLE:
+                r.raise_for_status()  # 4xx: do not retry, surface it
+        if time.monotonic() - started > deadline:
+            raise TimeoutError("retry deadline exceeded")
+        delay = min(cap, base * 2 ** attempt) + random.uniform(0, base)
+        time.sleep(delay)
+    raise RuntimeError("max attempts exhausted")
+```
+
+In Python prefer `tenacity` 9.1.4 (`@retry` with `wait_exponential_jitter`,
+`stop_after_attempt`, `retry_if_exception_type`) over a hand loop; in Node/TS use
+`undici` (the engine behind global `fetch()` since Node 18) with its retry
+interceptor. (PyPI/tenacity, nodejs/undici, accessed 2026-06-02.)
+
+## Rate limits
+
+Do not guess the wait — the server tells you. **Precedence:**
+
+1. **`Retry-After` present** (on a 429 or 503) → wait exactly that. It is either
+   a number of seconds or an HTTP-date; handle both.
+2. **No `Retry-After`** → compute the wait from `X-RateLimit-Reset` (a Unix epoch
+   or a delta-seconds, per vendor docs).
+3. **Proactively throttle** on `X-RateLimit-Remaining` — slow down *before* you
+   hit zero rather than absorbing a wall of 429s. (iotools.cloud rate-limiting
+   guidance, accessed 2026-06-02.)
+
+```python
+# Bad: ignore the headers, hammer, eat 429s, get the key throttled or banned.
+while more:
+    resp = client.get(next_url)   # no remaining check, no Retry-After
+    process(resp)
+```
+
+```python
+# Good: header-aware. Honor Retry-After, else reset; brake near the limit.
+def wait_for_rate_limit(resp):
+    ra = resp.headers.get("Retry-After")
+    if ra is not None:
+        return float(ra) if ra.isdigit() else _seconds_until_httpdate(ra)
+    remaining = int(resp.headers.get("X-RateLimit-Remaining", "1"))
+    if remaining <= 1:
+        reset = float(resp.headers.get("X-RateLimit-Reset", "0"))
+        return max(0.0, reset - time.time())  # or reset directly if delta-seconds
+    return 0.0
+```
+
+For sustained pulls, gate every request through a **token-bucket** sized to the
+documented budget (e.g. 60 req/min → refill 1 token/sec, capacity 60) so bursts
+smooth out instead of slamming the wall.
+
+## Pagination — loop to exhaustion
+
+There is no single best strategy; the vendor chose one and you follow it. The
+universal rule: **loop until the API says there is no next page — never a fixed
+page count.** A hardcoded `for page in range(10)` silently drops everything after
+page 10.
+
+| Style                      | Signal of "next"                          | Trade-off                                   |
+| -------------------------- | ----------------------------------------- | ------------------------------------------- |
+| **Offset / page number**   | `?offset=` / `?page=` until empty page    | simple; drifts on inserts, slow at depth    |
+| **Cursor / keyset**        | opaque `next_cursor` in body              | stable under writes, fixed cost — prefer it |
+| **Link header (REST)**     | `Link: <...>; rel="next"`                 | parse the header, follow until no `next`    |
+| **Relay (GraphQL)**        | `pageInfo.hasNextPage` + `endCursor`      | pass `endCursor` as `after` next query      |
+
+(graphql.org/learn/pagination + pagination pattern guides, accessed 2026-06-02.)
+
+Expose results as a generator / async-iterator so callers stream instead of
+buffering everything:
+
+```python
+def iter_records(client):
+    cursor = None
+    while True:
+        page = client.get("/items", params={"cursor": cursor, "limit": 100})
+        body = page.json()
+        yield from body["data"]
+        cursor = body.get("next_cursor")
+        if not cursor:           # exhaustion signal, not a counter
+            return
+```
+
+Full code for every style — offset, keyset, `Link`-header parsing, and GraphQL
+Relay connection walking, in Python and TS — is in `references/pagination.md`.
+
+## Putting it together
+
+A minimal connector wires all four pillars plus env config and structured logging.
+
+```python
+# connector.py — Python: httpx + tenacity
+import os, logging, httpx
+from tenacity import retry, stop_after_attempt, wait_exponential_jitter, retry_if_exception_type
+
+log = logging.getLogger("connector")
+TOKEN = os.environ["VENDOR_API_TOKEN"]          # from env, never hardcoded
+
+class Transient(Exception): ...
+
+@retry(stop=stop_after_attempt(5),
+       wait=wait_exponential_jitter(initial=0.5, max=20),
+       retry=retry_if_exception_type(Transient))
+def _request(client, method, path, **kw):
+    r = client.request(method, path, timeout=10.0, **kw)   # per-request timeout
+    log.info("req id=%s %s status=%s", r.headers.get("x-request-id"), path, r.status_code)
+    if r.status_code in (429, 502, 503, 504):
+        raise Transient(r.status_code)
+    r.raise_for_status()
+    return r
+
+def client():
+    return httpx.Client(base_url="https://api.vendor.com/v2",
+                        headers={"Authorization": f"Bearer {TOKEN}"})  # header, not query
+```
+
+```typescript
+// connector.ts — Node/TS: global fetch (undici) + bounded retry
+const TOKEN = process.env.VENDOR_API_TOKEN!;          // from env, never hardcoded
+const RETRYABLE = new Set([429, 502, 503, 504]);
+
+export async function request(path: string, init: RequestInit = {}, attempt = 0): Promise<Response> {
+  const res = await fetch(`https://api.vendor.com/v2${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${TOKEN}`, ...init.headers },
+    signal: AbortSignal.timeout(10_000),              // per-request timeout
+  });
+  console.info(JSON.stringify({ id: res.headers.get("x-request-id"), path, status: res.status, attempt }));
+  if (RETRYABLE.has(res.status) && attempt < 4) {
+    const ra = Number(res.headers.get("retry-after"));
+    const wait = Number.isFinite(ra) && ra > 0 ? ra * 1000 : Math.min(20_000, 500 * 2 ** attempt) + Math.random() * 500;
+    await new Promise((r) => setTimeout(r, wait));
+    return request(path, init, attempt + 1);
+  }
+  return res;                                          // caller checks res.ok / paginates
+}
+```
+
+## Anti-patterns
+
+| Anti-pattern                          | Consequence                              | Fix                                          |
+| ------------------------------------- | ---------------------------------------- | -------------------------------------------- |
+| Retry 4xx (401/403/404/422)           | Burns attempts; same error every time    | Retry only 429 + 5xx + network errors        |
+| `for page in range(N)` fixed loop     | Silently drops records past page N       | Loop on cursor / Link / hasNextPage          |
+| Flat `sleep(1)` between retries        | Synchronized herd hammers recovering API | Exponential backoff **with** jitter + cap    |
+| Log the token / Authorization header  | Leaked credential in shipped logs        | Log request id + status + attempt only       |
+| Hardcode the API key in source        | Leaks via git; cannot rotate cleanly     | Read from env / secret store                 |
+| No request timeout                    | One hung socket stalls the whole run     | Set a per-request timeout always             |
+| Ignore `Retry-After`                  | Keep 429-ing; key gets throttled/banned  | Honor `Retry-After`, else `X-RateLimit-Reset`|
+| Re-POST on retry with no idempotency  | Duplicate charges / records              | Send an idempotency key, or do not retry POST|
+| Token in query string                 | Token ends up in logs / referrers        | Bearer in the `Authorization` header         |
+| Implicit / password OAuth grant       | Removed in OAuth 2.1; insecure           | Auth-Code + PKCE, or Client Credentials      |
+
+## References & verify
+
+- `references/auth-flows.md` — per-flow walkthroughs, token storage + rotation,
+  OAuth 2.1 deltas, RFC 9700 refresh rotation, DPoP note. Python + TS.
+- `references/pagination.md` — full code for offset, cursor/keyset, Link-header,
+  and GraphQL Relay walking. Exhaustion-loop and dedup-on-overlap notes.
+
+Run `scripts/verify.sh` over the connector you write: it greps for hardcoded
+secrets, asserts a retry mechanism and a pagination loop and a request timeout
+exist, and flags `localStorage` token storage or plaintext token logging. It is a
+structure linter (read-only), not a behavior test — exit 0 on a clean target.

package/skills/api-connector-builder/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — api-connector-builder
+
+These cases are a hand-run rubric, not an automated test harness; no scoring
+script ships. To run them: paste a `should_trigger` prompt into a fresh agent
+session and confirm `api-connector-builder` is the skill that fires (and not a
+sibling). Paste a `should_not_trigger` prompt and confirm the agent routes to the
+named sibling instead. For the `capability` scenario, have the agent build the
+connector, then grade the result against the `must_include` list — every bullet
+should be satisfied by the code it produces. A connector that hardcodes the token,
+retries all 4xx, or stops after one page fails the rubric regardless of how clean
+it looks.

package/skills/api-connector-builder/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: api-connector-builder
+
+should_trigger:
+  - prompt: "Write a connector for the Linear GraphQL API that pulls every issue, not just the first page."
+    why: "Core task: a typed client against a third-party GraphQL API with Relay cursor connections, walked to exhaustion. The skill's flagship deliverable."
+  - prompt: "This vendor API keeps returning 429. Add backoff and respect their rate limit so we stop getting throttled."
+    why: "Rate-limit + retry symptom. Honor Retry-After / X-RateLimit-* with jittered backoff is squarely this skill."
+  - prompt: "We only ever get the first 100 results back from this API. Paginate through everything."
+    why: "Pagination-to-exhaustion. The fixed-first-page bug is the canonical thing this skill fixes."
+  - prompt: "Our access token expires halfway through a long run and the whole job dies. Add refresh."
+    why: "Non-obvious phrasing — never says 'OAuth' or 'connector', but mid-run token expiry is the auth/refresh concern the skill owns (refresh rotation)."
+  - prompt: "Conector para una API de terceros que nos banea la key cuando vamos demasiado rápido."
+    why: "Spanish trigger combining rate-limit + auth (banned key from hammering). Vendor-agnostic outbound client = this skill."
+  - prompt: "Wrap this vendor REST API as a typed SDK with retries and per-request timeouts."
+    why: "Typed-client framing. 'Wrap a REST API as an SDK' with resilience is the connector-module deliverable."
+  - prompt: "Build me a client for the Shopify Admin API that reads the cursor-based pages and handles the leaky-bucket rate limit."
+    why: "Vendor with no dedicated skill, cursor pagination + bucket rate limit — the generic connector case this skill covers."
+
+should_not_trigger:
+  - prompt: "Verify the incoming webhook signature from Stripe on our /hooks endpoint and reject replays."
+    route_to: webhooks
+    why: "Inbound callback — receiving and verifying events the vendor POSTs to us, the inverse of calling their API."
+  - prompt: "Design the versioning, resource model, and error envelope for OUR new public API."
+    route_to: api-design
+    why: "Authoring a contract others will consume, not consuming someone else's. Opposite side of the boundary."
+  - prompt: "Chain Gmail to Sheets to Slack into one automated if-this-then-that workflow."
+    route_to: automation-flows
+    why: "Multi-service orchestration across many tools, not building one connector for one vendor."
+  - prompt: "Scrape the product prices off this storefront — it has no public API at all."
+    route_to: data-scraper
+    why: "HTML/DOM scraping with no documented API; this skill requires a real API contract to obey."
+  - prompt: "Pull the structured fields out of this LLM's free-text answer into JSON."
+    route_to: structured-extraction
+    why: "Extracting structure from a model response, not making HTTP calls to a third-party API."
+
+capability:
+  - scenario: "Build a Python connector for a paginated REST API (cursor-based) that requires a Bearer token and rate-limits at 60 req/min with X-RateLimit-* headers. It must fetch all records."
+    must_include:
+      - "Reads the Bearer token from an environment variable / secret store — never hardcoded in source."
+      - "Sets a per-request timeout on every call (no unbounded socket wait)."
+      - "Retries only transient statuses (429, 502, 503, 504) and network errors; never retries other 4xx."
+      - "Uses exponential backoff WITH jitter and explicit stop conditions (max attempts 3–5 and/or a total deadline)."
+      - "Honors Retry-After when present, otherwise computes the wait from X-RateLimit-Reset; throttles proactively on X-RateLimit-Remaining."
+      - "Paginates by following the cursor until exhausted (no fixed page-count loop); ideally exposes a generator/iterator."
+      - "Logs request id / status / attempt but never the raw token or Authorization header."
+      - "Sends the token in the Authorization header, not a query string."
+      - "Returns or streams the FULL record set across all pages, not just the first page."

package/skills/api-connector-builder/references/auth-flows.md

@@ -0,0 +1,132 @@
+# Auth flows — per-flow walkthroughs
+
+OAuth 2.1 baseline (oauth.net/2.1, accessed 2026-06-02):
+
+- **PKCE is mandatory** for every authorization-code client, public and
+  confidential alike.
+- **Implicit grant and Resource-Owner-Password grant are removed.** If a vendor's
+  docs still show them, do not use them — pick Auth-Code + PKCE or Client
+  Credentials instead.
+- **Bearer tokens must not travel in query strings.** Header only. Query strings
+  leak into access logs, browser history, and `Referer` headers.
+
+## API key in header
+
+Simplest scheme. The vendor issues a static key; you send it on every request.
+Store it in env, never source. There is no refresh — rotate manually when it
+leaks or on a schedule.
+
+```python
+import os, httpx
+KEY = os.environ["VENDOR_API_KEY"]
+client = httpx.Client(base_url="https://api.vendor.com/v1",
+                      headers={"X-API-Key": KEY})  # header name per vendor docs
+```
+
+Some vendors want `Authorization: Bearer <key>` instead of a custom header — read
+the docs; do not guess the header name.
+
+## Bearer static token (personal access token)
+
+Treat exactly like an API key: long-lived, env-stored, no refresh. The only
+difference is the standard `Authorization: Bearer <token>` header.
+
+```typescript
+const TOKEN = process.env.VENDOR_PAT!;
+const headers = { Authorization: `Bearer ${TOKEN}` };
+```
+
+## OAuth2 Client Credentials (machine-to-machine)
+
+No end user is involved — your service authenticates as itself. You hold a
+`client_id` + `client_secret`, exchange them for a short-lived access token at the
+token endpoint, cache it until it expires, and re-mint on expiry or a 401.
+
+```python
+import os, time, httpx
+
+_cache = {"token": None, "exp": 0.0}
+
+def access_token():
+    if _cache["token"] and time.time() < _cache["exp"] - 30:  # 30s safety margin
+        return _cache["token"]
+    r = httpx.post("https://auth.vendor.com/oauth/token", data={
+        "grant_type": "client_credentials",
+        "client_id": os.environ["VENDOR_CLIENT_ID"],
+        "client_secret": os.environ["VENDOR_CLIENT_SECRET"],
+        "scope": "read:items",
+    }, timeout=10.0)
+    r.raise_for_status()
+    body = r.json()
+    _cache.update(token=body["access_token"], exp=time.time() + body["expires_in"])
+    return _cache["token"]
+```
+
+## OAuth2 Authorization Code + PKCE (acting for a user)
+
+The user-facing flow. PKCE prevents an intercepted authorization code from being
+redeemed by an attacker.
+
+1. Generate a `code_verifier` (43–128 chars, random) and its
+   `code_challenge = base64url(sha256(verifier))`.
+2. Redirect the user to the authorize endpoint with
+   `response_type=code`, `code_challenge`, `code_challenge_method=S256`,
+   `redirect_uri`, `scope`, and a random `state`.
+3. On callback, verify `state`, then POST `grant_type=authorization_code` with
+   the `code` **and the original `code_verifier`** to the token endpoint.
+4. Store the resulting refresh token securely; use the access token for calls.
+
+```python
+import base64, hashlib, os
+verifier = base64.urlsafe_b64encode(os.urandom(64)).rstrip(b"=").decode()
+challenge = base64.urlsafe_b64encode(
+    hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+# -> send `challenge` (S256) on /authorize, keep `verifier` for the token exchange
+```
+
+### Refresh-token rotation (RFC 9700 / OAuth 2.0 Security BCP)
+
+Refresh tokens for public clients must be **sender-constrained or one-time-use**:
+every refresh returns a *new* refresh token and invalidates the old one. If the
+old token is ever replayed, the server detects the reuse and revokes the whole
+chain (a sign of theft). Persist the latest refresh token atomically — a crash
+between "got new token" and "saved it" locks you out.
+
+```python
+def refresh(refresh_token: str) -> dict:
+    r = httpx.post("https://auth.vendor.com/oauth/token", data={
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": os.environ["VENDOR_CLIENT_ID"],
+    }, timeout=10.0)
+    r.raise_for_status()
+    body = r.json()
+    save_refresh_token(body["refresh_token"])  # ROTATE: store the new one, drop old
+    return body
+```
+
+Keep access tokens short-lived (minutes). Never log a raw token — log a partial
+(`tok…3f9c`) or a hash if you must correlate across services.
+
+## Device flow (input-constrained devices)
+
+For CLIs, TVs, and devices with no browser. Request a device + user code, show the
+user a URL and code to enter on another device, then **poll** the token endpoint
+until they approve (respect the `interval`; back off on `slow_down`). Once
+granted, you receive access + refresh tokens and rotate them exactly like the
+auth-code flow above.
+
+## DPoP (sender-constraining, brief)
+
+DPoP (Demonstrating Proof-of-Possession) binds a token to a client-held key: each
+request carries a signed `DPoP` header proving you hold the private key, so a
+stolen bearer token alone is useless. If a vendor offers DPoP-bound access tokens,
+prefer them for high-value scopes — it is the practical way to satisfy the
+"sender-constrained" requirement without mTLS infrastructure.
+
+## Storage rules (all flows)
+
+- Secrets in env vars or a secret manager — never in source, never in
+  `localStorage` (XSS-readable) for anything long-lived.
+- One credential set per vendor per environment; never share a prod key into dev.
+- Rotate on any suspected leak; the flows above make rotation cheap by design.