@mordn/chat-widget 0.7.0 → 0.8.0

package/README.md

@@ -1,20 +1,40 @@
 # @mordn/chat-widget
 
-A customizable AI chat widget for React/Next.js applications with built-in conversation persistence.
+A customizable, **secure-by-default** AI chat widget for React/Next.js apps,
+with conversation persistence and attachments handled for you.
+
+The widget owns the hard, dangerous-to-get-wrong backend plumbing — conversation
+ownership, idempotent persistence, history, private attachments, streaming —
+behind one mounted handler. You supply the three things that are genuinely
+yours: **who the user is** (auth), **which model**, and **which tools**.
+
+> ## ⚠️ Security: you establish identity on the server
+>
+> The widget sends an `X-User-Id` header, but **it is not an authentication
+> boundary** — the browser controls it. You must implement `getChatUserId(req)`
+> to return the user id from your **verified server session** (Clerk, NextAuth,
+> Supabase Auth, …). The scaffold's stub **throws until you do this**, so a
+> fresh install is never silently insecure.
+>
+> Trusting a client-supplied id is the IDOR bug that lets one user read another
+> user's chats. The package is designed so this is *unrepresentable* once you
+> wire up `getChatUserId`. **Read [SECURITY.md](./SECURITY.md).**
 
 ## Quick Start
 
 ```bash
-# 1. Install the package
+# 1. Install
 npm install @mordn/chat-widget drizzle-kit
 
 # 2. Run the setup wizard
 npx @mordn/chat-widget
 ```
 
-The setup wizard creates all required files:
-- API routes (`/api/chat/...`)
-- `drizzle.config.ts`
+The wizard creates exactly four files:
+
+- `app/api/chat/[[...chat]]/route.ts` — one catch-all that mounts the whole backend
+- `lib/chat-auth.ts` — the `getChatUserId` stub **you implement** (the security boundary)
+- `drizzle.config.ts` — points at the package's chat schema
 - `.env.example`
 
 ## Requirements
@@ -23,41 +43,56 @@ The setup wizard creates all required files:
 - React 18+
 - PostgreSQL database (Supabase recommended)
 - Tailwind CSS v4
+- `ai` v5 or v6 (peer dependency)
 
 ## Setup
 
 ### 1. Environment Variables
 
-Copy `.env.example` to `.env.local` and fill in your credentials:
+Copy `.env.example` to `.env.local` and fill in your credentials (see the file
+for the full list — `DATABASE_URL`, and the Supabase keys if you keep uploads).
 
-```env
-# Database (Required)
-DATABASE_URL="postgresql://postgres.xxx:[PASSWORD]@aws-0-region.pooler.supabase.com:6543/postgres"
+### 2. Implement the auth boundary
 
-# AI Provider (Required)
-AI_GATEWAY_API_KEY="your-ai-gateway-key"
-```
+Open `lib/chat-auth.ts` and replace the throwing stub with your real session
+lookup:
 
-### 2. Database Setup
+```ts
+// Clerk example
+import { auth } from '@clerk/nextjs/server';
+
+export async function getChatUserId() {
+  const { userId } = await auth();   // from the verified session — never a header
+  return userId;
+}
+```
 
-Push the schema to your database:
+### 3. Database Setup
 
 ```bash
-npx drizzle-kit push
+npx drizzle-kit push   # creates chat_conversations + chat_messages
 ```
 
-### 3. Configure Your AI Model
+### 4. Configure your model and tools
 
-Open `app/api/chat/route.ts` and update the config:
+Everything is configured in the single `route.ts` the wizard created — model,
+system prompt, store, storage, and tools:
 
-```typescript
-const DEVELOPER_CONFIG = {
-  model: 'openai/gpt-4o', // Your AI model
-  systemPrompt: 'You are a helpful assistant',
-  temperature: 0.7,
-};
+```ts
+export const { GET, POST, DELETE } = createChatHandler({
+  getUserId: getChatUserId,
+  model: anthropic('claude-sonnet-4-5'),
+  store: createDrizzleChatStore(),       // or bring your own ChatStore
+  storage: createSupabaseStorage(),      // or bring your own StorageAdapter
+  // buildTools: async (ctx) => ({ tools: { /* ... */ }, cleanup: async () => {} }),
+});
 ```
 
+**Bring your own database / storage:** pass a custom `store` / `storage` that
+implement the `ChatStore` / `StorageAdapter` interfaces from
+`@mordn/chat-widget/server`. The hosted defaults and your own implementations
+are interchangeable — same handler, same security.
+
 ### 4. Add the Widget
 
 ```tsx

