mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/api-marketplace/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: api-marketplace
+version: 1.0.0
+min_mindforge_version: 10.7.0
+status: stable
+triggers: API marketplace internal, API discovery platform, API versioning governance, API deprecation workflow, API developer onboarding, API portal, API catalog, API consumer management, API usage tracking, API lifecycle governance, internal API standard, API documentation portal
+compose: api-versioning
+---
+
+# Skill — API Marketplace
+
+## When this skill activates
+
+This skill activates when the user is designing or implementing an internal API marketplace. This includes API discovery platforms, versioning governance, deprecation workflows, developer onboarding for API consumers, API portals, API catalogs, consumer management, usage tracking, API lifecycle governance, internal API standards, and documentation portals.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. Inventory all internal APIs (REST, GraphQL, gRPC, event streams) and assess current discoverability and documentation quality.
+2. Define API lifecycle stages (proposal, alpha, beta, stable, deprecated, retired) and governance requirements for each stage.
+3. Identify API consumer personas (internal developers, data teams, mobile engineers) and their discovery and onboarding needs.
+4. Establish API standards (authentication, versioning, error handling, pagination, rate limiting) that all APIs must follow.
+5. Assess current API sprawl: duplicate APIs, shadow APIs (not documented), orphaned APIs (no owner).
+
+### During implementation
+
+- **API Discovery:** Central catalog searchable by domain, team, capability, or keyword. Each API should have: name, description, owner, SLA, OpenAPI spec, example requests, status (alpha/beta/stable/deprecated). Discovery should return results in under 500ms.
+- **API Portal:** Single entry point for all internal APIs. Include: catalog, interactive docs (Swagger UI, GraphQL Playground), try-it-now sandbox, code examples in 3+ languages, changelog per API. Portal must be indexed by internal search.
+- **Versioning Governance:** Enforce consistent versioning strategy (see `api-versioning` skill). APIs must publish a deprecation policy (minimum 6-month notice for stable APIs). Breaking changes require new major version.
+- **Deprecation Workflow:** Automated workflow: API owner announces deprecation → sunset headers added → usage monitoring dashboard → consumer outreach (email + Slack) → grace period (6 months) → removal. Track deprecation status in catalog.
+- **Developer Onboarding:** New API consumers should go from discovery to first successful API call in under 15 minutes. Include: API key provisioning (self-service), quick-start guide, sandbox environment, example code, troubleshooting tips.
+- **Consumer Management:** Track which teams consume which APIs. Use API keys or OAuth clients for attribution. Consumer dashboard shows: usage metrics, quota limits, deprecation notices, breaking change alerts.
+- **Usage Tracking:** Collect per-consumer metrics: request count, error rate, latency, quota consumption. Expose to API owners via dashboard. Alert when consumers exceed 80% of quota or hit high error rates.
+- **API Lifecycle Governance:** Alpha APIs can break without notice. Beta APIs require 1-month deprecation notice. Stable APIs require 6-month notice. Retired APIs return 410 Gone. Enforce via automated policy checks.
+- **Internal API Standards:** All APIs must: use standard authentication (OAuth2 or API keys), include OpenAPI spec, provide health check endpoint, emit structured logs, track RED metrics. Standards enforced via linting (Spectral) and API gateway policies.
+
+### After implementation
+
+- Verify the API catalog includes 100% of production-facing internal APIs with ownership and OpenAPI specs.
+- Confirm API portal enables discovery-to-first-call in under 15 minutes via user testing.
+- Validate deprecation workflows include automated sunset headers and consumer outreach.
+- Ensure usage tracking is per-consumer with dashboards for API owners.
+- Check that API standards are enforced via automated linting and gateway policies.
+
+## Self-check before task completion
+
+- [ ] API catalog is searchable and includes 100% of internal APIs with ownership and specs.
+- [ ] API portal enables discovery-to-first-call in under 15 minutes.
+- [ ] Versioning governance enforces consistent strategy across all APIs.
+- [ ] Deprecation workflow includes sunset headers, monitoring, and 6-month grace period.
+- [ ] Developer onboarding is self-service with API key provisioning and sandbox access.
+- [ ] Consumer management tracks per-team usage with quota limits and alerts.
+- [ ] Usage tracking provides per-consumer metrics to API owners via dashboard.
+- [ ] API lifecycle governance enforces deprecation policies automatically.
+- [ ] Internal API standards are enforced via linting and API gateway policies.

