feat(container): M-Box 1-8 — stack-agnostic standalone Docker container

Shade now ships as a self-contained Docker image. Deploy one container
per project, any stack (Bun, Python, Go, Rust, Kotlin) can talk to it via
plain HTTP. Zero coupling to consumer codebases.

M-Box 1: Stale identity cleanup API
- touchIdentity + purgeStaleIdentities on PrekeyStore interface
- Implemented for Memory, SQLite, and Postgres backends
- SQLite adds last_activity_at column with migration ALTER for existing DBs
- Postgres adds the same via raw SQL with IF NOT EXISTS guards
- Routes call touchIdentity on register, bundle fetch, replenish
- 4 new tests for the cleanup API

M-Box 2: Stale cleanup background task
- StaleCleanupTask runs purge on startup + every 24h (configurable)
- Reads SHADE_STALE_DAYS (default 30) and SHADE_CLEANUP_INTERVAL_HOURS
- Wired into standalone.ts, stopped on graceful shutdown
- 5 new tests for the task

M-Box 3: Observer baked into the container
- standalone.ts conditionally mounts @shade/observer at /shade-observer
  when SHADE_OBSERVER_TOKEN is set (and >= 16 chars)
- Shared PrekeyServerEvents emitter feeds both routes and observer
- @shade/observer added as optional dependency of @shade/server

M-Box 4: Dockerfile with dashboard build
- Multi-stage build: oven/bun:1 builder → oven/bun:1-alpine runtime
- COPY packages/ wholesale so workspace lockfile resolves cleanly
- RUN bun run build inside shade-dashboard → dist/ → observer/dist/
- Non-root shade user, /data volume, healthcheck, env defaults
- Final image: 260 MB

M-Box 5: OpenAPI spec for stack-agnostic clients
- packages/shade-server/openapi.yaml documents all 9 endpoints with
  request/response schemas, security (Ed25519 signatures + bearer token)
- createOpenApiRoutes serves /openapi.yaml and /docs (Redoc viewer)
- Any language can generate a client with openapi-generator

M-Box 6: Docker CI pipeline
- .gitea/workflows/docker.yml builds + pushes on git tag v*
- scripts/build-docker.ts for local builds, supports --push with GITEA_TOKEN
- Root package.json: build:docker, publish:docker scripts

M-Box 7: Deployment documentation
- packages/shade-server/README rewritten: 5-line quickstart with the image
- docs/DEPLOYMENT.md: full reference, env vars, backup, Dokploy, PG setup
- examples/05-dokploy-deployment/docker-compose.yml updated to pull
  published image (gt.zyon.no/stian/shade-prekey:latest)
- Root README deployment section rewritten

M-Box 8: End-to-end verification
- Image builds locally (bun run build:docker)
- /health, /openapi.yaml, /docs, /metrics, /shade-observer all respond
- 401 without observer token, 200 with
- Real SDK client round-trip: Alice → container → Bob → reply → Alice
- Persistence: identity + prekeys survive container restart (count 20→18
  as expected from two bundle fetches)

285 tests passing, 0 failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/shade-server/tests/cleanup.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from 'bun:test';
+import { StaleCleanupTask } from '../src/cleanup.js';
+import { MemoryPrekeyStore } from '../src/memory-store.js';
+
+function rand(n: number): Uint8Array {
+  const buf = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(buf);
+  return buf;
+}
+
+describe('StaleCleanupTask', () => {
+  test('runs once immediately on start', async () => {
+    const store = new MemoryPrekeyStore();
+    // Save an untouched (so stale) identity
+    await store.saveIdentity('ancient', rand(32), rand(32));
+
+    const task = new StaleCleanupTask(store, { staleDays: 1, intervalHours: 24 });
+    task.start();
+    // Give the immediate run a microtask to complete
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(await store.getIdentity('ancient')).toBeNull();
+    task.stop();
+  });
+
+  test('runOnce returns count of purged addresses', async () => {
+    const store = new MemoryPrekeyStore();
+    await store.saveIdentity('ancient1', rand(32), rand(32));
+    await store.saveIdentity('ancient2', rand(32), rand(32));
+
+    const task = new StaleCleanupTask(store, { staleDays: 1 });
+    const count = await task.runOnce();
+    expect(count).toBe(2);
+  });
+
+  test('leaves fresh identities alone', async () => {
+    const store = new MemoryPrekeyStore();
+    await store.saveIdentity('fresh', rand(32), rand(32));
+    await store.touchIdentity('fresh');
+
+    const task = new StaleCleanupTask(store, { staleDays: 30 });
+    const count = await task.runOnce();
+    expect(count).toBe(0);
+    expect(await store.getIdentity('fresh')).not.toBeNull();
+  });
+
+  test('stop clears the interval', () => {
+    const store = new MemoryPrekeyStore();
+    const task = new StaleCleanupTask(store, { staleDays: 1, intervalHours: 1 });
+    task.start();
+    expect(task.isRunning).toBe(true);
+    task.stop();
+    expect(task.isRunning).toBe(false);
+  });
+
+  test('reads defaults from env vars', () => {
+    const store = new MemoryPrekeyStore();
+    const oldDays = process.env.SHADE_STALE_DAYS;
+    const oldHours = process.env.SHADE_CLEANUP_INTERVAL_HOURS;
+    process.env.SHADE_STALE_DAYS = '7';
+    process.env.SHADE_CLEANUP_INTERVAL_HOURS = '12';
+    try {
+      const task = new StaleCleanupTask(store);
+      // staleMs = 7 days, intervalMs = 12 hours
+      expect((task as any).staleMs).toBe(7 * 24 * 60 * 60 * 1000);
+      expect((task as any).intervalMs).toBe(12 * 60 * 60 * 1000);
+    } finally {
+      if (oldDays !== undefined) process.env.SHADE_STALE_DAYS = oldDays;
+      else delete process.env.SHADE_STALE_DAYS;
+      if (oldHours !== undefined) process.env.SHADE_CLEANUP_INTERVAL_HOURS = oldHours;
+      else delete process.env.SHADE_CLEANUP_INTERVAL_HOURS;
+    }
+  });
+});