mustflow 2.85.4 → 2.99.0

package/templates/default/locales/en/.mustflow/skills/api-access-control-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.api-access-control-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: api-access-control-review
-description: Apply this skill when code is created, changed, reviewed, or reported and API security needs access-control review for BOLA or IDOR, object-level authorization, object-property authorization, function-level authorization, broken authentication, tenant isolation, role and relationship checks, mass assignment, DTO exposure, admin or internal APIs, route ordering, GraphQL resolvers, batch APIs, exports, downloads, signed URLs, cache keys, async jobs, webhooks, OAuth or OIDC, JWTs, sessions, cookies, reauthentication, reset tokens, account enumeration, automation defense, or denial-case tests.
+description: Apply this skill when code is created, changed, reviewed, or reported and API security needs access-control review for BOLA or IDOR, object-level authorization, object-property authorization, function-level authorization, payment or refund API authorization, broken authentication, tenant isolation, effective permission decisions, role and relationship checks, mass assignment, DTO exposure, admin or internal APIs, route ordering, GraphQL resolvers, batch APIs, exports, downloads, signed URLs, cache keys, async jobs, webhooks, OAuth or OIDC, JWTs, sessions, cookies, reauthentication, reset tokens, account enumeration, automation defense, or denial-case tests.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -43,6 +43,10 @@ perform this action on this object, this field, and this tenant context?"
   exports, downloads, previews, batch APIs, background jobs, webhooks, auth middleware, sessions,
   cookies, JWTs, OAuth or OIDC flows, password reset, MFA, admin APIs, internal APIs, cache keys,
   DTO mapping, tests, or API docs.
+- Payment, refund, transfer, payout, credit, entitlement, or subscription APIs need proof that the
+  requester may act on that specific object, amount-bearing operation, tenant, account, or current
+  resource state. Use `payment-integrity-review` for money-event correctness and this skill for the
+  API object, property, and function authorization proof.
 - A request, token, body, query string, path parameter, webhook payload, queue payload, or client
   state supplies `userId`, `accountId`, `tenantId`, `orgId`, `workspaceId`, `projectId`, `role`,
   `ownerId`, object id, file key, status, price, entitlement, plan, or other authority-bearing data.
@@ -73,6 +77,9 @@ perform this action on this object, this field, and this tenant context?"
 - Subject-object-action-context ledger: principal, session, token, API key, service account, tenant,
   organization, workspace, role, relationship, resource, object id, field or property, action,
   state, and request context.
+- Decision explanation ledger: effective permission, matched policy, explicit deny, inheritance
+  path, policy version, data revision, token issue time, and allow or deny reason when the product
+  has policy-engine or audit-log support.
 - Object authorization ledger: list, detail, count, search, export, download, preview, share,
   update, delete, approve, invite, refund, transfer, admin, batch, worker, and webhook paths that
   can reach the same object.
@@ -135,101 +142,111 @@ perform this action on this object, this field, and this tenant context?"
    - `role === "admin"` is usually too small.
    - Check whether the principal is admin for this organization, owner of this project, seller for
      this order, billing admin for this account, or allowed to act in this resource state.
-6. Compare list and detail scopes.
+   - Prefer effective-permission evidence and policy decision explanations over a raw role list.
+6. Check default-deny and explicit-deny behavior.
+   - No matching policy, unknown role, unknown action, malformed id, parsing failure, policy server
+     timeout, and policy-cache miss should not silently allow access.
+   - When allow and deny policies both match, the product needs a documented and tested combination
+     rule.
+7. Compare list and detail scopes.
    - If list filters by current user or tenant but detail, count, search, analytics, export, or
      download uses only object id, report the gap.
-7. Review write APIs harder than read APIs.
+8. Review write APIs harder than read APIs.
    - `PUT`, `PATCH`, `DELETE`, approve, refund, invite, transfer, publish, restore, and role-change
      operations need write-specific permission, state, amount, and audit checks.
    - Read permission is not write permission.
