---
phase: 16-multi-user-data-model
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/db/schema.ts
- src/db/seed.ts
- tests/helpers/db.ts
- src/server/middleware/auth.ts
- src/server/services/auth.service.ts
- src/server/services/oauth.service.ts
- src/server/index.ts
autonomous: true
requirements:
- MULTI-01
- MULTI-04
- MULTI-06
must_haves:
truths:
- "A users table exists with id (serial PK), logtoSub (text unique), createdAt (timestamp)"
- "Every entity table (items, categories, threads, setups, settings, apiKeys) has a userId integer FK column"
- "Categories have a composite unique constraint on (userId, name) instead of unique(name)"
- "Settings have a composite primary key on (userId, key) instead of just (key)"
- "requireAuth middleware resolves userId and sets it on Hono context"
- "verifyApiKey returns { userId } | null instead of boolean"
- "verifyAccessToken returns { userId } | null instead of boolean"
- "createTestDb returns { db, userId } with a seeded test user and per-user Uncategorized category"
- "All API routes require auth (no GET bypass) so userId is always available"
artifacts:
- path: "src/db/schema.ts"
provides: "Users table + userId columns on all entity tables + composite constraints"
contains: "export const users"
- path: "tests/helpers/db.ts"
provides: "Test DB with seeded user"
contains: "logtoSub"
- path: "src/server/middleware/auth.ts"
provides: "userId resolution middleware"
contains: "c.set(\"userId\""
key_links:
- from: "src/server/middleware/auth.ts"
to: "src/server/services/auth.service.ts"
via: "verifyApiKey returning userId"
pattern: "verifyApiKey.*userId"
- from: "src/server/middleware/auth.ts"
to: "src/server/services/oauth.service.ts"
via: "verifyAccessToken returning userId"
pattern: "verifyAccessToken.*userId"
---
Create the multi-user data model foundation: users table, userId columns on all entity tables, updated auth middleware that resolves userId onto Hono context, and updated test infrastructure.
Purpose: This is the foundation that all subsequent plans depend on. Without the schema changes, userId columns, and middleware resolution, no service or route can be updated to scope data per-user.
Output: Updated schema.ts with pgTable imports and users table, migration generated, auth middleware resolving userId, test helper returning { db, userId }.
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/16-multi-user-data-model/16-CONTEXT.md
@.planning/phases/16-multi-user-data-model/16-RESEARCH.md
@src/db/schema.ts
@src/db/seed.ts
@src/server/middleware/auth.ts
@src/server/services/auth.service.ts
@src/server/services/oauth.service.ts
@src/server/index.ts
@tests/helpers/db.ts
From src/db/schema.ts (current - uses sqliteTable, must switch to pgTable):
- categories: id, name (unique), icon, createdAt
- items: id, name, weightGrams, priceCents, categoryId, notes, productUrl, imageFilename, imageSourceUrl, quantity, createdAt, updatedAt
- threads: id, name, status, resolvedCandidateId, categoryId, createdAt, updatedAt
- threadCandidates: id, threadId, name, weightGrams, priceCents, categoryId, notes, productUrl, imageFilename, imageSourceUrl, status, pros, cons, sortOrder, createdAt, updatedAt
- setups: id, name, createdAt, updatedAt
- setupItems: id, setupId, itemId, classification
- settings: key (PK), value
- apiKeys: id, name, keyHash, keyPrefix, createdAt
- oauthClients: id, clientId, clientName, redirectUris, createdAt
- oauthCodes: id, code, clientId, codeChallenge, codeChallengeMethod, redirectUri, expiresAt, used
- oauthTokens: id, accessTokenHash, refreshTokenHash, clientId, expiresAt, refreshExpiresAt, createdAt
From src/server/services/auth.service.ts:
```typescript
export async function verifyApiKey(db: Db, rawKey: string): Promise
export async function createApiKey(db: Db, name: string)
export async function listApiKeys(db: Db)
export async function deleteApiKey(db: Db, id: number)
```
From src/server/services/oauth.service.ts:
```typescript
export async function verifyAccessToken(db: Db, token: string): Promise
```
Task 1: Migrate schema.ts to pgTable and add users table + userId columns
src/db/schema.ts, src/db/seed.ts
src/db/schema.ts, src/db/seed.ts, .planning/phases/16-multi-user-data-model/16-RESEARCH.md
1. Rewrite `src/db/schema.ts` to use `drizzle-orm/pg-core` imports instead of `drizzle-orm/sqlite-core`. Replace `sqliteTable` with `pgTable`, `integer("id").primaryKey({ autoIncrement: true })` with `serial("id").primaryKey()`, `integer` with `integer` from pg-core, `real` with `doublePrecision`, and `integer("...", { mode: "timestamp" })` with `timestamp("...").defaultNow()` (or equivalent).
2. Add the new `users` table per D-01:
```typescript
export const users = pgTable("users", {
id: serial("id").primaryKey(),
logtoSub: text("logto_sub").notNull().unique(),
createdAt: timestamp("created_at").defaultNow().notNull(),
});
```
3. Add `userId` column (integer, NOT NULL, FK to users.id) to these tables per D-04:
- `items`: `userId: integer("user_id").notNull().references(() => users.id)`
- `categories`: `userId: integer("user_id").notNull().references(() => users.id)`
- `threads`: `userId: integer("user_id").notNull().references(() => users.id)`
- `setups`: `userId: integer("user_id").notNull().references(() => users.id)`
- `apiKeys`: `userId: integer("user_id").notNull().references(() => users.id)` per D-07
- `oauthTokens`: `userId: integer("user_id").notNull().references(() => users.id)` (per Research open question 2)
4. Per D-05, change `categories` unique constraint from `name` alone to composite `(userId, name)`:
```typescript
export const categories = pgTable("categories", {
id: serial("id").primaryKey(),
name: text("name").notNull(),
icon: text("icon").notNull().default("package"),
userId: integer("user_id").notNull().references(() => users.id),
createdAt: timestamp("created_at").defaultNow().notNull(),
}, (table) => [
unique().on(table.userId, table.name),
]);
```
5. Per D-06, change `settings` PK from `key` alone to composite `(userId, key)`:
```typescript
export const settings = pgTable("settings", {
userId: integer("user_id").notNull().references(() => users.id),
key: text("key").notNull(),
value: text("value").notNull(),
}, (table) => [
primaryKey({ columns: [table.userId, table.key] }),
]);
```
6. Per D-08, do NOT add userId to `threadCandidates` or `setupItems` (they inherit ownership via parent FK).
7. Update `src/db/seed.ts`: The `seedDefaults()` function currently seeds a global Uncategorized category. Since categories now require userId, this global seed no longer works. Change `seedDefaults()` to be a no-op or remove the category seeding entirely (per-user Uncategorized will be created lazily or on first login per D-12). The function can remain as an empty function for now:
```typescript
export async function seedDefaults() {
// Per-user default categories are created on first login (Phase 16)
}
```
8. Run `bun run db:generate` to generate the new Drizzle migration into `drizzle-pg/`. Then verify the generated SQL includes the users table, userId columns, composite constraints, and FK relationships.
IMPORTANT: The schema.ts file MUST use pg-core imports (`pgTable`, `serial`, `text`, `timestamp`, `integer`, `doublePrecision`, `unique`, `primaryKey`). The existing `drizzle-pg/` migration directory already has PostgreSQL DDL from Phase 14.
grep -c "pgTable" src/db/schema.ts && grep -c "export const users" src/db/schema.ts && grep "userId" src/db/schema.ts | wc -l && grep -c "unique().on" src/db/schema.ts && grep -c "primaryKey" src/db/schema.ts
- `src/db/schema.ts` contains `import.*from "drizzle-orm/pg-core"` (no sqlite-core imports)
- `export const users = pgTable("users"` exists with `logtoSub`, `id`, `createdAt`
- `userId: integer("user_id").notNull().references(() => users.id)` appears in items, categories, threads, setups, apiKeys, oauthTokens
- `unique().on(table.userId, table.name)` exists in categories table definition
- `primaryKey({ columns: [table.userId, table.key] })` exists in settings table definition
- `threadCandidates` and `setupItems` do NOT have a userId column
- `src/db/seed.ts` no longer inserts a global Uncategorized category
- A new migration file exists in `drizzle-pg/` with the users table and userId column additions
Schema uses pg-core imports, users table exists, all 6 entity tables have userId FK, categories has composite unique, settings has composite PK, migration generated
Task 2: Update auth middleware and auth services to resolve userId
src/server/middleware/auth.ts, src/server/services/auth.service.ts, src/server/services/oauth.service.ts, src/server/index.ts
src/server/middleware/auth.ts, src/server/services/auth.service.ts, src/server/services/oauth.service.ts, src/server/index.ts, src/db/schema.ts
1. **Update `verifyApiKey` in `src/server/services/auth.service.ts`** per D-03/D-07:
Change return type from `Promise` to `Promise<{ userId: number } | null>`. The function queries apiKeys by keyPrefix, verifies the hash, and now returns `{ userId: candidate.userId }` on match or `null` on failure. Also update `createApiKey` to accept and store `userId`, `listApiKeys` to filter by `userId`, and `deleteApiKey` to filter by `userId` (using `and(eq(apiKeys.id, id), eq(apiKeys.userId, userId))`).
2. **Update `verifyAccessToken` in `src/server/services/oauth.service.ts`**:
Change return type from `Promise` to `Promise<{ userId: number } | null>`. Select `userId` from the oauthTokens record and return `{ userId: record.userId }` on success, `null` on failure. Also update `createTokens` to accept and store `userId`.
3. **Create `getOrCreateUser` function** in `src/server/services/auth.service.ts` per D-01:
```typescript
export async function getOrCreateUser(db: Db, logtoSub: string): Promise<{ id: number }> {
const [user] = await db
.insert(users)
.values({ logtoSub })
.onConflictDoUpdate({
target: users.logtoSub,
set: { logtoSub },
})
.returning({ id: users.id });
return user;
}
```
4. **Create `getOrCreateUncategorized` helper** in `src/server/services/category.service.ts` (or auth.service.ts):
```typescript
export async function getOrCreateUncategorized(db: Db, userId: number): Promise {
const [existing] = await db
.select({ id: categories.id })
.from(categories)
.where(and(eq(categories.userId, userId), eq(categories.name, "Uncategorized")));
if (existing) return existing.id;
const [created] = await db
.insert(categories)
.values({ name: "Uncategorized", icon: "package", userId })
.returning({ id: categories.id });
return created.id;
}
```
Place this in `category.service.ts` since it's category-related.
5. **Rewrite `requireAuth` in `src/server/middleware/auth.ts`** per D-03/D-10:
- For API key auth: call `verifyApiKey(db, apiKey)` which now returns `{ userId } | null`. On success, `c.set("userId", result.userId)` and call `next()`.
- For OAuth Bearer: call `verifyAccessToken(db, token)` which now returns `{ userId } | null`. On success, `c.set("userId", result.userId)`.
- For OIDC session: call `getAuth(c)` for the sub claim, then `getOrCreateUser(db, auth.sub)` to get the local userId. Then call `getOrCreateUncategorized(db, user.id)` to ensure the user has a default category. Set `c.set("userId", user.id)`.
- Import `getOrCreateUser` from auth.service and `getOrCreateUncategorized` from category.service.
6. **Update auth middleware configuration in `src/server/index.ts`** per Research pitfall 2:
Change the `/api/*` middleware from:
```typescript
if (c.req.method === "GET") return next();
```
to apply `requireAuth` to ALL methods on data routes (remove the GET bypass). This ensures userId is always available on context for read operations. Keep the `/api/auth` bypass and add a bypass for `/api/health`.
The new middleware block should be:
```typescript
app.use("/api/*", async (c, next) => {
if (c.req.path.startsWith("/api/auth")) return next();
if (c.req.path === "/api/health") return next();
return requireAuth(c, next);
});
```
grep -c "c.set(\"userId\"" src/server/middleware/auth.ts && grep "Promise<{ userId: number } | null>" src/server/services/auth.service.ts | wc -l && grep "Promise<{ userId: number } | null>" src/server/services/oauth.service.ts | wc -l && grep -c "getOrCreateUser" src/server/services/auth.service.ts && ! grep "GET.*return next" src/server/index.ts
- `src/server/middleware/auth.ts` calls `c.set("userId", ...)` in all three auth paths (API key, Bearer, OIDC)
- `verifyApiKey` in auth.service.ts has return type `Promise<{ userId: number } | null>`
- `verifyAccessToken` in oauth.service.ts has return type `Promise<{ userId: number } | null>`
- `getOrCreateUser` function exists in auth.service.ts with `onConflictDoUpdate` pattern
- `getOrCreateUncategorized` function exists in category.service.ts
- `src/server/index.ts` does NOT contain `if (c.req.method === "GET") return next()`
- `src/server/index.ts` still bypasses auth for `/api/auth` and `/api/health` paths
Auth middleware resolves userId for all auth methods, verifyApiKey and verifyAccessToken return userId, GET routes require auth, getOrCreateUser and getOrCreateUncategorized helpers exist
Task 3: Update test helper to seed user and return { db, userId }
tests/helpers/db.ts
tests/helpers/db.ts, src/db/schema.ts
Update `createTestDb()` in `tests/helpers/db.ts` to:
1. After running migrations, insert a test user: `await db.insert(schema.users).values({ logtoSub: "test-user-sub" }).returning()`
2. Insert the per-user Uncategorized category with the test user's ID: `await db.insert(schema.categories).values({ name: "Uncategorized", icon: "package", userId: user.id })`
3. Change the return type from just `db` to `{ db, userId: user.id }` so all tests can destructure it.
4. Also add a helper function `createSecondTestUser(db)` that creates a second user for cross-user isolation tests:
```typescript
export async function createSecondTestUser(db: Db) {
const [user] = await db
.insert(schema.users)
.values({ logtoSub: "test-user-2-sub" })
.returning();
await db
.insert(schema.categories)
.values({ name: "Uncategorized", icon: "package", userId: user.id });
return user.id;
}
```
The updated `createTestDb` should look like:
```typescript
export async function createTestDb() {
const db = drizzle({ schema });
await migrate(db, { migrationsFolder: "./drizzle-pg" });
const [user] = await db
.insert(schema.users)
.values({ logtoSub: "test-user-sub" })
.returning();
await db
.insert(schema.categories)
.values({ name: "Uncategorized", icon: "package", userId: user.id });
return { db, userId: user.id };
}
```
IMPORTANT: This changes the return type of createTestDb from `db` to `{ db, userId }`. All existing test files that call `createTestDb()` will need updating in Plan 04 to destructure the result.
grep -c "logtoSub" tests/helpers/db.ts && grep -c "userId: user.id" tests/helpers/db.ts && grep "return { db, userId" tests/helpers/db.ts | wc -l && grep -c "createSecondTestUser" tests/helpers/db.ts
- `createTestDb()` inserts a user with `logtoSub: "test-user-sub"`
- `createTestDb()` returns `{ db, userId: user.id }` (not just `db`)
- Uncategorized category is created with the test user's ID
- `createSecondTestUser` function exists and is exported
- Import of `schema.users` is present
Test helper seeds a user, returns { db, userId }, has a createSecondTestUser helper for isolation tests
After all tasks complete:
1. `grep "pgTable" src/db/schema.ts` shows pg-core usage throughout
2. `grep "export const users" src/db/schema.ts` confirms users table
3. `grep "userId" src/db/schema.ts` shows userId on items, categories, threads, setups, settings, apiKeys, oauthTokens
4. `grep "c.set(\"userId\"" src/server/middleware/auth.ts` shows userId set in middleware
5. `grep "getOrCreateUser" src/server/services/auth.service.ts` confirms user upsert helper
6. `grep "return { db, userId" tests/helpers/db.ts` confirms new test helper return type
7. No `sqliteTable` imports remain in schema.ts
- Schema uses pg-core imports exclusively (no sqlite-core)
- users table with id, logtoSub (unique), createdAt defined
- userId FK column present on items, categories, threads, setups, settings, apiKeys, oauthTokens
- categories: composite unique on (userId, name)
- settings: composite PK on (userId, key)
- requireAuth resolves userId for API key, Bearer token, and OIDC session
- verifyApiKey and verifyAccessToken return { userId } | null
- Test helper returns { db, userId } with seeded user
- All API routes require auth (no GET bypass)
- Drizzle migration generated in drizzle-pg/