With <QuickConvex/> you can implement authorization a number of ways. In this post we’ll look at implementing a row-level security abstraction by adding a layer of indirection which will validate the authorization of the user to read, write, or modify each document they interact with.

# Authorization: limiting access control

One of the goals in making a secure app is restricting which users can do what. Logged-out sessions should not be allowed to view private data, and logged-in users shouldn’t be able to delete other users’ data. I’ve worked on locking down access to Dropbox files, Spark deployments, and [private messages](https://stack.convex.dev/end-to-end-encryption-with-convex). So I got to thinking about how developers using Convex can manage permissions in their apps.

## Authorization via code

Convex allows developers to write arbitrary Javascript, which runs on the server within a transaction, that can check authorization. If you want to enforce an authorization rule, you can define it in code and check it whenever you want. Maybe before a user can “Like” a post, you require that the authenticated user is connected to the post’s author through the graph of friendships.

```tsx
export default likePost = mutation(async ({db, auth}, {postId}) => {
	const post = await db.get(postId);
	if (!await connectedInGraph(db, await auth.getUserIdentity(), post.author)) {
		throw new Error("you can't like that");
	}
	await db.patch(postId, {likes: post.likes + 1});
});
```

Although Convex allows flexible rules, it could become unruly if you need to do the same authorization check in different places. “Liking” a post should run the same authorization code as “Sharing” or “Reposting,” because the check isn’t a property of the mutation as much as it’s a property of the post. Even if everything is configured perfectly, it could all fall apart if a new engineer joins the team, makes a new mutation, and forgets the authorization check. Suddenly you have an [IDOR vulnerability](https://www.varonis.com/blog/what-is-idor-insecure-direct-object-reference). 

## Authorization via row-level security

We want some way of saying “if you’re accessing data in the ‘posts’ table, you need to run the access check.” Finding the right layer to put this access check can be tricky — I spent a year at Dropbox moving access checks for files into a central service. One layer that works well is row-level-security (RLS) where authorization is defined on individual rows, and the checks automatically run whenever code tries to read or write the row. How would you build that in Convex?

Let’s design a simple app where users create messages. Only the message’s author can edit a message or publish it. Logged-in users can view all messages, but logged-out sessions can only view published messages. We can codify these rules in code.

```tsx
// in convex/rls.js
export const {withQueryRLS, withMutationRLS} =
	RowLevelSecurity<{ auth: Auth }, DataModel>(
  {
    messages: {
		  read: async ({ auth }, message) => {
	      const identity = await auth.getUserIdentity();
	      if (identity === null) {
	        return message.published;
	      }
	      return true;
	    },
			write: async ({ auth }, message) => {
	      const identity = await auth.getUserIdentity();
	      if (identity === null) {
	        return false;
	      }
	      return message.author === identity.tokenIdentifier;
	    },
	  },
  }
);
```

Here we use some [middleware](https://stack.convex.dev/sessions-wrappers-as-middleware), defined in [`rowLevelSecurity.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/rowLevelSecurity.ts) in the [convex-helpers](https://github.com/get-convex/convex-helpers/) repo.

```jsx
// in convex/messages.js
import { withQueryRLS, withMutationRLS } from "./rls";

export const list = query(withQueryRLS(async ({ db }) => {
  return await db.query("messages").collect();
}));
export const publish = mutation(withMutationRLS(async ({ db }, { messageId }) => {
  await db.patch(messageId, {published: true});
}));
```

The middleware functions wrap queries and mutations, taking the `db` argument and wrapping it. The wrapper intercepts each row that would be returned from `db.get` or `db.query` and filters out rows based on your `read` rules. It intercepts each row that would be modified by `db.patch`, `db.replace`, or `db.delete` and confirms that the write is allowed by `modify` rules, and `db.insert` with the `insert` rules.

Now we have defined the authorization checks in a single place. The access rules can depend on the authorized user through `auth` and they can do database reads through `db`. Convex runs functions close to the database and caches query results, making it efficient to run the same authorization check on each document. However, you can also compose this pattern with other wrappers to provide user-level, team-level, or otherwise checks.

# Extending access functions

## Composing RLS with data-fetching functions

The rules you define for reading and writing documents are given the context that is provided to the function, including the `db`, `auth`, and other objects. If you want to optimize and avoid fetching the same thing multiple times, you can compose `RowLevelSecurity` with [middleware functions like `withUser`](https://stack.convex.dev/wrappers-as-middleware-authentication), which look up the user and pass it in the context  object to the function. 

```jsx
export const list = query(withUser(withQueryRLS(async ({ db, user }) => {
  return await db.query("messages").collect();
})));
```

In this case, it will also be passed to the authorization rules, making it easy to write rules involving `user` properties:

```jsx
// in convex/rls.js
export const {withQueryRLS, withMutationRLS} =
	RowLevelSecurity<{ auth: Auth }, DataModel>(
  {
    messages: {
		  read: async ({ user }, message) => {
        // Only show published posts to logged-in, active users.
	      if (user?.status === "active") {
	        return true;
	      }
	      return message.published;
	    },
...
```

You could extend this pattern to also look up the user’s team, role, and more.

## Filtering out fields

This middleware pattern can be extended to filtering out individual document fields, or blocking writes to certain fields. You could have the authorization function return the modified object, for instance. By building this abstraction in a library, you’re free to replace and extend the interface to meet your needs.

## Mixing RLS with bespoke authorization rules

One somewhat-obvious thing to point out is that, while you can use this abstraction to add RLS to your app, you can also decide where to not use it, or when to do other, more complex authorization with regular functions. Convex queries and mutations run on the server, so you can safely write access checks in code, whereas with some other platforms you’re limited to a special authorization markup and your code only runs on the client.

# Summary

In this post we looked at adding row-level security to endpoints by wrapping the database interface with per-document checks. As long as your documents express a logical concept that can have access control rules, you can implement security in your Convex app today, by copying [`rowLevelSecurity.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/rowLevelSecurity.ts) into your project.

This is one of many ways to authorize access for your Convex app. Please let us know what your favorite way of managing authorization is in [our Discord](https://convex.dev/community). Thanks for reading.

Implementing row-level security on Convex as a library. Wrap access to the database with access checks written in plain old JS / TS.

Row Level Security: Wrappers as "Middleware"

What's the maximum level of privacy an application can offer? Platforms like Convex encrypt data at rest but allow you to interact with it in unencrypted form via user-defined functions running on the server. This is tremendously useful but occasionally there's data that you don't want to exist in unencrypted form *anywhere*.

Consider a scenario where I need to send a crypto passphrase to my partner. That passphrase should be encrypted on a computer that I control, decrypted on a computer my partner controls, and not be accessible anywhere else. This is called end-to-end encryption, because only the endpoints of the communication — my partner and I — can see the secret passphrase.

I wanted to see what it would take to build end-to-end encryption on top of Convex, so I built Whisper.

### How to use Whisper

Check out [https://whisper-convex.vercel.app/](https://whisper-convex.vercel.app/), the final product.


![Screenshot of the app in use](https://cdn.sanity.io/images/ts10onj4/production/611e92f2d3c2d82aa2219e49372ba4eb3477fcc8-2258x960.gif)

1. Type in a secret message
2. The message is encrypted with an optional client-side password and stored in Convex.
3. Send the private URL to the recipient(s), through an external secure channel.
4. A recipient retrieves the encrypted message from Convex, and decrypts the message in their browser.

**Features:**

1. No login or setup, for either the sender or recipient.
2. In case the URL is intercepted, the sender can see the IP address of everyone who uses the URL to read the secret message, in a list that reactively updates.
3. The message expires after a certain number of accesses, or a configurable duration.
4. When the message expires, a [scheduled mutation](https://docs.convex.dev/using/scheduling) deletes it from Convex so no one can access it, even with the URL.

### How Whisper works

The full source code is at [https://github.com/ldanilek/whisper](https://github.com/ldanilek/whisper/blob/main/README.md), and I’ll highlight some of the key components here.

To create a Whisper — an encrypted secret message — we use AES symmetric encryption before calling the `createWhisper` mutation in Convex. This code runs in the browser, so the raw URL and secret are never sent to Convex.

```ts
if (password.length === 0) {
  password = uuid.v4();
}
const encryptedSecret = CryptoJS.AES.encrypt(secret, password).toString();
const passwordHash = hashPassword(password);
await createWhisperMutation(
	name, encryptedSecret, passwordHash, creatorKey, expiration,
);
```

Accessing the Whisper requires password hash to match, and it’s a mutation so the access can be recorded. This code runs in a transaction on Convex servers.

```ts
// accessWhisper.ts
export default mutation({
  args: {
      whisperName: v.string();
      passwordHash: v.string();
      accessKey: v.string();
      ip: v.union(v.string(), v.null());
  },
  handler: async (
    { db },
    {
      whisperName,
      passwordHash,
      accessKey,
      ip,
    }
  ) => {
    const whisperDoc = await getValidWhisper(db, whisperName, true);
    if (!timingSafeEqual(whisperDoc.passwordHash, passwordHash)) {
      throw Error("incorrect password");
    }
    await db.insert("accesses", {
      name: whisperName,
      accessKey,
      ip,
    });
  },
});
```

Once the access is registered, we use a Convex query to read the encrypted message, and AES to decrypt it.

```tsx
const SecretDisplay = ({name, accessKey, password}) => {
  const encryptedSecret = useQuery(api.readSecret.default, name, accessKey);
  return <div>{
    encryptedSecret ?
		CryptoJS.AES.decrypt(encryptedSecret, password).toString(CryptoJS.enc.Utf8) 
		: "Loading..."
  }</div>;
}
```

To delete expired secrets, we schedule a mutation to delete the encrypted message.

```tsx
// inside createWhisper.ts
await scheduler.runAt(expireTime, internal.deleteExpired.default, whisperName, creatorKey);
// inside expireNow.ts
await db.patch(whisperDoc!._id, {
  encryptedSecret: "",
});
```

Implementing end-to-end encryption on top of Convex to build a secret-sharing app.

Lee Danilek

All posts by Lee