-8. Stop mass assignment at the boundary.
+9. Stop mass assignment at the boundary.
    - Flag request-body-to-entity binding, raw DTO persistence, GraphQL input passthrough, ORM update
      data from raw body, and blind spread or object assignment.
    - Privileged fields such as `role`, `status`, `ownerId`, `tenantId`, `isVerified`, `plan`,
      `credit`, `deletedAt`, `price`, and `quota` must be derived, guarded, or allowlisted.
-9. Check response DTOs for property-level exposure.
+10. Check response DTOs for property-level exposure.
    - Entity-to-JSON responses can leak `passwordHash`, `mfaSecret`, `internalMemo`,
      `billingCustomerId`, storage keys, provider IDs, deletion reasons, or admin-only fields later.
    - Use public response mappers and role-aware field policies when field visibility differs.
-10. Treat client-side admin UI as decoration.
+11. Treat client-side admin UI as decoration.
     - Hidden buttons, disabled controls, frontend routes, mobile checks, and generated clients are
       not access control.
     - Admin and support operations need server-side scope, reason, audit, and denial tests.
-11. Search for temporary public holes.
+12. Search for temporary public holes.
     - Inspect `permitAll`, `anonymous`, `skipAuth`, `bypassAuth`, `public`, `internalOnly`,
       `devOnly`, `TODO auth`, debug endpoints, health endpoints with extra data, and test-only
       switches that can reach real data or operations.
-12. Review router and middleware order.
+13. Review router and middleware order.
     - Dynamic routes like `/:id` can shadow `/me`, `/admin`, or `/settings`.
     - Prefix middleware can leave sibling paths, nested routers, serverless functions, or framework
       route groups unauthenticated.
-13. Review GraphQL per resolver.
+14. Review GraphQL per resolver.
     - Endpoint-level auth is not enough.
     - Check `node(id)`, nested fields, connections, edges, aggregates, mutations, and field
       resolvers for object and property authorization.
-14. Review batch APIs per item.
+15. Review batch APIs per item.
     - Bulk create, delete, export, import, and update endpoints must authorize every object.
     - Define whether one denied item fails the whole request, returns per-item results, or produces
       a retrievable failure report.
-15. Review export, download, preview, thumbnail, and share paths.
+16. Review export, download, preview, thumbnail, and share paths.
     - CRUD may be protected while file delivery, generated previews, thumbnails, CSV exports, and
       shared links bypass the same policy.
-16. Treat signed storage URLs as outputs of authorization.
+17. Treat signed storage URLs as outputs of authorization.
     - S3, GCS, R2, CDN, and private file URLs must be generated only after object authorization.
     - Check key predictability, URL lifetime, scope, content disposition, cache behavior, revocation,
       and whether direct object access bypasses policy.
-17. Enforce tenant boundaries in every query and cache.
+18. Enforce tenant boundaries in every query and cache.
     - `WHERE id = ?` is weak in multi-tenant code; include tenant, membership, owner, sharing, or
       database policy constraints.
     - Cache keys for private data need tenant and permission dimensions, not just object id.
-18. Revalidate asynchronous jobs.
+19. Revalidate asynchronous jobs.
     - Queue payloads with only `userId`, `tenantId`, or `fileId` can outlive permission changes.
     - Workers, retries, admin reruns, scheduled tasks, and webhook-triggered jobs need actor,
       tenant, resource, state, and current permission or service-principal checks at execution time.
-19. Separate webhook authenticity from authorization.
+20. Separate webhook authenticity from authorization.
     - Signature verification proves the provider sent the event.
     - Ownership mapping proves the event belongs to this tenant, account, customer, installation,
       repository, subscription, or resource.
-20. Keep OAuth and OIDC purposes distinct.
+21. Keep OAuth and OIDC purposes distinct.
     - OIDC ID tokens identify a user for login.
     - OAuth access tokens authorize delegated API access.
     - Do not use an ID token as an API permission token or an access token as a login proof without
       the appropriate validation and intent.
