> For the complete documentation index, see [llms.txt](https://docs.soapjs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soapjs.com/plugins/node.js/soap-auth.md).

# Soap Auth

`@soapjs/soap-auth` provides authentication strategies and a small manager that wires them into your app. It integrates with `@soapjs/soap-express` in one call.

> Current version: **0.4.x**.

### Strategies

* **JWT** — bearer-token auth (issue + verify access/refresh tokens)
* **Local** — username/password, typically issuing a JWT on login
* **API key**, **Basic**, **OAuth2** (and hybrid OAuth2)

### Install

```bash
npm install @soapjs/soap-auth bcryptjs
```

### Configure

`SoapAuth` holds your strategies, grouped by transport category (`http`, `socket`, …) and exposes `getStrategy(name, type)` / `listStrategies(type)`:

```typescript
import { SoapAuth } from '@soapjs/soap-auth';

const soapAuth = new SoapAuth({
  http: {
    jwt:   { /* access token issuer + user.fetchUser */ },
    local: { /* extractCredentials + verifyCredentials + routes */ },
  },
});
```

See the [demo's `auth.setup.ts`](https://github.com/soapjs/soap-node-demo) for full, working JWT + Local configuration.

### Integrate with soap-express

Register every HTTP strategy on the app, then guard routes with the auth decorators:

```typescript
app.registerAuth(soapAuth);   // pulls all http strategies from SoapAuth
```

```typescript
@Controller('/auth')
export class AuthController {
  @Post('/login')
  async login(req: Request, res: Response): Promise<void> {
    const result = await this.localStrategy.login(req as any);   // verifies + issues JWT
    res.json({ user: result.user, tokens: result.tokens });
  }

  @Get('/me')
  @Auth('jwt')                 // requires a valid JWT
  async me(req: Request, res: Response): Promise<void> { /* ... */ }
}
```

Route guards: `@Auth('jwt')`, `@AdminOnly()`, `@RolesOnly(roles)`, `@SelfOnly()`, `@Public()`.

### Login flow

1. `POST /auth/login` → the Local strategy verifies credentials and issues a JWT.
2. Client sends `Authorization: Bearer <token>` on subsequent requests.
3. `@Auth('jwt')` routes validate the token and attach the user.