@harness-engineering/cli 1.13.0 → 1.14.0

package/dist/agents/skills/gemini-cli/harness-api-design/SKILL.md

@@ -0,0 +1,304 @@
+# Harness API Design
+
+> Advisory guide for REST, GraphQL, and gRPC API design. Produces OpenAPI specs, GraphQL schemas, or proto definitions with versioning strategies and consistency validation.
+
+## When to Use
+
+- When designing new API endpoints for a feature or service
+- When adding routes to an existing Express, Fastify, NestJS, or Hono application
+- When defining a GraphQL schema or extending an existing one
+- When creating gRPC service definitions with Protocol Buffers
+- When establishing or updating an API versioning strategy
+- When reviewing an API surface for consistency before release
+- NOT for API security review (use harness-security-review for authentication, authorization, and injection analysis)
+- NOT for API performance testing (use harness-perf or harness-load-testing for benchmarks and load simulation)
+- NOT for database schema design that backs the API (use harness-database for schema and migration work)
+- NOT for event-driven async APIs (use harness-event-driven for message queues, webhooks, and pub/sub)
+
+## Process
+
+### Phase 1: DISCOVER -- Detect API Style and Existing Surface
+
+1. **Detect the API style.** Scan the project for stack signals. WHERE `openapi.*` or `swagger.*` files exist, THEN classify as REST. WHERE `*.graphql` or `schema.graphql` exists, THEN classify as GraphQL. WHERE `*.proto` files exist, THEN classify as gRPC. If the `--style` argument is provided, use that instead of auto-detection.
+
+2. **Map existing endpoints.** For REST projects, scan route files (`src/**/routes/**`, `src/**/controllers/**`) and extract HTTP method, path, request body, and response shape. For GraphQL, parse `schema.graphql` or code-first schema definitions. For gRPC, parse `.proto` files for service and rpc definitions.
+
+3. **Identify the framework.** Detect Express (`app.get`, `router.post`), Fastify (`fastify.route`), NestJS (`@Controller`, `@Get`), Hono (`app.get`), Apollo (`typeDefs`, `resolvers`), or gRPC libraries (`@grpc/grpc-js`, `grpc-node`). Framework detection drives phase 2 recommendations.
+
+4. **Catalog existing conventions.** Record naming patterns (camelCase vs kebab-case paths), response envelope structure (e.g., `{ data, error, meta }`), pagination style (cursor vs offset), and error format (RFC 7807, custom). These become the baseline that new endpoints must follow.
+
+5. **Check for an existing OpenAPI spec.** If `openapi.yaml` or `openapi.json` exists, parse it and compare against the actual route definitions. Flag any drift where the spec does not match the implementation.
+
+### Phase 2: DESIGN -- Produce Endpoint Definitions and Schemas
+
+1. **Define resource models.** For each new resource, produce a schema with required fields, types, nullable markers, and validation constraints. Use JSON Schema for REST, GraphQL type definitions for GraphQL, or message definitions for gRPC.
+
+2. **Design endpoint signatures.** For REST: define method, path, path parameters, query parameters, request body schema, and response schema. Follow the conventions cataloged in phase 1. For GraphQL: define queries, mutations, and input types. For gRPC: define service RPCs with request and response messages.
+
+3. **Apply versioning strategy.** WHERE a versioning strategy is already in use, THEN follow it. WHERE no strategy exists, THEN recommend URL-path versioning (`/v1/resources`) for REST, schema evolution with `@deprecated` for GraphQL, or package versioning for gRPC. Document the strategy for future endpoints.
+
+4. **Design error responses.** For REST: use RFC 7807 Problem Details unless the project already uses a different format. Include `type`, `title`, `status`, `detail`, and `instance`. For GraphQL: use the `errors` array with `extensions.code`. For gRPC: use standard status codes with detailed error metadata.
+
+5. **Define pagination.** WHERE the endpoint returns a collection, THEN include pagination. Recommend cursor-based pagination for real-time data and offset-based for static datasets. Define the pagination envelope: `{ data: [], pagination: { cursor, hasMore } }` or equivalent.
+
+6. **Specify rate limiting and caching headers.** For each endpoint, recommend `Cache-Control`, `ETag`, and `Vary` headers where applicable. Identify endpoints that should be rate-limited and suggest `X-RateLimit-*` headers.
+
+### Phase 3: VALIDATE -- Check Against Best Practices
+
+1. **Verify naming consistency.** All resource names must follow the same convention (plural nouns for REST collections, singular for GraphQL types). Path segments must use the same casing throughout. Flag any deviation from the conventions cataloged in phase 1.
+
+2. **Check HTTP method correctness.** WHERE a REST endpoint modifies state, THEN it must not use GET. WHERE an endpoint is idempotent, THEN it should use PUT over POST. WHERE an endpoint creates a resource, THEN it must return 201 with a Location header.
+
+3. **Validate schema completeness.** Every endpoint must have a defined request schema (if it accepts input) and response schema. No `any` types. No untyped response bodies. For GraphQL, every field must have an explicit type. For gRPC, no `google.protobuf.Any` unless justified.
+
+4. **Check backward compatibility.** WHERE this is an update to an existing API, THEN verify that no required fields were added to request schemas, no fields were removed from response schemas, no endpoint paths changed, and no response status codes changed. Flag breaking changes explicitly.
+
+5. **Verify OpenAPI spec validity.** Run the OpenAPI spec through structural validation. Check for missing descriptions, missing examples, and undefined `$ref` targets. For GraphQL, validate the schema parses without errors. For gRPC, verify proto files compile with `protoc`.
+
+### Phase 4: DOCUMENT -- Generate or Update Specifications
+
+1. **Generate the OpenAPI spec.** For REST APIs, produce or update an `openapi.yaml` file with all endpoints, schemas, examples, and security definitions. Use OpenAPI 3.1 unless the project already uses 3.0. Include `operationId` for every endpoint.
+
+2. **Generate GraphQL schema documentation.** For GraphQL APIs, ensure every type, field, query, and mutation has a description. Produce a schema file that can be used for introspection. Add deprecation notices to fields being phased out.
+
+3. **Generate proto documentation.** For gRPC APIs, ensure every service, rpc, message, and field has a comment. Verify the proto file includes package name, syntax version, and appropriate options.
+
+4. **Produce a changelog entry.** For updates to existing APIs, write a changelog entry listing new endpoints, modified endpoints, deprecated endpoints, and breaking changes (if any). Follow the project's changelog format.
+
+5. **Create request/response examples.** For every new endpoint, include at least one success example and one error example in the spec. Examples must use realistic data, not placeholders like `"string"` or `0`.
+
+## Harness Integration
+
+- **`harness validate`** -- Run after generating specs to confirm project health
+- **`harness scan`** -- Refresh the knowledge graph after adding new route files
+- **`query_graph`** -- Trace dependencies between routes, controllers, and services
+- **`get_impact`** -- Understand blast radius when modifying shared API schemas
+
+## Success Criteria
+
+- API style was correctly detected or explicitly specified
+- Existing conventions were cataloged and followed in new designs
+- Every new endpoint has a complete schema (request and response)
+- Versioning strategy is documented and applied
+- Error responses follow a consistent format with machine-readable codes
+- OpenAPI/GraphQL/proto spec is valid and matches the implementation
+- No backward-incompatible changes were introduced without explicit flagging
+- Pagination, caching, and rate limiting were addressed for applicable endpoints
+
+## Examples
+
+### Example: REST API Design with Express
+
+**Input:** "Design CRUD endpoints for a blog posts resource in our Express app."
+
+**Phase 1 -- DISCOVER:**
+
+```
+Detected: REST API (Express 4.x)
+Routes directory: src/routes/
+Existing endpoints: GET /v1/users, POST /v1/users, GET /v1/users/:id
+Conventions: kebab-case paths, plural nouns, /v1/ prefix
+Response envelope: { data, meta, error }
+Pagination: cursor-based ({ cursor, limit })
+Error format: RFC 7807 Problem Details
+OpenAPI spec: openapi.yaml (last updated 2 weeks ago, 1 drift: missing GET /v1/users/:id/settings)
+```
+
+**Phase 2 -- DESIGN:**
+
+```yaml
+paths:
+  /v1/posts:
+    get:
+      operationId: listPosts
+      parameters:
+        - name: cursor
+          in: query
+          schema: { type: string }
+        - name: limit
+          in: query
+          schema: { type: integer, default: 20, maximum: 100 }
+        - name: status
+          in: query
+          schema: { type: string, enum: [draft, published, archived] }
+      responses:
+        200:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { type: array, items: { $ref: '#/components/schemas/Post' } }
+                  meta:
+                    type: object
+                    properties:
+                      cursor: { type: string, nullable: true }
+                      hasMore: { type: boolean }
+    post:
+      operationId: createPost
+      requestBody:
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/CreatePostInput' }
+      responses:
+        201:
+          headers:
+            Location: { schema: { type: string } }
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: '#/components/schemas/Post' }
+```
+
+**Phase 3 -- VALIDATE:**
+
+```
+Naming: PASS -- /v1/posts follows plural noun convention
+Methods: PASS -- GET for reads, POST for creation
+Schemas: PASS -- all endpoints have request/response schemas
+Compatibility: N/A -- new resource, no existing contract
+OpenAPI: WARN -- existing spec drift detected (1 endpoint missing)
+```
+
+**Phase 4 -- DOCUMENT:**
+Updated `openapi.yaml` with 5 new endpoints, 3 new schemas, and examples. Fixed existing drift for `GET /v1/users/:id/settings`.
+
+### Example: GraphQL Schema Extension with Apollo
+
+**Input:** "Add a comments system to our GraphQL API."
+
+**Phase 1 -- DISCOVER:**
+
+```
+Detected: GraphQL (Apollo Server 4, code-first with typeDefs)
+Schema: src/schema/typeDefs.ts
+Existing types: User, Post, Category
+Resolvers: src/resolvers/
+Conventions: PascalCase types, camelCase fields, relay-style connections for pagination
+```
+
+**Phase 2 -- DESIGN:**
+
+```graphql
+type Comment {
+  id: ID!
+  body: String!
+  author: User!
+  post: Post!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+  parentComment: Comment
+  replies(first: Int, after: String): CommentConnection!
+}
+
+type CommentConnection {
+  edges: [CommentEdge!]!
+  pageInfo: PageInfo!
+}
+
+type CommentEdge {
+  node: Comment!
+  cursor: String!
+}
+
+input CreateCommentInput {
+  postId: ID!
+  body: String!
+  parentCommentId: ID
+}
+
+extend type Query {
+  comments(postId: ID!, first: Int, after: String): CommentConnection!
+}
+
+extend type Mutation {
+  createComment(input: CreateCommentInput!): Comment!
+  updateComment(id: ID!, body: String!): Comment!
+  deleteComment(id: ID!): Boolean!
+}
+
+extend type Post {
+  comments(first: Int, after: String): CommentConnection!
+  commentCount: Int!
+}
+```
+
+**Phase 3 -- VALIDATE:**
+
+```
+Naming: PASS -- PascalCase types, camelCase fields
+Pagination: PASS -- relay-style connections with PageInfo
+Types: PASS -- all fields explicitly typed, no Any
+Compatibility: PASS -- uses extend, no modifications to existing types
+```
+
+### Example: gRPC Service Definition
+
+**Input:** "Define a notification service for our microservices platform."
+
+**Phase 1 -- DISCOVER:**
+
+```
+Detected: gRPC (proto3, @grpc/grpc-js)
+Proto directory: proto/
+Existing services: UserService, OrderService
+Package: platform.v1
+Conventions: PascalCase services and messages, snake_case fields
+```
+
+**Phase 2 -- DESIGN:**
+
+```protobuf
+syntax = "proto3";
+
+package platform.v1;
+
+import "google/protobuf/timestamp.proto";
+
+service NotificationService {
+  // Send a notification to a specific user.
+  rpc SendNotification(SendNotificationRequest) returns (SendNotificationResponse);
+
+  // List notifications for a user with cursor pagination.
+  rpc ListNotifications(ListNotificationsRequest) returns (ListNotificationsResponse);
+
+  // Mark a notification as read.
+  rpc MarkAsRead(MarkAsReadRequest) returns (MarkAsReadResponse);
+
+  // Stream real-time notifications for a user.
+  rpc StreamNotifications(StreamNotificationsRequest) returns (stream Notification);
+}
+
+message Notification {
+  string id = 1;
+  string user_id = 2;
+  string title = 3;
+  string body = 4;
+  NotificationType type = 5;
+  bool is_read = 6;
+  google.protobuf.Timestamp created_at = 7;
+}
+
+enum NotificationType {
+  NOTIFICATION_TYPE_UNSPECIFIED = 0;
+  NOTIFICATION_TYPE_ORDER_UPDATE = 1;
+  NOTIFICATION_TYPE_SYSTEM_ALERT = 2;
+  NOTIFICATION_TYPE_PROMOTION = 3;
+}
+```
+
+## Gates
+
+- **Every endpoint must have a complete schema.** No endpoint may be added without defined request parameters, request body (if applicable), response body, and error responses. An endpoint without a schema is not designed -- it is a stub.
+- **Breaking changes must be explicitly flagged.** WHERE a change removes a field, renames an endpoint, or adds a required request parameter, THEN the skill must flag it as a breaking change and halt until the human acknowledges the break. Silent breaking changes are not permitted.
+- **Generated specs must be valid.** The OpenAPI spec must pass structural validation. The GraphQL schema must parse without errors. Proto files must compile with `protoc`. An invalid spec is worse than no spec.
+- **Naming conventions must be consistent.** WHERE the project uses a naming convention (detected in phase 1), THEN all new endpoints must follow it. A single inconsistent name pollutes the entire API surface.
+
+## Escalation
+
+- **No existing conventions detected:** When the project has no existing API endpoints and no spec file, the skill cannot infer conventions. Report: "No existing API conventions found. Provide a style guide or approve the defaults (plural nouns, kebab-case paths, RFC 7807 errors, cursor pagination) before proceeding."
+- **Breaking change required by the feature:** When the requested feature inherently requires a breaking change (e.g., restructuring a response), present the break explicitly with migration guidance: "This feature requires removing the `legacyField` from the response. Recommend a deprecation period: add `newField` in v1, remove `legacyField` in v2."
+- **Conflicting API styles in the same project:** When both REST routes and GraphQL resolvers exist, ask: "This project has both REST and GraphQL endpoints. Which style should the new feature use? Mixing styles for the same resource creates maintenance burden."
+- **OpenAPI spec severely out of date:** When more than 30% of implemented endpoints are missing from the spec, flag: "The OpenAPI spec is significantly drifted from implementation (N endpoints missing). Recommend a full spec regeneration before adding new endpoints to avoid compounding the drift."

