# auth-service design

## Scope

`auth-service` owns Web Studio account/password login, users, roles, role assignments, and permission checks.

The auth domain is single-workspace. Auth API payloads and auth tables do not carry workspace partition fields.

## Frontend Contract

Frontend requests go through `/gateway`:

- `POST /gateway/auth/login`
- `GET /gateway/auth/users`
- `GET /gateway/auth/roles`
- `POST /gateway/auth/permissions/check`

Gateway proxies them to auth-service:

- `POST /auth/login`
- `GET /auth/users`
- `GET /auth/roles`
- `POST /auth/permissions/check`

After login, frontend sends:

- `Authorization: Bearer ...`
- `x-user-id`

## Database

PostgreSQL:

```text
postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb
```

Runtime setting:

```powershell
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb"
```

## Tables

### auth_user

- `id`
- `username`
- `password_hash`
- `display_name`
- `email`
- `status`: `active | disabled | deleted`
- `metadata_json`
- `last_login_time`
- audit fields
- `version`

### auth_role

- `id`
- `code`
- `name`
- `description`
- `status`: `active | disabled`
- `permissions_json`
- audit fields
- `version`

### auth_role_assignment

- `id`
- `user_id`
- `role_id`
- `status`: `active | revoked`
- `scope_type`
- `scope_id`
- `expires_time`
- audit fields
- `version`

## Login

`POST /auth/login`

```json
{
  "username": "demo-user",
  "password": "demo-password"
}
```

Response:

```json
{
  "access_token": "apt_xxx",
  "token_type": "bearer",
  "expires_time": "2026-04-28T07:10:00Z",
  "user": {
    "id": "user-id",
    "username": "demo-user",
    "display_name": "Demo User",
    "email": "demo@example.com",
    "status": "active",
    "metadata_json": {},
    "last_login_time": "2026-04-27T23:10:00Z",
    "created_time": "2026-04-27T23:00:00Z"
  }
}
```

Passwords are stored with salted `PBKDF2-HMAC-SHA256`. Access tokens are HMAC signed with `AGENT_PLATFORM_CREDENTIAL_ENCRYPTION_KEY`.

## Token Verification

`POST /auth/tokens/verify`

```json
{
  "access_token": "apt_xxx"
}
```

Response:

```json
{
  "active": true,
  "user_id": "user-id",
  "username": "demo-user",
  "expires_time": "2026-04-28T07:10:00"
}
```

## Permission Check

`POST /auth/permissions/check`

```json
{
  "user_id": "user-id",
  "permission": "workflow:read",
  "scope_type": null,
  "scope_id": null
}
```

Response:

```json
{
  "allowed": true,
  "reason": "matched",
  "matched_role_ids": ["role-id"]
}
```

## Migration

```powershell
cd services/auth-service
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://admin:hFOvG5UBeK5KIGhz5cQH@git.newpoint.work:5432/vectordb"
alembic upgrade head
```