docs: overhaul repository documentation

docs/_archive/admin-token-operations.md

@@ -0,0 +1,93 @@
+ID: DOC_000006 | Version: 0.2.1 | Status: Draft
+Archived – superseded by new documentation.
+By: Codex (GPT-5)
+
+# Admin Token Operations
+
+## Purpose
+This document describes how operators create and manage pre-shared enrollment tokens for clients.
+
+## Pre-Shared Token Creation
+Operators generate a single-use enrollment token and share it out-of-band with the client.
+
+Recommended properties:
+- Single-use only
+- Short TTL (e.g., 24h)
+- Scoped to `project_id` and optional `client_id`/`software_id`
+
+## Admin Interfaces
+We provide both an Admin API and a CLI tool for token operations. A frontend will be added later.
+
+### Admin User and Access
+- An admin user must exist to operate token workflows.
+- Initial access uses a local admin token.
+- Later, admin auth will be integrated with the OIDC service.
+
+### CLI and Admin API Capabilities
+- Create enrollment tokens
+- List token metadata (no plaintext output)
+- Revoke tokens
+- Export a token as a file for client installation
+
+### Local Admin Token (Initial Phase)
+- Admin requests must include `Authorization: Bearer <ADMIN_TOKEN>`.
+- The admin token is stored locally (e.g., `.env`) and never committed.
+
+Example `.env` (local only):
+```
+ADMIN_TOKEN=change-me-please
+```
+
+Minimal flow (first token):
+1) Set `ADMIN_TOKEN` in `.env`.
+2) Call `POST /v1/admin/enrollment-tokens` with the bearer token.
+3) Export the returned one-time token to a file and hand it to the client.
+
+## Admin API (Draft)
+All admin endpoints are authenticated. Initial auth is local; later OIDC.
+
+Base path:
+- `/v1/admin`
+
+Endpoints:
+- `POST /v1/admin/enrollment-tokens`
+  - Create a pre-shared enrollment token.
+  - Request: `project_id`, optional `client_id`, optional `software_id`, optional `expires_at`.
+  - Response: token metadata + one-time plaintext token.
+- `GET /v1/admin/enrollment-tokens`
+  - List token metadata (never return plaintext tokens).
+  - Supports filtering by `project_id`, `client_id`, `status` (active/used/expired).
+- `POST /v1/admin/enrollment-tokens/{token_id}/revoke`
+  - Revoke a token (marks as revoked or sets `used_at`/`revoked_at`).
+- `GET /v1/admin/enrollment-tokens/{token_id}/export`
+  - Export the one-time token to a file download (single use).
+
+## CLI (Draft)
+Example commands (names can be adjusted):
+- `update-service admin token create --project <id> [--client <id>] [--software <id>] [--expires <iso8601>]`
+- `update-service admin token list --project <id> [--status active|used|expired|revoked]`
+- `update-service admin token revoke --id <token_id>`
+- `update-service admin token export --id <token_id> --out ./enroll-token.txt`
+
+Example format:
+```
+enroll_<random_32_bytes>
+```
+
+## Storage and Safety
+- Store only a hash of the enrollment token (never plaintext).
+- Track `created_at`, `expires_at`, and `used_at`.
+- Deny enrollment if `expires_at` is exceeded or `used_at` is set.
+
+## Rotation and Revocation
+- Revoke enrollment tokens by invalidating their stored hash.
+- Issue a new enrollment token if the previous one expires or is leaked.
+
+## Distribution
+Preferred channels:
+- One-time install code (copy/paste)
+- QR code
+- Encrypted file included in an install bundle
+
+## Audit Expectations
+- Log token creation and enrollment usage for traceability.