@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/skills/shared/external/api-security-best-practices/references/identity-and-access.md

@@ -0,0 +1,207 @@
+# Identity and Access
+
+How a request proves who it is, and how the server decides what that identity
+may do. Examples use TypeScript on Node with `jose` and Python with `PyJWT`;
+the rules are the same in any stack.
+
+## Contents
+
+1. Choosing a credential type
+2. Validating JWT access tokens
+3. Refresh tokens and sessions
+4. API keys for machine clients
+5. Service-to-service identity
+6. Authorization models
+7. Enforcing authorization in code
+8. Credential endpoints
+9. Scoping a lookup by principal
+
+## 1. Choosing a credential type
+
+| Caller | Credential | Notes |
+|---|---|---|
+| Browser app on your own domain | HttpOnly, Secure, SameSite cookie session | Tokens never touch JavaScript; add CSRF protection for unsafe methods |
+| Native mobile app | OAuth 2.1 authorization code + PKCE, short access token, rotating refresh token | Store in Keychain / Keystore, never plain preferences |
+| Third-party developer integration | OAuth 2.1 with scoped consent, or scoped API keys | Let customers revoke per integration |
+| Your own backend services | Workload identity (mTLS, cloud IAM, SPIFFE) or client-credentials tokens | No shared static secrets across services |
+
+Avoid long-lived bearer tokens in browsers' `localStorage`; any XSS reads them.
+
+## 2. Validating JWT access tokens
+
+Validate the same way on every route, in one middleware, with a library.
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+const jwks = createRemoteJWKSet(new URL("https://id.example.com/.well-known/jwks.json"));
+
+export async function authenticate(req) {
+  const header = req.headers.authorization ?? "";
+  const [scheme, token] = header.split(" ");
+  if (scheme !== "Bearer" || !token) throw unauthorized();
+
+  const { payload } = await jwtVerify(token, jwks, {
+    issuer: "https://id.example.com/",
+    audience: "orders-api",
+    algorithms: ["ES256"],
+    clockTolerance: 30,
+  });
+  return { subject: payload.sub, accountId: payload.acc, scopes: String(payload.scope ?? "").split(" ") };
+}
+```
+
+Rules the snippet encodes:
+
+- **Algorithm allowlist.** The token header never picks the algorithm. This
+  blocks `none` and RS256-to-HS256 key confusion.
+- **Issuer and audience.** A token minted for another API must fail here.
+- **Expiry with small skew.** Tens of seconds, not minutes.
+- **Keys from JWKS with caching**, so rotation needs no deploy.
+- **Asymmetric keys** (ES256, EdDSA, RS256) when more than one service verifies;
+  a shared HMAC secret means every verifier can also mint.
+
+Keep claims minimal. A JWT is signed, not encrypted; anyone holding it can read
+the payload. Do not put email addresses, names or permissions that change often
+into it; look volatile permissions up server-side.
+
+Python equivalent of the core call:
+
+```python
+import jwt
+from jwt import PyJWKClient
+
+jwks = PyJWKClient("https://id.example.com/.well-known/jwks.json")
+
+def verify(token: str) -> dict:
+    key = jwks.get_signing_key_from_jwt(token).key
+    return jwt.decode(
+        token, key,
+        algorithms=["ES256"],
+        audience="orders-api",
+        issuer="https://id.example.com/",
+        leeway=30,
+    )
+```
+
+## 3. Refresh tokens and sessions
+
+- Refresh tokens are opaque random values stored hashed server-side, bound to a
+  client and a device record.
+- Rotate on every use: issue a new refresh token, invalidate the old one. If an
+  already-used refresh token appears again, revoke the whole token family; it
+  has been stolen.
+- Give refresh tokens an absolute lifetime (for example 30 days) and an idle
+  timeout.
+- Logout, password change and "sign out everywhere" revoke refresh tokens. Access
+  tokens then die at their short expiry; if you need instant revocation, keep a
+  small deny list keyed by `jti` until expiry.
+
+Cookie sessions: regenerate the session id at sign-in, set `HttpOnly`, `Secure`,
+`SameSite=Lax` (or `Strict`), and scope `Path` and `Domain` tightly.
+
+## 4. API keys for machine clients
+
+```ts
+import { randomBytes, createHash, timingSafeEqual } from "node:crypto";
+
+export function mintKey() {
+  const secret = randomBytes(32).toString("base64url");
+  const key = `sk_live_${secret}`;
+  return { key, prefix: key.slice(0, 12), hash: createHash("sha256").update(key).digest() };
+}
+
+export function matches(presented: string, storedHash: Buffer) {
+  const hash = createHash("sha256").update(presented).digest();
+  return hash.length === storedHash.length && timingSafeEqual(hash, storedHash);
+}
+```
+
+- Show the full key once at creation; store only the hash and the prefix.
+- Look up by prefix, compare the hash in constant time.
+- Keys carry scopes and an owner, have an optional expiry, and log last use.
+- A recognisable prefix (`sk_live_`) lets secret scanners and GitHub push
+  protection catch leaks.
+
+## 5. Service-to-service identity
+
+- Prefer platform identity: Kubernetes service accounts with projected tokens,
+  cloud IAM roles, or mTLS with certificates issued by a mesh or SPIFFE.
+- When tokens are used, each service requests a token whose audience is the
+  callee; do not forward the end user's token to every downstream service.
+- If user context must travel, pass it as a separate signed assertion or as
+  claims in a token exchange (RFC 8693), and have the callee still apply its own
+  authorization.
+
+## 6. Authorization models
+
+| Model | Fits | Watch for |
+|---|---|---|
+| Ownership check | Personal data: my notes, my orders | Forgetting it on one route (BOLA) |
+| RBAC (roles to permissions) | Staff tools, tiered plans | Role explosion; check permissions, not role names |
+| ABAC / policy rules | Rules on attributes: region, status, amount | Policies scattered in code instead of one place |
+| ReBAC (relationship graph) | Sharing and teams: "editor of folder X" | Needs a dedicated service (OpenFGA, SpiceDB) at scale |
+
+Multi-tenant systems add one invariant above all others: every query is scoped
+by tenant. Enforce it structurally (row-level security in Postgres, a repository
+layer that requires a tenant id) so a missing `WHERE` cannot leak.
+
+## 7. Enforcing authorization in code
+
+Centralise decisions and keep them testable.
+
+```ts
+type Action = "order:read" | "order:cancel" | "order:refund";
+
+export function can(principal: Principal, action: Action, order: Order): boolean {
+  if (order.accountId !== principal.accountId) return false;
+  switch (action) {
+    case "order:read":
+      return true;
+    case "order:cancel":
+      return order.status === "pending";
+    case "order:refund":
+      return principal.permissions.includes("refunds:write");
+  }
+}
+```
+
+- Deny by default: unknown actions return false.
+- Load the object scoped by tenant first, then call `can` for the finer rule.
+- Unit-test the policy table exhaustively; integration-test that each route
+  calls it.
+
+Postgres row-level security as a backstop:
+
+```sql
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON orders
+  USING (account_id = current_setting('app.account_id')::uuid);
+```
+
+Set `app.account_id` per transaction from the authenticated principal, and make
+sure the application role is not the table owner (owners bypass RLS unless
+`FORCE ROW LEVEL SECURITY` is set).
+
+## 8. Credential endpoints
+
+Sign-in, password reset, OTP verification and sign-up are the most attacked
+routes.
+
+- Same response and similar timing whether the account exists or not.
+- Rate limit per account identifier and per source; add progressive delays.
+- Hash passwords with Argon2id (or bcrypt with cost 12 or more); check new
+  passwords against a breached-password list rather than composition rules.
+- Reset tokens: single use, short expiry (15 to 60 minutes), stored hashed.
+- Offer passkeys (WebAuthn) and TOTP; treat SMS OTP as the weakest factor.
+- Notify the user on sign-in from a new device and on credential changes.
+
+## 9. Scoping a lookup by principal
+
+```ts
+// Scoped at the data layer: a foreign id simply is not found.
+const order = await db.order.findFirst({
+  where: { id: req.params.orderId, accountId: req.auth.accountId },
+});
+if (!order) return reply.code(404).send(problem("order-not-found"));
+```

package/pipeline/skills/shared/external/api-security-best-practices/references/operations.md

@@ -0,0 +1,66 @@
+# API security operations
+
+SSRF controls, secrets handling, transport headers, security logging and security tests, summarised in SKILL.md.
+
+## Contents
+
+- SSRF controls
+- Secrets and keys
+- Transport and headers
+- Logging and detection
+- Testing security controls
+
+## Secrets and keys
+
+- Load secrets from the platform secret store (AWS Secrets Manager, GCP Secret
+  Manager, Vault, Kubernetes secrets with encryption at rest), never from the
+  repository. Scan commits with a secret scanner in CI.
+- Separate keys per environment and per service; rotate on a schedule and on
+  every staff departure that had access.
+- Hash API keys at rest (store a SHA-256 of a high-entropy key, show a prefix
+  for identification), and let customers create, scope and revoke their own.
+- Never log tokens, keys, passwords or full card numbers; redact at the logger.
+
+## Transport and headers
+
+- TLS 1.2 minimum, 1.3 preferred; redirect or refuse plain HTTP.
+- `Strict-Transport-Security: max-age=31536000; includeSubDomains`.
+- `Cache-Control: no-store` on responses that carry personal data or tokens.
+- `X-Content-Type-Options: nosniff`; for APIs, a restrictive
+  `Content-Security-Policy: default-src 'none'` costs nothing.
+
+## Logging and detection
+
+Log security-relevant events as structured records with a request id: sign-in
+success and failure, token refresh, permission denials, rate limit hits,
+password and email changes, admin actions. Alert on bursts of 401/403/404 from
+one identity (enumeration), unusual geographies, and spikes on sensitive flows.
+Keep logs free of secrets and minimise personal data in them.
+
+## Testing security controls
+
+Security checks are code and belong in the test suite:
+
+```ts
+test("a user cannot read another account's order", async () => {
+  const alice = await login("alice");
+  const bobsOrder = await createOrderAs("bob");
+  const res = await api.get(`/orders/${bobsOrder.id}`, { token: alice });
+  assert.equal(res.status, 404);
+});
+```
+
+- One BOLA test per resource type, one function-level test per privileged route.
+- A test that unknown or privileged fields in a write are ignored or rejected.
+- A test that oversized bodies and pages are refused.
+- Dependency audit (`npm audit`, `pip-audit`, OSV scanner) and a DAST pass
+  (OWASP ZAP baseline) in CI for public surfaces.
+
+## SSRF controls
+
+*Does any endpoint fetch a URL the caller supplied?*
+
+Webhook targets, image imports, link previews. Allowlist schemes and hosts,
+resolve DNS and reject private, loopback and link-local ranges (including cloud
+metadata at `169.254.169.254`), disable redirects or re-check each hop, and run
+fetchers in an egress-restricted network.

package/pipeline/skills/shared/external/api-security-best-practices/references/request-handling.md

@@ -0,0 +1,175 @@
+# Request Handling
+
+Everything that crosses the boundary is untrusted until a schema says
+otherwise: body, query, path, headers, cookies, uploaded files, and responses
+from other services.
+
+## Contents
+
+1. Validate at the edge with a schema
+2. Writable fields only (mass assignment)
+3. Shape every response explicitly
+4. Injection
+5. Files and uploads
+6. Fetching user-supplied URLs (SSRF)
+7. Errors that do not leak
+8. Consuming third-party APIs
+
+## 1. Validate at the edge with a schema
+
+Parse, do not check. A schema turns unknown input into a typed value or a 400,
+and the handler only ever sees the typed value.
+
+TypeScript with Zod:
+
+```ts
+import { z } from "zod";
+
+const CreateOrder = z.object({
+  productId: z.string().regex(/^p_[a-z0-9]{6,24}$/),
+  quantity: z.number().int().min(1).max(100),
+  note: z.string().trim().max(500).optional(),
+}).strict();
+
+app.post("/orders", async (req, reply) => {
+  const parsed = CreateOrder.safeParse(req.body);
+  if (!parsed.success) return reply.code(400).send(validationProblem(parsed.error));
+  const order = await orders.create(req.auth, parsed.data);
+  return reply.code(201).send(toOrderView(order));
+});
+```
+
+Python with Pydantic v2:
+
+```python
+from pydantic import BaseModel, ConfigDict, Field
+
+class CreateOrder(BaseModel):
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+    product_id: str = Field(pattern=r"^p_[a-z0-9]{6,24}$")
+    quantity: int = Field(ge=1, le=100)
+    note: str | None = Field(default=None, max_length=500)
+```
+
+Guidelines:
+
+- Bound every string, number and array. Unbounded input is a resource risk.
+- Prefer allowlists (enums, patterns) over deny lists.
+- Validate path and query parameters too, not just the body.
+- Normalise before validating (trim, Unicode NFC) and validate before use.
+- Reject unknown fields (`strict()`, `extra="forbid"`) on write endpoints, or at
+  minimum drop them; never pass them through.
+
+## 2. Writable fields only (mass assignment)
+
+The failure: `await db.user.update({ where: { id }, data: req.body })`. The
+client adds `"role": "admin"` and the ORM obliges.
+
+Fix by construction:
+
+- A separate input schema per operation (`CreateNote`, `UpdateNote`), listing
+  only fields the caller may set.
+- Server-owned fields (`id`, `ownerId`, `createdAt`, `status`, `price`) are set
+  by the server from context, never read from input.
+- Different roles, different schemas: an admin update schema may allow
+  `status`; the customer schema does not include it at all.
+
+## 3. Shape every response explicitly
+
+```ts
+export function toOrderView(o: OrderRow) {
+  return {
+    id: o.id,
+    status: o.status,
+    items: o.items.map((i) => ({ productId: i.productId, quantity: i.quantity })),
+    total: { amount: o.totalMinor, currency: o.currency },
+    createdAt: o.createdAt.toISOString(),
+  };
+}
+```
+
+- Never return ORM entities or `SELECT *` rows; new columns then leak
+  automatically.
+- Filtering sensitive fields in the client is not a control.
+- In FastAPI use `response_model`; in NestJS use serialisation groups or
+  explicit DTO mapping; in GraphQL expose only fields with resolvers you wrote.
+
+## 4. Injection
+
+**SQL.** Parameterised queries or a query builder, always. String building with
+user values is a defect even when "it's only an integer".
+
+```ts
+await sql`SELECT id, status FROM orders WHERE account_id = ${accountId} AND id = ${orderId}`;
+```
+
+Dynamic identifiers (sort column, direction) come from an allowlist map, never
+from input directly:
+
+```ts
+const SORTABLE = { created: "created_at", total: "total_minor" } as const;
+const column = SORTABLE[req.query.sort as keyof typeof SORTABLE] ?? "created_at";
+```
+
+**NoSQL.** Reject objects where scalars are expected; `{ "$ne": null }` in a
+MongoDB filter bypasses equality checks. Schema validation handles this.
+
+**Command execution.** Avoid shells. Use `execFile` / `subprocess.run([...])`
+with an argument array and no `shell=True`.
+
+**Templates and HTML.** APIs usually return JSON, but anything rendered later
+(emails, PDFs, admin dashboards) must escape by context. Use the template
+engine's auto-escaping; sanitise rich text with a maintained sanitiser
+(DOMPurify, `nh3`).
+
+**Log injection.** Structured JSON logging escapes newlines; avoid string
+concatenation of user input into log lines.
+
+## 5. Files and uploads
+
+- Cap size at the proxy and in the app. Stream to storage; do not buffer whole
+  files in memory.
+- Decide type from content (magic bytes), not the filename or `Content-Type`.
+- Store outside the web root, under a server-generated name, in object storage
+  with private ACLs; serve through short-lived signed URLs.
+- Scan for malware where users share files with each other.
+- Re-encode images to strip metadata (location data in EXIF) and neutralise
+  malformed payloads.
+- Archives: limit entry count and total uncompressed size, and reject paths with
+  `..` (zip slip).
+
+## 6. Fetching user-supplied URLs (SSRF)
+
+Any feature that fetches a URL on the caller's behalf needs a dedicated client.
+
+1. Parse the URL; allow only `https` (and `http` only if you must).
+2. Resolve the hostname yourself and reject private, loopback, link-local,
+   unique-local IPv6 and cloud metadata addresses.
+3. Connect to the resolved IP (to defeat DNS rebinding between check and use),
+   sending the original host in SNI and `Host`.
+4. Disable automatic redirects, or re-run the checks on every hop.
+5. Apply a short timeout and a response size cap.
+6. Run the fetcher where network policy blocks internal ranges anyway.
+
+Libraries such as `ssrf-req-filter` (Node) or an egress proxy like Smokescreen
+implement most of this; still test with `http://169.254.169.254/`,
+`http://[::1]/`, decimal IP forms and a redirecting URL.
+
+## 7. Errors that do not leak
+
+- Return a problem-details body with a stable `type`, a generic `title`, and a
+  request id. Log the stack trace server-side under that id.
+- Do not echo raw input back in error messages where it could be rendered.
+- Validation errors may name the field and the rule; they must not reveal
+  whether a related record exists in another tenant.
+- Turn off framework debug pages in every environment reachable from outside.
+
+## 8. Consuming third-party APIs
+
+- Validate upstream responses with the same schema tooling you use for requests.
+- Set connect and read timeouts, retry only idempotent calls with backoff, and
+  wrap the dependency in a circuit breaker.
+- Cap response size; a compromised or buggy upstream can return gigabytes.
+- Pin TLS verification on; never disable certificate checks to "make it work".
+- Treat webhook payloads as untrusted until the signature verifies, then still
+  validate the body.