package/SECURITY.md

@@ -0,0 +1,101 @@
+# Security model
+
+This document explains how `@mordn/chat-widget` keeps one user's
+conversations and attachments private from another's, and the one thing **you**
+must do to uphold it.
+
+## TL;DR
+
+- **You establish identity on the server.** You implement `getChatUserId(req)`
+  to return the user id from your *verified* server session.
+- **The widget's `X-User-Id` header is not an auth boundary.** The client sends
+  it; the server ignores it for authorization. Never trust it.
+- **The package enforces the rest.** Conversation ownership, per-user data
+  scoping, private attachments, and signed URLs are handled inside the package
+  and are not your responsibility to wire up correctly.
+
+## The threat we designed against: IDOR
+
+IDOR — *Insecure Direct Object Reference* — is when a server uses a
+client-supplied identifier to fetch data **without checking the requester owns
+it**. For a chat product the identifier is the user id (and the conversation
+id). If a route does this:
+
+```ts
+// ❌ NEVER do this
+const userId = req.headers.get('X-User-Id');     // browser controls this
+return getConversations(userId);                  // returns anyone's chats
+```
+
+…then any user can read or write any other user's conversations by changing a
+header. This is the single most important class of bug for a multi-user chat
+app, and it is easy to introduce by accident.
+
+## How the package prevents it
+
+### 1. Identity comes from your server session — `getChatUserId`
+
+`createChatHandler` calls **your** `getChatUserId(request)` and uses whatever it
+returns as the only identity for the request. Implement it against your auth
+system's *server-verified* session:
+
+```ts
+// ✅ Clerk
+import { auth } from '@clerk/nextjs/server';
+export async function getChatUserId() {
+  const { userId } = await auth();
+  return userId;            // from a verified session cookie/JWT
+}
+```
+
+The `request` is passed in so you can read **verified** cookies — not so you can
+read a client-asserted id. Returning a value derived from `req.headers`,
+`req.url` query params, or the JSON body re-introduces the IDOR. The scaffolded
+stub **throws until you implement it**, so a fresh install is never silently
+insecure.
+
+### 2. The data layer is bound to one user — IDOR is unrepresentable
+
+Internally, the store and storage adapters are **constructed bound to the
+verified `userId`**. None of their methods accept a user id. There is no
+parameter through which a foreign id could enter, so "fetch user B's data while
+acting as user A" cannot be expressed in the code at all — it's a type-level
+guarantee, not a convention you have to remember.
+
+- `getConversation(id)` returns `null` when the conversation exists but belongs
+  to another user — indistinguishable from "not found", so existence can't be
+  probed.
+- Creating/writing a conversation that belongs to another user is rejected
+  (HTTP 403) before anything is persisted.
+- Listing and message reads are implicitly scoped to the bound user.
+
+### 3. Attachments are private by default
+
+The default storage adapter:
+
+- writes to a **private** bucket (never a public URL),
+- returns **short-lived signed URLs**, re-signed on demand when old
+  conversations are reloaded,
+- stores files under **user-namespaced, unguessable paths** derived from the
+  bound user id, and refuses to sign or delete anything outside that namespace.
+
+The bucket you create **must be private**. The adapter never relies on public
+read; if you make the bucket public you reopen a hole the package otherwise
+closes.
+
+## Your responsibilities checklist
+
+- [ ] Implement `getChatUserId` to return the id from your **server** session.
+- [ ] Never read identity from `X-User-Id`, query params, or the request body.
+- [ ] Create the attachments bucket as **private** (if you keep uploads).
+- [ ] Keep `SUPABASE_SERVICE_ROLE_KEY` server-side only (never `NEXT_PUBLIC_`).
+
+If you bring your own `ChatStore` or `StorageAdapter`, uphold the invariants
+documented on those interfaces — they are the security boundary for the custom
+path.
+
+## Reporting a vulnerability
+
+Please open a private report at
+<https://github.com/arnavv-guptaa/chat-widget/security/advisories> rather than a
+public issue.

