scim2-ast-mongo

A MongoDB adapter for scim2-ast. Converts SCIM 2.0 filter strings or ASTs into MongoDB query objects.

This package depends on scim2-ast for parsing SCIM filter strings.

Installation

pnpm add scim2-ast-mongo
# or
npm install scim2-ast-mongo
# or
yarn add scim2-ast-mongo

Usage

import { toMongo } from 'scim2-ast-mongo';

// Convert SCIM filter string to MongoDB query
const filter = 'userName eq "bjensen" and title pr';
const query = toMongo(filter);

// query is:
// {
//   $and: [
//     { userName: { $eq: "bjensen" } },
//     { title: { $exists: true } }
//   ]
// }

// Use with MongoDB driver
await collection.find(query).toArray();

// Use with Mongoose
await User.find(query).exec();

Pre-parsed AST

You can also pass a pre-parsed AST (from scim2-ast) instead of a string.

import { parse } from 'scim2-ast';
import { toMongo } from 'scim2-ast-mongo';

const ast = parse('userName eq "bjensen"');
const query = toMongo(ast);

Options

mapPath

You can transform SCIM attribute paths to MongoDB paths using the mapPath option. This is useful if your database schema uses different field names than the SCIM interface.

const query = toMongo('userName eq "bjensen"', {
  mapPath: (path) => {
    if (path === 'userName') return 'username'; // Map to lowercase
    return path;
  }
});
// Result: { username: { $eq: "bjensen" } }

Supported Operators

| SCIM Operator | MongoDB Operator | Notes | |---|---|---| | eq | $eq | Equal | | ne | $ne | Not equal | | co | $regex | Contains (escaped) | | sw | $regex | Starts with (^...) | | ew | $regex | Ends with (...$) | | gt | $gt | Greater than | | lt | $lt | Less than | | ge | $gte | Greater than or equal | | le | $lte | Less than or equal | | pr | $exists: true | Present (attribute exists) | | in | $in | In array | | nin | $nin | Not in array | | any | $in | Alias for in | | all | $all | Contains all elements | | regexp | $regex | Regular expression match | | and | $and | Logical AND | | or | $or | Logical OR | | not | $not, $ne, $nor | Negation (optimized) | | [] | $elemMatch | Value path filter for arrays |

Logic Handling

• and / or: Mapped to $and and $or.
• not:
  • not (A or B) -> $nor: [A, B] (De Morgan's laws applied where possible).
  • not (A and B) -> $or: [not A, not B].
  • not (a eq b) -> a: { $ne: b }.
  • not (a pr) -> a: { $exists: false }.
  • Nested not operations are simplified.

Build

This package uses tsup for building.

pnpm build

Test

This package uses vitest for testing.

pnpm test

Security

Regular Expression Denial of Service (ReDoS)

The regexp operator passes the user supplied regular expression pattern directly to MongoDB's $regex operator.

Risk: If an attacker submits a "catastrophic" regular expression (e.g. (a+)+$), it can cause the database engine to consume 100% CPU while trying to match it against documents, potentially causing a Denial of Service.

Mitigation: If exposing this API to untrusted users, consider:

• Disabling or restricting the regexp operator if not strictly needed.
• Using a library like safe-regex to validate patterns before execution.
• Ensuring your MongoDB instance has query execution time limits enabled.

Contributing

This package is part of the scim2-ast monorepo. Please follow the contribution guidelines in the scim2-ast package.