CEXT-6151: Add ACL admin UI schema and helper to check permissions by oshmyheliuk · Pull Request #522 · adobe/aio-commerce-sdk

oshmyheliuk · 2026-06-16T02:00:06Z

Description

https://jira.corp.adobe.com/browse/CEXT-6151

Update adminUISdk schema to support ACL fields for menu items
Add a public helper that extensions can call from the SPA and from runtime actions to check whether the current user is allowed to use a given ACL resource.

Related Issue

https://github.com/magento-commerce/adobe-commerce-backend-uix/pull/352

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have read the DEVELOPMENT document.
I have added tests to cover my changes.
All new and existing tests passed.

changeset-bot · 2026-06-16T02:00:11Z

🦋 Changeset detected

Latest commit: 9ec1234

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@adobe/aio-commerce-lib-app	Minor
@adobe/aio-commerce-lib-admin-ui	Minor
@adobe/aio-commerce-lib-core	Minor
@adobe/aio-commerce-sdk	Patch
@adobe/aio-commerce-lib-api	Patch
@adobe/aio-commerce-lib-auth	Patch
@adobe/aio-commerce-lib-config	Patch
@adobe/aio-commerce-lib-events	Patch
@adobe/aio-commerce-lib-webhooks	Patch
@aio-commerce-sdk/common-utils	Patch
@aio-commerce-sdk/scripting-utils	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

obarcelonap · 2026-06-16T13:16:04Z