package/dist/chat-store-DERCPwhl.d.mts

@@ -0,0 +1,278 @@
+import { UIMessage } from 'ai';
+
+/**
+ * Server-core domain types.
+ *
+ * This is the shared vocabulary for the server side of the widget — the
+ * persistence interfaces (`ChatStore`, `StorageAdapter`), the request
+ * router, and the lifecycle hooks all speak in these types.
+ *
+ * Design notes
+ * ------------
+ * 1. These types are deliberately decoupled from any specific database or
+ *    ORM. `ChatStore` is an interface; the Drizzle/Postgres implementation
+ *    that ships as the default is just *one* implementation of it. A hosted
+ *    backend, a Prisma store, or an in-memory test double are equally valid.
+ *
+ * 2. Messages are stored as AI SDK `UIMessage`s — specifically their `parts`
+ *    array — not as a flattened `content` string. The `parts` array is the
+ *    canonical representation the AI SDK round-trips (text, reasoning, tool
+ *    calls, sources, files). Storing anything less loses information on
+ *    rehydration. We keep a denormalised `text` alongside it purely for
+ *    cheap previews / titles / search — never as the source of truth.
+ *
+ * 3. Identity (`userId`) never appears as a *parameter* on read/write
+ *    methods. A `ChatStore` is constructed already bound to one verified
+ *    user (see `ChatStoreFactory`). This makes cross-user access
+ *    unrepresentable at the type level — you cannot ask a store for another
+ *    user's data because no method accepts a foreign id. That is the
+ *    security property, encoded in the shape of the API rather than left to
+ *    each caller's discipline.
+ */
+
+/**
+ * A single attachment as persisted on a message part.
+ *
+ * The `url` is a *freshly signed, short-lived* URL when this object is
+ * handed to the client — never a permanent public link. `storagePath` is
+ * the durable pointer the `StorageAdapter` uses to re-sign on demand when an
+ * old conversation is reloaded. Only `storagePath` is guaranteed stable
+ * across reads; treat `url` as ephemeral.
+ */
+interface StoredAttachment {
+    /** Durable, opaque pointer into the storage backend. Stable across reads. */
+    storagePath: string;
+    /** Freshly-signed, expiring URL for the client to fetch. Ephemeral. */
+    url: string;
+    /** Original filename as uploaded (for display + download). */
+    filename: string;
+    /** MIME type (e.g. `image/png`, `application/pdf`). */
+    mediaType: string;
+    /** Size in bytes. */
+    size: number;
+}
+/**
+ * A conversation row, as the store returns it. Summary-level — does not
+ * include messages. Use `listConversations` for the sidebar/history list and
+ * `getConversation` + `listMessages` to open one.
+ */
+interface StoredConversation {
+    id: string;
+    /**
+     * Human-readable title. Defaults to "New Chat" until the first user
+     * message lands, at which point the router auto-titles from it. Consumers
+     * can override via `renameConversation`.
+     */
+    title: string;
+    /** Free-form metadata bag the host app may stamp (never read by the core). */
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * Number of messages in the conversation. Populated by `listConversations`
+     * for the history list; may be omitted (`undefined`) by single-row reads
+     * where the count isn't needed.
+     */
+    messageCount?: number;
+}
+/**
+ * A message row, as the store returns it.
+ *
+ * `parts` is the canonical AI SDK representation and the source of truth for
+ * rendering. `text` is a denormalised convenience for previews/search and
+ * may be empty for messages whose content is entirely non-text (e.g. a
+ * tool-only assistant turn).
+ */
+interface StoredMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    /** Canonical AI SDK parts. Source of truth for rendering + model replay. */
+    parts: UIMessage['parts'];
+    /** Denormalised plain text for previews/titles/search. Not authoritative. */
+    text: string;
+    /** Which model produced this message, when known (assistant turns). */
+    model?: string;
+    createdAt: Date;
+}
+/**
+ * Pagination request for message history. The store returns the most-recent
+ * `limit` messages so a freshly-opened conversation shows the latest turns;
+ * `before` lets the client page backwards into older history.
+ */
+interface ListMessagesOptions {
+    /** Max messages to return. The store clamps this to a sane ceiling. */
+    limit?: number;
+    /**
+     * Return only messages created strictly before this instant. Used for
+     * "load older messages" infinite-scroll. Omit for the most-recent page.
+     */
+    before?: Date;
+}
+/**
+ * What `saveTurn` persists at the end of a streamed response: the final,
+ * complete set of UI messages for the turn (user message + assistant
+ * message, including any tool/reasoning/source parts the SDK emitted).
+ *
+ * The store is responsible for idempotency — re-saving messages whose ids
+ * already exist must be a no-op, never a duplicate. (Replays, retries, and
+ * the AI SDK's own resumability all deliver already-seen ids.)
+ */
+interface SaveTurnInput {
+    conversationId: string;
+    messages: UIMessage[];
+    /** Model that produced the assistant message(s) in this turn. */
+    model?: string;
+}
+
+/**
+ * ChatStore — the persistence contract for chat conversations and messages.
+ *
+ * This is one of the two pluggable backends of the widget (the other is
+ * `StorageAdapter` for attachments). The package ships a Drizzle/Postgres
+ * implementation as the default; a hosted backend or a BYO store (Prisma,
+ * raw SQL, DynamoDB, a test double) is simply another implementation of this
+ * same interface.
+ *
+ * ──────────────────────────────────────────────────────────────────────────
+ * The security model is in the shape of this API, not in its callers.
+ * ──────────────────────────────────────────────────────────────────────────
+ *
+ * A `ChatStore` is *bound to one verified user* at construction time (see
+ * `ChatStoreFactory`). None of its methods accept a `userId`. This is
+ * deliberate and it is the core defence against the IDOR class of bug:
+ *
+ *   - You cannot ask the store for "conversation X belonging to user Y",
+ *     because there is no parameter through which a foreign `userId` could
+ *     enter. The only user the store will ever read or write is the one it
+ *     was constructed with.
+ *
+ *   - Every method is therefore *implicitly scoped*. `listConversations()`
+ *     returns only the bound user's conversations. `getConversation(id)`
+ *     returns `null` — not someone else's row — when `id` exists but belongs
+ *     to a different user. `saveTurn(...)` refuses (throws
+ *     `ConversationOwnershipError`) if `conversationId` exists under another
+ *     user.
+ *
+ * The route layer's job shrinks to: authenticate the request, derive the
+ * real `userId` from the *server* session, construct a store bound to it,
+ * and call methods. There is no per-route ownership check to forget, because
+ * the store cannot be made to cross users.
+ *
+ * Implementations MUST uphold the contract documented on each method. The
+ * Drizzle default does; if you write your own, these invariants are the
+ * security boundary — treat them as load-bearing, not advisory.
+ */
+
+/**
+ * Thrown by mutating methods when the target conversation exists but is owned
+ * by a different user than the one this store is bound to. Callers should map
+ * this to an HTTP 403. (Read methods don't throw — they return `null`/`[]` —
+ * so that probing for existence can't distinguish "not found" from
+ * "forbidden", which would itself leak information.)
+ */
+declare class ConversationOwnershipError extends Error {
+    readonly conversationId: string;
+    constructor(conversationId: string);
+}
+interface ChatStore {
+    /**
+     * The user this store instance is bound to. Read-only; set at construction.
+     * Exposed so the router can stamp it onto storage paths, logs, etc. — never
+     * as something a caller can change.
+     */
+    readonly userId: string;
+    /**
+     * List the bound user's conversations, most-recently-updated first.
+     * Returns `messageCount` on each row for the history list. Returns `[]`
+     * (never throws) when the user has none.
+     */
+    listConversations(): Promise<StoredConversation[]>;
+    /**
+     * Fetch a single conversation by id, scoped to the bound user.
+     *
+     * Returns `null` when the conversation does not exist OR exists but belongs
+     * to another user — the two cases are intentionally indistinguishable to
+     * the caller (and thus to an attacker). Never returns another user's row.
+     */
+    getConversation(id: string): Promise<StoredConversation | null>;
+    /**
+     * Ensure a conversation row exists for `id`, owned by the bound user.
+     *
+     * - If no row exists for `id`: creates it, owned by the bound user, and
+     *   returns it.
+     * - If a row exists and is owned by the bound user: returns it unchanged
+     *   (idempotent — safe to call at the top of every request).
+     * - If a row exists but is owned by a *different* user: throws
+     *   `ConversationOwnershipError` and writes nothing.
+     *
+     * This is the single chokepoint that makes "write into someone else's
+     * conversation" impossible: the router calls it before persisting any
+     * message, so a forged conversation id is rejected before any data lands.
+     */
+    ensureConversation(id: string, init?: {
+        title?: string;
+    }): Promise<StoredConversation>;
+    /**
+     * Rename a conversation owned by the bound user. No-op (does not throw) if
+     * the conversation doesn't exist or isn't owned by the user — renaming is
+     * not security-sensitive and silent failure is friendlier here.
+     */
+    renameConversation(id: string, title: string): Promise<void>;
+    /**
+     * Delete a conversation (and cascade its messages + attachment rows) owned
+     * by the bound user. No-op if it doesn't exist or isn't owned by the user.
+     * Returns `true` if a row was actually deleted, `false` otherwise — lets
+     * the route return 404 vs 200 honestly without a separate existence check.
+     *
+     * Note: this deletes message *rows*. Purging the underlying attachment
+     * blobs from storage is the router's job (it has the `StorageAdapter`),
+     * driven off the attachments this method returns having referenced.
+     */
+    deleteConversation(id: string): Promise<boolean>;
+    /**
+     * Load messages for a conversation, scoped to the bound user, newest-first
+     * internally but returned in chronological order (oldest → newest) ready to
+     * render. Returns `[]` if the conversation doesn't exist or isn't owned by
+     * the user — same non-distinguishing contract as `getConversation`.
+     *
+     * Honours `ListMessagesOptions` for pagination. Implementations MUST clamp
+     * `limit` to a ceiling (default ceiling: 100) so a hostile client can't
+     * request an unbounded page.
+     */
+    listMessages(conversationId: string, opts?: ListMessagesOptions): Promise<StoredMessage[]>;
+    /**
+     * Persist the final messages of a completed turn.
+     *
+     * Contract:
+     *  - MUST verify the conversation is owned by the bound user first; throws
+     *    `ConversationOwnershipError` otherwise (defence in depth — the router
+     *    already called `ensureConversation`, but `saveTurn` must not trust
+     *    that).
+     *  - MUST be idempotent on message id: a message whose id already exists is
+     *    skipped, not duplicated. (The AI SDK delivers stable ids; replays and
+     *    retries re-deliver them.)
+     *  - MUST persist each message's full `parts` array as the source of truth,
+     *    plus a denormalised text projection for previews.
+     *  - MUST bump the conversation's `updatedAt`.
+     *
+     * Errors other than ownership (e.g. a transient DB failure) propagate so
+     * the router can log them loudly — a silently-dropped assistant turn is
+     * exactly the bug we're trying to design out.
+     */
+    saveTurn(input: SaveTurnInput): Promise<void>;
+}
+/**
+ * Constructs a `ChatStore` bound to a specific, already-verified user.
+ *
+ * The router calls this *after* it has authenticated the request and derived
+ * `userId` from the server session — never from anything client-supplied.
+ * Passing a client-controlled value here would reintroduce the very IDOR the
+ * bound-store design exists to prevent, so implementations should treat
+ * `userId` as a trusted server secret, not as request input.
+ *
+ * Construction is intended to be cheap (the underlying DB pool/connection is
+ * shared across instances) so a fresh store per request is the norm.
+ */
+type ChatStoreFactory = (userId: string) => ChatStore;
+
+export { type ChatStoreFactory as C, type ListMessagesOptions as L, type StoredAttachment as S, type StoredConversation as a, type StoredMessage as b, type SaveTurnInput as c, type ChatStore as d, ConversationOwnershipError as e };