cognitox 0.1.2

AWS Cognito User Pools emulator for local development
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# cognitox

<div align="center">
<img width="100px" height="100px" src="./public/icon-512-rounded.png" />
</div>
<br />

Amazon Cognito User Pools emulator for local development.

> **Warning**: cognitox is designed for **local development and testing only**.
> It is not suitable for production use. CORS is fully open (`Allow-Origin: *`) and
> there is no authentication on the admin endpoints.

## Quick Start

### With Docker (GHCR)

```bash
# Pull pre-built image from GitHub Container Registry
docker pull ghcr.io/unvalley/cognitox:latest
docker run -p 9229:9229 ghcr.io/unvalley/cognitox:latest
```

### With Docker (local build)

```bash
docker build -t cognitox .
docker run -p 9229:9229 cognitox
```

### With Cargo

```bash
cargo install cognitox
cognitox
```

The admin console and Preact UI are embedded into the binary, so `cargo install` gives you a fully self-contained emulator — no extra assets to ship.

## Usage

Point the SDK endpoint to cognitox:

```javascript
// JavaScript / TypeScript
import { CognitoIdentityProviderClient } from "@aws-sdk/client-cognito-identity-provider";

const client = new CognitoIdentityProviderClient({
  region: "local",
  endpoint: "http://localhost:9229",
  credentials: { accessKeyId: "local", secretAccessKey: "local" },
});
```

```python
# Python (boto3)
import boto3

client = boto3.client(
    "cognito-idp",
    region_name="local",
    endpoint_url="http://localhost:9229",
    aws_access_key_id="local",
    aws_secret_access_key="local",
)
```

### Hosted UI

cognitox includes a built-in Hosted UI for login and signup flows.

```
// example
http://localhost:9229/login?response_type=code&client_id=<client-id>&redirect_uri=http://localhost:3000/callback&scope=openid
```

### Admin Console

A management UI for browsing user pools, users, clients, and groups:

```
http://localhost:9229/admin/
```

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `COGNITOX_PORT` | `9229` | Server port |
| `RUST_LOG` | `info` | Log level (`debug` for verbose output) |
| `COGNITOX_DATA_FILE` | *(unset)* | Path to persist emulator state (JSON snapshot). If set, state survives restarts. |

### Persistence

By default, all data is in-memory and lost on restart. To persist state:

```bash
COGNITOX_DATA_FILE=./cognitox-data.json cargo run
```

The emulator auto-saves every 500ms when changes are detected, and flushes on graceful shutdown (Ctrl+C).

## API Coverage

cognitox has all 119 API operations but some have partial functionality or known limitations (see below).
See [COVERAGE.md](COVERAGE.md) for the full list with links to each handler. If you find any missing or incorrectly implemented operations, please open an issue.

## Spec Drift Check

See [spec/README.md](spec/README.md).

## Known Limitations

- **SRP authentication** (`USER_SRP_AUTH`) -- partially implemented
- **Lambda triggers** -- not supported (no pre/post auth hooks)
- **Email/SMS delivery** -- confirmation codes are returned in API responses but not sent
- **Password policy per pool** -- only global min/max length is enforced
- **MFA enforcement** -- MFA operations are implemented but not enforced during auth
- **Advanced security features** -- risk configuration is stored but not evaluated

## License

MIT