Expose MongoDB collections via read-only OAuth2Server getter for granular access

[alloalexandre]

Is your feature request related to a problem? Please describe.

Currently, the OAuth2Server package encapsulates its MongoDB collections (AccessTokens, RefreshTokens, AuthCodes, Clients) within the OAuthMeteorModel, making it impossible for developers to perform custom queries or create indexes directly on these collections. This is frustrating when implementing features like admin dashboards (e.g., listing expired tokens) or custom cleanup logic (e.g., removing stale authorization codes), as developers must rely solely on the model's predefined methods, which may not cover all use cases.

Describe the solution you'd like

Add a read-only getter (collections) to the OAuth2Server class that exposes the underlying Mongo.Collection instances (AccessTokens, RefreshTokens, AuthCodes, Clients). The getter should return a frozen object (using Object.freeze) to prevent mutations, ensuring OAuth2 compliance by forcing write operations through the model's methods. This allows developers to perform custom queries or indexing while maintaining encapsulation.

Example Usage:

import { OAuth2Server } from 'meteor/leaonline:oauth2-server';

const server = new OAuth2Server({ /* config */ });
const expiredTokens = server.collections.AccessTokens.find({
  accessTokenExpiresAt: { $lt: new Date() }
}).fetch();
console.log(expiredTokens); // Array of expired access tokens
// Mutation attempt fails:
server.collections.AccessTokens = {}; // TypeError: Cannot assign to read only property

Describe alternatives you've considered

1. Using Mongo.getCollection from the MongoDB driver: This would expose raw MongoDB collections, bypassing Meteor's Mongo.Collection abstraction. It risks breaking Meteor's reactivity, security rules, and OAuth2 compliance, and is less user-friendly for Meteor developers.
2. Adding specific query methods to OAuthMeteorModel: Instead of exposing collections, we could add methods like findAccessTokens or createIndex. However, this would require anticipating all possible use cases, leading to a bloated API and maintenance overhead.
3. No exposure, rely on existing methods: Continuing to restrict access to collections forces developers to work around limitations using less efficient or hacky solutions (e.g., duplicating data in custom collections), which is suboptimal.

The proposed getter approach is the most flexible, secure, and Meteor-aligned solution, as it leverages existing Mongo.Collection instances without exposing low-level driver APIs.

Additional context

• Security: The getter uses Object.freeze to ensure read-only access, preventing accidental mutations that could violate OAuth2 standards (e.g., RFC 6749). Write operations must still use OAuthMeteorModel methods like saveToken or revokeAuthorizationCode.
• Meteor Compatibility: Exposing Mongo.Collection instances aligns with Meteor's conventions, supporting reactivity and publication/subscription patterns.
• No Breaking Changes: This is an additive feature, preserving the existing API.
• Reference Integration: Compatible with accounts-lea (per CONTRIBUTING.md), as it doesn't alter the OAuth2 flow or model behavior.
• Implementation Details: Requires exporting collections from lib/model/meteor-model.js, assigning it in OAuthMeteorModel, and adding the getter in lib/oauth.js. Tests and JSDoc will be included, and API.md will be updated via meteor npm run build:docs.

[jankapunkt]

Hi @alloalexandre

I'd like to inform you about a recently added API Method in Meteor available via https://docs.meteor.com/api/collections.html#Mongo-getCollection (note: this is not returning a Raw collection but the Meteor Mongo.Collection instance).

You can use it like so:

import { Mongo } from 'meteor/mongo'

const AccessTokenCollection = Mongo.getCollection('oauth_access_tokens')

This allows the same functionality as dburles:mongo-collection-instances (part of Meteor Community Packages) which you can alternatively use in older Meteor versions:

import { Mongo } from 'meteor/mongo'

const AccessTokenCollection = Mongo.Collection.get('oauth_access_tokens')

The default collection names are defined here https://github.com/leaonline/oauth2-server/blob/master/lib/model/DefaultModelConfig.js

They can also be overridden in the options when creating a new OAuth2Server.

Please let me know if this satisfies your requirements.

[alloalexandre]

Hey @jankapunkt !

Thanks for sharing this! Yes, I’m aware of the new Mongo.getCollection method. At the moment, this is the workaround we’re using as well.

That said, I think it’s cleaner to access the collections directly from the class, since that way we preserve "type safety" from the object itself rather than relying on the collection name string. This helps us avoid potential mismatches and keeps the codebase more robust.

[jankapunkt]

I see your point and this scenario (users want collection access but don't want to use dburles:mongo-collection-instances) was initially designed as a dependency injection. I have to admit, though that passing collections was not explicitly documented until I just checked the readme. 🙈

The readme shows only how to pass custom collection names but the default implementation also allows to pass your own collections:

export const OAuthCollections = {
  accessTokensCollection: new Mongo.Collection('oauth_accessTokens'),
  refreshTokensCollection: new Mongo.Collection('oauth_refreshTokens'),
  authCodesCollection: new Mongo.Collection('oauth_authCodes'),
  clientsCollection: new Mongo.Collection('oauth_clients')
}

import { OAuthCollections } from '/path/to/OAuthCollections.js'
import { OAuth2Server } from 'meteor/leaonline:oauth2-server'

const server = new OAuth2Server({
  model: {
    ...OAuthCollections
  }
})

https://github.com/leaonline/oauth2-server/blob/3276db3913a46440c080de12d1132646709b9d3a/lib/model/model.js#L20C7-L28

Also not really documented is the ability to create entirely own model instances, as long as they comply with the interface:

https://github.com/alloalexandre/oauth2-server/blob/3276db3913a46440c080de12d1132646709b9d3a/lib/oauth.js#L82-L90

Please let me know if this satisfies your requirements. If you still think the above features do not satisfy your usecase then please make sure your implementation considers the model interface and allows for custom models without breaking current behavior (we don't know who out there currently uses custom models).

[alloalexandre]

I appreciate the suggestions about passing custom collections or using Mongo.getCollection / dburles:mongo-collection-instances.

However, my goal is not to inject collections or rely on external packages. I would like to access the existing collections already used internally by OAuth2Server directly, through a read-only getter on the class itself.

This approach would allow safe queries, indexing, and other read operations while preserving type safety, Meteor reactivity, and OAuth2 compliance, without the risk of mismatches or additional dependencies.

At the same time, I think it’s great that the current design still allows providing a custom model if needed, which keeps the API flexible while maintaining its integrity.