# Dashboard / Config Routes

Base path: `/tc-auth/config`

Authentication:

- `GET /pulse` is public.
- All other routes in this group require `Authorization: Bearer <access_token>` and the `superadmin` role.

Notes:

- The current code exposes `GET /load/`; there is no separate `/redirect` route in the route module anymore.
- Configuration is stored in memory on the running service instance.

## GET `/pulse`

Health and readiness-style probe.

Response:

```json
{
  "system_time": "2026-08-12T10:00:00.000000",
  "response": "Hello",
  "status": "healthy",
  "state": "active"
}
```

Example:

```js
const res = await fetch(`${baseUrl}/tc-auth/config/pulse`);
const data = await res.json();
```

## GET `/load/`

Loads the current email, GitHub, Google, Discord, and JWT configuration.

Response:

```json
{
  "email": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "mailer@example.com",
    "password": "***",
    "sender": "noreply@example.com",
    "sender_name": "Auth Module",
    "use_tls": true
  },
  "github": {
    "client_id": "...",
    "client_secret": "...",
    "redirect_uri": "https://app.example.com/tc-auth/github/callback"
  },
  "google": {
    "client_id": "...",
    "client_secret": "...",
    "redirect_uri": "https://app.example.com/tc-auth/google/callback"
  },
  "discord": {
    "client_id": "...",
    "client_secret": "...",
    "redirect_uri": "https://app.example.com/tc-auth/discord/callback"
  },
  "jwt": {
    "secret_key": "...",
    "algorithm": "HS256",
    "session_duration_days": 7
  },
  "cookie": {
    "cookie_mode": false,
    "access_cookie_name": "access_token",
    "refresh_cookie_name": "refresh_token",
    "path": "/",
    "domain": null,
    "secure": false,
    "httponly": true,
    "samesite": "lax",
    "max_age": null
  },
  "logging": {
    "logging": true,
    "logs_dir": "D:\\path\\to\\logs",
    "store_dir": "D:\\path\\to\\logs\\store",
    "level": "INFO",
    "console_output": true,
    "capture_terminal": false,
    "redact_sensitive": true,
    "redact_patterns": [],
    "max_log_lines": 10000,
    "trim_log_lines": 1000
  }
}
```

Example:

```js
const res = await fetch(`${baseUrl}/tc-auth/config/load/`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
});

const config = await res.json();
```

## GET `/counts`

Returns counts for the main tables.

Response:

```json
{
  "accounts": 123,
  "oauth": 7,
  "sessions": 42,
  "otp": 3
}
```

Example:

```js
const res = await fetch(`${baseUrl}/tc-auth/config/counts`, {
  method: "GET",
  headers: { Authorization: `Bearer ${accessToken}` },
});

const counts = await res.json();
```

## POST `/email`

Configures the email service.

Body:

```json
{
  "host": "smtp.example.com",
  "port": 587,
  "username": "mailer@example.com",
  "password": "secret",
  "sender": "noreply@example.com",
  "sender_name": "Auth Module",
  "use_tls": true
}
```

Response:

```json
{
  "success": true,
  "message": "Email service configured successfully"
}
```

## POST `/github`

Configures GitHub OAuth.

Body:

```json
{
  "client_id": "...",
  "client_secret": "...",
  "redirect_uri": "https://app.example.com/tc-auth/github/callback"
}
```

Response:

```json
{
  "success": true,
  "message": "GitHub OAuth configured successfully"
}
```

## POST `/google`

Configures Google OAuth.

Body:

```json
{
  "client_id": "...",
  "client_secret": "...",
  "redirect_uri": "https://app.example.com/tc-auth/google/callback"
}
```

Response:

```json
{
  "success": true,
  "message": "Google OAuth configured successfully"
}
```

## POST `/discord`

Configures Discord OAuth.

Body:

```json
{
  "client_id": "...",
  "client_secret": "...",
  "redirect_uri": "https://app.example.com/tc-auth/discord/callback"
}
```

Response:

```json
{
  "success": true,
  "message": "Discord OAuth configured successfully"
}
```

## POST `/jwt`

Configures JWT signing, session lifetime, and optional dual-token architecture.

Body:

```json
{
  "secret_key": "super-secret",
  "algorithm": "HS256",
  "session_duration_days": 7,
  "dual_token_mode": false,
  "access_token_expire_minutes": 15,
  "refresh_token_expire_days": 7
}
```

- `session_duration_days` (required): Integer $\ge 1$. Controls single-token access expiration and database session lifetime. Default is `7`.
- `dual_token_mode` (optional): Boolean. When `true`, login and signup issue both a short-lived `access_token` and a long-lived `refresh_token`.
- `access_token_expire_minutes` (optional): Integer $\ge 1$. Lifespan of access tokens when dual-token mode is enabled (default `15`).
- `refresh_token_expire_days` (optional): Integer $\ge 1$. Lifespan of refresh tokens when dual-token mode is enabled (defaults to `session_duration_days`).

