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

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