use authorization on mutations. Decode SQLite types to Convex mutation payloads. Update Schema with PowerSync CLI.

Author: stevensJourney

demos/react-convex-todolist/README.md

@@ -56,3 +56,7 @@ Convex Auth handles user authentication (email/password). The Convex Auth sessio
 ## Mutations
 
 Client writes go into the PowerSync upload queue, which calls `uploadData()` in the connector. This calls Convex mutations directly via the `ConvexReactClient` (e.g. `lists:create`, `todos:update`, `todos:remove`).
+
+## ID Mapping
+
+Convex requires server-side generated row IDs, while PowerSync needs stable local IDs for queued writes before the backend mutation has completed. This demo uses PowerSync's [sequential ID mapping](https://docs.powersync.com/client-sdks/advanced/sequential-id-mapping#sequential-id-mapping) pattern: client-side rows use a local `uuid`, and Convex mutations resolve that `uuid` to the corresponding Convex `_id` on the server.

demos/react-convex-todolist/convex/_generated/api.d.ts

@@ -9,8 +9,10 @@
  */
 
 import type * as auth from "../auth.js";
+import type * as authorization from "../authorization.js";
 import type * as http from "../http.js";
 import type * as lists from "../lists.js";
+import type * as mutationErrors from "../mutationErrors.js";
 import type * as powersync_checkpoints from "../powersync_checkpoints.js";
 import type * as todos from "../todos.js";
 
