security(core): scope auth tokens with explicit CRUD permissions and server-assigned login

[ar2rsawseen]

Summary

Replaces the token app/endpoint scoping model with explicit CRUD permissions, and makes permission to open a dashboard session an explicit, server-assigned property of the token.

Why the old model could not express what it looked like it expressed. A token's app/endpoint fields are a data-scoping control: authorizer.verify_token matches endpoint against the request path and app against the request's app_id, and only when one is present. They say nothing about what the resolved member may do, and rights.js did not carry them past token resolution, so once a token resolved to its owner it authorized whatever that owner could. Login capability had the same shape: it was inferred from purpose, a string the caller supplies at creation.

The model

Two new fields on auth_tokens, both optional, so existing tokens are untouched.

token_permission - a member.permission-shaped grant ({_:{a,u}, c/r/u/d:{appId:{all, allowed}}}).

• rights.js intersects it with the owner's own permissions as soon as the member is loaded, before any validator authorizes anything. Every existing feature check therefore becomes scope-aware without being modified - one line at each of the 7 member-load sites.
• The intersected member does not carry global_admin; that is the authority a scoped token was narrowed away from.
• Recomputed per request, so it follows the owner's current permissions rather than those they held at creation.

can_login - server-assigned only.

• Set where the server establishes or propagates a session: setLoggedInVariables, the renderer (/o/render, dashboards reports), the ban-warning mail, and OIDC (enterprise-plugins, linked below).
• /i/token/create grants it only when the creating credential holds it and the child is not narrowed. It never reads purpose.
• /login/token/:token gates on it. purpose returns to being a description.

Grants are bounded by the creating credential, not the owner. Because the intersection has already happened, params.member is the creating credential's authority, so isPermissionSubset needs no second lookup. An owner with apps A and B may hold an A-scoped token, and that token cannot produce a child that reaches B. An all grant may only be passed on by a holder of all, since it covers features that do not exist yet.

Token creation, listing and deletion require a full-permission credential. /o/token/list returns whole documents and a document's _id is the token itself, so these three endpoints hand out, expose and revoke the owner's credentials respectively.

Compatibility

Tokens created before this change keep working on data endpoints: with no token_permission they are neither intersected nor re-scoped, the endpoint regex still applies to them, and /login/token still accepts the unrestricted login-purpose tokens it accepted before. No migration, no backfill.

One deliberate exception. The three token-management endpoints now require a full-permission credential, so a legacy token restricted by app or endpoint is refused at /i/token/create, /o/token/list and /i/token/delete - including on /o/token/list where its endpoint restriction would previously have matched. That is the point of the change rather than a side effect: listing returns whole token documents, and a document's _id is the token, so a scoped credential could otherwise read out credentials wider than itself. The existing test that asserted the old behaviour is updated in this PR.

The two documented flows keep working: the dashboard session token still authenticates API calls in place of the api_key, and creating a login token and redirecting through /login/token still works from a credential that may itself sign in.

Token manager

The drawer now grants app, CRUD and feature permissions instead of endpoint regexes, reusing the same permission grid helpers as user management (countlyAuth.permissionSetGenerator / combinePermissionObject) and the same feature list (GET /o/users/permissions). Existing tokens still render their legacy endpoint value read-only.

Tests

• test/unit-tests/api.utils.rights.tokenPermissions.js - the permission algebra: subset boundaries, all propagation, admin apps, the intersection, global_admin stripping, and permissions reduced after issue.
• test/unit-tests/api.utils.authorizer.tokenFields.js - the token record: field persistence, can_login strictness, and that the endpoint regex still applies to legacy tokens but not to permission-scoped ones.
• test/2.api/16.token.manager.js - 16 cases covering the create, login, list and delete boundaries.

Run against a clean instance (isolated dashboard + API on their own MongoDB), the full test/1.frontend + test/2.api chain gives 238 passing / 21 failing, with all 16 token cases and all 21 unit tests passing. The 21 failures are Testing event settings and are pre-existing: pristine origin/master fails the same 21 on the same instance. Note api/parts/data/usage.js requires offline-geocoder, which is declared but not installed by a plain npm install here, and pluginManager.connectToAllDatabases hardcodes the database names, so isolating a test instance needs a separate mongod rather than a different database name.

The regression tests earned their keep: they caught a real hole in the first version of this change. A scoped credential could still mint an unrestricted child by simply omitting the permission parameter - the subset check had no object to compare and so never ran. Fixed in the second commit; a scoped credential must now state what it grants.

Related

• countly-server release.24.05: security(core): scope auth tokens with explicit CRUD permissions and server-assigned login (24.05) #7964
• countly-platform: Countly/countly-platform#1119
• countly-enterprise-plugins (OIDC mint): Countly/countly-enterprise-plugins#3379

Supersedes the earlier containment PRs #7957 / #7958, which were closed in favour of this model.