+  // → "Magento_CommerceBackendUix::adminuisdk_app_acme_promotions"
+
+  // Check access in a runtime action:
+  const client = getAdminUiPermissionClient({


would it be possible to create a function in aio-commerce-lib-app that returns a permission client which auto resolves the app id from the one set in the commerce config so we don't need to pass this value on each function call.
Something like

const app = getAppPermissionClient({httpClient}); // resolves appId from app.commerce.config

resolves appId From app.commerce.config

That's something we may need to be cautious with. Runtime code (that runs in a runtime action) that depends on that file can not easily read the configuration unless it's bundled with the action, which requires extra setup in ext.config.yaml via include or via some import trick (messy bundle/build stuff).

It's the same problem we have (for now) with lib-config: we need to receive the schema in initialize. There are ways to make this work, but they are not trivial.

- add spec

jcuerdo · 2026-06-17T08:54:37Z

+ * @returns The full Commerce ACL resource id for the menu leaf node (e.g.
+ *   `"Magento_CommerceBackendUix::adminuisdk_app_approval_dashboard_app_menu_approval_dashboard"`).
+ */
+export function getMenuAclResourceId(


Should be documented in usage.md?

Added examples here e726578

iivvaannxx · 2026-06-17T13:28:39Z

This documentation should be completely agnostic of app.commerce.config, it doesn't know about it.

iivvaannxx · 2026-06-17T13:30:18Z

+
+const permissionClient = getAdminUiPermissionClient({
+  httpClient, // AdobeCommerceHttpClient — reuse the one from createAdminUiApiClient
+  appId: "acme-promotions", // metadata.id from your app config; enables no-argument calls


What's the appId used for? What happens if I am not an App Management user? If this is intended to be used with App Management shouldn't it be in lib-app?

appId is used to generate the ACL resource ID for future permission checks in the permission client.
I think it should be a part of the admin-ui library. The comment in usage.md was confusing, so I updated it.

iivvaannxx · 2026-06-17T13:31:22Z

+ * This is a cross-repo contract shared with the Commerce module. Both sides must produce
+ * the exact same output for the same input. Any change here must be coordinated with the
+ * Commerce module's ACL id generator.


This will end up in public docs. Isn't this kind of an internal comment?

Yeah, it's more like an internal comment. We need to maintain consistent logic between Commerce and aio-commerce-sdk to generate the same ACL resources.
I updated comments https://github.com/adobe/aio-commerce-sdk/pull/522/commits

iivvaannxx · 2026-06-17T13:32:51Z

+/** Options used to create an Admin UI SDK permission client. */
+export interface AdminUiPermissionClientOptions {
+  /** The application's `metadata.id` value. When provided, `check()` and `require()` can be called with no resource argument. */
+  appId?: string;


Now that I see how appId works, I would challenge the fact that it is tightly coupled to a concept outside this library (app IDs). It's a useful convenience, but I am not sure it's the right layer to implement it.

The appID is optional; the client can check permissions directly by providing the full ACL Resource ID.
But this client can check only resources created by the Admin UI commerce module. All ACL resources are created based on the installed apps, so the client is tightly coupled to the Admin UI and the installed applications' logic.

It's not like you can use this client to check any ACL Resource in Commerce; for resources not created by the Admin UI module, the API endpoint would always return false.

iivvaannxx · 2026-06-17T13:33:56Z

+   * Throws `AdminUiPermissionDeniedError` if denied.
+   * Throws `AdminUiPermissionError` on 401, network, and parse errors.
+   * When called with no argument, defaults to the ACL resource id derived from `appId`.
+   * Throws `AdminUiPermissionError` immediately when neither `resource` nor a valid `appId` is available.


These lines should use proper JSDoc so that the autogenerated documentation picks those correctly. @throws with proper @link

Updated in 5f29d20

iivvaannxx · 2026-06-17T13:34:22Z

+      });
+}
+
+/** Creates a client for checking Admin UI SDK ACL resources. */


options is not documented as @param.

Updated in 5f29d20

iivvaannxx · 2026-06-17T13:35:36Z

+    .post("adminuisdk/permission/check", {
+      json: { resource: params.resource },
+    })
+    .json<unknown>();


I believe unknown is the default so .json() should be equivalent.

Updated in e958f27

iivvaannxx · 2026-06-17T13:35:56Z

+ * @param httpClient - The {@link AdobeCommerceHttpClient} to use to make the request.
+ * @param params - The resource to check.
+ *
+ * @throws An `HTTPError` if the status code is not 2XX.


Maybe @link is better for this throws?

Added in e958f27

iivvaannxx · 2026-06-17T13:37:20Z

+
+  public constructor(
+    resource: string,
+    options?: ErrorOptions & { traceId?: string },


From where is this ErrorOptions sourced? In any case, I would create a custom Options for each error even if equivalent to the default, this way we decouple both and we avoid type contract changes in the future if we need to add some options.

I added an export for error options from the core package
9ec1234. It sounds logical to re-use them.

iivvaannxx · 2026-06-17T13:38:51Z

This wasn't merged separately? In any case Implemented should be marked.

…data id - add example to usage.md

…data id - update comment

…data id - update commentі

…data id - update docs

…data id - code review

oshmyheliuk added 2 commits June 15, 2026 15:45

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

ab9b042

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

89fedcb

github-actions Bot added with-changeset The PR contains a Changeset file. pkg: aio-commerce-lib-app Includes changes in `packages/aio-commerce-lib-app` pkg: aio-commerce-lib-admin-ui labels Jun 16, 2026

oshmyheliuk mentioned this pull request Jun 16, 2026

[ON HOLD] CEXT-6151: Add ACL admin UI schema and helper to check permissions #426

Closed

11 tasks

obarcelonap approved these changes Jun 16, 2026

View reviewed changes

CEXT-6151: [SDK] Add ACL admin UI schema and helper to check permissions

b68a249

- add spec

github-actions Bot added the spec Includes changes in `specs/features` label Jun 17, 2026

Merge branch 'main' into CEXT-6151-v2

58ac264

jcuerdo reviewed Jun 17, 2026

View reviewed changes

iivvaannxx reviewed Jun 17, 2026

View reviewed changes

oshmyheliuk added 6 commits June 17, 2026 09:07

CEXT-6379: Failed to create event subscription with hyphens from meta…

e726578

…data id - add example to usage.md

CEXT-6379: Failed to create event subscription with hyphens from meta…

5422680

…data id - update comment

CEXT-6379: Failed to create event subscription with hyphens from meta…

56484be

…data id - update commentі

CEXT-6379: Failed to create event subscription with hyphens from meta…

5f29d20

…data id - update docs

CEXT-6379: Failed to create event subscription with hyphens from meta…

e958f27

…data id - code review

CEXT-6379: Failed to create event subscription with hyphens from meta…

9ec1234

…data id - code review

github-actions Bot added the pkg: aio-commerce-lib-core Includes changes in `packages/aio-commerce-lib-core` label Jun 17, 2026

oshmyheliuk requested review from iivvaannxx and jcuerdo June 17, 2026 17:10

Conversation

oshmyheliuk commented Jun 16, 2026

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

Uh oh!

changeset-bot Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iivvaannxx Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading

iivvaannxx Jun 16, 2026 •

edited

Loading