Mongoose adapter for Cerbos Query Plans v2.0

Cerbos Query Plans solve a common challenge in decoupled authorization: how to efficiently determine which records a user is allowed to access without fetching everything from the database and checking permissions one by one. Instead of forcing your application to load and filter entire collections, a query plan gives you a structured set of conditions derived from your policies. You pass that plan into your data access layer, the adapter turns it into native filters, and MongoDB returns only the permitted documents.

With the original Mongoose adapter, we introduced a straightforward method for translating those conditions into MongoDB queries. Version 2.0 takes this further, covering a wider range of policy patterns, adding deeper schema awareness, and enhancing the overall developer experience.

What’s new in v2.0 Mongoose adapter

All policy logic enforced inside MongoDB

The adapter now maps the full set of Cerbos logical and comparison operators into native MongoDB filters. Everything stays inside the database engine. This includes string helpers, membership checks, scoped fields, and the collection-aware lambda operators.

Expressions that previously returned “unsupported”, such as hasIntersection involving projected fields or the all lambda over nested arrays, now translate cleanly to $elemMatch. This makes complex resource attributes and deeply nested schemas fully compatible with Cerbos Query Plans without any additional glue code.

A refreshed mapper contract

Mapping Cerbos fields to MongoDB paths is now clearer and more explicit. The adapter distinguishes between scalar fields, one-to-one relations, and arrays, and understands scoped fields such as tags.name or owner.id without guesswork.

You can also provide either a mapping object or a mapper function, useful when your models follow consistent naming conventions. The result is more reliable translations and fewer surprises when writing policies that reflect your data model.

Using the v2.0 Mongoose adapter

import { GRPC as Cerbos } from "@cerbos/grpc";
import mongoose from "mongoose";

import { queryPlanToMongoose, PlanKind } from "@cerbos/orm-mongoose";

// connect to mongo
await mongoose.connect("mongodb://127.0.0.1:27017/test");
// connect to Cerbos PDP
const cerbos = new Cerbos("localhost:3592", { tls: false });

// Mongoose models (schema excluded for brevity)
const MyModel = mongoose.model("MyModel", ....);

// Fetch the query plan from Cerbos passing in the principal
// resource type and action
const queryPlan = await cerbos.planResources({
  principal: {....},
  resource: { kind: "resourceKind" },
  action: "view"
});

// Generate the mongoose filter from the query plan
const result = queryPlanToMongoose({
  queryPlan,
  fieldNameMapper: {
    "request.resource.attr.owner.id": "ownerId",
    "request.resource.attr.tags.name": "tags.name"
  }
});

// The query plan says the user would always be denied
// return empty or throw an error depending on your app.
if(result.kind == PlanKind.ALWAYS_DENIED) {
  return console.log([]);
}

// Pass the filters in as where conditions
const rows = await MyModel.find({
  ...result.filters
});

console.log(rows);

Try it out

The updated adapter is available now on npm and in the query-plan-adapter repository, which also includes the Prisma and SQLAlchemy adapters.

Version 2.0 makes it easier to express richer authorization logic in your policies and have those constraints enforced efficiently inside MongoDB. If you rely on Mongoose and Cerbos Query Plans, this is a significant upgrade.

If you’re looking to enforce fine-grained, contextual, and continuous authorization across apps, APIs, AI agents, MCPs, services and workloads - give Cerbos a try. Curious how Cerbos could fit into your architecture or have specific requirements to discuss? Feel free to book a call with a Cerbos engineer for a free 1:1 session.