package/pipeline/skills/shared/external/app-clips/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: app-clips
 description: "Build iOS App Clips with invocation URLs, App Clip Codes, NFC, QR codes, Safari banners, Maps, Messages, target setup, App Store Connect experiences, size/capability constraints, NSUserActivity routing, SKOverlay promotion, App Group/keychain handoff, ephemeral notifications, location confirmation, and full-app migration. Use when creating App Clips or wiring App Clip invocation, experience configuration, or full-app handoff."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # App Clips

package/pipeline/skills/shared/external/app-intents/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: app-intents
 description: "Implement App Intents for Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence on iOS. Covers AppIntent actions, AppEntity and EntityQuery models, AppShortcutsProvider phrases, IndexedEntity Spotlight indexing, WidgetConfigurationIntent, SnippetIntent, and assistant schemas. Use when exposing app actions or entities to system surfaces."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # App Intents (iOS 26+)

package/pipeline/skills/shared/external/app-store-changelog/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: app-store-changelog
 description: "Generate user-facing App Store release notes from git history since the last tag. Use when release notes have to be written from the commits since the last tag."
-risk: safe
-source: "Dimillian/Skills (MIT)"
-date_added: "2026-03-25"
+metadata:
+  risk: safe
+  source: "Dimillian/Skills (MIT)"
+  date_added: "2026-03-25"
 ---
 
 # App Store Changelog