-21. Verify JWTs completely.
+22. Verify JWTs completely.
     - Decoding is not verification.
     - Check signature, algorithm allowlist, issuer, audience, expiry, not-before when used, key
       source, key rotation, subject, tenant binding, and stale authorization claims.
-22. Treat token claims as snapshots, not eternal truth.
+23. Treat token claims as snapshots, not eternal truth.
     - Long-lived `role`, `plan`, `tenantId`, and permission claims can survive demotion, removal,
       subscription cancellation, suspension, or revocation.
     - Important decisions should check current server-side state or use short-lived tokens with
       revocation strategy.
-23. Regenerate session identity after privilege changes.
+24. Measure revocation and stale-permission windows.
+    - User removal, role demotion, organization leave, policy-version changes, subscription state
+      changes, and ownership transfers should say how quickly sessions, JWTs, caches, search
+      indexes, queued jobs, and signed URLs stop authorizing old access.
+25. Regenerate session identity after privilege changes.
     - Login, password change, MFA changes, role changes, user-to-admin transitions, and account
       recovery should rotate session identifiers or refresh tokens according to local policy.
-24. Check authentication cookies.
+26. Check authentication cookies.
     - Cookies carrying session authority need `Secure`, `HttpOnly`, appropriate `SameSite`,
       domain, path, lifetime, rotation, logout, revocation, and CSRF posture.
     - Avoid URL-carried session identifiers.
-25. Require reauthentication for sensitive actions.
+27. Require reauthentication for sensitive actions.
     - Password change, email change, MFA disable, payment method change, organization ownership
       transfer, API-key creation, and destructive admin actions should require fresh proof.
-26. Review reset and magic-link tokens.
+28. Review reset and magic-link tokens.
     - Tokens need strong randomness, one-time use, short expiration, purpose binding, user binding,
       safe storage, link-preview protection, session invalidation where needed, and no reuse across
       unrelated flows.
-27. Compare account-enumeration responses.
+29. Compare account-enumeration responses.
     - Login, signup, password reset, magic link, invitation, and email verification should avoid
       leaking account existence through message, status, timing, or email-sending behavior unless
       product policy accepts that disclosure.
-28. Treat automation defense as part of authentication.
+30. Treat automation defense as part of authentication.
     - Login, OTP, magic link, password reset, invite acceptance, coupon application, email
       verification, and MFA attempts need rate limits, lockouts, challenge policy, IP/device/user
       dimensions, and observability.
-29. Separate internal and external identity planes.
+31. Separate internal and external identity planes.
     - Backoffice, operator, database, middleware, and support accounts should not flow through the
       same customer login path unless the product intentionally models and audits that boundary.
-30. Test the denial matrix.
+32. Test the denial matrix.
     - Success tests prove little.
     - For each protected resource, cover anonymous, normal user, other owner, same organization
       different role, other tenant, admin wrong tenant, revoked user, suspended member, stale token,
@@ -240,6 +257,8 @@ perform this action on this object, this field, and this tenant context?"
 
 - The API access-control decision names subject, object, action, field or property, tenant or owner,
   current state, and trusted context when those apply.
+- Effective permission, matched policy, explicit deny, inheritance path, policy version, data
+  revision, token issue time, and revocation window are checked or named as gaps when relevant.
 - Authentication, object authorization, property authorization, and function authorization are not
   collapsed into one route guard.
 - Client-supplied identity and authority fields are either ignored, verified against server-side
@@ -287,6 +306,8 @@ and account-enumeration response parity.
 
 - API access control reviewed
 - Subject, object, action, field, tenant or owner, state, and trusted context
+- Effective permission, decision explanation, policy version, data revision, token age, and
+  revocation-window findings
 - Object, property, and function authorization findings
 - Authentication, session, token, cookie, OAuth/OIDC, reset, reauthentication, enumeration, and
   automation findings

package/templates/default/locales/en/.mustflow/skills/api-failure-triage/SKILL.md

