# @suaveplan/auth - Provider-agnostic authentication: JWT lifecycle, API key management, session management, and request middleware with pluggable storage adapters

## Summary

Provider-agnostic authentication library for Suaveplan. Ships JWT token lifecycle, API key management, session management, and framework-agnostic middleware — all backed by a pluggable `AuthAdapter` interface.

<!-- begin:auto-docs -->
## Documentation tree

- [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [errors](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [auth-error](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [jwt](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [token-lifecycle](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [auth-middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
- [schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
  - [auth.schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
<!-- end:auto-docs -->  - [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-error](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-lifecycle](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth.schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-error](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-lifecycle](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth.schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-error](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-lifecycle](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth-middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth.schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [auth](./src/adapters/auth/auth.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_  - [memory](./src/adapters/memory/memory.md) — <!-- begin:auto-docs --> _(no submodules)_- [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_  - [api-keys](./src/api-keys/api-keys.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_  - [auth-error](./src/errors/auth-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [jwt](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_  - [token-lifecycle](./src/jwt/token-lifecycle.md) — <!-- begin:auto-docs --> _(no submodules)_- [middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_  - [auth-middleware](./src/middleware/auth-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_  - [auth.schemas](./src/schemas/auth.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_
## Packages

| Module | Description |
|---|---|
| [errors/auth-error](src/errors/auth-error.md) | Stable AUTH.* error code registry and concrete error classes |
| [types/auth.types](src/types/auth.types.md) | All public interfaces and type aliases |
| [schemas/auth.schemas](src/schemas/auth.schemas.md) | Zod validation schemas for option types |
| [adapters/auth-adapter](src/adapters/auth-adapter/auth-adapter.md) | AuthAdapter interface definition |
| [adapters/memory-adapter](src/adapters/memory-adapter/memory-adapter.md) | In-memory AuthAdapter implementation |
| [api-keys](src/api-keys/api-keys.md) | Full API key lifecycle |
| [jwt/token-lifecycle](src/jwt/token-lifecycle.md) | JWT issue, validate, refresh, revoke |
| [middleware/auth-middleware](src/middleware/auth-middleware.md) | Permission middleware helpers |

## Quick Start

```ts
import {
  MemoryAuthAdapter,
  issueToken,
  validateSessionToken,
  createApiKey,
  validateApiKey,
  requirePermission,
} from "@suaveplan/auth";

const adapter = new MemoryAuthAdapter();
const jwtOpts = { secret: process.env["JWT_SECRET"] ?? "" };

// Issue JWT tokens
const { accessToken, refreshToken } = await issueToken(adapter, userId, jwtOpts);

// Validate
const result = await validateSessionToken(adapter, accessToken, jwtOpts);

// API keys
const { rawKey } = await createApiKey(adapter, { name: "CI Key", userId });
const v = await validateApiKey(adapter, rawKey);

// Middleware
const adminOnly = requirePermission("admin:write", adapter, jwtOpts);
```