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-storage-sqlite/src/sqlite-prekey-store.ts

@@ -25,6 +25,8 @@ export class SqlitePrekeyStore implements PrekeyStore {
     deleteIdentity: ReturnType<Database['prepare']>;
     deleteSignedPreKey: ReturnType<Database['prepare']>;
     deleteOTPKs: ReturnType<Database['prepare']>;
+    touchIdentity: ReturnType<Database['prepare']>;
+    findStale: ReturnType<Database['prepare']>;
   };
 
   constructor(dbPath?: string) {
@@ -40,7 +42,8 @@ export class SqlitePrekeyStore implements PrekeyStore {
       CREATE TABLE IF NOT EXISTS identities (
         address TEXT PRIMARY KEY,
         identity_signing_key TEXT NOT NULL,
-        identity_dh_key TEXT NOT NULL
+        identity_dh_key TEXT NOT NULL,
+        last_activity_at INTEGER NOT NULL DEFAULT 0
       );
       CREATE TABLE IF NOT EXISTS signed_prekeys (
         address TEXT PRIMARY KEY,
@@ -55,12 +58,23 @@ export class SqlitePrekeyStore implements PrekeyStore {
         public_key TEXT NOT NULL
       );
       CREATE INDEX IF NOT EXISTS idx_otp_address ON one_time_prekeys(address);
+      CREATE INDEX IF NOT EXISTS idx_identities_activity ON identities(last_activity_at);
     `);
+
+    // Migrate existing databases: add last_activity_at if missing
+    try {
+      const cols = this.db.prepare('PRAGMA table_info(identities)').all() as any[];
+      const hasActivity = cols.some((c) => c.name === 'last_activity_at');
+      if (!hasActivity) {
+        this.db.exec('ALTER TABLE identities ADD COLUMN last_activity_at INTEGER NOT NULL DEFAULT 0');
+        this.db.exec('CREATE INDEX IF NOT EXISTS idx_identities_activity ON identities(last_activity_at)');
+      }
+    } catch {}
   }
 
   private prepareStatements() {
     this.stmts = {
-      saveIdentity: this.db.prepare('INSERT OR REPLACE INTO identities (address, identity_signing_key, identity_dh_key) VALUES (?, ?, ?)'),
+      saveIdentity: this.db.prepare('INSERT OR REPLACE INTO identities (address, identity_signing_key, identity_dh_key, last_activity_at) VALUES (?, ?, ?, ?)'),
       getIdentity: this.db.prepare('SELECT identity_signing_key, identity_dh_key FROM identities WHERE address = ?'),
       saveSignedPreKey: this.db.prepare('INSERT OR REPLACE INTO signed_prekeys (address, key_id, public_key, signature) VALUES (?, ?, ?, ?)'),
       getSignedPreKey: this.db.prepare('SELECT key_id, public_key, signature FROM signed_prekeys WHERE address = ?'),
@@ -70,6 +84,8 @@ export class SqlitePrekeyStore implements PrekeyStore {
       deleteIdentity: this.db.prepare('DELETE FROM identities WHERE address = ?'),
       deleteSignedPreKey: this.db.prepare('DELETE FROM signed_prekeys WHERE address = ?'),
       deleteOTPKs: this.db.prepare('DELETE FROM one_time_prekeys WHERE address = ?'),
+      touchIdentity: this.db.prepare('UPDATE identities SET last_activity_at = ? WHERE address = ?'),
+      findStale: this.db.prepare('SELECT address FROM identities WHERE last_activity_at < ?'),
     };
   }
 
@@ -78,7 +94,7 @@ export class SqlitePrekeyStore implements PrekeyStore {
   }
 
   async saveIdentity(address: string, identitySigningKey: Uint8Array, identityDHKey: Uint8Array): Promise<void> {
-    this.stmts.saveIdentity.run(address, toBase64(identitySigningKey), toBase64(identityDHKey));
+    this.stmts.saveIdentity.run(address, toBase64(identitySigningKey), toBase64(identityDHKey), Date.now());
   }
 
   async getIdentity(address: string): Promise<{ identitySigningKey: Uint8Array; identityDHKey: Uint8Array } | null> {
@@ -135,4 +151,26 @@ export class SqlitePrekeyStore implements PrekeyStore {
     });
     deleteAllTx();
   }
+
+  // ─── Stale cleanup ──────────────────────────────────────
+
+  async touchIdentity(address: string): Promise<void> {
+    this.stmts.touchIdentity.run(Date.now(), address);
+  }
+
+  async purgeStaleIdentities(olderThanMs: number): Promise<number> {
+    const cutoff = Date.now() - olderThanMs;
+    const staleRows = this.stmts.findStale.all(cutoff) as Array<{ address: string }>;
+    if (staleRows.length === 0) return 0;
+
+    const purgeTx = this.db.transaction(() => {
+      for (const row of staleRows) {
+        this.stmts.deleteIdentity.run(row.address);
+        this.stmts.deleteSignedPreKey.run(row.address);
+        this.stmts.deleteOTPKs.run(row.address);
+      }
+    });
+    purgeTx();
+    return staleRows.length;
+  }
 }