@owlmeans/iam 0.1.5 → 0.1.7

package/build/errors.d.ts

@@ -11,4 +11,12 @@ export declare class IamResourceError extends IamError {
     static typeName: string;
     constructor(message?: string);
 }
+export declare class IamGrantError extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
+export declare class IamUnsupported extends IamError {
+    static typeName: string;
+    constructor(message?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAkC;gBAErD,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAwC;gBAE3D,OAAO,SAAU;CAI9B;AAED,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAuB,QAAQ,SAA0C;gBAE7D,OAAO,SAAU;CAI9B;AAED,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAuB,QAAQ,SAAuC;gBAE1D,OAAO,SAAU;CAI9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAA6C;gBAEhE,OAAO,SAAU;CAI9B"}

package/build/errors.js

@@ -20,7 +20,23 @@ export class IamResourceError extends IamError {
         this.type = IamResourceError.typeName;
     }
 }
+export class IamGrantError extends IamError {
+    static typeName = `IamGrant${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`grant:${message}`);
+        this.type = IamGrantError.typeName;
+    }
+}
+export class IamUnsupported extends IamError {
+    static typeName = `IamUnsupported${ResilientError.typeName}`;
+    constructor(message = 'error') {
+        super(`unsupported:${message}`);
+        this.type = IamUnsupported.typeName;
+    }
+}
 ResilientError.registerErrorClass(IamError);
 ResilientError.registerErrorClass(IamClientError);
 ResilientError.registerErrorClass(IamResourceError);
+ResilientError.registerErrorClass(IamGrantError);
+ResilientError.registerErrorClass(IamUnsupported);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEjE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAA;IAC/B,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,YAAY,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEvE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,MAAM,OAAO,gBAAiB,SAAQ,QAAQ;IACrC,MAAM,CAAU,QAAQ,GAAG,cAAc,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEzE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,YAAY,OAAO,EAAE,CAAC,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAA;IACvC,CAAC;;AAGH,MAAM,OAAO,aAAc,SAAQ,QAAQ;IAClC,MAAM,CAAU,QAAQ,GAAG,WAAW,cAAc,CAAC,QAAQ,EAAE,CAAA;IAEtE,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,SAAS,OAAO,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAA;IACpC,CAAC;;AAGH,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,cAAc,CAAC,QAAQ,EAAE,CAAA;IAE5E,YAAY,OAAO,GAAG,OAAO;QAC3B,KAAK,CAAC,eAAe,OAAO,EAAE,CAAC,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;;AAGH,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,gBAAgB,CAAC,CAAA;AACnD,cAAc,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAA;AAChD,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './types.js';
 export * from './consts.js';
 export * from './errors.js';
+export * from './utils.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/index.js

@@ -1,3 +1,4 @@
 export * from './consts.js';
 export * from './errors.js';
+export * from './utils.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA"}

package/build/types.d.ts

@@ -15,11 +15,38 @@ export interface IamCredentialsPair {
 export interface IamPermissionArgs {
     /** Action name. When absent the permission is unscoped (project-wide). */
     permission?: string;
+    /** Declares that grants of this permission may be bound to specific resource ids. */
+    resourceScoped?: boolean;
+    /** Optional human-readable title for the permission definition. */
+    title?: string;
 }
 export interface IamResourceSpec {
     name: string;
     displayName?: string;
 }
+/** A permission declared for an entity's client (project). */
+export interface IamPermissionDefinition {
+    /** Canonical name: "res--action" or bare "res" when unscoped. */
+    name: string;
+    resource: string;
+    action?: string;
+    resourceScoped?: boolean;
+    title?: string;
+}
+export interface IamGrantArgs {
+    /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
+    resources?: string[];
+}
+/** A permission granted to an end-user subject of an entity's client. */
+export interface IamGrant {
+    /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+    profileId: string;
+    clientId: string;
+    /** Canonical permission name. */
+    permission: string;
+    /** Present only for resource-scoped grants. */
+    resources?: string[];
+}
 /** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
 export interface IamService extends InitializedService {
     getEntityAdminConfig: (entityId: string) => Promise<OidcProviderConfig>;
@@ -35,5 +62,19 @@ export interface IamService extends InitializedService {
      * the entity-owner role. Used by payment provisioning for account/project/wl resources.
      */
     ensureResourceOwnership: (entityId: string, clientId: string, resource: IamResourceSpec) => Promise<void>;
+    /** Lists permission definitions registered for the entity's client. */
+    listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>;
+    /**
+     * Grants a permission to an end-user subject. With args.resources the grant is
+     * resource-scoped (bound to those resource ids); without it the grant is project-wide.
+     */
+    grantPermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<IamGrant>;
+    /**
+     * Revokes a grant. With args.resources only those resource ids are removed;
+     * without it the whole grant is removed.
+     */
+    revokePermission: (entityId: string, clientId: string, profileId: string, permission: string, args?: IamGrantArgs) => Promise<void>;
+    /** Lists grants for the entity's client, optionally for a single subject. */
+    listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6FAA6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,yGAAyG;AACzG,MAAM,WAAW,UAAW,SAAQ,kBAAkB;IAEpD,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IACvE,kBAAkB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;IAGrE,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAA;IAExE;;;OAGG;IACH,gBAAgB,EAAE,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,iBAAiB,KACrB,OAAO,CAAC,MAAM,CAAC,CAAA;IAEpB;;;OAGG;IACH,uBAAuB,EAAE,CACvB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,eAAe,KACtB,OAAO,CAAC,IAAI,CAAC,CAAA;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/build/utils.d.ts

@@ -0,0 +1,13 @@
+import type { Authorization } from '@owlmeans/auth';
+export interface HasPermissionOptions {
+    /** Restrict the check to PermissionSets of this scope (the project's clientId). */
+    scope?: string;
+    /** Resource-scoped check: the set must list this id — unless the set itself is unscoped. */
+    resourceId?: string;
+}
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export declare const hasPermission: (auth: Authorization, permission: string, opts?: HasPermissionOptions) => boolean;
+//# sourceMappingURL=utils.d.ts.map

package/build/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,EACnB,YAAY,MAAM,EAClB,OAAO,oBAAoB,KAC1B,OAIO,CAAA"}

package/build/utils.js

@@ -0,0 +1,8 @@
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export const hasPermission = (auth, permission, opts) => auth.permissions?.some(set => (opts?.scope == null || set.scope === opts.scope)
+    && set.permissions[permission] === true
+    && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))) ?? false;
+//# sourceMappingURL=utils.js.map

package/build/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAmB,EACnB,UAAkB,EAClB,IAA2B,EAClB,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CACzC,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,GAAG,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC;OAC9C,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,IAAI;OACpC,CAAC,IAAI,EAAE,UAAU,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAClG,IAAI,KAAK,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/iam",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,9 +22,10 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.5",
-    "@owlmeans/error": "^0.1.5",
-    "@owlmeans/oidc": "^0.1.5"
+    "@owlmeans/auth": "^0.1.7",
+    "@owlmeans/context": "^0.1.7",
+    "@owlmeans/error": "^0.1.7",
+    "@owlmeans/oidc": "^0.1.7"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/src/errors.ts

@@ -27,6 +27,26 @@ export class IamResourceError extends IamError {
   }
 }
 
+export class IamGrantError extends IamError {
+  public static override typeName = `IamGrant${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`grant:${message}`)
+    this.type = IamGrantError.typeName
+  }
+}
+
+export class IamUnsupported extends IamError {
+  public static override typeName = `IamUnsupported${ResilientError.typeName}`
+
+  constructor(message = 'error') {
+    super(`unsupported:${message}`)
+    this.type = IamUnsupported.typeName
+  }
+}
+
 ResilientError.registerErrorClass(IamError)
 ResilientError.registerErrorClass(IamClientError)
 ResilientError.registerErrorClass(IamResourceError)