package/.mindforge/skills/api-versioning/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: api-versioning
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: api version strategy, api deprecation lifecycle, breaking change detection, consumer contract strategy, sunset header strategy, version negotiation, api migration guide, backward compatibility strategy, api evolution pattern, api lifecycle management, api sunset policy, deprecation timeline
+---
+
+# API Versioning
+
+## When this skill activates
+
+This skill activates when the user is designing, implementing, or managing API
+versioning strategies. This includes choosing versioning schemes (URL, header, query),
+managing deprecation lifecycles, detecting breaking changes, implementing consumer-driven
+contracts, designing sunset policies, creating migration guides for consumers, and
+planning backward-compatible API evolution.
+
+## Mandatory actions
+
+### Before
+
+1. Identify the API type (REST, GraphQL, gRPC, event-driven) and existing versioning approach.
+2. Determine the consumer landscape (internal teams, external partners, public developers).
+3. Assess the current API lifecycle stage (greenfield, stable, legacy with many consumers).
+4. Review existing breaking change history and consumer migration friction.
+5. Check for contractual SLA obligations around API stability and deprecation timelines.
+
+### During
+
+**Versioning Strategies:**
+- **URL Path (`/v1/`, `/v2/`):** Most explicit, easiest for consumers to understand. Best for public APIs. Downside: duplicates route definitions.
+- **Header (`Accept: application/vnd.api+json;version=2`):** Cleaner URLs, version in content negotiation. Best for APIs with many versions. Downside: harder to test in browser.
+- **Query Parameter (`?version=2`):** Easy to implement, visible in URLs. Best for internal APIs. Downside: pollutes query string, caching complexity.
+- **No versioning (additive-only):** Evolve by only adding, never removing. Best for GraphQL. Downside: field bloat over time.
+- Choose ONE strategy per API surface. Do not mix approaches.
+
+**Breaking vs Non-Breaking Changes:**
+- **Breaking (requires new version):** Field removal, type change, adding required field, changing response structure, removing endpoint, changing authentication, altering error codes.
+- **Non-breaking (safe to deploy):** Adding optional field, adding new endpoint, adding optional query parameter, adding new enum value (if consumer ignores unknown), relaxing validation.
+- When in doubt, treat it as breaking. Consumer assumptions are hard to predict.
+
+**Deprecation Lifecycle:**
+- **Phase 1 — Announce:** Document deprecation in changelog, API docs, and developer portal. Set `Sunset` header (RFC 8594) with target date.
+- **Phase 2 — Sunset Header:** Return `Sunset: <date>` and `Deprecation: true` headers on every response from deprecated endpoints.
+- **Phase 3 — Migration Period:** Minimum 6 months for external APIs, 3 months for internal. Provide migration guide with code examples.
+- **Phase 4 — Usage Monitoring:** Track deprecated endpoint usage. Reach out to remaining consumers directly.
+- **Phase 5 — Removal:** Return 410 Gone with a body pointing to the new version. Remove after usage drops to zero (or contractual deadline).
+
+**Consumer-Driven Contracts:**
+- Consumers declare what fields/endpoints they actually use (contract).
+- Provider runs consumer contracts as part of CI (Pact, Spring Cloud Contract).
+- Breaking changes are detected automatically when a provider change violates a consumer contract.
+- Reduces false positives: only truly consumed features are protected.
+- Each consumer maintains their own contract; provider tests against all.
+
+**Sunset Header (RFC 8594):**
+- Format: `Sunset: Sat, 01 Jan 2028 00:00:00 GMT`
+- Accompanies `Deprecation: true` header.
+- Signals to automated tooling when an endpoint will be removed.
+- Include `Link` header pointing to migration documentation.
+- Example: `Link: <https://api.example.com/docs/migrate-v1-v2>; rel="sunset"`
+
+**Migration Guides:**
+- One guide per breaking change (not per version — granularity matters).
+- Include: what changed, why, before/after code examples, timeline.
+- Provide automated migration tooling where possible (codemods, SDK upgrades).
+- Offer a compatibility shim or adapter layer for complex migrations.
+- Test migration guide accuracy with a sample consumer before publishing.
+
+**Version Negotiation:**
+- Default to latest stable version if no version specified (for new consumers).
+- Return `API-Version` response header confirming which version served the request.
+- Support version discovery endpoint (`GET /versions` or API docs endpoint).
+- For header-based versioning, return 406 Not Acceptable if version is unsupported.
+
+**Backward Compatibility Strategies:**
+- Tolerant reader: consumers ignore unknown fields (Postel's law).
+- Additive evolution: only add, never remove or rename.
+- Envelope pattern: wrap responses so structure can evolve independently.
+- Feature flags: toggle new behavior per consumer via API keys or headers.
+
+### After
+
+1. Verify the chosen versioning strategy is consistently applied across all endpoints.
+2. Confirm deprecated endpoints include `Sunset` and `Deprecation` headers.
+3. Validate migration guides include before/after code examples.
+4. Check that consumer-driven contracts run in CI and detect breaking changes.
+5. Ensure monitoring tracks deprecated endpoint usage for removal decisions.
+
+## Self-check before task completion
+
+- [ ] A single versioning strategy is chosen and applied consistently.
+- [ ] Breaking vs non-breaking changes are clearly categorized.
+- [ ] Deprecation lifecycle includes announcement, sunset headers, migration period, and removal.
+- [ ] Migration period meets minimum duration (6 months external, 3 months internal).
+- [ ] Consumer-driven contracts detect breaking changes automatically in CI.
+- [ ] Sunset headers conform to RFC 8594 with linked documentation.
+- [ ] Migration guides provide per-change code examples.
+- [ ] Deprecated endpoint usage is monitored to inform removal timing.

package/.mindforge/skills/app-store-deployment/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: app-store-deployment
+version: 1.0.0
+min_mindforge_version: 10.4.0
+status: stable
+triggers: app store deployment, release management mobile, staged rollout mobile, app store compliance, app review guideline, mobile A/B testing, app store optimization deployment, mobile release pipeline, code push update, hot patch mobile, mobile feature flags, app store submission
+---
+
+# Skill — App Store Deployment & Release Management
+
+## When this skill activates
+This skill activates when managing mobile app releases, including app store submissions, staged rollouts, A/B testing, release automation, code push updates, or ensuring compliance with platform guidelines.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Review App Store Review Guidelines (iOS) and Google Play policies (Android) to ensure compliance
+2. Establish release checklist: version bumps, changelog, screenshots, metadata, certificates, entitlements
+3. Plan rollout strategy: percentage-based staged rollout, internal testing groups, beta testing timelines
+4. Configure feature flags or code push mechanism for post-release updates without app store review
+
+### During implementation
+- Implement proper build versioning (semantic versioning, build numbers, consistent across platforms)
+- Use Fastlane or similar automation for code signing, building, uploading, and screenshot generation
+- Configure app store metadata, descriptions, keywords, categories, and age ratings correctly
+- Set up staged rollout configuration (Google Play: percentage rollout, iOS: phased release)
+- Implement A/B testing framework with proper analytics events and experiment tracking
+- Use code push (CodePush, Expo Updates) for JavaScript-only changes that don't require app store review
+- Prepare app store assets: screenshots (all required device sizes), app previews, promotional text
+
+### After implementation
+- Submit to internal testing tracks first (TestFlight, Google Play Internal Testing) before production
+- Monitor crash rates and user feedback during staged rollout, pause if issues detected
+- Track rollout metrics: adoption rate, crash-free sessions, key performance indicators
+- Respond to app review feedback promptly with clarifications or necessary changes
+- Validate that all app store links, privacy policy URLs, and support contacts are functional
+
+## Self-check before task completion
+- [ ] App complies with platform guidelines (no private API usage, proper permission descriptions, content policies)
+- [ ] Release pipeline is automated with minimal manual steps (Fastlane, GitHub Actions, Bitrise, CircleCI)
+- [ ] Staged rollout is configured to gradually release to users with ability to halt if issues arise
+- [ ] Feature flags are in place for high-risk features to enable quick rollback without new submission
+- [ ] App store metadata is complete, optimized, and localized for target markets
+- [ ] Monitoring and alerting are configured to detect issues during rollout (crash rates, performance regressions)

package/.mindforge/skills/architecture-tradeoff-analysis/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: architecture-tradeoff-analysis
+version: 1.0.0
+min_mindforge_version: 10.1.0
+status: stable
+triggers: architecture tradeoff, ATAM, quality attribute scenario, sensitivity point, tradeoff point, risk theme, architecture evaluation, quality attribute tradeoff, architecture decision quality, non-functional tradeoff, architecture risk, scenario-based evaluation
+---
+
+# Architecture Tradeoff Analysis Method (ATAM)
+
+## When this skill activates
+
+This skill activates when the team needs to evaluate architectural decisions against
+competing quality attributes, identify sensitivity and tradeoff points, or assess
+architectural risk. It implements the ATAM methodology for systematic architecture
+evaluation using scenario-based analysis.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Present the architecture** — Document the current or proposed architecture with
+   sufficient detail: components, connectors, deployment topology, key design decisions,
+   and the rationale behind major choices.
+2. **Identify stakeholders** — List all parties with quality attribute concerns
+   (developers, ops, security, product, business).
+3. **Elicit quality attributes** — Gather the quality attributes that matter most for
+   this system from stakeholder interviews.
+
+### During
+
+4. **Define quality attributes under evaluation:**
+   - **Performance** — Latency, throughput, resource utilization targets.
+   - **Availability** — Uptime requirements, failover behavior, recovery time.
+   - **Security** — Authentication, authorization, data protection, audit requirements.
+   - **Modifiability** — Cost of change, deployment independence, backward compatibility.
+   - **Testability** — Isolation capability, observability, deterministic behavior.
+   - **Usability** — Learnability, efficiency, error recovery for operators and users.
+   - **Scalability** — Growth handling, elasticity, degradation under load.
+
+5. **Generate quality attribute scenarios** (for each relevant attribute):
+   - **Source** — Who or what causes the stimulus?
+   - **Stimulus** — What event or condition triggers the scenario?
+   - **Artifact** — What part of the system is affected?
+   - **Environment** — Under what conditions (normal, peak, degraded)?
+   - **Response** — What should the system do?
+   - **Response measure** — How do we know the response was acceptable?
+
+6. **Analyze via architectural approaches:**
+   - Map each scenario to the architectural decisions that address it.
+   - Identify which architectural patterns, tactics, or styles are employed.
+   - Assess whether the approach adequately satisfies the scenario's response measure.
+
+7. **Identify sensitivity points:**
+   - A sensitivity point is an architectural decision that critically affects ONE
+     quality attribute.
+   - Document: "If we change X, quality attribute Y is significantly affected."
+   - These are single-attribute risks.
+
+8. **Identify tradeoff points:**
+   - A tradeoff point is an architectural decision that affects MULTIPLE quality
+     attributes in opposing directions.
+   - Document: "Decision X improves attribute Y but degrades attribute Z."
+   - These are the hardest decisions and require explicit stakeholder prioritization.
+
+9. **Generate risk themes:**
+   - Cluster related sensitivity and tradeoff points into themes.
+   - Name each theme descriptively (e.g., "Performance vs. Security tension in
+     the authentication layer").
+   - Prioritize risk themes by business impact and likelihood.
+
+10. **Propose mitigations:**
+    - For each high-priority risk theme, propose architectural alternatives or
+      complementary tactics.
+    - Assess whether mitigations introduce new tradeoffs.
+
+### After
+
+11. **Document findings** — Produce an ATAM report with: architecture overview, quality
+    attribute tree, scenario table, sensitivity points, tradeoff points, risk themes,
+    and recommended actions.
+12. **Prioritize with stakeholders** — Present tradeoff points to stakeholders for
+    explicit priority decisions. Record their choices.
+13. **Feed into ADRs** — Convert key decisions into Architecture Decision Records with
+    tradeoff rationale preserved.
+
+## Self-check before task completion
+
+- [ ] Architecture presented with sufficient detail for analysis
+- [ ] Quality attributes identified and prioritized by stakeholders
+- [ ] At least 3 quality attribute scenarios generated per relevant attribute
+- [ ] Sensitivity points identified and documented
+- [ ] Tradeoff points identified with opposing quality attributes named
+- [ ] Risk themes generated from clustered findings
+- [ ] Stakeholder priorities recorded for tradeoff resolution
+- [ ] Mitigations proposed for high-priority risk themes
+- [ ] ATAM findings documented in a shareable format

package/.mindforge/skills/audit-logging/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: audit-logging
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: audit logging, immutable audit trail, audit event, who what when why, retention policy, compliance logging, tamper detection, audit query, audit archival, audit schema, change tracking, audit correlation
+---
+
+# Skill — Audit Logging
+
+## When this skill activates
+Any task involving audit trails, compliance logging, change tracking, tamper detection,
+event recording for accountability, or data retention policies.
+
+## Mandatory actions when this skill is active
+
+### Before implementing audit logging
+1. Identify what events must be audited (regulatory + business requirements).
+2. Define the retention policy (how long, where stored, who can access).
+3. Design the event schema before writing any code.
+
+### Event schema (the 5 Ws)
+
+Every audit event MUST capture:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **who** | user_id, IP address, session_id, service account | `{ userId: "u-123", ip: "10.0.1.5", sessionId: "sess-abc" }` |
+| **what** | action performed, resource affected, changes made | `{ action: "update", resource: "user/u-456", changes: { email: { from: "old@x.com", to: "new@x.com" } } }` |
+| **when** | UTC timestamp, monotonic sequence number | `{ timestamp: "2025-01-15T10:30:00Z", sequence: 1042 }` |
+| **why** | correlation_id, request_id, triggering event | `{ correlationId: "req-789", trigger: "user_request" }` |
+| **outcome** | success or failure, error details if failed | `{ status: "success" }` or `{ status: "failure", error: "permission_denied" }` |
+
+### Immutability guarantees
+
+**Append-only storage:**
+- Audit table has NO UPDATE or DELETE permissions for application roles.
+- Use a dedicated audit service account with INSERT-only grants.
+- Application database user must not have ALTER TABLE on audit tables.
+
+**Hash chain for tamper detection:**
+```
+event.hash = SHA-256(event.data + previous_event.hash)
+```
+- Each event references the hash of the previous event.
+- Broken chain = tampering detected.
+- Verify chain integrity on scheduled basis (daily audit job).
+
+**Alternative: immutable storage backends:**
+- AWS QLDB (purpose-built immutable ledger).
+- Object storage with Object Lock (S3 with WORM).
+- Append-only Kafka topic with compaction disabled.
+
+### Retention policy
+
+| Tier | Duration | Storage | Access |
+|------|----------|---------|--------|
+| Hot | 90 days | Primary database (indexed) | Real-time query |
+| Warm | 1 year | Object storage (Parquet/JSON) | Query via data warehouse |
+| Cold | 7+ years | Compressed archive (Glacier/equivalent) | Manual retrieval |
+
+**Rules:**
+- Define retention per event type (auth events may need longer than UI events).
+- Automate tier transitions (cron job moves hot → warm → cold).
+- Deletion must be cryptographic (delete encryption key, not data) for compliance.
+- Document retention policy in compliance documentation.
+
+### What to audit (mandatory events)
+
+**Authentication:**
+- Login success and failure (with failure reason).
+- Logout.
+- Password change / reset.
+- MFA enrollment / removal.
+- Session creation and termination.
+
+**Authorization:**
+- Permission grants and revocations.
+- Role assignments and removals.
+- Access denied events.
+
+**Data mutations:**
+- Create, update, delete of business entities.
+- Bulk operations (with count and scope).
+- Data exports and downloads.
+
+**Admin actions:**
+- Configuration changes.
+- User account management (create, disable, delete).
+- System setting modifications.
+
+**Failed access attempts:**
+- Rate limit violations.
+- Invalid token usage.
+- Attempts to access other tenants' data.
+
+### Querying audit logs
+
+**Required indexes:**
+- `user_id` — "show me everything user X did."
+- `resource_id` — "show me everything that happened to resource Y."
+- `timestamp` — "show me events in time range."
+- `action` — "show me all delete events."
+- `correlation_id` — "show me the full request chain."
+
+**Search capabilities:**
+- Full-text search on action descriptions.
+- Filter by outcome (success/failure).
+- Aggregate by user, resource, or time window.
+
+### Implementation patterns
+
+**Middleware/interceptor approach:**
+```
+Request → [Auth] → [Audit: log attempt] → Handler → [Audit: log outcome] → Response
+```
+
+**Event-driven approach:**
+- Domain events trigger audit entries asynchronously.
+- Decouples audit from business logic.
+- Risk: event loss if queue fails (use durable queue with DLQ).
+
+**Database trigger approach:**
+- PostgreSQL triggers capture all changes automatically.
+- No application code needed — cannot be bypassed.
+- Downside: less context (no user_id unless set in session).
+
+### Anti-patterns
+
+- Logging sensitive data in audit trail (passwords, full credit card numbers).
+- Audit log in same table/database as business data (lifecycle coupling).
+- Synchronous audit blocking the business transaction.
+- No alerting on audit failures (silent data loss).
+- Audit logs accessible to the application for modification.
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?

package/.mindforge/skills/auth-patterns/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: auth-patterns
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: auth architecture design, oauth2 flow design, oidc implementation, session strategy design, jwt architecture pattern, token rotation strategy, mfa flow design, social login integration, rbac model design, abac policy engine, authorization architecture, identity provider pattern
+compose: guardrails-and-safety
+---
+
+# Skill — Auth Patterns
+
+## When this skill activates
+Any task involving authentication flow design, authorization model selection,
+token lifecycle management, MFA implementation, or identity provider integration.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify the auth requirements: Who are the users? What are the trust boundaries?
+2. Select the appropriate OAuth2 flow for the client type.
+3. Decide between sessions and JWTs based on revocation requirements.
+4. Map out the authorization model (RBAC vs ABAC vs hybrid).
+
+### During implementation
+- Never store plain-text credentials anywhere.
+- Use short-lived access tokens (15 min max) with long-lived refresh tokens (7 days max).
+- Implement token rotation on every refresh (detect reuse = compromised).
+- Check permissions in code, never roles directly.
+- Log every auth failure with context (IP, user agent, timestamp).
+
+### After implementation
+- Verify no auth bypass exists on any protected route.
+- Test token expiration and refresh flows end-to-end.
+- Confirm MFA cannot be bypassed via API directly.
+- Run security scan on auth-related endpoints.
+
+## OAuth2 Flows
+
+### Authorization Code + PKCE (SPAs, Mobile)
+```
+1. Client generates code_verifier + code_challenge
+2. Redirect to /authorize with code_challenge
+3. User authenticates, IdP redirects with auth_code
+4. Client exchanges auth_code + code_verifier for tokens
+5. IdP verifies challenge, returns access + refresh tokens
+```
+Use for: Browser apps, mobile apps, any public client.
+
+### Client Credentials (Machine-to-Machine)
+```
+1. Service sends client_id + client_secret to /token
+2. IdP returns access token (no refresh token needed)
+3. Service uses access token for API calls
+```
+Use for: Backend services, cron jobs, microservice-to-microservice.
+
+### Device Authorization (CLI, TV)
+```
+1. Device requests device_code + user_code from /device/authorize
+2. User visits verification URL, enters user_code
+3. Device polls /token until user completes auth
+```
+Use for: CLI tools, IoT devices, smart TVs.
+
+## Session vs JWT
+
+### Sessions (Server-Side)
+- **Pros**: Instantly revocable, smaller payload, server controls lifetime.
+- **Cons**: Requires session store (Redis), sticky sessions or shared store in distributed systems.
+- **Use when**: You need instant revocation, have a monolith or can share session store.
+
+### JWT (Stateless)
+- **Pros**: No server-side storage, works across services, self-contained claims.
+- **Cons**: Cannot revoke until expiry (unless you add a blocklist, negating statelessness).
+- **Use when**: Microservices, short-lived tokens acceptable, combined with refresh token rotation.
+
+### Hybrid (Recommended)
+- Short-lived JWT access token (15 min) — never stored server-side.
+- Long-lived refresh token (7 days) — stored server-side, rotated on each use.
+- Revoke by deleting refresh token and waiting for access token expiry.
+
+## Token Rotation
+```
+1. Client sends refresh_token to /token
+2. Server issues NEW access_token + NEW refresh_token
+3. Server invalidates the OLD refresh_token
+4. If old refresh_token is used again → COMPROMISED
+5. Revoke entire token family (all refresh tokens for this session)
+```
+
+## MFA Implementation
+
+### TOTP (Time-Based One-Time Password) — Preferred
+- Generate shared secret, encode as QR code for authenticator apps.
+- Verify with time-window tolerance (±1 step = 30 seconds).
+- Store backup codes (hashed) for account recovery.
+
+### WebAuthn / Passkeys — Most Secure
+- Phishing-resistant (bound to origin).
+- No shared secrets to steal.
+- Use as primary or second factor.
+
+### SMS — Last Resort
+- Vulnerable to SIM swapping.
+- Use only if no alternative and combine with other signals.
+
+## Authorization Models
+
+### RBAC (Role-Based Access Control)
+```
+User → Role → Permissions → Actions
+
+// In code: check PERMISSION, not ROLE
+if (user.hasPermission('posts:delete')) { ... }
+// NOT: if (user.role === 'admin') { ... }
+```
+
+### ABAC (Attribute-Based Access Control)
+```
+Policy: user.department === resource.department AND user.clearance >= resource.classification
+
+// More flexible than RBAC, but harder to audit
+const allowed = evaluatePolicy(user.attributes, resource.attributes, action);
+```
+
+### Hybrid (RBAC + ABAC)
+- Use RBAC for coarse-grained access (can this user access this module?).
+- Use ABAC for fine-grained rules (can this user edit THIS specific resource?).
+
+## Anti-patterns to avoid
+- Storing JWT in localStorage (XSS vulnerable — use httpOnly cookies or memory).
+- Checking roles instead of permissions in application code.
+- Long-lived access tokens without refresh rotation.
+- MFA bypass via direct API calls (always enforce server-side).
+- Shared secrets in client-side code.
+- Missing auth on internal/admin routes ("it's internal" is not security).
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] No plain-text credentials stored anywhere?
+- [ ] Access tokens are short-lived (≤15 min)?
+- [ ] Refresh token rotation implemented and reuse detected?
+- [ ] Permissions checked in code (not roles)?
+- [ ] Every protected route has auth middleware?
+- [ ] Auth failures logged with sufficient context?
+- [ ] MFA cannot be bypassed via API?