package/dist/agents/skills/gemini-cli/harness-api-design/skill.yaml

@@ -0,0 +1,74 @@
+name: harness-api-design
+version: "1.0.0"
+description: REST, GraphQL, gRPC API design with OpenAPI specs and versioning strategies
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-api-design
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: style
+      description: "API style: rest, graphql, or grpc. Auto-detected when omitted."
+      required: false
+    - name: versioning
+      description: "Versioning strategy: url-path, header, or query-param. Defaults to url-path."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-api-design
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - API
+  - REST
+  - GraphQL
+  - gRPC
+  - OpenAPI
+  - swagger
+  - endpoint
+  - versioning
+  - schema
+  - protobuf
+stack_signals:
+  - "openapi.*"
+  - "swagger.*"
+  - "*.proto"
+  - "schema.graphql"
+  - "*.graphql"
+  - "src/**/routes/**"
+  - "src/**/controllers/**"
+  - "src/**/resolvers/**"
+phases:
+  - name: discover
+    description: Detect API style, existing endpoints, and technology stack
+    required: true
+  - name: design
+    description: Produce endpoint definitions, schemas, and versioning plan
+    required: true
+  - name: validate
+    description: Verify design against REST/GraphQL/gRPC best practices and consistency rules
+    required: true
+  - name: document
+    description: Generate or update OpenAPI spec, GraphQL schema, or proto definitions
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/harness-architecture-advisor/skill.yaml