@@ -22,8 +24,10 @@ import type {
 
 declare const fullApi: ApiFromModules<{
   auth: typeof auth;
+  authorization: typeof authorization;
   http: typeof http;
   lists: typeof lists;
+  mutationErrors: typeof mutationErrors;
   powersync_checkpoints: typeof powersync_checkpoints;
   todos: typeof todos;
 }>;

demos/react-convex-todolist/convex/auth.config.ts

@@ -0,0 +1,12 @@
+import type { AuthConfig } from 'convex/server';
+
+const convexSiteUrl: string = process.env.CONVEX_SITE_URL ?? 'http://localhost:3211';
+
+export default {
+  providers: [
+    {
+      domain: convexSiteUrl,
+      applicationID: 'convex'
+    }
+  ]
+} satisfies AuthConfig;

demos/react-convex-todolist/convex/authorization.ts

@@ -0,0 +1,31 @@
+import { getAuthUserId } from '@convex-dev/auth/server';
+import { ConvexError } from 'convex/values';
+import type { Doc } from './_generated/dataModel';
+import type { MutationCtx } from './_generated/server';
+import { MUTATION_ERROR_CODES, type MutationErrorCode } from './mutationErrors';
+
+export function mutationError(code: MutationErrorCode, message: string) {
+  return new ConvexError({
+    code,
+    message
+  });
+}
+
+export async function requireOwnerId(ctx: Pick<MutationCtx, 'auth'>) {
+  const userId = await getAuthUserId(ctx);
+  if (userId === null) {
+    throw mutationError(MUTATION_ERROR_CODES.NOT_AUTHENTICATED, 'Not authenticated');
+  }
+
+  return userId;
+}
+
+export function assertOwnerIdMatches(actualOwnerId: string, expectedOwnerId: string) {
+  if (actualOwnerId !== expectedOwnerId) {
+    throw mutationError(MUTATION_ERROR_CODES.NOT_AUTHORIZED, 'Not authorized');
+  }
+}
+
+export function assertListOwner(list: Doc<'lists'>, ownerId: string) {
+  assertOwnerIdMatches(list.owner_id, ownerId);
+}

demos/react-convex-todolist/convex/lists.ts

@@ -1,5 +1,7 @@
 import { v } from 'convex/values';
 import { DatabaseReader, mutation } from './_generated/server';
+import { assertListOwner, assertOwnerIdMatches, mutationError, requireOwnerId } from './authorization';
+import { MUTATION_ERROR_CODES } from './mutationErrors';
 import schema from './schema';
 
 /**
@@ -22,6 +24,8 @@ export const findListByUuid = async (params: { db: DatabaseReader; uuid: string
 export const create = mutation({
   args: schema.tables.lists.validator,
   handler: async (ctx, args) => {
+    const ownerId = await requireOwnerId(ctx);
+    assertOwnerIdMatches(args.owner_id, ownerId);
     await ctx.db.insert('lists', args);
   }
 });
@@ -32,10 +36,16 @@ export const create = mutation({
 export const update = mutation({
   // The uuid is required, every other field is an optional patch
   args: v.object({ uuid: v.string() }).extend(schema.tables.lists.validator.partial().fields),
-  handler: async ({ db }, { uuid, ...fields }) => {
+  handler: async (ctx, { uuid, ...fields }) => {
+    const { db } = ctx;
+    const ownerId = await requireOwnerId(ctx);
     const matching = await findListByUuid({ db, uuid });
     if (!matching) {
-      return;
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for uuid=${uuid}`);
+    }
+    assertListOwner(matching, ownerId);
+    if (fields.owner_id !== undefined) {
+      assertOwnerIdMatches(fields.owner_id, ownerId);
     }
     await db.patch(matching._id, fields);
   }
@@ -48,11 +58,14 @@ export const remove = mutation({
   args: {
     uuid: v.string()
   },
-  handler: async ({ db }, { uuid }) => {
+  handler: async (ctx, { uuid }) => {
+    const { db } = ctx;
+    const ownerId = await requireOwnerId(ctx);
     const matching = await findListByUuid({ db, uuid });
     if (!matching) {
-      return;
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for uuid=${uuid}`);
     }
+    assertListOwner(matching, ownerId);
     await db.delete(matching._id);
   }
 });

demos/react-convex-todolist/convex/mutationErrors.ts

@@ -0,0 +1,18 @@
+export const MUTATION_ERROR_CODES = {
+  // We should never reach this on the client side.
+  NOT_AUTHENTICATED: 'NOT_AUTHENTICATED',
+  NOT_AUTHORIZED: 'NOT_AUTHORIZED',
+  NOT_FOUND: 'NOT_FOUND'
+} as const;
+
+export type MutationErrorCode = (typeof MUTATION_ERROR_CODES)[keyof typeof MUTATION_ERROR_CODES];
+
+export type ConvexMutationErrorData = {
+  code?: MutationErrorCode;
+  message?: string;
+};
+
+export const UPLOAD_REJECTION_MUTATION_ERROR_CODES = new Set<string>([
+  MUTATION_ERROR_CODES.NOT_AUTHORIZED,
+  MUTATION_ERROR_CODES.NOT_FOUND
+]);

demos/react-convex-todolist/convex/schema.ts

@@ -29,7 +29,7 @@ export default defineSchema({
      */
     uuid: v.string(),
     created_at: v.string(),
-    completed_at: v.optional(v.union(v.null(), v.string())),
+    completed_at: v.optional(v.string()),
     description: v.string(),
     completed: v.optional(v.number()),
     list_id: v.id('lists'),

demos/react-convex-todolist/convex/todos.ts

@@ -1,6 +1,8 @@
 import { v } from 'convex/values';
 import { DatabaseReader, mutation } from './_generated/server';
+import { assertListOwner, mutationError, requireOwnerId } from './authorization';
 import { findListByUuid } from './lists';
+import { MUTATION_ERROR_CODES } from './mutationErrors';
 import schema from './schema';
 
 /**
@@ -26,12 +28,14 @@ export const create = mutation({
   args: schema.tables.todos.validator.omit('list_id'),
   handler: async (ctx, args) => {
     const { db } = ctx;
+    const ownerId = await requireOwnerId(ctx);
     const { list_uuid } = args;
     //need to set the corresponding list_id for the provided list_uuid
     const matchingList = await findListByUuid({ db, uuid: list_uuid });
     if (!matchingList) {
-      throw new Error(`No matching list found for uuid=${list_uuid}`);
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for uuid=${list_uuid}`);
     }
+    assertListOwner(matchingList, ownerId);
     return await db.insert('todos', {
       ...args,
       list_id: matchingList._id
@@ -45,11 +49,28 @@ export const create = mutation({
 export const update = mutation({
   // The uuid is required, every other field is an optional patch
   args: v.object({ uuid: v.string() }).extend(schema.tables.todos.validator.partial().fields),
-  handler: async ({ db }, { uuid, ...fields }) => {
+  handler: async (ctx, { uuid, ...fields }) => {
+    const { db } = ctx;
+    const ownerId = await requireOwnerId(ctx);
     let matching = await findTodoByUuid({ db, uuid });
     if (!matching) {
-      return;
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching todo found for uuid=${uuid}`);
+    }
+    const currentList = await db.get(matching.list_id);
+    if (!currentList) {
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for todo uuid=${uuid}`);
+    }
+    assertListOwner(currentList, ownerId);
+
+    if (fields.list_uuid !== undefined) {
+      const nextList = await findListByUuid({ db, uuid: fields.list_uuid });
+      if (!nextList) {
+        throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for uuid=${fields.list_uuid}`);
+      }
+      assertListOwner(nextList, ownerId);
+      fields.list_id = nextList._id;
     }
+
     await db.patch(matching._id, fields);
   }
 });
@@ -61,11 +82,18 @@ export const remove = mutation({
   args: {
     uuid: v.string()
   },
-  handler: async ({ db }, { uuid }) => {
+  handler: async (ctx, { uuid }) => {
+    const { db } = ctx;
+    const ownerId = await requireOwnerId(ctx);
     let matching = await findTodoByUuid({ db, uuid });
     if (!matching) {
-      return;
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching todo found for uuid=${uuid}`);
+    }
+    const list = await db.get(matching.list_id);
+    if (!list) {
+      throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for todo uuid=${uuid}`);
     }
+    assertListOwner(list, ownerId);
     await db.delete(matching._id);
   }
 });
@@ -75,8 +103,14 @@ export const createBatch = mutation({
     todos: v.array(schema.tables.todos.validator)
   },
   handler: async (ctx, args) => {
+    const ownerId = await requireOwnerId(ctx);
     const ids = [];
     for (const todo of args.todos) {
+      const list = await ctx.db.get(todo.list_id);
+      if (!list) {
+        throw mutationError(MUTATION_ERROR_CODES.NOT_FOUND, `No matching list found for id=${todo.list_id}`);
+      }
+      assertListOwner(list, ownerId);
       const id = await ctx.db.insert('todos', todo);
       ids.push(id);
     }

demos/react-convex-todolist/package.json

@@ -8,7 +8,8 @@
     "dev:convex": "convex dev",
     "build": "tsc -b && vite build",
     "preview": "vite preview",
-    "start": "pnpm build && pnpm preview"
+    "start": "pnpm build && pnpm preview",
+    "update:schema": "powersync generate schema --output-path=./src/library/powersync/AppSchema.ts --output=ts"
   },
   "dependencies": {
     "@convex-dev/auth": "^0.0.91",

demos/react-convex-todolist/powersync/sync-config.yaml

@@ -19,7 +19,7 @@ streams:
         FROM lists
         WHERE uuid in user_lists
       - |
-        SELECT uuid as id, list_uuid as list_id, *
+        SELECT uuid as id, *
         FROM todos
         WHERE list_uuid IN user_lists
   archived_user_data:
@@ -35,6 +35,6 @@ streams:
         FROM lists
         WHERE uuid in archived_user_lists
       - |
-        SELECT uuid as id, list_uuid as list_id, *
+        SELECT uuid as id, *
         FROM todos
         WHERE list_uuid IN archived_user_lists