From 53a0e3576e358081e2ee2c325874fabdd72fc509 Mon Sep 17 00:00:00 2001
From: Codex <codex@example.com>
Date: Wed, 18 Feb 2026 14:19:24 +0000
Subject: [PATCH] docs: document internal worker, retention, and abuse
 configuration

---
 .env.example            |  6 ++++++
 README.md               | 20 +++++++++++++++++---
 test/deployment.test.js |  3 +++
 3 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/.env.example b/.env.example
index 798a6ca..472e2bb 100644
--- a/.env.example
+++ b/.env.example
@@ -8,6 +8,7 @@ APP_BASE_URL=https://xartaudio.example.com
 BETTER_AUTH_SECRET=replace-me
 BETTER_AUTH_BASE_PATH=/api/auth
 BETTER_AUTH_DEV_PASSWORD=replace-me
+INTERNAL_API_TOKEN=replace-me
 
 # Convex
 CONVEX_DEPLOYMENT_URL=https://your-deployment.convex.cloud
@@ -56,3 +57,8 @@ MAX_CHARS_PER_ARTICLE=120000
 WEBHOOK_RPM=120
 AUTH_RPM=30
 ACTION_RPM=60
+
+# Anti-abuse policy
+ABUSE_MAX_JOBS_PER_USER_PER_DAY=0
+ABUSE_COOLDOWN_SEC=0
+ABUSE_DENY_USER_IDS=
diff --git a/README.md b/README.md
index e020ee8..431aa3e 100644
--- a/README.md
+++ b/README.md
@@ -336,6 +336,7 @@ This repository now contains a deployable production-style app (single container
 - all wallet/job/asset/access state is snapshotted through Convex query/mutation functions
 7. Abuse protection:
 - fixed-window rate limiting for webhook, auth, and action routes
+ - deny-list, per-user daily job cap, and cooldown windows for mention processing
 8. PWA support:
 - `manifest.webmanifest`
 - `sw.js`
@@ -367,7 +368,13 @@ This repository now contains a deployable production-style app (single container
 - `GET /api/me/wallet`
 - `GET /api/jobs/:id`
 - `POST /api/audio/:id/unlock`
+- `DELETE /api/audio/:id` (owner takedown)
 - `GET /health`
+4. Internal worker/ops:
+- `POST /internal/jobs/:id/start`
+- `POST /internal/jobs/:id/complete`
+- `POST /internal/jobs/:id/fail`
+- `POST /internal/retention/run`
 
 ### Local commands
 1. `bun test`
@@ -386,6 +393,7 @@ Use `.env.example` as the source of truth.
 - `BETTER_AUTH_SECRET`
 - `BETTER_AUTH_BASE_PATH`
 - `BETTER_AUTH_DEV_PASSWORD`
+- `INTERNAL_API_TOKEN`
 - `CONVEX_DEPLOYMENT_URL`
 - `CONVEX_AUTH_TOKEN`
 - `CONVEX_STATE_QUERY`
@@ -421,6 +429,10 @@ Use `.env.example` as the source of truth.
 - `WEBHOOK_RPM`
 - `AUTH_RPM`
 - `ACTION_RPM`
+6. Anti-abuse:
+- `ABUSE_MAX_JOBS_PER_USER_PER_DAY`
+- `ABUSE_COOLDOWN_SEC`
+- `ABUSE_DENY_USER_IDS`
 
 ## Coolify Deployment
 
@@ -428,14 +440,16 @@ Use `.env.example` as the source of truth.
 2. Set container port to `3000`.
 3. Configure all secrets and policy env vars from `.env.example`.
 4. Ensure `CONVEX_DEPLOYMENT_URL` is reachable from the container network.
-5. Expose HTTPS URL and point providers to:
+5. Set `INTERNAL_API_TOKEN` for internal worker and retention endpoints.
+6. Expose HTTPS URL and point providers to:
 - `https://<your-domain>/api/webhooks/x`
 - `https://<your-domain>/api/webhooks/polar`
-6. Verify deployment health with `GET /health`.
+7. Verify deployment health with `GET /health`.
 
 ## Production Checklist
 
 1. Replace `/auth/dev-login` with direct Better Auth UI/OAuth sign-in for public launch.
 2. Populate integration keys in Coolify environment for X, Polar, Qwen3 TTS, MinIO, and Convex.
 3. Implement Convex functions named by `CONVEX_STATE_QUERY` and `CONVEX_STATE_MUTATION`.
-4. Add tracing and external alerting.
+4. Move Better Auth from memory adapter to a persistent production adapter.
+5. Add tracing and external alerting.
diff --git a/test/deployment.test.js b/test/deployment.test.js
index 606e808..b8d4ce7 100644
--- a/test/deployment.test.js
+++ b/test/deployment.test.js
@@ -29,6 +29,9 @@ test("env example includes required webhook and credit settings", () => {
   assert.match(envFile, /MINIO_ENDPOINT=/);
   assert.match(envFile, /CONVEX_DEPLOYMENT_URL=/);
   assert.match(envFile, /BETTER_AUTH_SECRET=/);
+  assert.match(envFile, /INTERNAL_API_TOKEN=/);
+  assert.match(envFile, /ABUSE_MAX_JOBS_PER_USER_PER_DAY=/);
+  assert.match(envFile, /ABUSE_COOLDOWN_SEC=/);
   assert.match(envFile, /INCLUDED_CHARS=/);
   assert.match(envFile, /WEBHOOK_RPM=/);
 });