secure-scan-js/wasm-version/AUTH.md

A JavaScript implementation of Yelp's detect-secrets tool - no Python required

# CLI Authentication Flow

## Overview

The CLI authentication workflow allows users to authenticate using their web credentials in a browser, and then use the CLI tool seamlessly. This document explains how the authentication flow works and how to use it.

## Commands

### Login

```bash
yarn custom:login
```

This command:
1. Opens your default web browser to the authentication page
2. Starts a local server on port 3005 to receive the callback
3. After successful authentication, captures the token and stores it locally
4. Token is valid for 3 minutes (180 seconds)

### Check Status

```bash
yarn custom:status
```

This command:
1. Checks if you have a valid authentication token
2. Shows if the token is valid or expired
3. Displays time remaining until expiration

### Logout

```bash
yarn custom:logout
```

This command:
1. Removes your authentication token
2. Logs you out of the current session

## How It Works

1. **Web-based Authentication**: 
   - The CLI opens your browser to authenticate
   - You log in using your regular web credentials
   - The web app redirects back to the local CLI server with a token

2. **Token Storage**:
   - The token is stored in `.detect-secrets-token.json` in your home directory
   - Tokens are valid for 3 minutes by default
   - Token includes expiration timestamp

3. **Security Features**:
   - CSRF protection using a random state parameter
   - Local server only runs during the authentication process
   - Token has a short lifetime

## Troubleshooting

- If authentication fails, try running `yarn custom:login` again
- If the browser doesn't open automatically, manually open the URL shown in the terminal
- If you see "Port in use" errors, you may have another authentication process running