@@ -28,6 +28,7 @@ mcp:
     skill: harness-architecture-advisor
     path: string
 type: flexible
+tier: 2
 phases:
   - name: discover
     description: Ask questions about the problem space and constraints

package/dist/agents/skills/gemini-cli/harness-auth/SKILL.md

@@ -0,0 +1,279 @@
+# Harness Auth
+
+> OAuth2, JWT, RBAC/ABAC, session management, and MFA pattern analysis. Detects authentication and authorization mechanisms, evaluates security posture against OWASP guidelines, and recommends improvements for token lifecycle, permission models, and multi-factor authentication.
+
+## When to Use
+
+- When implementing or modifying authentication flows (login, registration, password reset, OAuth2)
+- On PRs that change authorization logic, middleware guards, or permission models
+- To audit existing auth implementation for security vulnerabilities and best practice compliance
+- NOT for network-level security or infrastructure hardening (use harness-security-review)
+- NOT for compliance framework audits (use harness-compliance for SOC2/HIPAA/GDPR)
+- NOT for secrets management or credential rotation (use harness-secrets)
+
+## Process
+
+### Phase 1: DETECT -- Identify Auth Mechanisms and Providers
+
+1. **Discover authentication providers.** Scan the codebase for auth framework usage:
+   - Passport.js: `passport.use()`, strategy configurations, `passport.authenticate()` calls
+   - NextAuth.js / Auth.js: `next-auth` config, provider definitions, callback handlers
+   - Auth0: `@auth0/nextjs-auth0`, `auth0-js`, management API client initialization
+   - Firebase Auth: `firebase/auth`, `signInWithPopup`, `onAuthStateChanged` usage
+   - Custom: JWT signing/verification, bcrypt hashing, session store initialization
+   - Spring Security: `@EnableWebSecurity`, `SecurityFilterChain`, `UserDetailsService`
+   - ASP.NET Identity: `AddAuthentication()`, `[Authorize]` attributes, `ClaimsPrincipal`
+
+2. **Map token flows.** Trace the authentication lifecycle:
+   - Token issuance: Where and how are JWTs or session tokens created?
+   - Token storage: Cookie (httpOnly, secure, sameSite?), localStorage, sessionStorage, or in-memory?
+   - Token refresh: Is there a refresh token flow? What is the access token lifetime?
+   - Token revocation: Can tokens be invalidated before expiry? Is there a blocklist?
+   - Token propagation: How are tokens passed between services (Authorization header, cookie, custom header)?
+
+3. **Identify authorization models.** Determine how permissions are enforced:
+   - RBAC: Role definitions, role-to-permission mappings, role assignment to users
+   - ABAC: Attribute-based policies, policy evaluation engine, context attributes
+   - ACL: Per-resource access control lists, ownership checks
+   - Middleware guards: Express middleware, NestJS guards, Spring interceptors, ASP.NET policies
+   - Route-level: Declarative route protection, public vs protected route definitions
+
+4. **Check for MFA implementation.** Look for multi-factor authentication:
+   - TOTP: `otplib`, `speakeasy`, Google Authenticator integration
+   - SMS/Email OTP: Twilio, SendGrid verification flows
+   - WebAuthn/FIDO2: `@simplewebauthn/server`, hardware key registration
+   - Recovery codes: Generation, storage, and redemption logic
+
+5. **Inventory session management.** If sessions are used:
+   - Session store: Redis, database, in-memory, or cookie-based
+   - Session lifecycle: creation, renewal, expiry, and destruction
+   - Concurrent session handling: single-session enforcement, session listing
+
+---
+
+### Phase 2: ANALYZE -- Evaluate Security Posture
+
+1. **Check JWT implementation against OWASP guidelines.** Verify:
+   - Algorithm is explicitly set (no `alg: none` vulnerability)
+   - Secret/key is sufficiently strong (RS256/ES256 preferred over HS256 for distributed systems)
+   - Token lifetime is appropriate (access: 15-60 min, refresh: 7-30 days)
+   - Claims include `iss`, `aud`, `exp`, `iat`, and `sub` at minimum
+   - Tokens are validated on every request, not just on login
+   - JWTs are not stored in localStorage (XSS vulnerability)
+
+2. **Evaluate OAuth2/OIDC flows.** If OAuth2 is used:
+   - Is PKCE used for public clients (SPAs, mobile apps)?
+   - Are redirect URIs strictly validated (no open redirect)?
+   - Is the state parameter used to prevent CSRF?
+   - Are scopes minimized to the principle of least privilege?
+   - Is token exchange happening server-side (not exposing client secret)?
+
+3. **Assess password handling.** If password authentication exists:
+   - Hashing algorithm: bcrypt, scrypt, or argon2 (not MD5, SHA-1, or SHA-256 without salt)
+   - Salt: unique per user, generated with cryptographic RNG
+   - Password policy: minimum length, complexity requirements, breach database check
+   - Rate limiting on login attempts (brute force protection)
+   - Account lockout or CAPTCHA after failed attempts
+
+4. **Review authorization enforcement.** For each protected resource:
+   - Is authorization checked at the API layer (not just the UI)?
+   - Are there IDOR (Insecure Direct Object Reference) vulnerabilities?
+   - Is the permission check granular enough (not just "is authenticated")?
+   - Are admin routes protected by role checks, not just authentication?
+   - Is horizontal privilege escalation prevented (user A cannot access user B's data)?
+
+5. **Check session security.** If sessions are used:
+   - Session ID entropy: cryptographically random, sufficient length
+   - Cookie flags: `httpOnly`, `secure`, `sameSite=Strict` or `sameSite=Lax`
+   - Session fixation prevention: regenerate ID on login
+   - Session timeout: absolute and idle timeout configured
+   - CSRF protection: token-based or SameSite cookie
+
+---
+
+### Phase 3: DESIGN -- Recommend Improvements
+
+1. **Token lifecycle improvements.** Based on analysis findings:
+   - Recommend specific token lifetimes with rationale
+   - Design refresh token rotation (one-time-use refresh tokens with family tracking)
+   - Propose token revocation strategy (blocklist in Redis with TTL matching token expiry)
+   - If using JWTs in cookies: recommend cookie configuration (httpOnly, secure, sameSite, path, domain)
+
+2. **Permission model design.** Based on the application's needs:
+   - For simple apps: RBAC with predefined roles (admin, editor, viewer)
+   - For multi-tenant apps: RBAC with tenant-scoped roles
+   - For complex resource access: ABAC with policy engine (CASL, Casbin, Open Policy Agent)
+   - Generate permission matrix: roles/attributes x resources x actions
+
+3. **MFA implementation plan.** If MFA is missing or incomplete:
+   - Recommend TOTP as baseline (widely supported, no SMS dependency)
+   - Design enrollment flow: QR code generation, backup codes, verification step
+   - Design authentication flow: primary factor -> MFA challenge -> session creation
+   - Recommend WebAuthn as optional upgrade path for phishing resistance
+
+4. **Security hardening recommendations.** Prioritized by risk:
+   - P0: Fix any authentication bypass, broken access control, or token vulnerability
+   - P1: Add missing CSRF protection, fix insecure token storage, add rate limiting
+   - P2: Implement MFA, add session management improvements, enhance logging
+   - P3: Add breach notification flow, implement progressive security (step-up auth)
+
+5. **Generate implementation guidance.** Produce:
+   - Middleware/guard code templates for the project's framework
+   - Migration plan for moving from insecure to secure token storage
+   - Database schema for RBAC tables (users, roles, permissions, user_roles)
+   - Configuration templates for OAuth2 providers
+
+---
+
+### Phase 4: VALIDATE -- Verify Against OWASP and Common Vulnerabilities
+
+1. **OWASP Authentication Verification.** Check against OWASP ASVS (Application Security Verification Standard) Level 2:
+   - V2.1: Password security (hashing, policy, breach check)
+   - V2.2: General authenticator security (MFA, recovery codes)
+   - V2.5: Credential recovery (secure reset flow, no secret questions)
+   - V2.7: Out-of-band verification (email/SMS verification security)
+   - V2.8: Single or multi-factor authentication (session binding)
+
+2. **OWASP Authorization Verification.** Check against OWASP ASVS:
+   - V4.1: Access control design (deny by default, least privilege)
+   - V4.2: Operation-level access control (every API endpoint protected)
+   - V4.3: Data-level access control (row-level security, tenant isolation)
+
+3. **Test coverage verification.** Check that auth logic is tested:
+   - Authentication tests: valid login, invalid credentials, expired tokens, refresh flow
+   - Authorization tests: permitted access, denied access, privilege escalation attempt
+   - Edge cases: expired session, concurrent sessions, token replay, CSRF
+   - Integration tests: full OAuth2 flow with mocked provider
+
+4. **Verify logging and monitoring.** Confirm security events are logged:
+   - Successful and failed login attempts with timestamps and IP addresses
+   - Password changes and account recovery events
+   - Permission changes and role assignments
+   - Token refresh and revocation events
+   - Log format must not include passwords, tokens, or session IDs
+
+5. **Produce the auth audit report.** Output a structured summary:
+   - Authentication mechanism inventory
+   - OWASP ASVS compliance status by section
+   - Prioritized findings with severity and remediation
+   - Permission model diagram or matrix
+   - Recommended implementation timeline
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-auth`** -- Primary CLI entry point. Runs all four phases.
+- **`harness validate`** -- Run after implementing auth changes to verify project integrity.
+- **`harness check-deps`** -- Verify auth library dependencies are properly declared and up to date.
+- **`emit_interaction`** -- Used at permission model design (checkpoint:decision) when choosing between RBAC and ABAC, and before recommending OAuth2 provider changes.
+- **`Glob`** -- Discover auth middleware, guard files, policy definitions, and session configurations.
+- **`Grep`** -- Search for JWT signing, password hashing, token validation, and authorization checks.
+- **`Write`** -- Generate permission matrices, migration plans, and middleware templates.
+- **`Edit`** -- Update existing auth middleware, guards, and token configurations.
+
+## Success Criteria
+
+- All authentication providers and token flows are mapped with specific file locations
+- JWT implementation is checked against all OWASP ASVS V2 requirements
+- Authorization model is documented with a permission matrix covering all roles and resources
+- Every finding includes a severity level, specific file location, and concrete remediation step
+- Token storage recommendations specify exact cookie flags or storage mechanism
+- Security event logging is verified to capture auth events without leaking sensitive data
+
+## Examples
+
+### Example: Next.js Application with NextAuth.js and Prisma
+
+```
+Phase 1: DETECT
+  Provider: NextAuth.js v4 in src/app/api/auth/[...nextauth]/route.ts
+  Strategies: Google OAuth2, GitHub OAuth2, email/password (credentials provider)
+  Token flow: JWT mode, access token in httpOnly cookie, 30-day expiry
+  Authorization: Custom middleware in src/middleware.ts checking session.user.role
+  Roles: admin, member (stored in User table via Prisma)
+  MFA: Not implemented
+  Session store: JWT-based (no server-side session)
+
+Phase 2: ANALYZE
+  Findings:
+    [HIGH] JWT expiry 30 days is excessive — recommend 1 hour with refresh token
+    [HIGH] Credentials provider uses bcrypt cost factor 8 — recommend 12
+    [MEDIUM] No PKCE on OAuth2 flows (NextAuth handles this but verify config)
+    [MEDIUM] No rate limiting on /api/auth/callback/credentials
+    [LOW] Role check only in middleware — no API-level authorization guards
+    [LOW] No audit logging for login events
+
+Phase 3: DESIGN
+  Recommendations:
+    1. Switch to database sessions with 1-hour access, 7-day refresh
+    2. Increase bcrypt rounds to 12 in credentials provider
+    3. Add rate-limiter-flexible middleware on auth endpoints (5 attempts/15min)
+    4. Create src/lib/guards/requireRole.ts middleware for API routes
+    5. Add TOTP MFA via otplib with QR enrollment flow
+    6. Add auth event logging to audit table via Prisma middleware
+
+Phase 4: VALIDATE
+  OWASP ASVS V2 status:
+    V2.1 Password Security: PARTIAL (hashing OK, cost factor low, no breach check)
+    V2.2 Authenticator Security: FAIL (no MFA)
+    V2.5 Credential Recovery: PASS (email-based reset via NextAuth)
+    V4.1 Access Control Design: PARTIAL (roles exist, enforcement incomplete)
+  Test coverage: 60% — missing tests for role escalation and token expiry
+```
+
+### Example: NestJS API with Passport.js, JWT, and CASL
+
+```
+Phase 1: DETECT
+  Provider: Passport.js with passport-jwt and passport-local strategies
+  Token flow:
+    - Access token: RS256 JWT, 15-min expiry, in Authorization header
+    - Refresh token: opaque, 30-day expiry, in httpOnly cookie
+    - Token refresh endpoint: POST /auth/refresh
+  Authorization: CASL abilities defined in src/casl/ability.factory.ts
+  Roles: super-admin, org-admin, member, viewer (stored in PostgreSQL)
+  MFA: TOTP via speakeasy, WebAuthn via @simplewebauthn/server
+  Session: Stateless JWT (no server-side session)
+
+Phase 2: ANALYZE
+  Findings:
+    [HIGH] Refresh token not rotated on use — token replay possible
+    [MEDIUM] CASL abilities not checked on 3 admin endpoints (src/admin/admin.controller.ts)
+    [MEDIUM] No token blocklist — revoked tokens valid until expiry
+    [LOW] WebAuthn registration does not verify attestation
+    [LOW] Login failure logging does not include client IP
+
+Phase 3: DESIGN
+  Recommendations:
+    1. Implement refresh token rotation with family tracking in Redis
+       - On refresh: invalidate old token, issue new pair
+       - On reuse of old token: revoke entire token family (detect theft)
+    2. Add @CheckPolicies() decorator to admin.controller.ts endpoints
+    3. Add Redis-backed token blocklist with TTL = access token lifetime
+    4. Add attestation verification for WebAuthn with expected origin check
+    5. Enhance auth logging with IP, user-agent, and geolocation
+
+Phase 4: VALIDATE
+  OWASP ASVS V2 status:
+    V2.1 Password Security: PASS
+    V2.2 Authenticator Security: PASS (TOTP + WebAuthn)
+    V2.8 Multi-Factor: PASS
+    V4.1 Access Control: PARTIAL (CASL defined, 3 endpoints uncovered)
+    V4.3 Data-Level: PASS (CASL policies include tenant isolation)
+  Test coverage: 85% — missing tests for token family revocation
+```
+
+## Gates
+
+- **No authentication bypass findings left unresolved.** Any finding that allows unauthenticated access to a protected resource is a P0 blocker. The auth audit cannot be marked complete while bypass vulnerabilities exist.
+- **No tokens stored in localStorage.** JWTs or session tokens in localStorage are accessible via XSS. This is a blocking finding. Tokens must be stored in httpOnly cookies or secure server-side sessions.
+- **No plaintext or weakly hashed passwords.** MD5, SHA-1, or unsalted SHA-256 for password storage is a blocking finding. Passwords must use bcrypt (cost 12+), scrypt, or argon2id.
+- **No authorization checks skipped at the API layer.** UI-only authorization is not authorization. Every API endpoint that serves user-specific or role-restricted data must enforce permissions server-side.
+
+## Escalation
+
+- **When the auth architecture requires a fundamental redesign:** Report: "The current auth implementation has [N] high-severity findings that require architectural changes (e.g., switching from localStorage tokens to httpOnly cookies). This is not a patch — recommend a dedicated auth migration sprint with a rollback plan."
+- **When third-party auth provider documentation is insufficient:** Report: "The [provider] SDK does not document [specific behavior]. Recommend testing the behavior empirically in a sandbox environment and documenting the findings in the project's auth architecture doc."
+- **When MFA adoption requires UX changes beyond the auth layer:** Report: "Implementing MFA requires changes to [login flow, account settings, recovery flow]. Coordinate with the frontend team to design the enrollment and challenge UX before implementing the backend."
+- **When the permission model is too simple for current requirements:** Report: "The current RBAC model with [N] roles cannot express [specific access pattern]. Recommend evaluating ABAC with [CASL/Casbin/OPA] to support attribute-based policies. This is a significant migration — plan for 2-3 sprints."