+ResilientError.registerErrorClass(IamGrantError)
+ResilientError.registerErrorClass(IamUnsupported)

package/src/index.ts

@@ -1,3 +1,4 @@
 export type * from './types.js'
 export * from './consts.js'
 export * from './errors.js'
+export * from './utils.js'

package/src/types.ts

@@ -18,6 +18,10 @@ export interface IamCredentialsPair {
 export interface IamPermissionArgs {
   /** Action name. When absent the permission is unscoped (project-wide). */
   permission?: string
+  /** Declares that grants of this permission may be bound to specific resource ids. */
+  resourceScoped?: boolean
+  /** Optional human-readable title for the permission definition. */
+  title?: string
 }
 
 export interface IamResourceSpec {
@@ -25,6 +29,32 @@ export interface IamResourceSpec {
   displayName?: string
 }
 
+/** A permission declared for an entity's client (project). */
+export interface IamPermissionDefinition {
+  /** Canonical name: "res--action" or bare "res" when unscoped. */
+  name: string
+  resource: string
+  action?: string
+  resourceScoped?: boolean
+  title?: string
+}
+
+export interface IamGrantArgs {
+  /** Resource ids for the resource-scoped grant form; omit for an unscoped (project-wide) grant. */
+  resources?: string[]
+}
+
+/** A permission granted to an end-user subject of an entity's client. */
+export interface IamGrant {
+  /** Backend-specific subject id: integrated = IdentityProfile.profileId, keycloak = KC user id. */
+  profileId: string
+  clientId: string
+  /** Canonical permission name. */
+  permission: string
+  /** Present only for resource-scoped grants. */
+  resources?: string[]
+}
+
 /** Unified IAM provider interface — all platform/agent code calls only this, never a backend directly */
 export interface IamService extends InitializedService {
   // --- Admin config (backend → OIDC RP config, payment provisioning) ---
@@ -54,4 +84,36 @@ export interface IamService extends InitializedService {
     clientId: string,
     resource: IamResourceSpec
   ) => Promise<void>
+
+  // --- Authorization (permission definitions & grants) ---
+
+  /** Lists permission definitions registered for the entity's client. */
+  listPermissions: (entityId: string, clientId: string) => Promise<IamPermissionDefinition[]>
+
+  /**
+   * Grants a permission to an end-user subject. With args.resources the grant is
+   * resource-scoped (bound to those resource ids); without it the grant is project-wide.
+   */
+  grantPermission: (
+    entityId: string,
+    clientId: string,
+    profileId: string,
+    permission: string,
+    args?: IamGrantArgs
+  ) => Promise<IamGrant>
+
+  /**
+   * Revokes a grant. With args.resources only those resource ids are removed;
+   * without it the whole grant is removed.
+   */
+  revokePermission: (
+    entityId: string,
+    clientId: string,
+    profileId: string,
+    permission: string,
+    args?: IamGrantArgs
+  ) => Promise<void>
+
+  /** Lists grants for the entity's client, optionally for a single subject. */
+  listGrants: (entityId: string, clientId: string, profileId?: string) => Promise<IamGrant[]>
 }

package/src/utils.ts

@@ -0,0 +1,22 @@
+import type { Authorization } from '@owlmeans/auth'
+
+export interface HasPermissionOptions {
+  /** Restrict the check to PermissionSets of this scope (the project's clientId). */
+  scope?: string
+  /** Resource-scoped check: the set must list this id — unless the set itself is unscoped. */
+  resourceId?: string
+}
+
+/**
+ * True when any PermissionSet grants `permission`. An unscoped set (no resources)
+ * satisfies a resourceId check too — a project-wide grant covers every resource.
+ */
+export const hasPermission = (
+  auth: Authorization,
+  permission: string,
+  opts?: HasPermissionOptions
+): boolean => auth.permissions?.some(set =>
+  (opts?.scope == null || set.scope === opts.scope)
+  && set.permissions[permission] === true
+  && (opts?.resourceId == null || set.resources == null || set.resources.includes(opts.resourceId))
+) ?? false

package/tests/utils.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test'
+import { hasPermission } from '@owlmeans/iam'
+import type { Authorization } from '@owlmeans/auth'
+
+const auth: Authorization = {
+  scopes: [],
+  permissions: [
+    // unscoped (project-wide) grant — shared set per client
+    { scope: 'my-project', permissions: { 'article--modify': true } },
+    // resource-scoped grant — dedicated set carrying its resource ids
+    {
+      scope: 'my-project',
+      title: 'department--modify',
+      permissions: { 'department--modify': true },
+      resources: ['dep-12345678']
+    }
+  ]
+}
+
+describe('@owlmeans/iam — hasPermission', () => {
+  test('grants an unscoped permission', () => {
+    expect(hasPermission(auth, 'article--modify')).toBe(true)
+    expect(hasPermission(auth, 'article--delete')).toBe(false)
+  })
+
+  test('grants a resource-scoped permission only for listed resource ids', () => {
+    expect(hasPermission(auth, 'department--modify', { resourceId: 'dep-12345678' })).toBe(true)
+    expect(hasPermission(auth, 'department--modify', { resourceId: 'dep-87654321' })).toBe(false)
+  })
+
+  test('an unscoped set satisfies a resourceId check (project-wide grant covers every resource)', () => {
+    expect(hasPermission(auth, 'article--modify', { resourceId: 'art-12345678' })).toBe(true)
+  })
+
+  test('scope option restricts the check to one client', () => {
+    expect(hasPermission(auth, 'article--modify', { scope: 'my-project' })).toBe(true)
+    expect(hasPermission(auth, 'article--modify', { scope: 'other-project' })).toBe(false)
+  })
+})