botschat 0.1.10 → 0.1.13

package/README.md

@@ -117,24 +117,17 @@ Clone, install, and run the server on your machine. Wrangler uses [Miniflare](ht
 git clone https://github.com/botschat-app/botsChat.git
 cd botsChat
 npm install
-# One-command startup: build web → migrate D1 → start on 0.0.0.0:8787
 ./scripts/dev.sh
 ```
 
-Or step by step:
-
-```bash
-npm run build -w packages/web                          # Build the React frontend
-npm run db:migrate                                     # Apply D1 migrations (local)
-npx wrangler dev --config wrangler.toml --ip 0.0.0.0   # Start on port 8787
-```
-
-Open `http://localhost:8787` in your browser.
+One command does everything: build frontend → migrate database → start server → launch Mock AI → open browser with auto-login. No environment variables to set, no separate terminals to manage.
 
 Other dev commands:
 
 ```bash
-./scripts/dev.sh reset     # Nuke local DB → re-migrate → start
+./scripts/dev.sh reset     # Nuke local DB → re-migrate → start full dev env
+./scripts/dev.sh server    # Server only (no mock AI, no browser)
+./scripts/dev.sh mock      # Start mock OpenClaw standalone (foreground)
 ./scripts/dev.sh migrate   # Only run D1 migrations
 ./scripts/dev.sh build     # Only build web frontend
 ./scripts/dev.sh sync      # Sync plugin to remote OpenClaw host + restart gateway
@@ -282,16 +275,19 @@ openclaw plugins remove botschat
 
 ## Development
 
-### Build the plugin
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full development guide — local setup, Mock OpenClaw for testing, architecture principles, WebSocket protocol, database migrations, and more.
+
+### Quick Start
 
 ```bash
-npm run build:plugin
+./scripts/dev.sh         # Build + migrate + start server + mock AI + open browser
 ```
 
-### Type-check everything
+### Build
 
 ```bash
-npm run typecheck
+npm run build -w packages/web      # Build frontend
+npm run build -w packages/plugin   # Build plugin
 ```
 
 

package/migrations/0012_push_tokens.sql

@@ -0,0 +1,11 @@
+-- Push notification device tokens (FCM registration tokens)
+CREATE TABLE IF NOT EXISTS push_tokens (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token TEXT NOT NULL,
+  platform TEXT NOT NULL CHECK (platform IN ('web', 'ios', 'android')),
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE(user_id, token)
+);
+CREATE INDEX IF NOT EXISTS idx_push_tokens_user ON push_tokens(user_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botschat",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "description": "A self-hosted chat interface for OpenClaw AI agents",
   "workspaces": [
     "packages/*"
@@ -16,6 +16,14 @@
     "db:migrate:remote": "wrangler d1 migrations apply botschat-db --remote",
     "typecheck": "tsc --noEmit",
     "build:plugin": "npm run build -w packages/plugin",
+    "ios:build": "npm run build -w packages/web && npx cap sync ios",
+    "ios:open": "npx cap open ios",
+    "ios:run": "npx cap run ios",
+    "ios:sync": "npx cap sync ios",
+    "android:build": "npm run build -w packages/web && npx cap sync android",
+    "android:open": "npx cap open android",
+    "android:run": "npx cap run android",
+    "android:sync": "npx cap sync android",
     "test:e2e": "npx tsx scripts/verify-e2e.ts && npx tsx packages/e2e-crypto/e2e-crypto.test.ts",
     "test:e2e-db": "npx tsx scripts/verify-e2e-db.ts"
   },
@@ -49,10 +57,21 @@
     "url": "git+https://github.com/botschat-app/botsChat.git"
   },
   "devDependencies": {
+    "@capacitor/cli": "^8.1.0",
     "typescript": "^5.7.0",
     "wrangler": "^3.100.0"
   },
   "dependencies": {
+    "@capacitor/android": "^8.1.0",
+    "@capacitor/app": "^8.0.1",
+    "@capacitor/core": "^8.1.0",
+    "@capacitor/haptics": "^8.0.0",
+    "@capacitor/ios": "^8.1.0",
+    "@capacitor/keyboard": "^8.0.0",
+    "@capacitor/push-notifications": "^8.0.1",
+    "@capacitor/splash-screen": "^8.0.1",
+    "@capacitor/status-bar": "^8.0.1",
+    "@capgo/capacitor-social-login": "^8.3.1",
     "react-resizable-panels": "^4.6.2"
   }
 }

package/packages/api/src/do/connection-do.ts

@@ -1,5 +1,6 @@
 import type { Env } from "../env.js";
-import { verifyToken, getJwtSecret } from "../utils/auth.js";
+import { verifyToken, getJwtSecret, signMediaUrl } from "../utils/auth.js";
+import { getFcmAccessToken, sendPushNotification } from "../utils/fcm.js";
 import { generateId as generateIdUtil } from "../utils/id.js";
 import { randomUUID } from "../utils/uuid.js";
 
@@ -27,6 +28,9 @@ export class ConnectionDO implements DurableObject {
   /** Pending resolve for a real-time task.scan.request → task.scan.result round-trip. */
   private pendingScanResolve: ((tasks: Array<Record<string, unknown>>) => void) | null = null;
 
+  /** Browser sessions that report themselves in foreground (push notifications are suppressed). */
+  private foregroundSessions = new Set<string>();
+
   constructor(state: DurableObjectState, env: Env) {
     this.state = state;
     this.env = env;
@@ -115,7 +119,10 @@ export class ConnectionDO implements DurableObject {
         JSON.stringify({ type: "openclaw.disconnected" }),
       );
     }
-    // No explicit cleanup needed — the runtime manages the socket list
+    // Clean up foreground tracking for browser sessions
+    if (tag?.startsWith("browser:")) {
+      this.foregroundSessions.delete(tag);
+    }
   }
 
   /** Called when a WebSocket encounters an error. */
@@ -313,6 +320,17 @@ export class ConnectionDO implements DurableObject {
       console.log(`[DO] Forwarding agent.text to browsers: encrypted=${msg.encrypted}, messageId=${msg.messageId}, textLen=${typeof msg.text === "string" ? msg.text.length : "?"}`);
     }
     this.broadcastToBrowsers(JSON.stringify(msg));
+
+    // Send push notification if no browser session is in foreground
+    if (
+      (msg.type === "agent.text" || msg.type === "agent.media" || msg.type === "agent.a2ui") &&
+      this.foregroundSessions.size === 0 &&
+      this.env.FCM_SERVICE_ACCOUNT_JSON
+    ) {
+      this.sendPushNotifications(msg).catch((err) => {
+        console.error("[DO] Push notification failed:", err);
+      });
+    }
   }
 
   private async handleBrowserMessage(
@@ -370,6 +388,18 @@ export class ConnectionDO implements DurableObject {
       return;
     }
 
+    // Handle foreground/background state tracking for push notifications
+    if (msg.type === "foreground.enter") {
+      const tag = attachment.tag;
+      if (tag) this.foregroundSessions.add(tag);
+      return;
+    }
+    if (msg.type === "foreground.leave") {
+      const tag = attachment.tag;
+      if (tag) this.foregroundSessions.delete(tag);
+      return;
+    }
+
     // Persist user messages to D1
     if (msg.type === "user.message") {
       console.log("[DO] User inbound:", JSON.stringify({
@@ -564,6 +594,65 @@ export class ConnectionDO implements DurableObject {
     }
   }
 
+  // ---- Push notifications ----
+
+  /**
+   * Send push notifications to all of the user's registered devices.
+   * Called when an agent message arrives and no browser session is in foreground.
+   * Sends data-only FCM messages so clients can decrypt E2E content before showing.
+   */
+  private async sendPushNotifications(msg: Record<string, unknown>): Promise<void> {
+    const userId = await this.state.storage.get<string>("userId");
+    if (!userId) return;
+
+    const { results } = await this.env.DB.prepare(
+      "SELECT id, token, platform FROM push_tokens WHERE user_id = ?",
+    )
+      .bind(userId)
+      .all<{ id: string; token: string; platform: string }>();
+
+    if (!results || results.length === 0) return;
+
+    // Build data payload — includes ciphertext so the client can decrypt
+    const data: Record<string, string> = {
+      type: msg.type as string,
+      sessionKey: (msg.sessionKey as string) ?? "",
+      messageId: (msg.messageId as string) ?? "",
+      encrypted: msg.encrypted ? "1" : "0",
+    };
+
+    if (msg.type === "agent.text") {
+      data.text = (msg.text as string) ?? "";
+    } else if (msg.type === "agent.media") {
+      data.text = (msg.caption as string) || "";
+      data.mediaUrl = (msg.mediaUrl as string) ?? "";
+    } else if (msg.type === "agent.a2ui") {
+      data.text = "New interactive message";
+    }
+
+    const accessToken = await getFcmAccessToken(this.env.FCM_SERVICE_ACCOUNT_JSON!);
+    const projectId = this.env.FIREBASE_PROJECT_ID ?? "botschat-130ff";
+
+    const invalidTokenIds: string[] = [];
+    await Promise.allSettled(
+      results.map(async (row) => {
+        const ok = await sendPushNotification({
+          accessToken,
+          projectId,
+          fcmToken: row.token,
+          data,
+        });
+        if (!ok) invalidTokenIds.push(row.id);
+      }),
+    );
+
+    // Clean up invalid/expired tokens
+    for (const id of invalidTokenIds) {
+      await this.env.DB.prepare("DELETE FROM push_tokens WHERE id = ?").bind(id).run();
+      console.log(`[DO] Removed invalid push token: ${id}`);
+    }
+  }
+
   // ---- Media caching ----
 
   // ---- SSRF protection ----
@@ -639,16 +728,11 @@ export class ConnectionDO implements DurableObject {
         return null;
       }
 
-      const contentType = response.headers.get("Content-Type") ?? "image/png";
-      // Validate that the response is actually an image
-      if (!contentType.startsWith("image/")) {
-        console.warn(`[DO] cacheExternalMedia: non-image Content-Type "${contentType}", skipping ${url.slice(0, 120)}`);
-        return null;
-      }
+      const contentType = response.headers.get("Content-Type") ?? "application/octet-stream";
 
-      // Reject SVG (can contain scripts — XSS vector)
-      if (contentType.includes("svg")) {
-        console.warn(`[DO] cacheExternalMedia: blocked SVG content from ${url.slice(0, 120)}`);
+      // Reject SVG (can contain scripts — XSS vector) and executable types
+      if (contentType.includes("svg") || contentType.includes("javascript") || contentType.includes("executable")) {
+        console.warn(`[DO] cacheExternalMedia: blocked dangerous Content-Type "${contentType}" from ${url.slice(0, 120)}`);
         return null;
       }
 
@@ -670,14 +754,18 @@ export class ConnectionDO implements DurableObject {
         return null;
       }
 
-      // Determine extension from Content-Type (no SVG)
+      // Determine extension from Content-Type
       const extMap: Record<string, string> = {
         "image/png": "png",
         "image/jpeg": "jpg",
         "image/gif": "gif",
         "image/webp": "webp",
+        "application/pdf": "pdf",
+        "audio/mpeg": "mp3",
+        "audio/wav": "wav",
+        "video/mp4": "mp4",
       };
-      const ext = extMap[contentType] ?? "png";
+      const ext = extMap[contentType] ?? (contentType.startsWith("image/") ? "png" : "bin");
       const key = `media/${userId}/${Date.now()}-${randomUUID().slice(0, 8)}.${ext}`;
 
       // Upload to R2
@@ -685,7 +773,11 @@ export class ConnectionDO implements DurableObject {
         httpMetadata: { contentType },
       });
 
-      const localUrl = `/api/media/${key.replace("media/", "")}`;
+      // Sign the cached media URL so the browser can fetch it without Bearer auth.
+      // key is "media/{userId}/{filename}" — extract just the filename part.
+      const cachedFilename = key.replace(`media/${userId}/`, "");
+      const secret = getJwtSecret(this.env);
+      const localUrl = await signMediaUrl(userId, cachedFilename, secret, 3600);
       console.log(`[DO] cacheExternalMedia: OK ${url.slice(0, 80)} → ${localUrl} (${body.byteLength} bytes)`);
       return localUrl;
     } catch (err) {
@@ -694,6 +786,21 @@ export class ConnectionDO implements DurableObject {
     }
   }
 
+  /**
+   * Re-sign a media URL with a fresh signature. Handles both relative
+   * (/api/media/...) and absolute (https://host/api/media/...) URLs.
+   * Returns a freshly signed relative URL, or the original if not a media URL.
+   */
+  private async refreshMediaUrl(url: string, secret: string): Promise<string> {
+    // Extract userId and filename from /api/media/:userId/:filename patterns
+    const match = url.match(/\/api\/media\/([^/?]+)\/([^?]+)/);
+    if (!match) return url; // Not a media URL — return as-is
+
+    const userId = decodeURIComponent(match[1]);
+    const filename = decodeURIComponent(match[2]);
+    return signMediaUrl(userId, filename, secret, 3600);
+  }
+
   // ---- Message persistence ----
 
   private async persistMessage(opts: {
@@ -785,16 +892,27 @@ export class ConnectionDO implements DurableObject {
         }
       }
 
-      const messages = (result.results ?? []).map((row: Record<string, unknown>) => ({
-        id: row.id,
-        sender: row.sender,
-        text: row.text ?? "",
-        timestamp: ((row.created_at as number) ?? 0) * 1000, // unix seconds → ms
-        mediaUrl: row.media_url ?? undefined,
-        a2ui: row.a2ui ?? undefined,
-        threadId: row.thread_id ?? undefined,
-        encrypted: row.encrypted ?? 0,
-      }));
+      // Re-sign media URLs so they're always fresh when loading history.
+      // Stored URLs may have expired signatures or no signature at all.
+      const secret = getJwtSecret(this.env);
+      const messages = await Promise.all(
+        (result.results ?? []).map(async (row: Record<string, unknown>) => {
+          let mediaUrl = (row.media_url as string | null) ?? undefined;
+          if (mediaUrl) {
+            mediaUrl = await this.refreshMediaUrl(mediaUrl, secret);
+          }
+          return {
+            id: row.id,
+            sender: row.sender,
+            text: row.text ?? "",
+            timestamp: ((row.created_at as number) ?? 0) * 1000, // unix seconds → ms
+            mediaUrl,
+            a2ui: row.a2ui ?? undefined,
+            threadId: row.thread_id ?? undefined,
+            encrypted: row.encrypted ?? 0,
+          };
+        }),
+      );
 
       return Response.json({ messages, replyCounts });
     } catch (err) {

package/packages/api/src/env.ts

@@ -6,6 +6,12 @@ export type Env = {
   ENVIRONMENT: string;
   JWT_SECRET?: string;
   FIREBASE_PROJECT_ID?: string;
+  GOOGLE_WEB_CLIENT_ID?: string;
+  GOOGLE_IOS_CLIENT_ID?: string;
   /** Canonical public URL override — if set, always use this as cloudUrl. */
   PUBLIC_URL?: string;
+  /** Secret for dev-token auth bypass (automated testing). Endpoint is 404 when unset. */
+  DEV_AUTH_SECRET?: string;
+  /** FCM Service Account JSON for push notifications (stored as secret via `wrangler secret put`). */
+  FCM_SERVICE_ACCOUNT_JSON?: string;
 };

package/packages/api/src/index.ts

@@ -11,7 +11,9 @@ import { models } from "./routes/models.js";
 import { pairing } from "./routes/pairing.js";
 import { sessions } from "./routes/sessions.js";
 import { upload } from "./routes/upload.js";
+import { push } from "./routes/push.js";
 import { setup } from "./routes/setup.js";
+import { devAuth } from "./routes/dev-auth.js";
 
 // Re-export the Durable Object class so wrangler can find it
 export { ConnectionDO } from "./do/connection-do.js";
@@ -23,6 +25,9 @@ const PRODUCTION_ORIGINS = [
   "https://console.botschat.app",
   "https://botschat.app",
   "https://botschat-api.auxtenwpc.workers.dev",
+  "capacitor://localhost",  // iOS Capacitor app
+  "http://localhost",       // Android Capacitor app (http scheme)
+  "https://localhost",      // Android Capacitor app (https scheme)
 ];
 
 // CORS and security headers — skip for WebSocket upgrade requests
@@ -81,6 +86,7 @@ app.get("/api/health", (c) => c.json({ status: "ok", version: "0.1.0" }));
 
 // ---- Public routes (no auth) ----
 app.route("/api/auth", auth);
+app.route("/api/dev-auth", devAuth);
 app.route("/api/setup", setup);
 
 // ---- Protected routes (require Bearer token) ----
@@ -271,6 +277,7 @@ protectedApp.route("/channels/:channelId/tasks/:taskId/jobs", jobs);
 // Nested session routes under /api/channels/:channelId/sessions
 protectedApp.route("/channels/:channelId/sessions", sessions);
 protectedApp.route("/pairing-tokens", pairing);
+protectedApp.route("/push-tokens", push);
 protectedApp.route("/upload", upload);
 
 // ---- Media serving route (signed URL or Bearer auth) ----

package/packages/api/src/routes/auth.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import type { Env } from "../env.js";
 import { createToken, createRefreshToken, verifyRefreshToken, hashPassword, verifyPassword, getJwtSecret } from "../utils/auth.js";
-import { verifyFirebaseIdToken } from "../utils/firebase.js";
+import { verifyAnyGoogleToken } from "../utils/firebase.js";
 import { generateId } from "../utils/id.js";
 
 const auth = new Hono<{ Bindings: Env }>();
@@ -140,20 +140,21 @@ async function handleFirebaseAuth(c: {
     return c.json({ error: "Firebase sign-in is not configured" }, 500);
   }
 
-  // 1. Verify the Firebase ID token
+  // 1. Verify the ID token (Firebase or native Google)
+  // Allowed Google client IDs for native iOS/Android sign-in
+  const allowedGoogleClientIds = [
+    c.env.GOOGLE_WEB_CLIENT_ID,       // Web Client ID (iOSServerClientId)
+    c.env.GOOGLE_IOS_CLIENT_ID,       // iOS Client ID
+  ].filter(Boolean) as string[];
+
   let firebaseUser;
   try {
-    firebaseUser = await verifyFirebaseIdToken(idToken, projectId);
+    firebaseUser = await verifyAnyGoogleToken(idToken, projectId, allowedGoogleClientIds);
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Token verification failed";
     return c.json({ error: msg }, 401);
   }
 
-  const email = firebaseUser.email?.toLowerCase();
-  if (!email) {
-    return c.json({ error: "Account has no email address" }, 400);
-  }
-
   const firebaseUid = firebaseUser.sub;
   // Determine provider from Firebase token (google.com, github.com, etc.)
   const signInProvider = firebaseUser.firebase?.sign_in_provider ?? "unknown";
@@ -161,7 +162,21 @@ async function handleFirebaseAuth(c: {
     ? "google"
     : signInProvider.includes("github")
       ? "github"
-      : signInProvider;
+      : signInProvider.includes("apple")
+        ? "apple"
+        : signInProvider;
+
+  // Apple Sign-In may hide the user's real email; generate a short placeholder
+  let email = firebaseUser.email?.toLowerCase() || null;
+  if (!email && authProvider === "apple") {
+    const hash = Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(firebaseUid))))
+      .slice(0, 6).map(b => b.toString(16).padStart(2, "0")).join("");
+    email = `apple_${hash}@privaterelay.appleid.com`;
+  }
+  if (!email) {
+    return c.json({ error: "Account has no email address" }, 400);
+  }
+
   const displayName = firebaseUser.name ?? email.split("@")[0];
 
   // 2. Look up existing user by firebase_uid first, then by email
@@ -235,6 +250,44 @@ async function handleFirebaseAuth(c: {
 auth.post("/firebase", (c) => handleFirebaseAuth(c));
 auth.post("/google", (c) => handleFirebaseAuth(c));
 auth.post("/github", (c) => handleFirebaseAuth(c));
+auth.post("/apple", (c) => handleFirebaseAuth(c));
+
+/**
+ * POST /api/auth/dev-login — development-only passwordless login by email.
+ * Used for mobile debugging when OAuth is not yet working.
+ */
+auth.post("/dev-login", async (c) => {
+  if (c.env.ENVIRONMENT !== "development") {
+    return c.json({ error: "Dev login is only available in development mode" }, 403);
+  }
+
+  const { email } = await c.req.json<{ email: string }>();
+  if (!email?.trim()) {
+    return c.json({ error: "email is required" }, 400);
+  }
+
+  const row = await c.env.DB.prepare(
+    "SELECT id, email, display_name FROM users WHERE email = ?",
+  )
+    .bind(email.trim().toLowerCase())
+    .first<{ id: string; email: string; display_name: string | null }>();
+
+  if (!row) {
+    return c.json({ error: "User not found" }, 404);
+  }
+
+  const secret = getJwtSecret(c.env);
+  const token = await createToken(row.id, secret);
+  const refreshToken = await createRefreshToken(row.id, secret);
+
+  return c.json({
+    id: row.id,
+    email: row.email,
+    displayName: row.display_name,
+    token,
+    refreshToken,
+  });
+});
 
 /** POST /api/auth/refresh — exchange a refresh token for a new access token */
 auth.post("/refresh", async (c) => {
@@ -264,6 +317,7 @@ auth.get("/config", (c) => {
     emailEnabled: isDev,
     googleEnabled: !!c.env.FIREBASE_PROJECT_ID,
     githubEnabled: !!c.env.FIREBASE_PROJECT_ID,
+    appleEnabled: !!c.env.FIREBASE_PROJECT_ID,
   });
 });
 
@@ -299,4 +353,26 @@ auth.get("/me", async (c) => {
   });
 });
 
+/** DELETE /api/auth/account — permanently delete the authenticated user's account and all data */
+auth.delete("/account", async (c) => {
+  const userId = c.get("userId" as never) as string;
+  if (!userId) return c.json({ error: "Unauthorized" }, 401);
+
+  // Delete all user media from R2
+  const prefix = `${userId}/`;
+  let cursor: string | undefined;
+  do {
+    const listed = await c.env.MEDIA.list({ prefix, cursor });
+    if (listed.objects.length > 0) {
+      await Promise.all(listed.objects.map(obj => c.env.MEDIA.delete(obj.key)));
+    }
+    cursor = listed.truncated ? listed.cursor : undefined;
+  } while (cursor);
+
+  // Delete user record — all related tables use ON DELETE CASCADE
+  await c.env.DB.prepare("DELETE FROM users WHERE id = ?").bind(userId).run();
+
+  return c.json({ ok: true });
+});
+
 export { auth };

package/packages/api/src/routes/channels.ts

@@ -74,10 +74,11 @@ channels.post("/", async (c) => {
     .bind(taskId, id, "Ad Hoc Chat", "adhoc", sessionKey)
     .run();
 
-  // Auto-create a default session
+  // Auto-create a default session (INSERT OR IGNORE to handle duplicate session_key
+  // gracefully — can happen if user re-creates a channel with the same name)
   const sessionId = generateId("ses_");
   await c.env.DB.prepare(
-    "INSERT INTO sessions (id, channel_id, user_id, name, session_key) VALUES (?, ?, ?, ?, ?)",
+    "INSERT OR IGNORE INTO sessions (id, channel_id, user_id, name, session_key) VALUES (?, ?, ?, ?, ?)",
   )
     .bind(sessionId, id, userId, "Session 1", sessionKey)
     .run();

package/packages/api/src/routes/dev-auth.ts

@@ -0,0 +1,45 @@
+import { Hono } from "hono";
+import type { Env } from "../env.js";
+import { createToken, getJwtSecret } from "../utils/auth.js";
+import { generateId } from "../utils/id.js";
+
+const devAuth = new Hono<{ Bindings: Env }>();
+
+/**
+ * POST /api/dev-auth/login — secret-gated dev login for automated testing.
+ * Returns 404 when DEV_AUTH_SECRET is not configured (endpoint invisible).
+ * Auto-creates the user record in D1 if it doesn't exist (upsert).
+ */
+devAuth.post("/login", async (c) => {
+  const devSecret = c.env.DEV_AUTH_SECRET;
+  if (!devSecret || c.env.ENVIRONMENT !== "development") {
+    return c.json({ error: "Not found" }, 404);
+  }
+
+  const { secret, userId: requestedUserId } = await c.req.json<{ secret: string; userId?: string }>();
+  if (!secret || secret !== devSecret) {
+    return c.json({ error: "Forbidden" }, 403);
+  }
+
+  const userId = requestedUserId || "dev-test-user";
+  const jwtSecret = getJwtSecret(c.env);
+  const token = await createToken(userId, jwtSecret);
+
+  // Ensure the user exists in D1 (upsert) so foreign key constraints are satisfied.
+  // Dev-auth users get a placeholder email and no password (login only via dev-auth).
+  try {
+    const existing = await c.env.DB.prepare("SELECT id FROM users WHERE id = ?").bind(userId).first();
+    if (!existing) {
+      const email = `${userId}@dev.botschat.test`;
+      await c.env.DB.prepare(
+        "INSERT INTO users (id, email, password_hash, display_name) VALUES (?, ?, '', ?)",
+      ).bind(userId, email, userId).run();
+    }
+  } catch (err) {
+    console.error("[dev-auth] Failed to upsert user:", err);
+  }
+
+  return c.json({ token, userId });
+});
+
+export { devAuth };

package/packages/api/src/routes/push.ts

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+import type { Env } from "../env.js";
+import { generateId } from "../utils/id.js";
+
+const push = new Hono<{ Bindings: Env; Variables: { userId: string } }>();
+
+/** POST /api/push-tokens — register or update a device push token */
+push.post("/", async (c) => {
+  const userId = c.get("userId");
+  const { token, platform } = await c.req.json<{ token: string; platform: string }>();
+
+  if (!token || !platform) {
+    return c.json({ error: "Missing token or platform" }, 400);
+  }
+  if (!["web", "ios", "android"].includes(platform)) {
+    return c.json({ error: "Invalid platform (web | ios | android)" }, 400);
+  }
+
+  const id = generateId("pt_");
+  const now = Math.floor(Date.now() / 1000);
+
+  // Upsert: if the same user+token already exists, update the timestamp
+  await c.env.DB.prepare(
+    `INSERT INTO push_tokens (id, user_id, token, platform, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(user_id, token) DO UPDATE SET platform = excluded.platform, updated_at = excluded.updated_at`,
+  )
+    .bind(id, userId, token, platform, now, now)
+    .run();
+
+  return c.json({ ok: true, id }, 201);
+});
+
+/** DELETE /api/push-tokens — unregister a device push token */
+push.delete("/", async (c) => {
+  const userId = c.get("userId");
+  const { token } = await c.req.json<{ token: string }>().catch(() => ({ token: "" }));
+
+  if (!token) {
+    return c.json({ error: "Missing token" }, 400);
+  }
+
+  await c.env.DB.prepare(
+    "DELETE FROM push_tokens WHERE user_id = ? AND token = ?",
+  )
+    .bind(userId, token)
+    .run();
+
+  return c.json({ ok: true });
+});
+
+export { push };