Reported through the security bug bounty program (received 2026-08-18).

🤖 Generated with Claude Code

[ar2rsawseen]

[P1] Do not bypass endpoint scoping until every verifier applies token permissions

This disables the legacy endpoint check for any token carrying token_permission, assuming the request will be intersected in rights.js. /o/actions is a counterexample: its countly-token branch calls authorize.verify_return() directly, receives only the owner, and then invokes getHeatmap() without any rights validator. A token scoped to another feature on the same app therefore passes its derived app list and reads heatmap data it was not granted. Return/apply the token document in that branch, or centralize permission enforcement in authorization before skipping endpoint restrictions.

[ar2rsawseen]

Confirmed — /o/actions was the one route where applyTokenScope never ran. Fixed in ad5a444.

It resolves its own token: authorize.verify_return in the countly-token branch, then straight to getHeatmap. So only the token's app restriction was ever checked, and its permissions were not consulted at all — a token scoped to another feature on the same app passed, exactly as you describe.

Took your first option, since the second (centralising in authorization) would mean the authorizer deciding feature-level rights, which is what rights.js is for:

return_data: true,
callback: function(tokenData, expires_after) {
    …
    params.token_data = tokenData;
    common.db.collection('members').findOne({_id: common.db.ObjectID(tokenData.owner + "")}, function(memberErr, member) {
        var scoped = (memberErr || !member) ? null : applyTokenScope(params, member);
        if (!viewsUtils.ownerCanRead(scoped, app._id + "", FEATURE_NAME)) {
            common.returnMessage(params, 401, 'User does not have view right for this application');
            return false;
        }
        …

applyTokenScope is exported for it, so this route bounds the member the same way and in the same order rights.js does — before anything is authorized.

Two details in the read check, so it does not over-correct:

• Legacy user_of membership is honoured. hasReadRight alone does not cover it, but validateRead does, so refusing it here would take away access the same member's api_key still has.
• A locked account is refused, as validateRead refuses it. This branch checked neither before.

Endpoint scoping stays disabled for permission-carrying tokens, which I read as the intent of the change rather than the problem — the problem was that nothing applied the permissions in its place on this route. Now something does.

Unit cases cover applyTokenScope directly: unchanged for a token with no permissions, narrowed for one with them (events on the app is refused though the owner has it), never widened, and a global admin still bounded by their own token's scope.

[ar2rsawseen]

[P1] Block scoped tokens from account-level 2FA management too

This protects token deletion as credential management, but the same scoped token can call /i/two-factor-auth?method=disable, enable, or generate-qr-code: those routes use only validateUser, which applies the app permission intersection but does not reject the request, and disable needs no current TOTP code. A token narrowed to one app/feature can therefore weaken or replace its owner's second factor. Apply isScopedCredential to these account-level authentication routes (and audit other validateUser-only credential mutations), not just the token manager.

[ar2rsawseen]

Confirmed on all three methods — fixed in ad5a444.

disable is the sharp one: it takes no current TOTP code, so a token narrowed to one feature on one app could simply switch off the factor protecting everything its owner can reach. enable replaces the secret and generate-qr-code hands out a fresh one to enable with, so all three are credential management in the sense the token manager already uses.

All three now refuse a scoped credential through one helper:

function refuseScopedCredential(params, what) {
    if (isScopedCredential(params)) {
        common.returnMessage(params, 403, "A restricted token cannot " + what);
        return true;
    }
    return false;
}

You are right about the mechanism as well as the routes: validateUser bounds what a scoped token may touch per app, and an account-level route has no app to bound — so bounding is not the same as refusing, and only refusing helps here.

On the audit you asked for, the other validateUser-only routes in requestProcessor.js:

route	verdict
/i/token/create	already ceilinged — params.member is the creating credential's authority, so a scoped token cannot mint a wider child
/o/token/check	reports on a token supplied as a parameter; the caller must already hold it
/o/countly_version, getCurrentUserApps	read-only, no credential state
/i/users/update, admin_check, admin_disable	global admin, not validateUser

So the 2FA trio was the whole set. The 24.05 branch has no generate-qr-code method, so it gets the two it has.

Integration tests cover all three refusing a scoped token, and an unrestricted api_key still getting through — a guard that also blocks the legitimate path would be its own bug.

---

Separately, while adding those: on the platform PR both unit suites this branch adds sit in test/unit-tests/, which the platform's runner does not glob —

"test:unit": "… mocha … 'test/unit/*.unit.js' 'plugins/*/tests/**/*.unit.js' …"

— so neither api.utils.rights.tokenPermissions.js nor api.utils.authorizer.tokenFields.js has ever run in platform CI. Moved to test/unit/ with the .unit.js suffix; 25 passing once they actually run. (The server repo globs test/unit-tests/, so they were fine there.)