feat: add hasPolicyGranting check

Author: onebytegone

src/SubjectAuthorizer.ts

@@ -7,9 +7,11 @@ import {
    PolicyEffect,
    PolicyWithID,
    ISubjectAuthorizerOpts,
+   HasPolicyGrantingOpts,
 } from './fsaba-types';
 import isAllowed from './utils/is-allowed';
 import makeSubjectSpecificPolicies from './utils/make-subject-specific-policies';
+import hasPolicyGranting from './utils/has-policy-granting';
 
 export class SubjectAuthorizer implements ISubjectAuthorizer {
 
@@ -43,4 +45,8 @@ export class SubjectAuthorizer implements ISubjectAuthorizer {
       return isAllowed(this._policies, action, resource, opts);
    }
 
+   public hasPolicyGranting(action: string, opts?: Partial<HasPolicyGrantingOpts>): boolean {
+      return hasPolicyGranting(this._policies, action, opts);
+   }
+
 }

src/fsaba-types.ts

@@ -274,6 +274,18 @@ export interface IsAllowedOpts {
    ignoreConditions: boolean;
 }
 
+export interface HasPolicyGrantingOpts {
+
+   /**
+    * An optional resource prefix pattern (e.g. 'budgets:kazoo/*'). If provided, the
+    * authorizer checks if any policy grants the action on a resource that matches this
+    * prefix.
+    *
+    * Note: This must end with a wildcard (`*`) and cannot contain wildcards elsewhere.
+    */
+   resourcePrefixPattern?: string;
+}
+
 /**
  * A subject authorizer is used to determine what actions each subject can perform.
  */
@@ -288,6 +300,19 @@ export interface ISubjectAuthorizer {
     */
    isAllowed(action: string, resource: string, opts?: Partial<IsAllowedOpts>): boolean;
 
+   /**
+    * Perform an early check to see if the user has a policy allowing them to perform the
+    * provided action at all, with an optional resource prefix. This is useful for APIs to
+    * perform an early check before doing expensive processing to load any data needed to
+    * determine if the user has access to perform the action.
+    *
+    * This does not replace the need to call `isAllowed` to determine if the user has
+    * access to perform the action. This is a tool that can be used to reduce the
+    * information disclosed (e.g. via timing-based probing) to users who don't have access
+    * to perform an action at all.
+    */
+   hasPolicyGranting(action: string, opts?: HasPolicyGrantingOpts): boolean;
+
 }
 
 /**

src/index.ts

@@ -1,2 +1,3 @@
 export * from './fsaba-types';
 export * from './AuthorizerFactory';
+export * from './SubjectAuthorizer';

src/utils/has-policy-granting.ts

@@ -0,0 +1,35 @@
+import { HasPolicyGrantingOpts, PolicyWithID } from '../fsaba-types';
+import stringMatchesPattern from './string-matches-pattern';
+
+/**
+ * Perform an early check to see if the user has a policy to perform an action at all,
+ * with an optional resource prefix.
+ */
+export default function hasPolicyGranting(policies: { allow: readonly PolicyWithID[] }, action: string, opts?: HasPolicyGrantingOpts): boolean {
+   return policies.allow.some((policy) => {
+      const actionMatches = policy.actions.some((policyAction) => {
+         return stringMatchesPattern(policyAction, action);
+      });
+
+      if (!actionMatches) {
+         return false;
+      }
+
+      const resourcePrefixPattern = opts?.resourcePrefixPattern;
+
+      if (!resourcePrefixPattern) {
+         return true;
+      }
+
+      if (!resourcePrefixPattern.endsWith('*') || resourcePrefixPattern.indexOf('*') !== resourcePrefixPattern.length - 1) {
+         throw new Error('resourcePrefixPattern must end with a wildcard and cannot contain wildcards elsewhere');
+      }
+
+      const prefix = resourcePrefixPattern.slice(0, -1);
+
+      return policy.resources.some((policyResource) => {
+         return stringMatchesPattern(policyResource, resourcePrefixPattern)
+            || policyResource.startsWith(prefix);
+      });
+   });
+}

tests/SubjectAuthorizer.test.ts

@@ -1,6 +1,14 @@
 import { expect } from 'chai';
-import { AuthorizerFactory, Claims } from '../src';
-import { ADMINISTER_OWN_AUTH, ADMINISTER_OTHER_AUTH, DO_NEARLY_EVERYTHING } from './sample-data';
+import { AuthorizerFactory, Claims, SubjectAuthorizer } from '../src';
+import {
+   ADMINISTER_OWN_AUTH,
+   ADMINISTER_OTHER_AUTH,
+   DO_NEARLY_EVERYTHING,
+   ALL_ROLES,
+   BUDGET_VIEWER_KAZOO_PM,
+   BUDGET_VIEWER_SINGLE,
+   BUDGET_VIEWER_MFG_HEAD,
+} from './sample-data';
 
 
 describe('SubjectAuthorizer', () => {
@@ -39,4 +47,65 @@ describe('SubjectAuthorizer', () => {
       expect(factory2.makeAuthorizerForSubject(user, { throwOnUnknownRole: true })).to.be.ok; // eslint-disable-line no-unused-expressions
    });
 
+   describe('hasPolicyGranting', () => {
+
+      it('returns true if the user has a policy for the action', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_SINGLE);
+
+         expect(authorizer.hasPolicyGranting('budget:View')).to.strictlyEqual(true);
+      });
+
+      it('returns false if the user does not have a policy for the action', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_SINGLE);
+
+         expect(authorizer.hasPolicyGranting('budget:Create')).to.strictlyEqual(false);
+      });
+
+      it('returns true if the user has a policy matching resource prefix', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_KAZOO_PM);
+
+         expect(authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:kazoo/*' })).to.strictlyEqual(true);
+      });
+
+      it('returns true if the policy resource is broader than the requested prefix', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_MFG_HEAD);
+
+         // BUDGET_VIEWER_MFG_HEAD has budget:*
+         expect(authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:kazoo/mktg/*' })).to.strictlyEqual(true);
+      });
+
+      it('returns false if the user has the action but on different resources', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_KAZOO_PM);
+
+         // KAZOO PM has budget:View on budget:* but we can test with a non-matching
+         // prefix.
+         expect(authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget-v2/*' })).to.strictlyEqual(false);
+      });
+
+      it('throws an error if resourcePrefixPattern does not end with a wildcard or contains internal wildcards', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_KAZOO_PM);
+
+         expect(() => { authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:kazoo' }); }).to.throw();
+
+         expect(() => { authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:*/foo' }); }).to.throw();
+
+         expect(() => { authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: '*budget:foo' }); }).to.throw();
+      });
+
+      it('correctly handles prefix match', () => {
+         const authorizer = new SubjectAuthorizer(ALL_ROLES, BUDGET_VIEWER_KAZOO_PM);
+
+         // BUDGET_VIEWER_KAZOO_PM has policy for budget:kazoo/*. The requested prefix is
+         // budget:kazoo/mktg/*. This should be true because the policy resource
+         // (budget:kazoo/*) matches the requested prefix (budget:kazoo/mktg/*).
+         expect(authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:kazoo/mktg/*' })).to.strictlyEqual(true);
+
+         // Now, if the requested prefix is budget:kaz*, it should still be true because
+         // the requested resource prefix (budget:kaz*) matches the policy resource
+         // (budget:kazoo/*).
+         expect(authorizer.hasPolicyGranting('budget:View', { resourcePrefixPattern: 'budget:kaz*' })).to.strictlyEqual(true);
+      });
+
+   });
+
 });