# Harness Auth

> Harness Auth

- Skill: `intense-visions/harness-auth` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add intense-visions/harness-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/intense-visions/harness-auth/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Intense-Visions (https://skillmd.com/u/intense-visions)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/intense-visions/harness-auth

---

# 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.

## Evidence Requirements

When this skill makes claims about existing code, architecture, or behavior,
it MUST cite evidence using one of:

1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
   "existing bcrypt wrapper")
3. **Test/command output:** Inline or referenced output from a test run or CLI command
4. **Session evidence:** Write to the `evidence` session section via `manage_state`

**Uncited claims:** Technical assertions without citations MUST be prefixed with
`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.

## Red Flags

### Universal

These apply to ALL skills. If you catch yourself doing any of these, STOP.

- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
  reference. Belief is not evidence.
- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
  Search the codebase first. The project may already have a convention.
- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
  but do not expand scope beyond the stated task.

### Domain-Specific

- **"Let's store the token in localStorage for convenience"** — Stop. localStorage is accessible to XSS. Use httpOnly cookies or secure server-side storage.
- **"We can use a simple hash for passwords"** — Stop. Passwords require slow hashing (bcrypt, scrypt, argon2id). Fast hashes like MD5/SHA are crackable in seconds.
- **"Let's implement our own JWT validation"** — Stop. Use a vetted library. Custom crypto is a known source of vulnerabilities.
- **"The session expiry is just a UX concern"** — Stop. Session management is a security control. Timeout values are security-relevant configuration.

## Rationalizations to Reject

### Universal

These reasoning patterns sound plausible but lead to bad outcomes. Reject them.

- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
- **"This is best practice"** — Best practice in what context? Cite the source and
  confirm it applies to this codebase.
- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
  with a concrete follow-up plan.

### Domain-Specific

| Rationalization                                                      | Reality                                                                                             |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| "No one would guess this token format"                               | Security by obscurity. Tokens must be cryptographically secure regardless of format predictability. |
| "This is an internal service, auth is less critical"                 | Internal services are lateral movement targets. Authenticate all service boundaries.                |
| "The frontend validates permissions, so the backend doesn't need to" | Client-side checks are bypassable. Server-side authorization is the only real enforcement.          |

## 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."