Initial public release v0.1.0

docs/INTEGRATION_BZOD.md

@@ -0,0 +1,113 @@
+# BZOD Consumer Integration Guide
+
+This guide details how BZOD consumes authentication and authorization services provided by `nx9-auth`.
+
+---
+
+## 1. Authentication
+
+To authenticate a user and establish a session, send a `POST` request to `/api/v1/auth/login`.
+
+### Request
+- **Method**: `POST`
+- **Path**: `/api/v1/auth/login`
+- **Headers**: `Content-Type: application/json`
+- **Payload**:
+  ```json
+  {
+    "username": "admin",
+    "password": "super_secure_password"
+  }
+  ```
+
+### Response
+- **Status**: `200 OK`
+- **Headers**: `Set-Cookie: nx9_session=<session_token>; HttpOnly; Secure; SameSite=Lax; Path=/`
+- **Payload**:
+  ```json
+  {
+    "success": true
+  }
+  ```
+
+---
+
+## 2. Session Validation
+
+To validate an existing session cookie and get the authenticated user's profile, roles, and permissions, make a `GET` request to `/api/v1/auth/me`.
+
+### Request
+- **Method**: `GET`
+- **Path**: `/api/v1/auth/me`
+- **Headers**: Include the `nx9_session` cookie in the request.
+
+### Response
+- **Status**: `200 OK`
+- **Payload**:
+  ```json
+  {
+    "user": {
+      "id": "e4d3a2b1-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
+      "username": "admin",
+      "status": "active",
+      "last_login_at": "2026-06-21T18:09:13Z",
+      "created_at": "2026-06-20T12:00:00Z"
+    },
+    "roles": ["admin"],
+    "permissions": ["users:create", "users:update", "users:delete", "tokens:create", "tokens:revoke"]
+  }
+  ```
+
+---
+
+## 3. Personal Access Token (PAT) Authentication
+
+For programmatic API access (service-to-service or CLI usage), clients can authenticate using a Personal Access Token (PAT) passed in the `Authorization` header.
+
+### Request
+- **Headers**: `Authorization: Bearer nx9_pat_<64_hex_chars>`
+
+For example:
+```bash
+curl -H "Authorization: Bearer nx9_pat_29b2fd8c34f0f089..." https://auth.nx9.local/api/v1/auth/me
+```
+
+---
+
+## 4. Permissions Mapping
+
+The following table maps BZOD features and features to their required `nx9-auth` permissions:
+
+| BZOD Feature / Action | Required Permission | Description |
+|---|---|---|
+| Create link | `links:create` | Allows creating new shortened links |
+| Delete link | `links:delete` | Allows deleting existing shortened links |
+| View link stats | `links:stats` | Allows viewing redirection analytics and link statistics |
+| Create user accounts | `users:create` | Allows administrative user creation |
+| Modify user status | `users:update` | Allows enabling, disabling, or locking users |
+| Delete user accounts | `users:delete` | Allows soft-deleting/disabling users |
+
+---
+
+## 5. Unified Error Payload
+
+All `nx9-auth` errors return a unified JSON payload format mapping to standard HTTP status codes:
+
+```json
+{
+  "error": "Reason for the error",
+  "code": "error_code"
+}
+```
+
+### Standard Status Codes & Codes Mapping
+
+| HTTP Status | Code | Description | Example Error |
+|---|---|---|---|
+| `401 Unauthorized` | `unauthorized` | Credentials are invalid, or session/token is missing/expired | `{"error": "invalid credentials", "code": "unauthorized"}` |
+| `403 Forbidden` | `forbidden` | Authenticated user lacks the required permission | `{"error": "insufficient permissions", "code": "forbidden"}` |
+| `404 Not Found` | `not_found` | Resource does not exist | `{"error": "resource not found", "code": "not_found"}` |
+| `409 Conflict` | `conflict` | Unique constraint violation (e.g. username taken) | `{"error": "conflict: username already taken", "code": "conflict"}` |
+| `422 Unprocessable` | `invalid_input` | Request body or payload format is invalid | `{"error": "invalid input: username cannot be empty", "code": "invalid_input"}` |
+| `429 Too Many Requests` | `rate_limited` | Rate limit threshold exceeded | `{"error": "too many requests", "code": "rate_limited"}` |
+| `500 Internal Error` | `internal_error` | Database query failure or unexpected server error | `{"error": "internal error", "code": "internal_error"}` |