package/pipeline/skills/shared/external/app-store-optimization/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: app-store-optimization
 description: "Optimize App Store product pages for search visibility and conversion. Use for App Store Optimization (ASO), keyword research, app name/subtitle/keyword-field strategy, conversion-focused descriptions and promotional text, screenshot captions and ordering, Custom Product Pages with assigned search keywords, In-App Events, Product Page Optimization tests, localized metadata, ratings/review strategy, and in-app review prompt timing with RequestReviewAction or AppStore.requestReview. Also use when routing ASO vs App Store review, privacy/ATT, or StoreKit implementation boundaries."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # App Store Optimization (ASO)

package/pipeline/skills/shared/external/app-store-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: app-store-review
 description: "Prepare for App Store review and prevent rejections. Covers App Store review guidelines, app rejection reasons, PrivacyInfo.xcprivacy privacy manifest requirements, required API reason codes, in-app purchase IAP and StoreKit rules, App Store Guidelines compliance, ATT App Tracking Transparency, EU DMA Digital Markets Act, HIG compliance checklist, app submission preparation, review preparation, metadata requirements, entitlements, widgets, and Live Activities review rules. Use when preparing for App Store submission, fixing rejection reasons, auditing privacy manifests, implementing ATT consent flow, configuring StoreKit IAP, or checking HIG compliance."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # App Store Review Preparation

package/pipeline/skills/shared/external/apple-on-device-ai/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: apple-on-device-ai
 description: "Integrate on-device AI using Foundation Models framework, Core ML, and open-source LLM runtimes on Apple Silicon. Covers Foundation Models (LanguageModelSession, @Generable, @Guide, SystemLanguageModel, structured output, tool calling), Core ML (coremltools, model conversion, quantization, palettization, pruning, Neural Engine, MLTensor), MLX Swift (transformer inference, unified memory), and llama.cpp (GGUF, cross-platform LLM). Use when building tool-calling AI features, working with guided generation schemas, converting models, or running on-device inference."
+metadata:
+  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
 ---
 
 # On-Device AI for Apple Platforms