@gradientedge/cdk-utils-azure 2.47.0 → 2.49.0

package/dist/src/construct/event-handler/main.d.ts

@@ -3,8 +3,36 @@ import { Output } from '@pulumi/pulumi';
 import { AzureFunctionApp } from '../function-app/index.js';
 import { AzureEventHandlerProps, EventHandlerEventGridSubscription, EventHandlerServiceBus } from './types.js';
 /**
- * Provides a construct to create and deploy an Azure EventGrid Event Handler with Service Bus integration
+ * Provides a construct to create and deploy an Azure EventGrid Event Handler with Service Bus integration.
+ *
+ * ## Service Bus configuration
+ *
+ * The construct manages a Service Bus namespace and queue. Each can independently be created by the
+ * construct or resolved from existing Azure resources via the `namespace.useExisting` and
+ * `queue.useExisting` flags on {@link EventHandlerServiceBusProps}:
+ *
+ * | `namespace.useExisting` | `queue.useExisting` | Behaviour |
+ * |---|---|---|
+ * | `false` | `false` | Create both — the default. Used by single-purpose stacks that own the whole Service Bus surface. |
+ * | `true`  | `false` | Look up the namespace, create a new queue under it. Use this when one namespace is provisioned by a shared infrastructure stack and multiple event-handler stacks each provision their own queue under it. |
+ * | `true`  | `true`  | Look up both. Cross-stack pattern where the producer/owner of the queue is a different stack (e.g. `WebhookEventHandler` consuming a queue created by `WebhookGateway`). |
+ * | `false` | `true`  | **Invalid** — construct-time error. You cannot resolve an existing queue under a namespace the construct is creating. |
+ *
+ * The top-level `serviceBus.useExisting` flag is retained as a deprecated alias that sets both
+ * per-resource flags to the same value, so existing callers continue to work unchanged.
+ *
+ * ## Authorization and the `EVENT_INGEST_SERVICE_BUS` connection string
+ *
+ * When the construct owns the queue (`queue.useExisting=false`), it provisions a per-queue
+ * authorization rule named `listen-send` (scoped to the queue) with `Listen + Send` rights, and the function app's
+ * `EVENT_INGEST_SERVICE_BUS` connection string is sourced from that rule. This avoids granting the
+ * function app access to sibling queues when the namespace is shared.
+ *
+ * When the queue is external (`queue.useExisting=true`) the construct does not own auth rules on it
+ * and falls back to reading the namespace-level `RootManageSharedAccessKey` for the connection string.
+ *
  * @example
+ * // Minimal subclass (defaults — both namespace and queue created by the construct):
  * import { AzureEventHandler, AzureEventHandlerProps } from '@gradientedge/cdk-utils'
  *
  * class CustomConstruct extends AzureEventHandler {
@@ -15,6 +43,30 @@ import { AzureEventHandlerProps, EventHandlerEventGridSubscription, EventHandler
  *     this.initResources()
  *   }
  * }
+ *
+ * @example
+ * // Shared-namespace pattern — reuse a namespace provisioned by another stack, create a new
+ * // queue under it. Useful when multiple event handlers should share a single Service Bus namespace.
+ * import * as pulumi from '@pulumi/pulumi'
+ *
+ * const sharedInfraStack = new pulumi.StackReference('shared-infra')
+ * const sharedNamespace = sharedInfraStack.getOutput('serviceBusNamespace')
+ *
+ * new CustomConstruct('my-event-handler', {
+ *   ...baseProps,
+ *   serviceBus: {
+ *     namespace: {
+ *       useExisting: true,
+ *       namespaceName: sharedNamespace.apply((ns) => ns.name),
+ *       resourceGroupName: sharedNamespace.apply((ns) => ns.resourceGroupName),
+ *     },
+ *     queue: {
+ *       useExisting: false,
+ *       queueName: 'my-event-queue',
+ *     },
+ *   },
+ * })
+ *
  * @category Construct
  */
 export declare class AzureEventHandler extends AzureFunctionApp {
@@ -44,6 +96,18 @@ export declare class AzureEventHandler extends AzureFunctionApp {
      * @summary Method to create the dead-letter queue storage container for EventGrid subscriptions
      */
     protected createEventGridSubscriptionDlqStorageContainer(): void;
+    /**
+     * @summary Resolve effective `useExisting` flags for the Service Bus namespace and queue.
+     *
+     * Per-resource flags (`namespace.useExisting`, `queue.useExisting`) take precedence over the
+     * deprecated top-level `serviceBus.useExisting`, which is treated as an alias that sets both.
+     * Throws if the invalid combination (namespace.useExisting=false + queue.useExisting=true) is
+     * requested — a queue cannot be looked up under a namespace the construct is about to create.
+     */
+    protected resolveServiceBusUseExisting(): {
+        namespace: boolean;
+        queue: boolean;
+    };
     /**
      * @summary Method to create the Service Bus namespace
      */
@@ -52,16 +116,37 @@ export declare class AzureEventHandler extends AzureFunctionApp {
      * @summary Method to create the Service Bus queue
      */
     protected createServiceBusQueue(): void;
+    /**
+     * @summary Provision a per-queue Listen+Send authorization rule.
+     *
+     * Skipped when the construct does not own the queue (`queue.useExisting=true`) — in that case
+     * the producer/owner of the queue is responsible for its auth rules and the function app's
+     * connection string falls back to the namespace-level root rule in {@link createFunctionAppSiteConfig}.
+     *
+     * Replaces the previous reliance on `RootManageSharedAccessKey`, which grants Listen+Send+Manage
+     * on every queue in the namespace. The new rule narrows the scope to this one queue while keeping
+     * Listen+Send so existing function code can both consume and publish through it (Manage is
+     * intentionally dropped — a runtime app should not create or delete queues).
+     */
+    protected createServiceBusQueueAuthorizationRule(): void;
     /**
      * @summary Method to create or resolve an existing EventGrid topic
      */
     protected createEventGrid(): void;
     /**
-     * @summary Method to create the EventGrid event subscription with Service Bus queue destination
+     * @summary Method to create the EventGrid event subscription with Service Bus queue destination.
+     *
+     * Skipped when the construct is reusing an existing queue (the producer/owner of that queue owns
+     * the subscription). When the construct creates a new queue — including the case where the queue
+     * is new but the parent namespace is externally-managed — the subscription is wired here.
      */
     protected createEventGridEventSubscription(): void;
     /**
-     * @summary Method to create diagnostic log settings for the Service Bus namespace
+     * @summary Method to create diagnostic log settings for the Service Bus namespace.
+     *
+     * Diagnostic settings live on the namespace, so the construct only registers them when it owns
+     * the namespace. When the namespace is external (e.g. provisioned by a shared infrastructure
+     * stack), its owner is responsible for diagnostic settings — registering again here would conflict.
      */
     protected createServiceBusDiagnosticLog(): void;
     /**
@@ -72,6 +157,17 @@ export declare class AzureEventHandler extends AzureFunctionApp {
      * @summary Override to extend the function app site config with service bus connection strings
      */
     protected createFunctionAppSiteConfig(): void;
+    /**
+     * @summary Resolve the connection string injected as `EVENT_INGEST_SERVICE_BUS` on the function app.
+     *
+     * - When the construct provisioned the queue itself, read from the per-queue Listen-scoped
+     *   authorization rule created in {@link createServiceBusQueueAuthorizationRule}. Scope is
+     *   limited to this one queue, which is correct for a shared (per-domain) namespace.
+     * - When the queue is external (legacy `WebhookEventHandler` cross-stack pattern), fall back to
+     *   the namespace-level `RootManageSharedAccessKey` — preserves pre-existing behaviour for that
+     *   caller shape since the construct does not own the queue and cannot provision a rule on it.
+     */
+    protected resolveServiceBusConnectionString(): Output<string>;
     /**
      * @summary Override to extend the dashboard variables with service bus and event grid specifics
      */

package/dist/src/construct/event-handler/main.js

@@ -1,10 +1,39 @@
 import { Provider } from '@pulumi/azure-native';
 import { getTopicOutput } from '@pulumi/azure-native/eventgrid/index.js';
-import { getNamespaceOutput, getQueueOutput, listNamespaceKeysOutput } from '@pulumi/azure-native/servicebus/index.js';
+import { getNamespaceOutput, getQueueOutput, listNamespaceKeysOutput, listQueueKeysOutput, } from '@pulumi/azure-native/servicebus/index.js';
+import { AccessRights } from '@pulumi/azure-native/types/enums/servicebus/index.js';
 import { AzureFunctionApp } from '../function-app/index.js';
 /**
- * Provides a construct to create and deploy an Azure EventGrid Event Handler with Service Bus integration
+ * Provides a construct to create and deploy an Azure EventGrid Event Handler with Service Bus integration.
+ *
+ * ## Service Bus configuration
+ *
+ * The construct manages a Service Bus namespace and queue. Each can independently be created by the
+ * construct or resolved from existing Azure resources via the `namespace.useExisting` and
+ * `queue.useExisting` flags on {@link EventHandlerServiceBusProps}:
+ *
+ * | `namespace.useExisting` | `queue.useExisting` | Behaviour |
+ * |---|---|---|
+ * | `false` | `false` | Create both — the default. Used by single-purpose stacks that own the whole Service Bus surface. |
+ * | `true`  | `false` | Look up the namespace, create a new queue under it. Use this when one namespace is provisioned by a shared infrastructure stack and multiple event-handler stacks each provision their own queue under it. |
+ * | `true`  | `true`  | Look up both. Cross-stack pattern where the producer/owner of the queue is a different stack (e.g. `WebhookEventHandler` consuming a queue created by `WebhookGateway`). |
+ * | `false` | `true`  | **Invalid** — construct-time error. You cannot resolve an existing queue under a namespace the construct is creating. |
+ *
+ * The top-level `serviceBus.useExisting` flag is retained as a deprecated alias that sets both
+ * per-resource flags to the same value, so existing callers continue to work unchanged.
+ *
+ * ## Authorization and the `EVENT_INGEST_SERVICE_BUS` connection string
+ *
+ * When the construct owns the queue (`queue.useExisting=false`), it provisions a per-queue
+ * authorization rule named `listen-send` (scoped to the queue) with `Listen + Send` rights, and the function app's
+ * `EVENT_INGEST_SERVICE_BUS` connection string is sourced from that rule. This avoids granting the
+ * function app access to sibling queues when the namespace is shared.
+ *
+ * When the queue is external (`queue.useExisting=true`) the construct does not own auth rules on it
+ * and falls back to reading the namespace-level `RootManageSharedAccessKey` for the connection string.
+ *
  * @example
+ * // Minimal subclass (defaults — both namespace and queue created by the construct):
  * import { AzureEventHandler, AzureEventHandlerProps } from '@gradientedge/cdk-utils'
  *
  * class CustomConstruct extends AzureEventHandler {
@@ -15,6 +44,30 @@ import { AzureFunctionApp } from '../function-app/index.js';
  *     this.initResources()
  *   }
  * }
+ *
+ * @example
+ * // Shared-namespace pattern — reuse a namespace provisioned by another stack, create a new
+ * // queue under it. Useful when multiple event handlers should share a single Service Bus namespace.
+ * import * as pulumi from '@pulumi/pulumi'
+ *
+ * const sharedInfraStack = new pulumi.StackReference('shared-infra')
+ * const sharedNamespace = sharedInfraStack.getOutput('serviceBusNamespace')
+ *
+ * new CustomConstruct('my-event-handler', {
+ *   ...baseProps,
+ *   serviceBus: {
+ *     namespace: {
+ *       useExisting: true,
+ *       namespaceName: sharedNamespace.apply((ns) => ns.name),
+ *       resourceGroupName: sharedNamespace.apply((ns) => ns.resourceGroupName),
+ *     },
+ *     queue: {
+ *       useExisting: false,
+ *       queueName: 'my-event-queue',
+ *     },
+ *   },
+ * })
+ *
  * @category Construct
  */
 export class AzureEventHandler extends AzureFunctionApp {
@@ -49,6 +102,7 @@ export class AzureEventHandler extends AzureFunctionApp {
         this.createEventGridSubscriptionDlqStorageContainer();
         this.createServiceBusNamespace();
         this.createServiceBusQueue();
+        this.createServiceBusQueueAuthorizationRule();
         this.createEventGrid();
         this.createEventGridEventSubscription();
         this.createServiceBusDiagnosticLog();
@@ -80,11 +134,35 @@ export class AzureEventHandler extends AzureFunctionApp {
             resourceGroupName: this.resourceGroup.name,
         });
     }
+    /**
+     * @summary Resolve effective `useExisting` flags for the Service Bus namespace and queue.
+     *
+     * Per-resource flags (`namespace.useExisting`, `queue.useExisting`) take precedence over the
+     * deprecated top-level `serviceBus.useExisting`, which is treated as an alias that sets both.
+     * Throws if the invalid combination (namespace.useExisting=false + queue.useExisting=true) is
+     * requested — a queue cannot be looked up under a namespace the construct is about to create.
+     */
+    resolveServiceBusUseExisting() {
+        // TODO: remove `deprecatedServiceBusUseExisting` and the `?? deprecatedServiceBusUseExisting`
+        //       fallbacks once all callers have migrated to the per-resource flags
+        //       (see EventHandlerServiceBusProps.useExisting in types.ts).
+        const deprecatedServiceBusUseExisting = this.props.serviceBus?.useExisting;
+        const namespaceUseExisting = this.props.serviceBus?.namespace?.useExisting;
+        const queueUseExisting = this.props.serviceBus?.queue?.useExisting;
+        const namespace = namespaceUseExisting ?? deprecatedServiceBusUseExisting ?? false;
+        const queue = queueUseExisting ?? deprecatedServiceBusUseExisting ?? false;
+        if (!namespace && queue) {
+            throw new Error(`[${this.id}] invalid serviceBus configuration: queue.useExisting=true requires namespace.useExisting=true ` +
+                `(cannot resolve an existing queue under a namespace the construct is creating).`);
+        }
+        return { namespace, queue };
+    }
     /**
      * @summary Method to create the Service Bus namespace
      */
     createServiceBusNamespace() {
-        if (this.props.serviceBus?.useExisting && this.props.serviceBus?.namespace?.namespaceName) {
+        const useExistingFlags = this.resolveServiceBusUseExisting();
+        if (useExistingFlags.namespace && this.props.serviceBus?.namespace?.namespaceName) {
             this.serviceBus.namespace = getNamespaceOutput({
                 namespaceName: this.props.serviceBus.namespace.namespaceName,
                 resourceGroupName: this.props.serviceBus.namespace.resourceGroupName,
@@ -105,7 +183,8 @@ export class AzureEventHandler extends AzureFunctionApp {
      * @summary Method to create the Service Bus queue
      */
     createServiceBusQueue() {
-        if (this.props.serviceBus?.useExisting &&
+        const useExistingFlags = this.resolveServiceBusUseExisting();
+        if (useExistingFlags.queue &&
             this.props.serviceBus?.namespace?.namespaceName &&
             this.props.serviceBus?.queue?.queueName) {
             this.serviceBus.queue = getQueueOutput({
@@ -115,11 +194,17 @@ export class AzureEventHandler extends AzureFunctionApp {
             });
         }
         else {
+            // Azure requires the queue's resource group to match its parent namespace's resource group.
+            // When the namespace is external, use the namespace's resource group from props;
+            // otherwise the construct is creating the namespace alongside the queue in the consumer stack's own resource group.
+            const namespaceResourceGroupName = useExistingFlags.namespace
+                ? (this.props.serviceBus?.namespace?.resourceGroupName ?? this.resourceGroup.name)
+                : this.resourceGroup.name;
             this.serviceBus.queue = this.serviceBusManager.createServiceBusQueue(this.id, this, {
                 ...this.props.serviceBus?.queue,
                 queueName: this.props.serviceBus?.queue?.queueName ?? this.id,
                 namespaceName: this.serviceBus.namespace.name,
-                resourceGroupName: this.resourceGroup.name,
+                resourceGroupName: namespaceResourceGroupName,
             });
         }
         this.registerOutputs({
@@ -127,6 +212,39 @@ export class AzureEventHandler extends AzureFunctionApp {
             serviceBusQueueName: this.serviceBus.queue.name,
         });
     }
+    /**
+     * @summary Provision a per-queue Listen+Send authorization rule.
+     *
+     * Skipped when the construct does not own the queue (`queue.useExisting=true`) — in that case
+     * the producer/owner of the queue is responsible for its auth rules and the function app's
+     * connection string falls back to the namespace-level root rule in {@link createFunctionAppSiteConfig}.
+     *
+     * Replaces the previous reliance on `RootManageSharedAccessKey`, which grants Listen+Send+Manage
+     * on every queue in the namespace. The new rule narrows the scope to this one queue while keeping
+     * Listen+Send so existing function code can both consume and publish through it (Manage is
+     * intentionally dropped — a runtime app should not create or delete queues).
+     */
+    createServiceBusQueueAuthorizationRule() {
+        const useExistingFlags = this.resolveServiceBusUseExisting();
+        if (useExistingFlags.queue)
+            return;
+        const namespaceResourceGroupName = useExistingFlags.namespace
+            ? (this.props.serviceBus?.namespace?.resourceGroupName ?? this.resourceGroup.name)
+            : this.resourceGroup.name;
+        // Azure caps `authorizationRuleName` at 50 chars. The rule's scope is the queue itself
+        // (`…/namespaces/<ns>/queues/<queue>/authorizationRules/<rule>`), so a literal name is
+        // unambiguous and avoids hitting the cap on long stack ids.
+        this.serviceBus.queueAuthorizationRule = this.serviceBusManager.createServiceBusQueueAuthorizationRule(this.id, this, {
+            authorizationRuleName: 'listen-send',
+            namespaceName: this.serviceBus.namespace.name,
+            queueName: this.serviceBus.queue.name,
+            resourceGroupName: namespaceResourceGroupName,
+            rights: [AccessRights.Listen, AccessRights.Send],
+        });
+        this.registerOutputs({
+            serviceBusQueueAuthorizationRuleId: this.serviceBus.queueAuthorizationRule.id,
+        });
+    }
     /**
      * @summary Method to create or resolve an existing EventGrid topic
      */
@@ -157,10 +275,15 @@ export class AzureEventHandler extends AzureFunctionApp {
         }
     }
     /**
-     * @summary Method to create the EventGrid event subscription with Service Bus queue destination
+     * @summary Method to create the EventGrid event subscription with Service Bus queue destination.
+     *
+     * Skipped when the construct is reusing an existing queue (the producer/owner of that queue owns
+     * the subscription). When the construct creates a new queue — including the case where the queue
+     * is new but the parent namespace is externally-managed — the subscription is wired here.
      */
     createEventGridEventSubscription() {
-        if (this.props.serviceBus?.useExisting || !this.eventGridEventSubscription.dlqStorageAccount)
+        const useExistingFlags = this.resolveServiceBusUseExisting();
+        if (useExistingFlags.queue || !this.eventGridEventSubscription.dlqStorageAccount)
             return;
         this.eventGridEventSubscription.eventSubscription = this.eventgridManager.createEventgridSubscription(this.id, this, {
             ...this.props.eventGridEventSubscription,
@@ -178,10 +301,15 @@ export class AzureEventHandler extends AzureFunctionApp {
         });
     }
     /**
-     * @summary Method to create diagnostic log settings for the Service Bus namespace
+     * @summary Method to create diagnostic log settings for the Service Bus namespace.
+     *
+     * Diagnostic settings live on the namespace, so the construct only registers them when it owns
+     * the namespace. When the namespace is external (e.g. provisioned by a shared infrastructure
+     * stack), its owner is responsible for diagnostic settings — registering again here would conflict.
      */
     createServiceBusDiagnosticLog() {
-        if (this.props.serviceBus?.useExisting)
+        const useExistingFlags = this.resolveServiceBusUseExisting();
+        if (useExistingFlags.namespace)
             return;
         this.monitorManager.createMonitorDiagnosticSettings(this.id, this, {
             name: `${this.id}-servicebus`,
@@ -230,15 +358,40 @@ export class AzureEventHandler extends AzureFunctionApp {
         this.appConnectionStrings = [
             {
                 name: 'EVENT_INGEST_SERVICE_BUS',
-                value: listNamespaceKeysOutput({
-                    resourceGroupName: this.props.serviceBus?.namespace?.resourceGroupName ?? this.resourceGroup.name,
-                    namespaceName: this.serviceBus.namespace.name,
-                    authorizationRuleName: 'RootManageSharedAccessKey',
-                }).primaryConnectionString,
+                value: this.resolveServiceBusConnectionString(),
                 type: 'ServiceBus',
             },
         ];
     }
+    /**
+     * @summary Resolve the connection string injected as `EVENT_INGEST_SERVICE_BUS` on the function app.
+     *
+     * - When the construct provisioned the queue itself, read from the per-queue Listen-scoped
+     *   authorization rule created in {@link createServiceBusQueueAuthorizationRule}. Scope is
+     *   limited to this one queue, which is correct for a shared (per-domain) namespace.
+     * - When the queue is external (legacy `WebhookEventHandler` cross-stack pattern), fall back to
+     *   the namespace-level `RootManageSharedAccessKey` — preserves pre-existing behaviour for that
+     *   caller shape since the construct does not own the queue and cannot provision a rule on it.
+     */
+    resolveServiceBusConnectionString() {
+        if (this.serviceBus.queueAuthorizationRule) {
+            const useExistingFlags = this.resolveServiceBusUseExisting();
+            const namespaceResourceGroupName = useExistingFlags.namespace
+                ? (this.props.serviceBus?.namespace?.resourceGroupName ?? this.resourceGroup.name)
+                : this.resourceGroup.name;
+            return listQueueKeysOutput({
+                resourceGroupName: namespaceResourceGroupName,
+                namespaceName: this.serviceBus.namespace.name,
+                queueName: this.serviceBus.queue.name,
+                authorizationRuleName: this.serviceBus.queueAuthorizationRule.name,
+            }).primaryConnectionString;
+        }
+        return listNamespaceKeysOutput({
+            resourceGroupName: this.props.serviceBus?.namespace?.resourceGroupName ?? this.resourceGroup.name,
+            namespaceName: this.serviceBus.namespace.name,
+            authorizationRuleName: 'RootManageSharedAccessKey',
+        }).primaryConnectionString;
+    }
     /**
      * @summary Override to extend the dashboard variables with service bus and event grid specifics
      */

package/dist/src/construct/event-handler/types.d.ts

@@ -1,5 +1,5 @@
 import { EventSubscription } from '@pulumi/azure-native/eventgrid/index.js';
-import { GetNamespaceResult, GetQueueResult, Namespace, Queue } from '@pulumi/azure-native/servicebus/index.js';
+import { GetNamespaceResult, GetQueueResult, Namespace, Queue, QueueAuthorizationRule } from '@pulumi/azure-native/servicebus/index.js';
 import { BlobContainer, StorageAccount } from '@pulumi/azure-native/storage/index.js';
 import { Input, Output } from '@pulumi/pulumi';
 import { DefenderForStorageProps, EventgridEventSubscriptionProps, EventgridTopicProps, ServiceBusNamespaceProps, ServiceBusQueueProps, StorageAccountProps, StorageContainerProps } from '../../services/index.js';
@@ -27,15 +27,47 @@ export interface EventHandlerEventGridSubscription {
     eventSubscription?: EventSubscription;
 }
 /**
- * Properties for configuring the Service Bus integration in the event handler
+ * Properties for configuring the Service Bus namespace inside the event handler.
+ * Wraps {@link ServiceBusNamespaceProps} with a `useExisting` flag controlling
+ * whether the construct creates the namespace or resolves an existing one.
+ * @category Interface
+ */
+export interface EventHandlerServiceBusNamespaceProps extends ServiceBusNamespaceProps {
+    /** When true, resolves an existing namespace via getNamespaceOutput instead of creating one */
+    useExisting?: boolean;
+}
+/**
+ * Properties for configuring the Service Bus queue inside the event handler.
+ * Wraps {@link ServiceBusQueueProps} with a `useExisting` flag controlling
+ * whether the construct creates the queue or resolves an existing one.
+ * @category Interface
+ */
+export interface EventHandlerServiceBusQueueProps extends ServiceBusQueueProps {
+    /** When true, resolves an existing queue via getQueueOutput instead of creating one */
+    useExisting?: boolean;
+}
+/**
+ * Properties for configuring the Service Bus integration in the event handler.
+ *
+ * `namespace.useExisting` and `queue.useExisting` are independent. The supported combinations are:
+ * - `namespace.useExisting=false, queue.useExisting=false` — create both (default)
+ * - `namespace.useExisting=true,  queue.useExisting=false` — reuse an existing (e.g. shared) namespace, create a new queue under it
+ * - `namespace.useExisting=true,  queue.useExisting=true`  — reuse both (cross-stack reference to a queue someone else owns)
+ * - `namespace.useExisting=false, queue.useExisting=true`  — invalid; construct throws at construct-time
  * @category Interface
  */
 export interface EventHandlerServiceBusProps {
-    /** Service Bus namespace properties */
-    namespace?: ServiceBusNamespaceProps;
-    /** Service Bus queue properties */
-    queue?: ServiceBusQueueProps;
-    /** When true, resolves an existing Service Bus instead of creating a new one */
+    /** Service Bus namespace properties (extends {@link ServiceBusNamespaceProps} with `useExisting`) */
+    namespace?: EventHandlerServiceBusNamespaceProps;
+    /** Service Bus queue properties (extends {@link ServiceBusQueueProps} with `useExisting`) */
+    queue?: EventHandlerServiceBusQueueProps;
+    /**
+     * Convenience alias that sets both `namespace.useExisting` and `queue.useExisting` to the same value.
+     * @deprecated Prefer `namespace.useExisting` and `queue.useExisting` individually. Retained as an alias
+     * so existing callers (e.g. WebhookEventHandler) continue to compile unchanged.
+     * TODO: remove once all callers have migrated to the per-resource flags. Also remove the
+     * resolution fallback in `resolveServiceBusUseExisting()` in main.ts.
+     */
     useExisting?: boolean;
 }
 /**
@@ -47,6 +79,13 @@ export interface EventHandlerServiceBus {
     namespace: Namespace | Output<GetNamespaceResult>;
     /** The provisioned or resolved Service Bus queue */
     queue: Queue | Output<GetQueueResult>;
+    /**
+     * Per-queue authorization rule (Listen+Send) used to build the function app's
+     * `EVENT_INGEST_SERVICE_BUS` connection string. Provisioned only when the
+     * construct owns the queue (`queue.useExisting=false`); undefined when the
+     * queue is external and the connection string falls back to the namespace-level rule.
+     */
+    queueAuthorizationRule?: QueueAuthorizationRule;
 }
 /**
  * Properties for configuring the EventGrid topic in the event handler

package/dist/src/services/authorisation/constants.d.ts

@@ -17,5 +17,7 @@ export declare enum RoleDefinitionId {
     /** Read, write, and delete Azure Storage blob data */
     STORAGE_BLOB_DATA_CONTRIBUTOR = "/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe",
     /** Read, write, and delete Azure Storage table data */
-    STORAGE_TABLE_DATA_CONTRIBUTOR = "/providers/Microsoft.Authorization/roleDefinitions/0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3"
+    STORAGE_TABLE_DATA_CONTRIBUTOR = "/providers/Microsoft.Authorization/roleDefinitions/0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3",
+    /** Full data-plane + management access on Service Bus namespaces (create queues/topics, listKeys on auth rules, send/receive) */
+    AZURE_SERVICE_BUS_DATA_OWNER = "/providers/Microsoft.Authorization/roleDefinitions/090c5cfd-751d-490a-894a-3ce6f1109419"
 }

package/dist/src/services/authorisation/constants.js

@@ -19,4 +19,6 @@ export var RoleDefinitionId;
     RoleDefinitionId["STORAGE_BLOB_DATA_CONTRIBUTOR"] = "/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe";
     /** Read, write, and delete Azure Storage table data */
     RoleDefinitionId["STORAGE_TABLE_DATA_CONTRIBUTOR"] = "/providers/Microsoft.Authorization/roleDefinitions/0a9a7e1f-b9d0-4cc4-a60d-0319b160aaa3";
+    /** Full data-plane + management access on Service Bus namespaces (create queues/topics, listKeys on auth rules, send/receive) */
+    RoleDefinitionId["AZURE_SERVICE_BUS_DATA_OWNER"] = "/providers/Microsoft.Authorization/roleDefinitions/090c5cfd-751d-490a-894a-3ce6f1109419";
 })(RoleDefinitionId || (RoleDefinitionId = {}));

package/dist/src/services/servicebus/main.d.ts

@@ -1,6 +1,6 @@
 import { ResourceOptions } from '@pulumi/pulumi';
 import { CommonAzureConstruct } from '../../common/index.js';
-import { ResolveServicebusQueueProps, ServiceBusNamespaceProps, ServiceBusQueueProps, ServiceBusSubscriptionProps, ServiceBusTopicProps } from './types.js';
+import { ResolveServicebusQueueProps, ServiceBusNamespaceProps, ServiceBusQueueAuthorizationRuleProps, ServiceBusQueueProps, ServiceBusSubscriptionProps, ServiceBusTopicProps } from './types.js';
 /**
  * Provides operations on Azure Servicebus using Pulumi
  * - A new instance of this class is injected into {@link CommonAzureConstruct} constructor.
@@ -47,6 +47,15 @@ export declare class AzureServiceBusManager {
      * @see [Pulumi Azure Native Service Bus Queue]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/service bus/queue/}
      */
     createServiceBusQueue(id: string, scope: CommonAzureConstruct, props: ServiceBusQueueProps, resourceOptions?: ResourceOptions): import("@pulumi/azure-native/servicebus/queue.js").Queue;
+    /**
+     * @summary Method to create a new service bus queue authorization rule
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param props service bus queue authorization rule properties
+     * @param resourceOptions Optional settings to control resource behaviour
+     * @see [Pulumi Azure Native Service Bus Queue Authorization Rule]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/servicebus/queueauthorizationrule/}
+     */
+    createServiceBusQueueAuthorizationRule(id: string, scope: CommonAzureConstruct, props: ServiceBusQueueAuthorizationRuleProps, resourceOptions?: ResourceOptions): import("@pulumi/azure-native/servicebus/queueAuthorizationRule.js").QueueAuthorizationRule;
     /**
      * @summary Method to create a new service bus subscription
      * @param id scoped id of the resource

package/dist/src/services/servicebus/main.js

@@ -1,4 +1,4 @@
-import { getQueueOutput, ManagedServiceIdentityType, Namespace, Queue, SkuName, Subscription, Topic, } from '@pulumi/azure-native/servicebus/index.js';
+import { getQueueOutput, ManagedServiceIdentityType, Namespace, Queue, QueueAuthorizationRule, SkuName, Subscription, Topic, } from '@pulumi/azure-native/servicebus/index.js';
 /**
  * Provides operations on Azure Servicebus using Pulumi
  * - A new instance of this class is injected into {@link CommonAzureConstruct} constructor.
@@ -87,6 +87,19 @@ export class AzureServiceBusManager {
             enablePartitioning: props.enablePartitioning ?? false,
         }, { parent: scope, ...resourceOptions });
     }
+    /**
+     * @summary Method to create a new service bus queue authorization rule
+     * @param id scoped id of the resource
+     * @param scope scope in which this resource is defined
+     * @param props service bus queue authorization rule properties
+     * @param resourceOptions Optional settings to control resource behaviour
+     * @see [Pulumi Azure Native Service Bus Queue Authorization Rule]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/servicebus/queueauthorizationrule/}
+     */
+    createServiceBusQueueAuthorizationRule(id, scope, props, resourceOptions) {
+        if (!props)
+            throw new Error(`Props undefined for ${id}`);
+        return new QueueAuthorizationRule(`${id}-sqar`, { ...props }, { parent: scope, ...resourceOptions });
+    }
     /**
      * @summary Method to create a new service bus subscription
      * @param id scoped id of the resource

package/dist/src/services/servicebus/types.d.ts

@@ -1,4 +1,4 @@
-import { GetQueueOutputArgs, NamespaceArgs, QueueArgs, SubscriptionArgs, TopicArgs } from '@pulumi/azure-native/servicebus/index.js';
+import { GetQueueOutputArgs, NamespaceArgs, QueueArgs, QueueAuthorizationRuleArgs, SubscriptionArgs, TopicArgs } from '@pulumi/azure-native/servicebus/index.js';
 /**
  * Properties for creating a Service Bus namespace
  * @see [Pulumi Azure Native Service Bus Namespace]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/servicebus/namespace/}
@@ -20,6 +20,13 @@ export interface ServiceBusTopicProps extends TopicArgs {
  */
 export interface ServiceBusQueueProps extends QueueArgs {
 }
+/**
+ * Properties for creating a Service Bus queue authorization rule
+ * @see [Pulumi Azure Native Service Bus Queue Authorization Rule]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/servicebus/queueauthorizationrule/}
+ * @category Interface
+ */
+export interface ServiceBusQueueAuthorizationRuleProps extends QueueAuthorizationRuleArgs {
+}
 /**
  * Properties for creating a Service Bus subscription
  * @see [Pulumi Azure Native Service Bus Subscription]{@link https://www.pulumi.com/registry/packages/azure-native/api-docs/servicebus/subscription/}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradientedge/cdk-utils-azure",
-  "version": "2.47.0",
+  "version": "2.49.0",
   "description": "Azure Pulumi utilities for @gradientedge/cdk-utils",
   "type": "module",
   "main": "dist/src/index.js",