Response:

```json
{
  "success": true,
  "message": "JWT configured successfully"
}
```

## POST `/cookie`

Configures the Cookie Subsystem parameters. Requires superadmin access.

Body:

```json
{
  "cookie_mode": true,
  "access_cookie_name": "access_token",
  "refresh_cookie_name": "refresh_token",
  "path": "/",
  "domain": null,
  "secure": true,
  "httponly": true,
  "samesite": "lax",
  "max_age": null
}
```

- `cookie_mode` (optional): Boolean. Toggle Cookie Mode on or off (default: `false`).
- `access_cookie_name` (optional): String. Name of access token cookie (default: `"access_token"`).
- `refresh_cookie_name` (optional): String. Name of refresh token cookie (default: `"refresh_token"`).
- `path` (optional): String. Cookie path (default: `"/"`).
- `domain` (optional): String or `null`. Cookie domain scope.
- `secure` (optional): Boolean. HTTPS requirement flag (default: `false`).
- `httponly` (optional): Boolean. XSS mitigation flag (default: `true`).
- `samesite` (optional): String. SameSite policy (`"lax"`, `"strict"`, `"none"`).
- `max_age` (optional): Integer or `null`. Custom cookie lifetime in seconds.

Response:

```json
{
  "success": true,
  "message": "Cookie configured successfully"
}
```

## POST `/logging`

Dynamically updates logging service settings. Supports partial updates; omitted fields retain their existing settings.

- **Authentication**: `Authorization: Bearer <superadmin_access_token>` or cookie session (`credentials: "include"`)
- **Role Requirement**: `superadmin`

### Request Body Fields (`LoggingConfig`)

> [!WARNING]
> **Strict Schema Validation (`extra="forbid"`)**: The backend API route enforces Pydantic `model_config = ConfigDict(extra="forbid")`. Unrecognized extra fields (e.g. `store_dir`, `custom_redact_keys`, or deprecated properties) are strictly forbidden and will be rejected with `422 Unprocessable Entity`. The frontend sanitizer automatically strips extraneous fields before dispatch.

| Field | Type | Required | Description |
|---|---|---|---|
| `logging` | `boolean \| null` | Optional | Master toggle to enable (`true`) or disable (`false`) all file logging. |
| `enabled` | `boolean \| null` | Optional | *(Deprecated)* Alias for `logging` toggle for backwards compatibility. Prefer `logging`. |
| `logs_dir` | `string \| null` | Optional | Base directory for log files. Note: `store_dir` is derived automatically and must not be passed. |
| `level` | `string \| null` | Optional | Logging level threshold (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Case-insensitive. |
| `console_output` | `boolean \| null` | Optional | Echo JSONL application events to stdout. **Operates independently**: can remain `true` even when `logging` is `false`. |
| `capture_terminal` | `boolean \| null` | Optional | Whether to pipe process `print()` statements to `server.log`. Default: `false`. |
| `redact_sensitive` | `boolean \| null` | Optional | Whether to automatically redact sensitive fields (tokens, passwords, cookies) in `tcauth.log`. Default: `true`. |
| `redact_patterns` | `string[] \| null` | Optional | List of custom regex patterns to redact in application logs and captured prints. Evaluated independently from `redact_sensitive`. |
| `max_log_lines` | `integer \| null` | Optional | Maximum retained lines for `server.log` and `tcauth.log` (integer &ge; 10, default: `10000`). |
| `trim_log_lines` | `integer \| null` | Optional | Number of oldest lines deleted when line limit is reached (integer &ge; 1, default: `1000`). |

### Example Request Payload (Full Update)

```json
{
  "logging": true,
  "level": "INFO",
  "console_output": true,
  "capture_terminal": false,
  "redact_sensitive": true,
  "redact_patterns": [
    "(?i)authorization:\\s*bearer\\s+\\S+",
    "(?i)token\\s*[:=]\\s*\\S+"
  ],
  "max_log_lines": 10000,
  "trim_log_lines": 1000,
  "logs_dir": "logs"
}
```

### Example Request Payload (Partial Update: Retention & Trimming)

```json
{
  "max_log_lines": 25000,
  "trim_log_lines": 2500
}
```

### Example Request Payload (Toggle Master Logging Only)

```json
{
  "logging": false
}
```

### Response (`200 OK`)

```json
{
  "success": true,
  "message": "Logging service configured successfully"
}
```

### Error Responses

- `400 Bad Request` (`InvalidConfigError`): Invalid level name, invalid regex pattern, or constraint violation (e.g., `max_log_lines < 10`, `trim_log_lines < 1`).
- `401 Unauthorized`: Missing or invalid Bearer token / session credentials.
- `403 Forbidden` (`role_mismatch`): User does not possess `superadmin` role.
- `422 Unprocessable Entity`: Extra forbidden fields provided in request body (`ConfigDict(extra="forbid")`) or invalid data types.