@@ -0,0 +1,270 @@
+---
+mustflow_doc: skill.api-failure-triage
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: api-failure-triage
+description: Apply this skill when an API request, SDK call, webhook callback, browser request, mobile call, gateway route, CORS preflight, CDN or load-balancer path, upstream dependency call, or OpenAPI-backed integration is failing, intermittent, slow, returning the wrong status or body, blocked by authentication or authorization, rate-limited, retried, cached incorrectly, or not yet localized to client, network, proxy, app, database, cache, provider, or deployment configuration. Use before api-request-performance-review when the first job is to preserve the failing wire evidence and cut the failure boundary.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.api-failure-triage
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# API Failure Triage
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Triage API failures by preserving the actual request and cutting the path boundary before editing
+code.
+
+The first question is not "which log looks suspicious?" It is "what bytes left the caller, what
+bytes came back, which boundary changed them, and what evidence would disprove each hypothesis?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A user reports that an API call, SDK request, browser request, mobile request, webhook callback,
+  backend-for-frontend path, gateway route, CDN path, load-balancer path, or provider integration is
+  failing or intermittent.
+- The failure is not yet localized to client code, DNS, TCP, TLS, proxy, CORS preflight, redirect,
+  gateway, app handler, database, cache, external provider, rate limiter, retry policy, auth,
+  deployment configuration, or OpenAPI drift.
+- Code or docs claim an API failure is a network issue, CORS issue, server issue, auth issue, cache
+  issue, provider issue, or retry issue without preserved wire evidence.
+- A fix might otherwise start from logs, framework assumptions, SDK behavior, browser console text,
+  or a broad search before one failing request is captured.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The failing request is already reproduced and the root cause is clear enough for a targeted fix;
+  use the narrower code, API contract, cache, retry, auth, database, or failure-integrity skill.
+- The task is only per-request latency optimization after the API path is known; use
+  `api-request-performance-review`.
+- The task is only public error wording or error-envelope cleanup; use
+  `error-message-integrity-review`.
+- The task is only observability design with no current API failure to localize; use
+  `observability-debuggability-review`.
+- Reproduction requires live production secrets, destructive calls, real payments, real user data,
+  private logs, or unconfigured external systems. Preserve available static evidence and report the
+  manual boundary instead.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Failure packet: observed time and timezone, request id or trace id when present, caller, client or
+  SDK version, API version, method, URL route template, sanitized headers, sanitized body shape,
+  status code, response headers, response body shape, total latency, and retry or redirect behavior.
+- Success comparator: a nearby successful request, previous working version, same request with one
+  dimension changed, or a documented expected request shape.
+- Boundary ledger: client, browser preflight, SDK middleware, DNS, TCP, TLS, proxy, CDN, WAF,
+  gateway, load balancer, app, queue, database, cache, external provider, and response serialization
+  boundaries relevant to the path.
+- Timing ledger: name lookup, connection, TLS, first byte, total transfer, app handler time, queue
+  time, pool wait, database time, cache time, external dependency time, serialization time, and
+  download time when evidence exists.
+- Contract ledger: HTTP method, redirect behavior, content negotiation, content type, encoding,
+  status code semantics, error envelope, retryability, idempotency, rate-limit headers, cache
+  headers, OpenAPI or generated-client contract, and deployment version.
+- Auth ledger: credential presence, token expiry and not-before time, signature timestamp, clock
+  skew, user or service principal, object authorization, tenant scope, and proxy header preservation.
+- Change ledger: deploy, config, secret, feature flag, routing rule, schema migration, provider
+  version, generated client, cache policy, rate-limit policy, and environment difference near the
+  first bad time.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
+  validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- Required request, response, boundary, timing, contract, auth, and change evidence is available or
+  can be reported as missing without guessing.
+- If the preserved evidence exposes secrets, tokens, cookies, personal data, payment data, private
+  URLs, raw bodies, or hidden reasoning, summarize and redact rather than copying it into docs,
+  tests, logs, commits, or final reports.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten request parsing, content-type handling, status mapping, Problem Details or local
+  error-envelope mapping, request ID propagation, trace context, auth checks, proxy header handling,
+  timeout classification, retry and idempotency classification, rate-limit response handling, cache
+  header handling, OpenAPI contract tests, deployment config comparison tests, and focused
+  reproduction fixtures.
+- Add focused tests that preserve the failing wire shape, success/failure comparator, status and
+  body contract, auth boundary, retryability, cache behavior, OpenAPI drift, or deployment config
+  difference.
+- Do not add broad retries, blanket cache bypasses, CORS wildcards, auth bypasses, status-code
+  remapping, proxy header trust, live provider calls, raw production log dumps, or speculative
+  framework rewrites before the failing boundary is localized.
+- Do not treat browser console text, SDK exception text, status code alone, or application logs alone
+  as the failing request evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Preserve one failing request packet.
+   - Record method, route template, sanitized headers, sanitized body shape, status, response
+     headers, response body shape, total latency, request id, trace id, caller version, API version,
+     and observed time basis.
+   - If the failure is intermittent, keep the first bad time and a small sample of failing and
+     successful packets rather than a raw log dump.
+2. Compare success and failure at the wire boundary.
+   - Compare actual transmitted method, URL encoding, query order and defaults, headers, cookies,
+     body shape, null versus empty string, array order, content type, accept header, charset, API
+     version, and redirect path.
+   - Do not compare only source code or SDK call arguments because middleware, retries, proxies,
+     redirects, and defaults can rewrite the request.
+3. Cut the path into boundaries.
+   - Check whether the request reaches each boundary: client, preflight, SDK, DNS, TCP, TLS, proxy,
+     CDN, WAF, gateway, load balancer, app handler, queue, database, cache, external provider, and
+     response serializer.
+   - Prefer evidence that halves the search space. If the app never sees the request, app logs are
+     not the first evidence source.
+4. Split timing before assigning blame.
+   - Separate name lookup, connection, TLS, first byte, total download, app handler time, queue time,
+     pool wait, database time, cache time, external dependency time, serialization time, and payload
+     transfer when available.
+   - Average latency is weak evidence. Use endpoint, status, region, client, API version, and
+     percentile slices when telemetry exists.
+5. Check browser-only failures separately.
+   - For browser-only symptoms, inspect preflight, allowed method, allowed headers, credentials
+     mode, redirect behavior, and whether the failing request happens before the real method is sent.
+   - For server-to-server failures, do not diagnose CORS unless a browser boundary is actually
+     involved.
+6. Check redirect and proxy mutation.
+   - Verify whether redirects change method, body, host, scheme, authorization, cookies, or signed
+     headers.
+   - Verify whether proxies preserve `Authorization`, `Host`, forwarded headers, request ids,
+     trace context, content length, idempotency keys, and rate-limit headers according to local
+     trust policy.
+7. Check status, body, and content-type consistency.
+   - A `200` response with an error body, a `500` for caller validation, a hidden `404` for auth,
+     or a JSON content type with an HTML error body can break clients and monitoring.
+   - Map API errors to stable codes, request IDs, invalid fields, retryability, and safe support
+     evidence when the local contract supports it.
+8. Split authentication from authorization.
+   - Verify credentials were sent, valid, not expired, and signed against the expected time basis.
+   - Separately verify whether the authenticated principal can access the target object, property,
+     tenant, or function.
+   - Treat "same token, different resource id returns another user's data" as an access-control
+     incident, not ordinary debugging.
+9. Check clock and signature time.
+   - Review token `exp` or `nbf`, signed request timestamps, webhook timestamps, cache expiry, rate
+     limit windows, and server/client clock skew when the failure is intermittent or boundary-time
+     sensitive.
+10. Check retry, timeout, rate limit, and idempotency.
+    - Separate connect, TLS, first-byte, read, write, dependency, pool, and total-deadline failures
+      when evidence exists.
+    - Confirm retries are bounded, jittered, scoped to one layer, and safe for the operation.
+    - For side-effecting requests, require a durable idempotency key and result replay or unknown
+      outcome reconciliation before retrying.
+    - Preserve `429`, rate-limit policy, and retry-after semantics instead of turning throttling into
+      generic server failure.
+11. Check cache and content negotiation.
+    - Compare cached and cache-bypassed behavior when allowed by the current command and environment
+      boundary.
+    - Inspect cache-control, validators, age, vary dimensions, authorization or cookie variance,
+      API version, language, query dimensions, and stale or negative-cache behavior.
+12. Check app-internal cost and dependency fan-out only after the request reaches the app.
+    - If the app receives the request, build a compact cost ledger for database, cache, external API,
+      serialization, compression, and response size.
+    - Use `api-request-performance-review`, database, cache, retry, queue, or observability skills
+      for the localized subproblem.
+13. Check OpenAPI and generated-client drift.
+    - Compare deployed behavior with the documented contract: required fields, nullability, enum
+      values, status codes, headers, content type, and error envelope.
+    - Treat generated client, SDK, or schema drift as a contract issue even when the server and
+      client each look locally correct.
+14. Check deployment and environment diffs.
+    - Near the first bad time, compare release id, config, secret names, routing rules, feature
+      flags, provider account, migration state, cache policy, rate-limit policy, and generated
+      artifacts.
+    - Do not blame code before environment and route changes are ruled in or out.
+15. Maintain a hypothesis table.
+    - For each hypothesis, write the expected evidence and the observation that would disprove it.
+    - Kill wrong hypotheses quickly. Long log reading without a falsifiable hypothesis is not
+      progress.
+16. Apply the smallest localized fix.
+    - Once the boundary is proven, switch to the specific skill for that boundary and edit only the
+      owning code, contract, test, doc, template, or config surface.
+    - Re-run the original reproduction path or the closest configured intent after the fix.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The failing request packet, success comparator, boundary ledger, timing ledger, contract ledger,
+  auth ledger, and change ledger are explicit or reported as missing.
+- The failure is localized to a boundary or left as a named evidence gap instead of a guessed cause.
+- Status/body/content-type, CORS/preflight, redirects, proxy headers, authn/authz, clock skew,
+  timeout/retry/rate-limit/idempotency, cache headers, OpenAPI drift, and deployment diffs are fixed
+  or reported where relevant.
+- Any follow-up skill is selected because the boundary is now localized, not because the first guess
+  sounded plausible.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that covers the
+localized API failure boundary. Do not infer raw servers, live providers, database shells, browser
+sessions, packet captures, production logs, load tests, profilers, or network probes outside the
+command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the failing request packet cannot be captured, stop speculative edits and report the closest
+  safe evidence plus the missing packet fields.
+- If evidence contains secrets or personal data, redact before storing or reporting it.
+- If boundary evidence requires live production access, private dashboards, external provider
+  consoles, or unconfigured network diagnostics, report the manual evidence boundary.
+- If a configured command fails, preserve the failing intent and output tail, then fix only the API
+  boundary or contract exercised by that failure.
+- If the root cause points to security, payment, rate limit, cache, retry, queue, or deployment risk,
+  switch to the narrower matching skill before editing that part.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- API failure triaged
+- Failing request packet and success comparator, with redactions
+- Boundary and timing ledger
+- Status/body/content-type, CORS/preflight, redirect/proxy, authn/authz, clock, retry/timeout,
+  rate-limit/idempotency, cache, OpenAPI, and deployment-diff findings
+- Hypotheses killed, still open, and selected localized boundary
+- Fix applied or recommended
+- Evidence level: reproduced packet, comparator evidence, configured-test evidence, static review
+  risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped diagnostics and reasons
+- Remaining API-failure risk

