feat: enforce openapi contract for admin audit APIs and add docs

Co-authored-by: MinecraftFuns <25814618+MinecraftFuns@users.noreply.github.com>
Agent-Logs-Url: https://github.com/BTreeMap/OneShot/sessions/bdc10cae-a610-4dbe-be98-e85ae99c06a3

Author: Copilot

AGENTS.md

@@ -58,3 +58,11 @@ You are expected to execute these commands in your workspace terminal to verify
 2. **Test-Driven:** Write `pytest` or `vitest` tests for your new logic *before* or alongside the implementation.
 3. **Adversarial Testing:** When writing security or token logic, write tests that specifically attempt to bypass the mechanism (e.g., concurrent requests, invalid headers).
 4. **Self-Correction:** Run the formatters, linters, and test suites. If a test fails, read the error output and fix your code autonomously. Do not submit a Pull Request with failing tests.
+
+## 6. OpenAPI Contract (MANDATORY)
+- The backend OpenAPI schema is the **single source of truth** for frontend API types.
+- Do not handwrite request/response interfaces for backend routes when generated OpenAPI types exist.
+- Regenerate schema and TS types whenever backend API shapes change:
+  - `cd web && npm run gen`
+- Import route/schema types from `web/src/api/openapi.ts` (or curated exports in `web/src/api/types.ts`) and use them directly in page/service code.
+- Keep compile-time route assertions in `web/src/api/types.ts` up to date for newly added endpoints so type drift is caught by TypeScript.

README.md

@@ -1,2 +1,25 @@
 # OneShot
 OneShot is a zero-trust file transfer portal. It replaces user accounts with single-use links to eliminate credential liability. Files are anonymized and stripped of executable risks. Access tokens bypass server logs, and upload windows close instantly upon completion.
+
+## API Contract and Type Safety
+
+OneShot treats OpenAPI as the contract between backend and frontend.
+
+- Backend schema source: `api/openapi.json`
+- Generated frontend contract: `web/src/api/openapi.ts`
+- Curated contract aliases/assertions: `web/src/api/types.ts`
+
+When backend API shapes change, regenerate the contract and types:
+
+```bash
+cd web
+npm run gen
+```
+
+This flow prevents type drift by compiling frontend code against the generated schema-derived types.
+
+## Documentation
+
+Project documentation is organized under `docs/`:
+
+- `docs/openapi-contract.md` – contract workflow and enforcement rules

api/alembic/versions/56fd3d38fe31_add_timestamps.py

@@ -21,8 +21,16 @@
 def upgrade() -> None:
     """Upgrade schema."""
     # ### commands auto generated by Alembic - please adjust! ###
-    op.add_column('file_metadata', sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False))
-    op.add_column('oneshot_tokens', sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False))
+    op.add_column(
+        "file_metadata",
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "oneshot_tokens",
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.execute("UPDATE file_metadata SET created_at = CURRENT_TIMESTAMP WHERE created_at IS NULL")
+    op.execute("UPDATE oneshot_tokens SET created_at = CURRENT_TIMESTAMP WHERE created_at IS NULL")
     # ### end Alembic commands ###