package/templates/default/locales/en/.mustflow/skills/auth-flow-triage/SKILL.md

@@ -0,0 +1,192 @@
+---
+mustflow_doc: skill.auth-flow-triage
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: auth-flow-triage
+description: Apply this skill when login, signup, logout, session refresh, OAuth or OIDC redirect, PKCE, nonce, state, passkey, MFA, password reset, magic link, cookie, JWT, token exchange, JWKS, IdP callback, account linking, or authorization-after-login behavior is failing, intermittent, browser-only, client-specific, or not yet localized to identity, cookie, token, proxy, session store, provider, clock, rate limit, or permission policy.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.auth-flow-triage
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Auth Flow Triage
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Localize authentication-flow failures without collapsing identity proof, session issuance, token
+validation, browser cookie behavior, external provider callbacks, MFA, and authorization into one
+"login is broken" bucket.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Login, signup, logout, refresh, password reset, magic link, MFA, passkey, OAuth, OIDC, SAML-like
+  handoff, API-key login, or account-linking behavior fails or behaves differently across clients.
+- A user appears authenticated on one boundary but logged out, forbidden, redirected, or assigned to
+  the wrong account on another boundary.
+- The failure may involve cookies, SameSite, CORS credentials, CSRF, proxy headers, redirect URI,
+  state, nonce, PKCE, authorization code exchange, JWT claims, JWKS rotation, refresh token
+  rotation, session storage, account lockout, rate limit, IdP metadata, passkeys, OTP, clocks, or
+  authorization after login.
+- The task is to diagnose or review an auth failure before the exact code owner is known.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is already localized to implementing or changing the permission model; use
+  `auth-permission-change`.
+- The task is specifically API object, property, or function authorization review; use
+  `api-access-control-review`.
+- The task is only generic API failure triage before any auth-specific signal exists; use
+  `api-failure-triage`.
+- The task asks for live credential testing, brute force, phishing simulation, or production token
+  collection. Stay within defensive code review, sanitized traces, and configured tests.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Auth attempt packet: observed time, timezone, trace or request id, client type, route, sanitized
+  request and response shape, redirect chain, status codes, user-facing message class, and result.
+- Stage ledger: user lookup, credential verification, external provider round trip, callback,
+  token exchange, session issue, cookie write, redirect, authorization decision, and logout or
+  revocation when relevant.
+- Token and session ledger: session id hash, token type, issuer, audience, subject, `jti`, `iat`,
+  `nbf`, `exp`, key id, refresh-token family state, cookie attributes, session-store key, and
+  revocation or rotation state.
+- Browser and proxy ledger: origin, host, forwarded proto and host, redirect URI, cookie domain and
+  path, SameSite, Secure, HttpOnly, CORS credentials, CSRF token, and proxy trust boundary.
+- Provider ledger: IdP issuer, discovery metadata, JWKS URI, registered redirect URIs, client id,
+  PKCE method, state, nonce, passkey RP ID, WebAuthn origin, MFA method, and provider error class.
+- Denial and privacy ledger: enumeration policy, lockout or rate-limit decision, internal result
+  code, public error message, redaction boundary, and denial-case tests.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked.
+- Secrets, tokens, OTPs, passwords, cookies, raw provider payloads, personal identifiers, and private
+  callback URLs are redacted before being written into docs, tests, commits, or reports.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten stage-specific result codes, safe trace ids, token validation, cookie settings,
+  proxy trust handling, redirect URI checks, PKCE, state, nonce, JWKS refresh behavior, session
+  rotation, refresh-token serialization, account-linking checks, passkey origin checks, MFA tests,
+  redaction, docs, fixtures, and denial-case tests.
+- Add focused tests that reproduce the sanitized failure stage, token claim mismatch, cookie
+  behavior, callback binding, refresh-token race, session fixation boundary, or account-linking
+  policy.
+- Do not add auth bypasses, broad CORS wildcards, loose redirect matching, disabled TLS checks,
+  widened clock skew, token logging, provider-console assumptions, or live credential probes.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Split the symptom by stage before editing: user lookup, credential or passkey verification,
+   provider redirect, callback validation, token exchange, session issue, cookie persistence,
+   refresh, logout, and authorization-after-login.
+2. Preserve one sanitized failing attempt plus one success comparator. Compare the actual redirect
+   chain, cookies sent and set, status codes, provider error class, token type, and client version.
+3. Keep public and internal errors separate. Public messages should avoid account enumeration;
+   internal evidence should keep stable reason codes such as missing user, credential mismatch,
+   disabled account, MFA required, token expired, nonce mismatch, PKCE mismatch, and policy denied.
+4. Verify clocks before treating tokens as bad. Compare server epoch, token `iat`, `nbf`, `exp`,
+   OTP window, signed request timestamp, certificate validity, and applied clock skew.
+5. For browser-only failures, check actual cookie attributes, CORS credential behavior, CSRF,
+   redirect handling, preflight, duplicate cookie names, and whether the callback writes the cookie
+   on the host and path the app later uses.
+6. For proxy-backed apps, verify trusted forwarded headers, external URL calculation, secure cookie
+   detection, host allowlists, and callback URL generation. Do not trust arbitrary forwarded headers.
+7. For OAuth or OIDC, compare the exact registered and transmitted redirect URI, issuer, discovery
+   metadata, client id, state, nonce, PKCE method, code-verifier binding, token endpoint, and JWKS.
+8. For token validation, check signature, algorithm allowlist, key id refresh, issuer, audience,
+   authorized party when needed, subject, expiry, not-before, nonce, token type, and stale role or
+   permission claims.
+9. For refresh and logout failures, separate local cookie deletion, server session revocation,
+   refresh-token family state, access-token lifetime, IdP SSO session, and provider logout.
+10. For passkeys and MFA, check challenge one-time use, origin, RP ID, credential id, user handle,
+    user-verification flags, OTP reuse, recovery path, reauthentication, and registration or removal
+    policy.
+11. For account linking, use provider `issuer + subject` as the external identity key. Treat email
+    equality as weak evidence that requires an authenticated linking flow.
+12. If authentication succeeds but the user is still blocked, switch to `auth-permission-change` or
+    `api-access-control-review` and inspect tenant, resource, role, scope, stale cache, and token
+    claim freshness.
+13. Apply the smallest localized fix and rerun the narrowest configured intent that covers the
+    affected auth stage, denial case, docs, template, or package surface.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The failing auth stage is localized or named as an evidence gap.
+- Public error wording, internal reason codes, trace ids, session or token identifiers, and redaction
+  boundaries are explicit.
+- Cookie, proxy, redirect, token, JWKS, provider metadata, passkey, MFA, refresh, logout, rate limit,
+  and authorization-after-login checks are fixed or reported where relevant.
+- Any permission follow-up is routed to the narrower access-control skill instead of hidden inside
+  login debugging.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured tests that cover the failing auth stage and denial behavior. Report
+missing browser cookie, provider callback, JWKS rotation, MFA, passkey, refresh-token race, and
+session-store integration evidence instead of inventing live auth probes.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the failing auth attempt cannot be captured safely, report the missing stage evidence instead
+  of changing auth code from guesses.
+- If sensitive values appear in evidence, stop repeating them and summarize the shape only.
+- If fixing the failure requires external IdP console changes, provider credentials, production
+  tokens, live email or SMS delivery, or browser automation outside the command contract, report the
+  manual boundary.
+- If configured verification fails, preserve the failing intent and output tail, then fix only the
+  localized auth stage or test contract.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Auth flow triaged
+- Failing stage, sanitized attempt packet, and success comparator
+- Cookie, proxy, redirect, provider, token, JWKS, session, refresh, logout, passkey, MFA, rate limit,
+  enumeration, and authorization-after-login findings
+- Fix applied or recommended
+- Evidence level: configured-test evidence, static review risk, manual-only, missing, or not
+  applicable
+- Command intents run
+- Skipped auth diagnostics and reasons
+- Remaining auth-flow risk