@ionite/core 0.0.23 → 0.0.24-beta.20260907.2

package/dist/index.d.ts

@@ -37,6 +37,12 @@ interface ListResult<T> {
 interface ListFilter {
 	/** Restrict catalog entries to those whose `requestable` flag equals this value. */
 	requestable?: boolean;
+	/** Exact match on the principal's login/userName (or workload `clientId` projected as userName). */
+	userName?: string;
+	/** Exact match on the store `externalId`. */
+	externalId?: string;
+	/** Exclusive lower bound on `updatedAt` (SCIM `meta.lastModified gt`; ISO string or Date). */
+	updatedAfter?: Date | string;
 }
 /** Shared options for paginated list operations. */
 interface ListOptions {
@@ -537,7 +543,8 @@ type CatalogEntityKind = "group" | "role" | "permission";
 *   entity declared in the catalog arrays, and every role -> permission reference likewise
 *   (`resources` refs are NOT validated here — resources live in the app's `ResourceProvider`);
 * - nested group composition is acyclic;
-* - `recommendedSubjectTypes` is a subset of `assignableSubjectTypes`.
+* - every entitlement declares a required non-empty `assignableSubjectTypes` within the platform
+*   ceiling, and `recommendedSubjectTypes` is a subset of it.
 *
 * Side effects: every entity (and its arrays/metadata) is frozen.
 */
@@ -573,84 +580,19 @@ declare function deprecateRetiredCodeCatalogRows(code: CodeCatalog | undefined,
 declare function unionCatalogRead(code: CodeCatalog | undefined, store: AccessCatalogStore | undefined): AccessCatalogStore | undefined;
 import { StandardSchemaV1 as StandardSchemaV15 } from "@standard-schema/spec";
 /**
-* IAM delta egress mode (RemoteConfig/ECI intent). Selects how IAM-visible runtime changes that
-* occur inside the application are surfaced to the enterprise's IAM/governance layer:
-*
-* - `'patch'`: outbound SCIM into the IAM tool (per-resource POST/PUT/PATCH/DELETE,
-*   correlated by the App-owned id carried as SCIM `externalId`). The IAM tool's view stays fresh as users, materialized entitlement
-*   definitions, and access change in the app. See the README "IAM delta egress" section.
-*
-* Origin/trust: every push is authenticated with the app's outgoing workload client (OAuth bearer);
-* the receiver treats the authenticated workload identity as the verified origin. Audit
-* accountability lives with the IdP that authenticated the workload and the IAM tool that granted
-* it access. The SDK only surfaces the signal; it never dictates the enterprise's workflow or
-* policy (flag, auto-revoke + notify, or simply audit).
-*/
-type IamDeltaMode = "patch";
-/** SCIM resource types the delta patch adapter addresses. */
-type IamDeltaResourceType = "user" | "group";
-/** Destination-owned reference captured from a SCIM User/Group response. */
-type DestinationReference = {
-	/** Service-provider-assigned SCIM resource id. */
-	providerId: string;
-	/** IAM-owned deep link where access to an entitlement can be requested, when supplied. */
-	requestUrl?: string;
-};
-/**
-* Full IAM delta snapshot supplied by the app's maintenance/reconcile path. It mirrors the entities
-* visible through IAM aggregation: users, durable entitlement definitions, and active access roots.
+* Resolve an access subject/target/resource reference (a string id or an object carrying one) to its
+* canonical, trimmed string id. This is the single id-resolution rule shared across the authz stack
+* (AUDIT_HISTORY.md §8.4): `accessRootId`, the access stores, the access index, and SCIM diff keys all key off
+* the same normalization so distinct roots never collapse and identical references never diverge.
+* Returns `''` when no id can be resolved.
 */
-type IamDeltaReconcileInput = {
-	users?: Iterable<BaseUser> | AsyncIterable<BaseUser>;
-	groups?: Iterable<Group> | AsyncIterable<Group>;
-	roles?: Iterable<Role> | AsyncIterable<Role>;
-	permissions?: Iterable<Permission> | AsyncIterable<Permission>;
-	access?: Iterable<AccessChange> | AsyncIterable<AccessChange>;
-};
-/** Result of an app-driven full reconcile (re-push of definitions, users, and active roots). */
-type IamDeltaReconcileResult = {
-	pushed: number;
-	skipped: number;
-	errors: string[];
-};
+declare function accessRefId(value: unknown): string;
 /**
-* Projects observed runtime mutations to the configured IAM delta destination. The invariant is:
-* every runtime mutation the SDK observes that would change what IAM full sync shows must also
-* egress through this handle. That includes users, materialized entitlement definitions, and access
-* roots. Code templates are not pushed during config apply.
-*
-* Request-triggered methods resolve when projection completes (or immediately when not ready). They
-* are best-effort egress: the SCIM mutation path awaits them inside the request, but a rejection is
-* caught and reported as degraded egress — it never turns a committed store mutation into a SCIM
-* error. Reactive catalog/resource events use the same methods outside a request and warn on failure.
-*
-* Readiness follows the shared contract: `isReady()` is a synchronous check; `ready(timeout?)`
-* resolves once the emitter first becomes usable.
+* Deterministic id for a granted root. Includes the resource scope so that two grants of the same
+* subject/target with different scopes are tracked as distinct roots. Application-wide scope (the
+* default, or `applyToApplication`) collapses to the `app` scope key.
 */
-interface IamDeltaEmitter {
-	/** Upsert a full SCIM User representation at the destination. */
-	onUserUpsert(user: BaseUser): Promise<void>;
-	/** Delete a destination User identified strictly by externalId. */
-	onUserDelete(externalId: string): Promise<void>;
-	/** Upsert a full SCIM Group representation for a group, role, or permission definition. */
-	onEntitlementUpsert(entity: Entitlement, type: EntitlementType): Promise<void>;
-	/** Delete a destination entitlement Group identified by the App-owned catalog id. */
-	onEntitlementDelete(type: EntitlementType, id: string): Promise<void>;
-	/** Project a granted root; resolves on completion (or immediately when not ready), rejects on push failure. */
-	onGrant(change: AccessChange): Promise<void>;
-	/** Project a revoked root; resolves on completion (or immediately when not ready), rejects on push failure. */
-	onRevoke(change: AccessChange): Promise<void>;
-	/** Re-push the complete IAM-visible snapshot to the destination (app-driven full reconcile). */
-	reconcile(input: IamDeltaReconcileInput): Promise<IamDeltaReconcileResult>;
-	/**
-	* Read a previously captured destination reference without making a network request. Returns
-	* undefined until the resource has been resolved or pushed to the configured IAM destination.
-	* `correlationId` is a User's `externalId` or an entitlement's App-owned catalog `id`.
-	*/
-	getDestinationRef(resourceType: IamDeltaResourceType, correlationId: string): Promise<DestinationReference | undefined>;
-	isReady(): boolean;
-	ready(timeout?: number): Promise<void>;
-}
+declare function accessRootId(change: AccessChange): string;
 import { StandardSchemaV1 as StandardSchemaV13 } from "@standard-schema/spec";
 /**
 * SCIM 2.0 User Resource
@@ -820,10 +762,10 @@ interface GroupMember {
 	display?: string;
 	/**
 	* The type of the member. `"Workload"` labels a service-account/workload principal (including
-	* config-declared trusted provisioning clients) so SCIM consumers can distinguish it from a human
-	* `"User"` or a nested `"Group"`.
+	* config-declared trusted provisioning clients) and `"Customer"` a CIAM customer so SCIM consumers
+	* can distinguish them from a workforce `"User"` or a nested `"Group"`.
 	*/
-	type?: "User" | "Group" | "Workload";
+	type?: "User" | "Group" | "Workload" | "Customer";
 }
 /**
 * SCIM 2.0 Group Resource
@@ -861,6 +803,45 @@ interface GroupResource {
 	*/
 	members?: GroupMember[];
 }
+/** SCIM Workload resource — machine/service principal, not a User. */
+interface ScimWorkload {
+	schemas?: string[];
+	id?: string;
+	externalId?: string;
+	/** Login identifier; typically the OAuth `clientId`. */
+	userName?: string;
+	displayName?: string;
+	description?: string;
+	active?: boolean;
+	providerId?: string;
+	requestUrl?: string;
+	meta?: {
+		resourceType?: string;
+		created?: string;
+		lastModified?: string;
+		location?: string;
+		version?: string;
+	};
+}
+/** SCIM Customer resource — CIAM consumer principal, not a workforce User. */
+interface ScimCustomer {
+	schemas?: string[];
+	id?: string;
+	externalId?: string;
+	userName?: string;
+	displayName?: string;
+	active?: boolean;
+	emails?: Email[];
+	providerId?: string;
+	requestUrl?: string;
+	meta?: {
+		resourceType?: string;
+		created?: string;
+		lastModified?: string;
+		location?: string;
+		version?: string;
+	};
+}
 /**
 * SCIM Role
 */
@@ -952,6 +933,10 @@ interface EnterpriseExtension {
 * https://ionite.com/schemas/ion-scim-user-extension.json
 */
 declare const ION_SCIM_USER_EXTENSION_URN = "urn:ionite:scim:schemas:extension:ion:2.0:User";
+/** SCIM core schema for a Workload principal (distinct ResourceType from User). */
+declare const ION_SCIM_WORKLOAD_SCHEMA = "urn:ionite:scim:schemas:core:2.0:Workload";
+/** SCIM core schema for a Customer principal (distinct ResourceType from User). */
+declare const ION_SCIM_CUSTOMER_SCHEMA = "urn:ionite:scim:schemas:core:2.0:Customer";
 /**
 * ionite SCIM User extension. See https://ionite.com/docs/llms-ecid.txt.
 */
@@ -1109,6 +1094,311 @@ declare function userSchema(vendor: string): StandardSchemaV13<Record<string, un
 * @returns A StandardSchemaV1 instance for SCIM Group resources
 */
 declare function groupResourceSchema(vendor: string): StandardSchemaV13<Record<string, unknown>, GroupResource>;
+/** Validates a SCIM Workload resource. */
+declare const workloadResourceSchema: StandardSchemaV13<unknown, ScimWorkload>;
+/** Validates a SCIM Customer resource. */
+declare const customerResourceSchema: StandardSchemaV13<unknown, ScimCustomer>;
+/**
+* Persisted CIAM customer record with identity fields and tracking metadata.
+*
+* Builds on the shared minimal identity fields with a lightweight set of
+* consumer-oriented attributes and an optional CIAM (`ciam`) session envelope.
+* This is the type returned by `CustomerStore`. Apps typically extend the
+* `BaseCustomer` Zod/Valibot schema to add custom attributes.
+*
+* @template TExtended - Type-safe custom data that consumers can add to customers
+*/
+type BaseCustomer<TExtended = object> = BaseUserFields & {
+	/**
+	* Optional ionite tenant identifier for tenant-aware apps.
+	*/
+	tenantId?: string;
+	/**
+	* Optional external identifier from a provisioning client.
+	*/
+	externalId?: string;
+	/**
+	* Optional destination service-provider id captured after IAM materializes this customer.
+	*/
+	providerId?: string;
+	/**
+	* Optional IAM-owned deep link associated with this customer receipt.
+	*/
+	requestUrl?: string;
+	/**
+	* Optional display name distinct from the simple `name` field.
+	*/
+	displayName?: string;
+	/**
+	* Optional email collection.
+	* The simple `email` field still stores the primary email for convenience.
+	*/
+	emails?: Email[];
+	/**
+	* Optional phone numbers.
+	*/
+	phoneNumbers?: PhoneNumber[];
+	/**
+	* Optional account state.
+	*/
+	active?: boolean;
+	/**
+	* Timestamp when the customer was first stored.
+	*/
+	createdAt?: Date;
+	/**
+	* Timestamp when the customer was last updated (e.g., on re-login).
+	*/
+	updatedAt?: Date;
+	/**
+	* Optional CIAM envelope for stores that persist customer session profile data.
+	* Simple app stores MAY omit this field.
+	*/
+	ciam?: Customer["ciam"];
+} & TExtended;
+type CustomerStoreOptions = {
+	tenantId: string;
+	tenants: TenantStore;
+};
+/**
+* Abstract interface for customer storage backends.
+*
+* Mirrors `UserStore` but for the CIAM customer domain. Consumers can
+* implement this for in-memory, Redis, or database-backed persistence.
+*
+* @template TExtended - Type-safe custom data that consumers can add to customers
+*/
+interface CustomerStore<TExtended = object> {
+	/**
+	* Retrieve a customer by their unique identifier.
+	*
+	* @param id - The customer's unique identifier as defined by the store implementation
+	* @returns The customer if found, undefined otherwise
+	*/
+	get(id: string): Promise<BaseCustomer<TExtended> | undefined>;
+	/**
+	* Retrieve a customer based on their identity attributes or CIAM claims.
+	*
+	* @param customer - The customer to lookup
+	* @returns The customer if found, undefined otherwise
+	*/
+	lookup(customer: BaseCustomer<TExtended>): Promise<BaseCustomer<TExtended> | undefined>;
+	/**
+	* Optional indexed lookup by `externalId`. When omitted, callers fall back to `lookup` or a list scan.
+	*/
+	getByExternalId?(externalId: string): Promise<BaseCustomer<TExtended> | undefined>;
+	/**
+	* Create or update a customer in the store.
+	*
+	* @param customer - The customer data to store
+	*/
+	upsert(customer: BaseCustomer<TExtended>): Promise<BaseCustomer<TExtended>>;
+	/**
+	* Delete a customer by their unique identifier.
+	*
+	* @param id - The customer's unique identifier as defined by the store implementation
+	* @returns The number of customers deleted (0 or 1)
+	*/
+	delete(id: string): Promise<number>;
+	/**
+	* List customers in the store with optional pagination and sort.
+	*
+	* @param options - Optional start (0-based), limit (page size), and sort
+	* @returns ListResult with total, count, items, size, page, pages
+	*/
+	list(options?: ListOptions): Promise<ListResult<BaseCustomer<TExtended>>>;
+}
+/**
+* Persisted workload principal record. Mirrors the registry/enrichment shape of `BaseUser`, scoped
+* to the small set of attributes meaningful for non-human identities.
+*
+* @template TExtended - Type-safe custom data that consumers can add to workload identities.
+*/
+type BaseWorkloadIdentity<TExtended = object> = {
+	/**
+	* Stable subject id for this workload. Used as the AccessIndex subject for
+	* `subjectType: 'workload'` checks. Typically `clientId`, a workload id, or the token `sub`.
+	*/
+	id: string;
+	/** OAuth client identifier, when the workload authenticates via client credentials. */
+	clientId?: string;
+	/** Human-friendly display name for the service account / machine identity. */
+	displayName?: string;
+	/** Free-form description of the workload's purpose. */
+	description?: string;
+	/** External identifier from the provisioning client (e.g. SCIM). */
+	externalId?: string;
+	/**
+	* Optional destination service-provider id captured after IAM materializes this workload.
+	*/
+	providerId?: string;
+	/**
+	* Optional IAM-owned deep link associated with this workload receipt.
+	*/
+	requestUrl?: string;
+	/**
+	* Optional Enterprise Controlled ID for this workload: `ecid:<realm>:<opaque>`. A workload is its
+	* own governance root, never folded into a human's ECID. See https://ionite.com/docs/llms-ecid.txt.
+	*/
+	ecid?: string;
+	/** Whether the workload is active. Set `false` to disable it without deleting the record. */
+	active?: boolean;
+	/** Default OAuth scopes associated with this workload (space-delimited tokens, normalized list). */
+	scopes?: string[];
+	/** Timestamp when the workload identity was first stored. */
+	createdAt?: Date;
+	/** Timestamp when the workload identity was last updated. */
+	updatedAt?: Date;
+	/** Optional free-form metadata bag. */
+	metadata?: Record<string, unknown>;
+} & TExtended;
+/**
+* Abstract interface for workload identity storage backends. Implement to back the registry with
+* in-memory, Redis, or a database. Mirrors {@link UserStore}.
+*
+* @template TExtended - Type-safe custom data that consumers can add to workload identities.
+*/
+interface WorkloadIdentityStore<TExtended = object> {
+	/**
+	* Retrieve a workload identity by its unique id.
+	*
+	* @param id - The workload's unique identifier.
+	* @returns The workload identity if found, undefined otherwise.
+	*/
+	get(id: string): Promise<BaseWorkloadIdentity<TExtended> | undefined>;
+	/**
+	* Retrieve a workload identity by matching identifying attributes (e.g. `clientId`, `externalId`).
+	*
+	* @param identity - The workload identity to look up.
+	* @returns The workload identity if found, undefined otherwise.
+	*/
+	lookup(identity: BaseWorkloadIdentity<TExtended>): Promise<BaseWorkloadIdentity<TExtended> | undefined>;
+	/**
+	* Optional indexed lookup by `externalId`. When omitted, callers fall back to `lookup` or a list scan.
+	*/
+	getByExternalId?(externalId: string): Promise<BaseWorkloadIdentity<TExtended> | undefined>;
+	/**
+	* Create or update a workload identity. If a record with the same `id` exists it is updated,
+	* otherwise a new record is created.
+	*
+	* @param identity - The workload identity to store.
+	*/
+	upsert(identity: BaseWorkloadIdentity<TExtended>): Promise<BaseWorkloadIdentity<TExtended>>;
+	/**
+	* Delete a workload identity by id.
+	*
+	* @param id - The workload's unique identifier.
+	* @returns The number of records deleted (0 or 1).
+	*/
+	delete(id: string): Promise<number>;
+	/**
+	* List workload identities with optional pagination and sort.
+	*
+	* @param options - Optional start (0-based), limit (page size), and sort.
+	* @returns ListResult with total, count, items, size, page, pages.
+	*/
+	list(options?: ListOptions): Promise<ListResult<BaseWorkloadIdentity<TExtended>>>;
+}
+/**
+* IAM delta egress mode (RemoteConfig/ECI intent). Selects how IAM-visible runtime changes that
+* occur inside the application are surfaced to the enterprise's IAM/governance layer:
+*
+* - `'patch'`: outbound SCIM into the IAM tool (per-resource POST/PUT/PATCH/DELETE,
+*   correlated by the App-owned id carried as SCIM `externalId`). The IAM tool's view stays fresh as users, materialized entitlement
+*   definitions, and access change in the app. See the README "IAM delta egress" section.
+*
+* Origin/trust: every push is authenticated with the app's outgoing workload client (OAuth bearer);
+* the receiver treats the authenticated workload identity as the verified origin. Audit
+* accountability lives with the IdP that authenticated the workload and the IAM tool that granted
+* it access. The SDK only surfaces the signal; it never dictates the enterprise's workflow or
+* policy (flag, auto-revoke + notify, or simply audit).
+*/
+type IamDeltaMode = "patch";
+type AccessRequestCreate = {
+	subject: string;
+	subjectType: SubjectType;
+	targetType: EntitlementType;
+	target: string;
+	justification?: string;
+};
+type AccessRequestResult = {
+	id: string;
+	status: "pending" | "approved" | "denied";
+	trackingUrl: string;
+};
+/** SCIM resource types the delta patch adapter addresses. */
+type IamDeltaResourceType = "user" | "group" | "workload" | "customer";
+/** Destination-owned reference captured from a SCIM User/Group response. */
+type DestinationReference = {
+	/** Service-provider-assigned SCIM resource id. */
+	providerId: string;
+	/** IAM-owned deep link where access to an entitlement can be requested, when supplied. */
+	requestUrl?: string;
+};
+/**
+* Full IAM delta snapshot supplied by the app's maintenance/reconcile path. It mirrors the entities
+* visible through IAM aggregation: users, durable entitlement definitions, and active access roots.
+*/
+type IamDeltaReconcileInput = {
+	users?: Iterable<BaseUser> | AsyncIterable<BaseUser>;
+	workloads?: Iterable<BaseWorkloadIdentity> | AsyncIterable<BaseWorkloadIdentity>;
+	customers?: Iterable<BaseCustomer> | AsyncIterable<BaseCustomer>;
+	groups?: Iterable<Group> | AsyncIterable<Group>;
+	roles?: Iterable<Role> | AsyncIterable<Role>;
+	permissions?: Iterable<Permission> | AsyncIterable<Permission>;
+	access?: Iterable<AccessChange> | AsyncIterable<AccessChange>;
+};
+/** Result of an app-driven full reconcile (re-push of definitions, users, and active roots). */
+type IamDeltaReconcileResult = {
+	pushed: number;
+	skipped: number;
+	errors: string[];
+};
+/**
+* Projects observed runtime mutations to the configured IAM delta destination. The invariant is:
+* every runtime mutation the SDK observes that would change what IAM full sync shows must also
+* egress through this handle. That includes users, materialized entitlement definitions, and access
+* roots. Code templates are not pushed during config apply.
+*
+* Request-triggered methods resolve when projection completes (or immediately when not ready). They
+* are best-effort egress: the SCIM mutation path awaits them inside the request, but a rejection is
+* caught and reported as degraded egress — it never turns a committed store mutation into a SCIM
+* error. Reactive catalog/resource events use the same methods outside a request and warn on failure.
+*
+* Readiness follows the shared contract: `isReady()` is a synchronous check; `ready(timeout?)`
+* resolves once the emitter first becomes usable.
+*/
+interface IamDeltaEmitter {
+	/** Upsert a full SCIM User representation at the destination. */
+	onUserUpsert(user: BaseUser): Promise<void>;
+	/** Delete a destination User identified strictly by externalId. */
+	onUserDelete(externalId: string): Promise<void>;
+	/** Upsert a full SCIM Group representation for a group, role, or permission definition. */
+	onEntitlementUpsert(entity: Entitlement, type: EntitlementType): Promise<void>;
+	/** Delete a destination entitlement Group identified by the App-owned catalog id. */
+	onEntitlementDelete(type: EntitlementType, id: string): Promise<void>;
+	/** Project a granted root; resolves on completion (or immediately when not ready), rejects on push failure. */
+	onGrant(change: AccessChange): Promise<void>;
+	/** Project a revoked root; resolves on completion (or immediately when not ready), rejects on push failure. */
+	onRevoke(change: AccessChange): Promise<void>;
+	/** Re-push the complete IAM-visible snapshot to the destination (app-driven full reconcile). */
+	reconcile(input: IamDeltaReconcileInput): Promise<IamDeltaReconcileResult>;
+	/**
+	* Submit an on-behalf access request at `${iam.url}/AccessRequests`. Requires only the
+	* destination channel (`url` plus the `deltaAudience` workload client) — not `isReady()`, which
+	* additionally demands delta egress (a per-kind `'patch'` mode and its receipt stores). A tenant
+	* whose IAM aggregates by pull alone may still submit requests.
+	*/
+	requestAccess(input: AccessRequestCreate): Promise<AccessRequestResult>;
+	/**
+	* Read a previously captured destination reference without making a network request. Returns
+	* undefined until the resource has been resolved or pushed to the configured IAM destination.
+	* `correlationId` is a User's `externalId` or an entitlement's App-owned catalog `id`.
+	*/
+	getDestinationRef(resourceType: IamDeltaResourceType, correlationId: string): Promise<DestinationReference | undefined>;
+	isReady(): boolean;
+	ready(timeout?: number): Promise<void>;
+}
 import { StandardSchemaV1 as StandardSchemaV14 } from "@standard-schema/spec";
 type ChangeListener = () => void;
 /**
@@ -1188,85 +1478,6 @@ type RequireReadyResult = {
 	}>;
 };
 /**
-* Persisted workload principal record. Mirrors the registry/enrichment shape of `BaseUser`, scoped
-* to the small set of attributes meaningful for non-human identities.
-*
-* @template TExtended - Type-safe custom data that consumers can add to workload identities.
-*/
-type BaseWorkloadIdentity<TExtended = object> = {
-	/**
-	* Stable subject id for this workload. Used as the AccessIndex subject for
-	* `subjectType: 'workload'` checks. Typically `clientId`, a workload id, or the token `sub`.
-	*/
-	id: string;
-	/** OAuth client identifier, when the workload authenticates via client credentials. */
-	clientId?: string;
-	/** Human-friendly display name for the service account / machine identity. */
-	displayName?: string;
-	/** Free-form description of the workload's purpose. */
-	description?: string;
-	/** External identifier from the provisioning client (e.g. SCIM). */
-	externalId?: string;
-	/**
-	* Optional Enterprise Controlled ID for this workload: `ecid:<realm>:<opaque>`. A workload is its
-	* own governance root, never folded into a human's ECID. See https://ionite.com/docs/llms-ecid.txt.
-	*/
-	ecid?: string;
-	/** Whether the workload is active. Set `false` to disable it without deleting the record. */
-	active?: boolean;
-	/** Default OAuth scopes associated with this workload (space-delimited tokens, normalized list). */
-	scopes?: string[];
-	/** Timestamp when the workload identity was first stored. */
-	createdAt?: Date;
-	/** Timestamp when the workload identity was last updated. */
-	updatedAt?: Date;
-	/** Optional free-form metadata bag. */
-	metadata?: Record<string, unknown>;
-} & TExtended;
-/**
-* Abstract interface for workload identity storage backends. Implement to back the registry with
-* in-memory, Redis, or a database. Mirrors {@link UserStore}.
-*
-* @template TExtended - Type-safe custom data that consumers can add to workload identities.
-*/
-interface WorkloadIdentityStore<TExtended = object> {
-	/**
-	* Retrieve a workload identity by its unique id.
-	*
-	* @param id - The workload's unique identifier.
-	* @returns The workload identity if found, undefined otherwise.
-	*/
-	get(id: string): Promise<BaseWorkloadIdentity<TExtended> | undefined>;
-	/**
-	* Retrieve a workload identity by matching identifying attributes (e.g. `clientId`, `externalId`).
-	*
-	* @param identity - The workload identity to look up.
-	* @returns The workload identity if found, undefined otherwise.
-	*/
-	lookup(identity: BaseWorkloadIdentity<TExtended>): Promise<BaseWorkloadIdentity<TExtended> | undefined>;
-	/**
-	* Create or update a workload identity. If a record with the same `id` exists it is updated,
-	* otherwise a new record is created.
-	*
-	* @param identity - The workload identity to store.
-	*/
-	upsert(identity: BaseWorkloadIdentity<TExtended>): Promise<BaseWorkloadIdentity<TExtended>>;
-	/**
-	* Delete a workload identity by id.
-	*
-	* @param id - The workload's unique identifier.
-	* @returns The number of records deleted (0 or 1).
-	*/
-	delete(id: string): Promise<number>;
-	/**
-	* List workload identities with optional pagination and sort.
-	*
-	* @param options - Optional start (0-based), limit (page size), and sort.
-	* @returns ListResult with total, count, items, size, page, pages.
-	*/
-	list(options?: ListOptions): Promise<ListResult<BaseWorkloadIdentity<TExtended>>>;
-}
-/**
 * Token caching for workload identity authentication.
 *
 * Token stores are optional but recommended for performance - they enable:
@@ -1737,6 +1948,14 @@ interface IAMHandlerConfig {
 	*/
 	groupsUrl?: string;
 	/**
+	* Base path for the SCIM Workloads endpoints (e.g., '/api/iam/Workloads')
+	*/
+	workloadsUrl?: string;
+	/**
+	* Base path for the SCIM Customers endpoints (e.g., '/api/iam/Customers')
+	*/
+	customersUrl?: string;
+	/**
 	* Handler overrides for SCIM discovery endpoints (e.g., '/api/iam/ServiceProviderConfig')
 	*/
 	discovery?: IAMDiscoveryHandlerConfig;
@@ -1760,6 +1979,19 @@ type IAMConfig = {
 	*/
 	userStore?: UserStore;
 	/**
+	* Store for inbound workload provisioning. When configured, `/Workloads` is served.
+	*/
+	workloadIdentityStore?: WorkloadIdentityStore;
+	/**
+	* Store for inbound customer provisioning. When configured, `/Customers` is served.
+	*/
+	customerStore?: CustomerStore;
+	/**
+	* Destination-only hook for `POST /AccessRequests`. Apps that are not IAM destinations omit this
+	* and the endpoint returns 404.
+	*/
+	accessRequests?: IAMAccessRequestsConfig;
+	/**
 	* Optional inbound user mapping hooks for SCIM provisioning.
 	* Use these when the default BaseUser <-> SCIM mapping is not a direct fit
 	* for your application's database model.
@@ -1776,13 +2008,28 @@ type IAMConfig = {
 	*/
 	usersUrl?: string;
 	groupsUrl?: string;
+	workloadsUrl?: string;
+	customersUrl?: string;
 	discovery?: IAMDiscoveryConfig;
 	/**
-	* RemoteConfig intent flag for the inbound SCIM Users endpoint. Set by Ops/ECI via the
-	* ConfigSource; not configurable from application code. When omitted, Users are enabled if the
-	* IAM module is present. Effective availability also requires a `userStore` capability.
+	* RemoteConfig intent for workforce principals. Set by Ops/ECI via the ConfigSource; not
+	* configurable from application code. `enabled` gates the inbound SCIM Users endpoint (default
+	* on when the IAM module is present). `assignment` is the Ops-owned in-app grant policy
+	* (default `'app'`). Effective Users availability also requires a `userStore` capability.
+	*/
+	users?: IamPrincipalKindFlag;
+	/**
+	* RemoteConfig intent for workload principals. Set by Ops/ECI via the ConfigSource; not
+	* configurable from application code. `enabled` gates `/Workloads` (default on). `assignment` is
+	* consumed by {@link Authz.grant}. `delta` is the Ops-owned per-kind egress mode.
+	*/
+	workloads?: IamPrincipalKindFlag;
+	/**
+	* RemoteConfig intent for CIAM customer principals. Set by Ops/ECI via the ConfigSource; not
+	* configurable from application code. `enabled` gates `/Customers` (default on). `assignment` is
+	* consumed by {@link Authz.grant}. `delta` is the Ops-owned per-kind egress mode.
 	*/
-	users?: IAMEndpointFlag;
+	customers?: IamPrincipalKindFlag;
 	/**
 	* RemoteConfig intent flag for the inbound SCIM Groups endpoint. Set by Ops/ECI via the
 	* ConfigSource; not configurable from application code. Effective availability also requires an
@@ -1790,21 +2037,9 @@ type IAMConfig = {
 	*/
 	groups?: IAMEndpointFlag;
 	/**
-	* RemoteConfig/ECI intent: how access changes that occur inside the application are surfaced to the
-	* enterprise IAM/governance layer. Not configurable from application code.
-	*
-	* `'patch'`: outbound SCIM into the IAM tool keyed by the App-owned catalog id carried as SCIM
-	* `externalId` (uses `url` as the destination base and `deltaAudience` for the outgoing workload client). Every observed runtime
-	* mutation that changes the IAM full-sync view egresses: user and entitlement upsert/delete, and
-	* access grant/revoke. See the README "IAM delta egress" section.
-	*
-	* When omitted, delta egress is disabled. The SDK only emits the signal; the enterprise's IAM
-	* tooling owns the response (flag, auto-revoke + notify, or audit). See `IamDeltaMode`.
-	*/
-	delta?: IamDeltaMode;
-	/**
-	* RemoteConfig/ECI intent: name of the outgoing workload client used to authenticate `delta:'patch'`
-	* pushes to the destination (`url`). When omitted, the default workload server token is used.
+	* RemoteConfig/ECI intent: name of the outgoing workload client used to authenticate per-kind
+	* `delta:'patch'` pushes to the destination (`url`). When omitted, the default workload server
+	* token is used. Module-wide; per-kind enablement lives on `users`/`workloads`/`customers`.
 	*/
 	deltaAudience?: string;
 };
@@ -1814,6 +2049,32 @@ type IAMConfig = {
 type IAMEndpointFlag = {
 	enabled?: boolean;
 };
+/**
+* RemoteConfig intent for one principal kind: endpoint enablement plus the Ops-owned assignment
+* policy. `assignment` defaults to `'app'` (today's notify-via-delta semantics).
+*/
+type IamPrincipalKindFlag = {
+	enabled?: boolean;
+	assignment?: IamAssignmentPolicy;
+	/** Per-kind IAM delta egress. `'patch'` enables outbound SCIM for this principal kind. */
+	delta?: IamDeltaMode;
+};
+/** Normalized, always-present principal-kind intent exposed on `ion.iam`. */
+type IamPrincipalKind = {
+	enabled: boolean;
+	assignment: IamAssignmentPolicy;
+	delta?: IamDeltaMode;
+};
+type IAMAccessRequestsConfig = {
+	create: (request: AccessRequestCreate) => Promise<AccessRequestResult>;
+};
+type AccessRequestSubmit = {
+	subject: AccessChange["subject"];
+	subjectType: SubjectType;
+	targetType: EntitlementType;
+	target: AccessChange["target"];
+	justification?: string;
+};
 type IAMEntitlementRequestUrlContext = {
 	request: Request;
 	tenantId?: string;
@@ -1821,6 +2082,8 @@ type IAMEntitlementRequestUrlContext = {
 type IAMValidators = {
 	user: StandardSchemaV15<unknown, User>;
 	group: StandardSchemaV15<unknown, GroupResource>;
+	workload?: StandardSchemaV15<unknown, ScimWorkload>;
+	customer?: StandardSchemaV15<unknown, ScimCustomer>;
 };
 interface IAMInboundUserContext {
 	/**
@@ -1928,8 +2191,12 @@ interface IAMDiscoveryContext {
 	basePath: string;
 	usersUrl: string;
 	groupsUrl: string;
+	workloadsUrl: string;
+	customersUrl: string;
 	supportsUsers: boolean;
 	supportsGroups: boolean;
+	supportsWorkloads: boolean;
+	supportsCustomers: boolean;
 }
 interface IAMDiscoveryConfig {
 	/**
@@ -1994,6 +2261,12 @@ interface UsersInboundHandlerConfig {
 	*/
 	basePath?: string;
 }
+interface PrincipalInboundHandlerConfig {
+	basePath?: string;
+}
+type IAMPrincipalsInbound = {
+	handler: (request: Request, config?: PrincipalInboundHandlerConfig) => Promise<Response>;
+};
 interface IAMDiscoveryHandlerConfig {
 	/**
 	* Base path for the IAM discovery endpoints (e.g., '/api/iam')
@@ -2043,7 +2316,13 @@ type IAMUsersInbound = {
 * - `groups_inbound` is available when a `catalogStore` is configured
 * - `users_inbound` is available when `userStore` is configured
 */
-type IAM = IAMConfig & {
+type IAM = Omit<IAMConfig, "users" | "workloads" | "customers" | "groups"> & {
+	users: IamPrincipalKind;
+	workloads: IamPrincipalKind;
+	customers: IamPrincipalKind;
+	groups: {
+		enabled: boolean;
+	};
 	/**
 	* Create a new user/account in the external IAM provider
 	* Only available when `url` is configured.
@@ -2068,9 +2347,11 @@ type IAM = IAMConfig & {
 	* Available when `userStore` is configured in IAMConfig.
 	*/
 	users_inbound?: IAMUsersInbound;
+	workloads_inbound?: IAMPrincipalsInbound;
+	customers_inbound?: IAMPrincipalsInbound;
 	/**
 	* Framework-agnostic request handler for the IAM module.
-	* Routes to discovery, users_inbound, or groups_inbound based on the request path.
+	* Routes to discovery, users_inbound, groups_inbound, or principal-kind inbound based on path.
 	*/
 	handler: (request: Request, config?: IAMHandlerConfig) => Promise<Response>;
 	/** Synchronous readiness: true once this IAM handle is configured and usable. */
@@ -2795,104 +3076,6 @@ type SSO<
 	ready?: (timeout?: number) => Promise<void>;
 };
 /**
-* Persisted CIAM customer record with identity fields and tracking metadata.
-*
-* Builds on the shared minimal identity fields with a lightweight set of
-* consumer-oriented attributes and an optional CIAM (`ciam`) session envelope.
-* This is the type returned by `CustomerStore`. Apps typically extend the
-* `BaseCustomer` Zod/Valibot schema to add custom attributes.
-*
-* @template TExtended - Type-safe custom data that consumers can add to customers
-*/
-type BaseCustomer<TExtended = object> = BaseUserFields & {
-	/**
-	* Optional ionite tenant identifier for tenant-aware apps.
-	*/
-	tenantId?: string;
-	/**
-	* Optional external identifier from a provisioning client.
-	*/
-	externalId?: string;
-	/**
-	* Optional display name distinct from the simple `name` field.
-	*/
-	displayName?: string;
-	/**
-	* Optional email collection.
-	* The simple `email` field still stores the primary email for convenience.
-	*/
-	emails?: Email[];
-	/**
-	* Optional phone numbers.
-	*/
-	phoneNumbers?: PhoneNumber[];
-	/**
-	* Optional account state.
-	*/
-	active?: boolean;
-	/**
-	* Timestamp when the customer was first stored.
-	*/
-	createdAt?: Date;
-	/**
-	* Timestamp when the customer was last updated (e.g., on re-login).
-	*/
-	updatedAt?: Date;
-	/**
-	* Optional CIAM envelope for stores that persist customer session profile data.
-	* Simple app stores MAY omit this field.
-	*/
-	ciam?: Customer["ciam"];
-} & TExtended;
-type CustomerStoreOptions = {
-	tenantId: string;
-	tenants: TenantStore;
-};
-/**
-* Abstract interface for customer storage backends.
-*
-* Mirrors `UserStore` but for the CIAM customer domain. Consumers can
-* implement this for in-memory, Redis, or database-backed persistence.
-*
-* @template TExtended - Type-safe custom data that consumers can add to customers
-*/
-interface CustomerStore<TExtended = object> {
-	/**
-	* Retrieve a customer by their unique identifier.
-	*
-	* @param id - The customer's unique identifier as defined by the store implementation
-	* @returns The customer if found, undefined otherwise
-	*/
-	get(id: string): Promise<BaseCustomer<TExtended> | undefined>;
-	/**
-	* Retrieve a customer based on their identity attributes or CIAM claims.
-	*
-	* @param customer - The customer to lookup
-	* @returns The customer if found, undefined otherwise
-	*/
-	lookup(customer: BaseCustomer<TExtended>): Promise<BaseCustomer<TExtended> | undefined>;
-	/**
-	* Create or update a customer in the store.
-	*
-	* @param customer - The customer data to store
-	*/
-	upsert(customer: BaseCustomer<TExtended>): Promise<BaseCustomer<TExtended>>;
-	/**
-	* Delete a customer by their unique identifier.
-	*
-	* @param id - The customer's unique identifier as defined by the store implementation
-	* @returns The number of customers deleted (0 or 1)
-	*/
-	delete(id: string): Promise<number>;
-	/**
-	* List customers in the store with optional pagination and sort.
-	*
-	* @param options - Optional start (0-based), limit (page size), and sort
-	* @returns ListResult with total, count, items, size, page, pages
-	*/
-	list(options?: ListOptions): Promise<ListResult<BaseCustomer<TExtended>>>;
-}
-/**
 * Magic link data stored in the store.
 *
 * @template TExtended - Type-safe custom data that consumers can add to magic links
@@ -3760,7 +3943,7 @@ type FrameworkConfig = {
 * enablement) are also stripped from code.
 */
 type SSOConfigFromCode = Omit<SSOConfig, "loginUrl" | "userUrl" | "logoutUrl" | "logoutBackChannelUrl" | "refreshUrl" | "redirectUri">;
-type IAMConfigFromCode = Omit<IAMConfig, "usersUrl" | "groupsUrl" | "users" | "groups" | "discovery" | "delta" | "deltaAudience"> & {
+type IAMConfigFromCode = Omit<IAMConfig, "usersUrl" | "groupsUrl" | "workloadsUrl" | "customersUrl" | "users" | "workloads" | "customers" | "groups" | "discovery" | "deltaAudience"> & {
 	discovery?: Omit<IAMDiscoveryConfig, "basePath">;
 };
 type WorkloadServerConfigFromCode = Omit<Partial<WorkloadConfig>, "tokenUrl" | "validateUrl" | "jwksUrl" | "refreshUrl">;
@@ -4180,7 +4363,7 @@ type CIAMConfigFromCode<
 	TMagicLinkData = Record<string, never>,
 	TCustomerData = Record<string, never>
 > = Omit<CIAMConfig<TMagicLinkData, TCustomerData>, "providers" | "customerLoginUrl" | "customerCallbackUrl" | "customerProvidersUrl">;
-/** Read Users and Groups via the SCIM endpoints. Gates `GET /iam/Users` and `GET /iam/Groups`. */
+/** Read Users, Groups, Workloads, and Customers via the SCIM endpoints. */
 declare const ION_IAM_READ: Permission;
 /**
 * Create, replace, modify (attribute changes), and delete Users via SCIM. Includes the access-root
@@ -4193,6 +4376,18 @@ declare const ION_IAM_USERS_WRITE: Permission;
 * `/iam/Groups`.
 */
 declare const ION_IAM_GROUPS_WRITE: Permission;
+/**
+* Create, replace, modify, and delete Workloads via SCIM. Gates write methods on `/iam/Workloads`.
+*/
+declare const ION_IAM_WORKLOADS_WRITE: Permission;
+/**
+* Create, replace, modify, and delete Customers via SCIM. Gates write methods on `/iam/Customers`.
+*/
+declare const ION_IAM_CUSTOMERS_WRITE: Permission;
+/**
+* Submit an on-behalf access request via `POST /iam/AccessRequests`. Gates the iam-request protocol.
+*/
+declare const ION_IAM_ACCESS_REQUESTS_WRITE: Permission;
 /** Read the capability manifest at `${basePath}/capabilitiez` (diagnostic; dev/ECV only). */
 declare const ION_CAPABILITIEZ_READ: Permission;
 /** Mint customer magic-link login credentials via `POST ${basePath}/magic-link`. Grant narrowly. */
@@ -4210,10 +4405,11 @@ declare const ION_SDK_PERMISSIONS: readonly Permission[];
 * The logical SDK endpoint operations that require authorization, mapped to the Permission and the
 * principal scope to check. This is the single source of truth the router/guards consult so the
 * enforcement contract lives in one place rather than scattered per route (AUDIT_HISTORY.md §1.32). The IAM
-* permission for a SCIM request is chosen from `iam.read` / `iam.users.write` / `iam.groups.write`
-* by SCIM resource + HTTP method (no request-body introspection).
+* permission for a SCIM request is chosen from `iam.read` / `iam.users.write` / `iam.groups.write` /
+* `iam.workloads.write` / `iam.customers.write` / `iam.access-requests.write` by resource + HTTP
+* method (no request-body introspection).
 */
-type EndpointOperation = "iam.read" | "iam.users.write" | "iam.groups.write" | "capabilitiez.read" | "ciam.magic-link.create" | "authz.oaa.sync" | "tenant.manage";
+type EndpointOperation = "iam.read" | "iam.users.write" | "iam.groups.write" | "iam.workloads.write" | "iam.customers.write" | "iam.access-requests.write" | "capabilitiez.read" | "ciam.magic-link.create" | "authz.oaa.sync" | "tenant.manage";
 type EndpointPermission = {
 	permission: Permission;
 	subjectType: SubjectScope;
@@ -4783,19 +4979,19 @@ type Resource = AuthzEntityBase & {
 /**
 * AppDev-owned subject-type scoping shared by every catalog entitlement (group/role/permission).
 *
-* - `assignableSubjectTypes` is the AppDev **veto**: the hard ceiling of principal kinds that may
-*   ever hold this entitlement. It is authored in application code and is **read-only** to the IAM
-*   tool (projected through SCIM as a `readOnly` attribute). When unset, the entitlement is
-*   unrestricted within the platform ceiling ({@link PLATFORM_ASSIGNABLE_SUBJECT_TYPES}); when set,
-*   it further narrows that ceiling. A grant whose `subjectType` is outside this set is rejected.
+* - `assignableSubjectTypes` is the AppDev **veto**: the hard, required, non-empty ceiling of
+*   principal kinds that may ever hold this entitlement. It is authored in application code and is
+*   **read-only** to the IAM tool (projected through SCIM as a `readOnly` attribute). There is no
+*   default-to-workforce and no unset-means-unrestricted: every entitlement declares its audience
+*   explicitly. A grant whose `subjectType` is outside this set is rejected.
 * - `recommendedSubjectTypes` is the AppDev **advisory default**: a (non-binding) subset of
 *   `assignableSubjectTypes` the IAM tool should default to. It is also read-only to IAM; the IAM
 *   tool is responsible for tracking changes to it over time. It MUST be a subset of
 *   `assignableSubjectTypes` (validated when the entitlement is authored).
 */
 type SubjectTypeScoping = {
-	/** AppDev veto: hard ceiling of principal kinds that may hold this entitlement (read-only to IAM). */
-	assignableSubjectTypes?: SubjectType[];
+	/** AppDev veto: required non-empty ceiling of principal kinds that may hold this entitlement (read-only to IAM). */
+	assignableSubjectTypes: SubjectType[];
 	/** AppDev advisory default principal kinds; must be a subset of `assignableSubjectTypes` (read-only to IAM). */
 	recommendedSubjectTypes?: SubjectType[];
 };
@@ -5020,20 +5216,21 @@ type SubjectType = "user" | "customer" | "workload";
 */
 type SubjectScope = SubjectType | SubjectType[] | "any";
 /**
-* Platform-wide ceiling of principal kinds the SDK currently allows to hold an entitlement. This is
-* the upper bound on {@link SubjectTypeScoping.assignableSubjectTypes}: even an unset (unrestricted)
-* entitlement is implicitly capped to these kinds. `customer` is intentionally excluded until the
-* customer-grant model (AUDIT_HISTORY.md §1.30) is resolved; granting a `customer` is rejected platform-wide.
+* Platform-wide ceiling of principal kinds the SDK allows to hold an entitlement. This is the
+* upper bound on {@link SubjectTypeScoping.assignableSubjectTypes}: every entitlement must declare
+* a non-empty audience that is a subset of these kinds. `customer` is grantable (AUDIT_HISTORY.md
+* §1.30 resolved); Apps still opt each entitlement in via an explicit audience.
 */
 declare const PLATFORM_ASSIGNABLE_SUBJECT_TYPES: SubjectType[];
 /**
 * Validate an entitlement's {@link SubjectTypeScoping} at authoring time (fail closed):
-* - every `assignableSubjectTypes` entry must be within the platform ceiling, and
-* - `recommendedSubjectTypes` must be a subset of `assignableSubjectTypes` (when the latter is set).
+* - `assignableSubjectTypes` is required and non-empty,
+* - every entry must be within the platform ceiling, and
+* - `recommendedSubjectTypes` must be a subset of `assignableSubjectTypes` when set.
 *
-* Throws an `Error` describing the first violation; returns void when valid (or when neither field is
-* set). Used by the SDK's catalog store wrapper and exported so custom stores can enforce the same
-* contract before persisting an app-authored catalog entry.
+* Throws an `Error` describing the first violation; returns void when valid. Used by the SDK's
+* catalog store wrapper and exported so custom stores can enforce the same contract before
+* persisting an app-authored catalog entry.
 */
 declare function assertValidSubjectTypeScoping(entity: SubjectTypeScoping & {
 	id?: string;
@@ -5378,7 +5575,52 @@ type Authz = {
 	* is wired. Always run it off the request path.
 	*/
 	reconcile(): Promise<ReconcileReport>;
+	/**
+	* App-facing grant: audience + assignment-policy checks, then write the root and materialize the
+	* index. IAM SCIM ingress does **not** use this path (it stays policy-exempt). Throws
+	* {@link AssignmentPolicyError} when Ops forbids in-app assignment for the principal kind.
+	*/
+	grant(change: AccessChange): Promise<AccessChange>;
+	/**
+	* Submit an access request on a principal's behalf. Allowed only when that kind's assignment
+	* policy is `'iam-request'`. Authenticated with the module-wide `deltaAudience` workload client.
+	*/
+	requestAccess(change: {
+		subject: AccessChange["subject"];
+		subjectType: SubjectType;
+		targetType: EntitlementType;
+		target: AccessChange["target"];
+		justification?: string;
+	}): Promise<{
+		id: string;
+		status: "pending" | "approved" | "denied";
+		trackingUrl: string;
+	}>;
+	/**
+	* App-facing revoke of a granted root. Does not re-check assignment policy (removing access is
+	* always allowed from the app once the root exists).
+	*/
+	revoke(change: AccessChange): Promise<void>;
 };
+/**
+* Ops-owned assignment policy for one principal kind (`RemoteConfig.iam.{users,workloads,customers}.assignment`).
+*
+* - `'app'` — the application may assign access; delta notifies IAM.
+* - `'iam'` — never assign in-app; show a request link (or a read-only entitlement table).
+* - `'iam-request'` — never assign in-app; the app submits a request on the principal's behalf via
+*   {@link Authz.requestAccess}.
+*/
+type IamAssignmentPolicy = "app" | "iam" | "iam-request";
+/**
+* Thrown by {@link Authz.grant} when the Ops-owned assignment policy forbids in-app assignment.
+* `requestUrl` is the IAM-written entitlement receipt when one exists, so the app can send the
+* caller to the request page without catching a generic error.
+*/
+declare class AssignmentPolicyError extends Error {
+	readonly policy: IamAssignmentPolicy;
+	readonly requestUrl?: string;
+	constructor(message: string, policy: IamAssignmentPolicy, requestUrl?: string);
+}
 /** Why an {@link AccessCheckResult} resolved the way it did. */
 type AccessCheckReason = "ok" | "unauthenticated" | "forbidden" | "not_configured";
 /**
@@ -5419,21 +5661,7 @@ declare function trustedClientPermissionsForPrincipal(authz: AuthzConfig | null
 * OAA full sync — they are NEVER written to a store or materialized into the AccessIndex.
 */
 declare function configTrustedClientGrants(authz: AuthzConfig | null | undefined): AccessChange[];
-/**
-* Resolve an access subject/target/resource reference (a string id or an object carrying one) to its
-* canonical, trimmed string id. This is the single id-resolution rule shared across the authz stack
-* (AUDIT_HISTORY.md §8.4): `accessRootId`, the access stores, the access index, and SCIM diff keys all key off
-* the same normalization so distinct roots never collapse and identical references never diverge.
-* Returns `''` when no id can be resolved.
-*/
-declare function accessRefId(value: unknown): string;
-/**
-* Deterministic id for a granted root. Includes the resource scope so that two grants of the same
-* subject/target with different scopes are tracked as distinct roots. Application-wide scope (the
-* default, or `applyToApplication`) collapses to the `app` scope key.
-*/
-declare function accessRootId(change: AccessChange): string;
-type CapabilityKey = "sso.login" | "sso.jit" | "sso.logout" | "sso.back_channel_logout" | "ciam.magic_link" | "ciam.oidc_login" | "ciam.customer" | "ciam.logout" | "iam.users" | "iam.groups" | "workload.incoming" | "workload.outgoing" | "authz.oaa";
+type CapabilityKey = "sso.login" | "sso.jit" | "sso.logout" | "sso.back_channel_logout" | "ciam.magic_link" | "ciam.oidc_login" | "ciam.customer" | "ciam.logout" | "iam.users" | "iam.groups" | "iam.workloads" | "iam.customers" | "workload.incoming" | "workload.outgoing" | "authz.oaa";
 type CapabilityEndpointUrls = {
 	readyzUrl: string;
 	capabilitiezUrl: string;
@@ -5453,6 +5681,8 @@ type CapabilityEndpointUrls = {
 		basePath: string;
 		usersUrl: string;
 		groupsUrl: string;
+		workloadsUrl: string;
+		customersUrl: string;
 	};
 	ciam: {
 		magicLinkUrl: string;
@@ -5633,6 +5863,17 @@ declare function list<T>(total: number, items: T[], start: number, limit: number
 */
 declare function listGenerator<T>(listFn: (start: number, limit: number) => Promise<ListResult<T>>, processItem?: (item: T) => Promise<T | void>, pageSize?: number): AsyncGenerator<T>;
 /**
+* Apply the shared principal-list filter fields. Unknown fields are ignored by callers that
+* only pass a subset. `userName` matches `userName` or, for workloads, `clientId`.
+*/
+declare function matchesListFilter(item: {
+	requestable?: boolean;
+	userName?: string;
+	clientId?: string;
+	externalId?: string;
+	updatedAt?: Date;
+}, filter: ListFilter | undefined): boolean;
+/**
 * Wrap an authored catalog entity with non-enumerable readiness observers tied to a background
 * persistence write. The returned object is the entity itself (same reference), so it can be used
 * synchronously and embedded as an {@link AccessRef} while persistence proceeds.
@@ -5824,4 +6065,4 @@ type LfvErrorResponse = {
 };
 /** Generates a ULID */
 declare function generateULID(prefix?: string): string;
-export { workloadTokenResponseSchema, withValidate, warnLogger, waitOn, version, validationFailureResponse, userSchema, unionCatalogRead, trustedClientPermissionsForPrincipal, trimTrailingSlash, tokenResponseSchema, toCodeCatalog, stripJsonComments, stableConfigHash, silentLogger, serializeConfig, remoteConfigSecretType, readyCatalogEntry, parseKmsPoolDocument, parseKmsPoolControlDocument, parseJsonc, parseEcid, oidcCallbackSchema, normalizeTenantRoutingStrategy, normalizeTenantPathNamespace, must, mergeConfig, mergeCodeCatalogEntity, materializeCodeCatalogEntity, matchTenantPath, listGenerator, list, jwtAssertionClaimsSchema, isStoreConflictError, isEcid, isConfigSourceError, isConfigLocator, isCodeCatalog, infoLogger, idTokenClaimsSchema, groupResourceSchema, getCodeCatalogEntity, generateULID, formatEcid, deprecateRetiredCodeCatalogRows, defineSecretType, defineCatalog, defaultSecretContentType, defaultLogger, deepEqualPlain, decodeUser, debugLogger, configTrustedClientGrants, claimsToUser, catalogEntityStore, buildTenantPath, assertValidSubjectTypeScoping, assertRequiredSubjectType, assertEcid, accessRootId, accessRefId, X509Certificate, WorkloadValidators, WorkloadTokenStore, WorkloadTokenResponse, WorkloadPrincipal, WorkloadIncomingOutgoing, WorkloadIdentityStore, WorkloadIdentity, WorkloadGetToken, WorkloadConfigMap, WorkloadConfig, WorkloadClient, Workload, WorkforceUser, VaultWorkloadAuthConfig, VaultWebSocketSecretsConfig, VaultWebSocketAuthHeader, VaultSecretsConfig, VaultLfvSecretsConfig, VaultConfigLocator, ValidateResult, UsersInboundHandlerConfig, UserStoreOptions, UserStore, UpdateTenantRequest, TrustedProvisioningClient, TrustedIdp, TokenValidationResult, TokenResponse, TenantWebhookPayload, TenantValidators, TenantStore, TenantStatus, TenantRoutingStrategy, TenantResponse, TenantPathRoutingStrategy, TenantPathNamespace, TenantPathMatch, TenantIonCache, SubscriptionMode, SubjectTypeScoping, SubjectType, SubjectScope, SubjectRef, StoreConflictKind, StoreConflictError, StateCookie, StandardSchemaWithValidate, SessionStore, Session, ServerOnlyWorkloadConfig, SecretsWriteOptions, SecretsValidators, SecretsSubscriptionOptions, SecretsSourceType, SecretsSourceMap, SecretsSourceConfig, SecretsSource, SecretsOperationOptions, SecretsModuleConfig, Secrets, SecretTypeRegistryEntry, SecretTypeInput, SecretTypeDescriptor, SecretRequestSeverity, SecretLifecycleRequest, SecretHandle, SecretFormat, SecretEventName, SecretEventListener, SecretEvent, SecretContentTypeMismatchError, SecretContentType, Secret, User as ScimUser, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, Role2 as ScimRole, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimMutationSummary, ScimListResponse, Group2 as ScimGroup, ScimError, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfigFromCode, SSOConfig, SSOAppValidators, SSOAppRegistry, SSO, RoutingOptions, RouteModule, RouteFilterResult, Role, ResourceProvider, ResourceChangeListener, ResourceChange, Resource, ResolvedVaultLfvSecretsConfig, ResolvedRoute, RequireReadyResult, RemoteConfigRetryOptions, RemoteConfigRetryHook, RemoteConfigRetryContext, RemoteConfigLoadErrorKind, RemoteConfig, RegisterSSOAppResult, RegisterSSOAppPayload, RegisterSSOAppError, RegisterIAMAppResult, RegisterIAMAppPayload, RegisterIAMAppError, ReconcileReport, ReadyzEndpointConfig, ReadyAccessCatalogEntry, ReadinessReport, ReactiveHandle, Photo, PhoneNumber, Permission, ParsedEcid, PLATFORM_ASSIGNABLE_SUBJECT_TYPES, OtelSignalName, OtelSignalConfig, OtelProviderType, OtelProtocol, OtelOAuthClientCredentialsConfig, OtelMetricsSignalConfig, OtelLogRecord, OtelLogLevel, OtelLevels, OtelConfig, OtelAttributes, OtelAttributeValue, Otel, OidcCallbackParams, OaaSyncResult, OaaSyncOptions, OaaSyncInput, OaaClient, OaaAccessTargetType, OaaAccessChangeBatchItem, Name, ModuleReadinessState, ModuleReadiness, ModuleName, ModifiableFrameworkConfig, MirrorConfigLocator, MetaData, MagicLinkStore, MagicLink, Logger, ListResult, ListOptions, ListFilter, LfvOtpResponse, LfvOtpRequest, LfvJwks, LfvErrorResponse, LfvErrorCode, LfvEd25519PublicJwk, LfvEd25519PrivateJwk, LfvCallbackTransport, LfvCallbackKind, LfvCallbackHeaders, LfvCallbackEnvelope, LfvActionRequestBase, LfvActionName, LfvActionAcceptedResponse, KmsRevokeKeyResult, KmsRevokeKeyRequest, KmsPoolSlot, KmsPoolListener, KmsPoolIssuer, KmsPoolDocument, KmsPoolControlDocument, KmsPoolConfig, KmsPool, KmsParkResult, KmsParkRequest, KmsParkReport, KmsParkDisposition, KmsKeyState, KmsKey, KmsIssuerEventName, KmsIssuerEventListener, KmsIssuerEvent, KmsIssuedKey, KmsConfig, KmsAllocationStrategy, KmsAllocationPolicy, KmsAddKeysResult, KmsAddKeysRequest, Kms, JwtBearerWorkloadConfig, JWTAssertionClaims, IoniteValidators, IoniteUserExtension, IoniteErrorOptions, IoniteError, IoniteBase, Ionite, InferSecretType, InMemoryTenantStoreOptions, IdentityResolution, IdTokenClaims, IamDeltaResourceType, IamDeltaReconcileResult, IamDeltaReconcileInput, IamDeltaMode, IamDeltaEmitter, ION_TENANT_MANAGE, ION_SDK_PERMISSIONS, ION_SCIM_USER_EXTENSION_URN, ION_IAM_USERS_WRITE, ION_IAM_READ, ION_IAM_GROUPS_WRITE, ION_ENDPOINT_PERMISSIONS, ION_CIAM_MAGIC_LINK_CREATE, ION_CAPABILITIEZ_READ, ION_AUTHZ_OAA_SYNC, ION_AUTHZ_GROUP_SCHEMA, IAMValidators, IAMUsersInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfigFromCode, IAMConfig, IAMAppValidators, IAMAppRegistry, IAM, GroupsInboundHandlerConfig, GroupResource, GroupMember, Group, GcpSecretsConfig, GcpConfigLocator, FrameworkWorkloadIncomingOutgoing, FrameworkWorkloadConfigFromCode, FrameworkWorkloadConfig, FrameworkStores, FrameworkSecretsSourceConfig, FrameworkSecretsModuleConfig, FrameworkOtelConfig, FrameworkLfvConfig, FrameworkConfigInput, FrameworkConfig, EnvironmentType, EntityStore, EntitlementType, Entitlement, EnterpriseExtension, EndpointPermission, EndpointOperation, Email, EgressOutcome, EgressChannelOutcome, EffectiveEdge, EcidFormatError, ECID_SCHEME, DevSecretsConfig, DestinationReference, DEFAULT_TENANT_UI_NAMESPACE, DEFAULT_TENANT_API_NAMESPACE, DEFAULT_SECRET_MIME_TYPES, CustomerStoreOptions, CustomerStore, Customer, CreateUserOptions, CreateTenantRequest, CreateGroupOptions, ConfigSubscriptionOptions, ConfigSourceType, ConfigSourceResolver, ConfigSourceErrorInit, ConfigSourceError, ConfigSourceEnv, ConfigSource, ConfigLocator, ConfigErrorKind, ConfigChangeResult, ConfigChangeOptions, ConfigChangeCallback, ConfigApplyStatus, CodeCatalogNamespace, CodeCatalogInput, CodeCatalog, ClientCredentialsWorkloadConfig, ChangeListener, CatalogEntityKind, CatalogChangeListener, CatalogChangeKind, CatalogChange, CapabilityState, CapabilityKey, CapabilityEndpointUrls, CapabilitiezManifest, CachedWorkloadToken, CacheConfig, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCodeInput, CIAMConfigFromCode, CIAMConfig, CIAM, BaseWorkloadIdentity, BaseUser, BaseTenant, BaseCustomer, AzureSecretsConfig, AzureConfigLocator, AzureAuthMethod, AwsSecretsConfig, AwsConfigLocator, AuthzScimGroupType, AuthzScimGroupExtension, AuthzOaaConfig, AuthzEntityBase, AuthzDecision, AuthzConfig, Authz, AuthenticatedUser, AuthenticatedPrincipal, ApplicationValidators, Address, AccessStatus, AccessRef, AccessProvenance, AccessMutationStatus, AccessMutationResult, AccessIndex, AccessCheckTarget, AccessCheckResult, AccessCheckReason, AccessChange, AccessCatalogStore, AccessAssignmentStore };
+export { workloadTokenResponseSchema, workloadResourceSchema, withValidate, warnLogger, waitOn, version, validationFailureResponse, userSchema, unionCatalogRead, trustedClientPermissionsForPrincipal, trimTrailingSlash, tokenResponseSchema, toCodeCatalog, stripJsonComments, stableConfigHash, silentLogger, serializeConfig, remoteConfigSecretType, readyCatalogEntry, parseKmsPoolDocument, parseKmsPoolControlDocument, parseJsonc, parseEcid, oidcCallbackSchema, normalizeTenantRoutingStrategy, normalizeTenantPathNamespace, must, mergeConfig, mergeCodeCatalogEntity, materializeCodeCatalogEntity, matchesListFilter, matchTenantPath, listGenerator, list, jwtAssertionClaimsSchema, isStoreConflictError, isEcid, isConfigSourceError, isConfigLocator, isCodeCatalog, infoLogger, idTokenClaimsSchema, groupResourceSchema, getCodeCatalogEntity, generateULID, formatEcid, deprecateRetiredCodeCatalogRows, defineSecretType, defineCatalog, defaultSecretContentType, defaultLogger, deepEqualPlain, decodeUser, debugLogger, customerResourceSchema, configTrustedClientGrants, claimsToUser, catalogEntityStore, buildTenantPath, assertValidSubjectTypeScoping, assertRequiredSubjectType, assertEcid, accessRootId, accessRefId, X509Certificate, WorkloadValidators, WorkloadTokenStore, WorkloadTokenResponse, WorkloadPrincipal, WorkloadIncomingOutgoing, WorkloadIdentityStore, WorkloadIdentity, WorkloadGetToken, WorkloadConfigMap, WorkloadConfig, WorkloadClient, Workload, WorkforceUser, VaultWorkloadAuthConfig, VaultWebSocketSecretsConfig, VaultWebSocketAuthHeader, VaultSecretsConfig, VaultLfvSecretsConfig, VaultConfigLocator, ValidateResult, UsersInboundHandlerConfig, UserStoreOptions, UserStore, UpdateTenantRequest, TrustedProvisioningClient, TrustedIdp, TokenValidationResult, TokenResponse, TenantWebhookPayload, TenantValidators, TenantStore, TenantStatus, TenantRoutingStrategy, TenantResponse, TenantPathRoutingStrategy, TenantPathNamespace, TenantPathMatch, TenantIonCache, SubscriptionMode, SubjectTypeScoping, SubjectType, SubjectScope, SubjectRef, StoreConflictKind, StoreConflictError, StateCookie, StandardSchemaWithValidate, SessionStore, Session, ServerOnlyWorkloadConfig, SecretsWriteOptions, SecretsValidators, SecretsSubscriptionOptions, SecretsSourceType, SecretsSourceMap, SecretsSourceConfig, SecretsSource, SecretsOperationOptions, SecretsModuleConfig, Secrets, SecretTypeRegistryEntry, SecretTypeInput, SecretTypeDescriptor, SecretRequestSeverity, SecretLifecycleRequest, SecretHandle, SecretFormat, SecretEventName, SecretEventListener, SecretEvent, SecretContentTypeMismatchError, SecretContentType, Secret, ScimWorkload, User as ScimUser, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, Role2 as ScimRole, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimMutationSummary, ScimListResponse, Group2 as ScimGroup, ScimError, ScimCustomer, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfigFromCode, SSOConfig, SSOAppValidators, SSOAppRegistry, SSO, RoutingOptions, RouteModule, RouteFilterResult, Role, ResourceProvider, ResourceChangeListener, ResourceChange, Resource, ResolvedVaultLfvSecretsConfig, ResolvedRoute, RequireReadyResult, RemoteConfigRetryOptions, RemoteConfigRetryHook, RemoteConfigRetryContext, RemoteConfigLoadErrorKind, RemoteConfig, RegisterSSOAppResult, RegisterSSOAppPayload, RegisterSSOAppError, RegisterIAMAppResult, RegisterIAMAppPayload, RegisterIAMAppError, ReconcileReport, ReadyzEndpointConfig, ReadyAccessCatalogEntry, ReadinessReport, ReactiveHandle, PrincipalInboundHandlerConfig, Photo, PhoneNumber, Permission, ParsedEcid, PLATFORM_ASSIGNABLE_SUBJECT_TYPES, OtelSignalName, OtelSignalConfig, OtelProviderType, OtelProtocol, OtelOAuthClientCredentialsConfig, OtelMetricsSignalConfig, OtelLogRecord, OtelLogLevel, OtelLevels, OtelConfig, OtelAttributes, OtelAttributeValue, Otel, OidcCallbackParams, OaaSyncResult, OaaSyncOptions, OaaSyncInput, OaaClient, OaaAccessTargetType, OaaAccessChangeBatchItem, Name, ModuleReadinessState, ModuleReadiness, ModuleName, ModifiableFrameworkConfig, MirrorConfigLocator, MetaData, MagicLinkStore, MagicLink, Logger, ListResult, ListOptions, ListFilter, LfvOtpResponse, LfvOtpRequest, LfvJwks, LfvErrorResponse, LfvErrorCode, LfvEd25519PublicJwk, LfvEd25519PrivateJwk, LfvCallbackTransport, LfvCallbackKind, LfvCallbackHeaders, LfvCallbackEnvelope, LfvActionRequestBase, LfvActionName, LfvActionAcceptedResponse, KmsRevokeKeyResult, KmsRevokeKeyRequest, KmsPoolSlot, KmsPoolListener, KmsPoolIssuer, KmsPoolDocument, KmsPoolControlDocument, KmsPoolConfig, KmsPool, KmsParkResult, KmsParkRequest, KmsParkReport, KmsParkDisposition, KmsKeyState, KmsKey, KmsIssuerEventName, KmsIssuerEventListener, KmsIssuerEvent, KmsIssuedKey, KmsConfig, KmsAllocationStrategy, KmsAllocationPolicy, KmsAddKeysResult, KmsAddKeysRequest, Kms, JwtBearerWorkloadConfig, JWTAssertionClaims, IoniteValidators, IoniteUserExtension, IoniteErrorOptions, IoniteError, IoniteBase, Ionite, InferSecretType, InMemoryTenantStoreOptions, IdentityResolution, IdTokenClaims, IamPrincipalKindFlag, IamPrincipalKind, IamDeltaResourceType, IamDeltaReconcileResult, IamDeltaReconcileInput, IamDeltaMode, IamDeltaEmitter, IamAssignmentPolicy, ION_TENANT_MANAGE, ION_SDK_PERMISSIONS, ION_SCIM_WORKLOAD_SCHEMA, ION_SCIM_USER_EXTENSION_URN, ION_SCIM_CUSTOMER_SCHEMA, ION_IAM_WORKLOADS_WRITE, ION_IAM_USERS_WRITE, ION_IAM_READ, ION_IAM_GROUPS_WRITE, ION_IAM_CUSTOMERS_WRITE, ION_IAM_ACCESS_REQUESTS_WRITE, ION_ENDPOINT_PERMISSIONS, ION_CIAM_MAGIC_LINK_CREATE, ION_CAPABILITIEZ_READ, ION_AUTHZ_OAA_SYNC, ION_AUTHZ_GROUP_SCHEMA, IAMValidators, IAMUsersInbound, IAMPrincipalsInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMEndpointFlag, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfigFromCode, IAMConfig, IAMAppValidators, IAMAppRegistry, IAMAccessRequestsConfig, IAM, GroupsInboundHandlerConfig, GroupResource, GroupMember, Group, GcpSecretsConfig, GcpConfigLocator, FrameworkWorkloadIncomingOutgoing, FrameworkWorkloadConfigFromCode, FrameworkWorkloadConfig, FrameworkStores, FrameworkSecretsSourceConfig, FrameworkSecretsModuleConfig, FrameworkOtelConfig, FrameworkLfvConfig, FrameworkConfigInput, FrameworkConfig, EnvironmentType, EntityStore, EntitlementType, Entitlement, EnterpriseExtension, EndpointPermission, EndpointOperation, Email, EgressOutcome, EgressChannelOutcome, EffectiveEdge, EcidFormatError, ECID_SCHEME, DevSecretsConfig, DestinationReference, DEFAULT_TENANT_UI_NAMESPACE, DEFAULT_TENANT_API_NAMESPACE, DEFAULT_SECRET_MIME_TYPES, CustomerStoreOptions, CustomerStore, Customer, CreateUserOptions, CreateTenantRequest, CreateGroupOptions, ConfigSubscriptionOptions, ConfigSourceType, ConfigSourceResolver, ConfigSourceErrorInit, ConfigSourceError, ConfigSourceEnv, ConfigSource, ConfigLocator, ConfigErrorKind, ConfigChangeResult, ConfigChangeOptions, ConfigChangeCallback, ConfigApplyStatus, CodeCatalogNamespace, CodeCatalogInput, CodeCatalog, ClientCredentialsWorkloadConfig, ChangeListener, CatalogEntityKind, CatalogChangeListener, CatalogChangeKind, CatalogChange, CapabilityState, CapabilityKey, CapabilityEndpointUrls, CapabilitiezManifest, CachedWorkloadToken, CacheConfig, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCodeInput, CIAMConfigFromCode, CIAMConfig, CIAM, BaseWorkloadIdentity, BaseUser, BaseTenant, BaseCustomer, AzureSecretsConfig, AzureConfigLocator, AzureAuthMethod, AwsSecretsConfig, AwsConfigLocator, AuthzScimGroupType, AuthzScimGroupExtension, AuthzOaaConfig, AuthzEntityBase, AuthzDecision, AuthzConfig, Authz, AuthenticatedUser, AuthenticatedPrincipal, AssignmentPolicyError, ApplicationValidators, Address, AccessStatus, AccessRequestSubmit, AccessRequestResult, AccessRequestCreate, AccessRef, AccessProvenance, AccessMutationStatus, AccessMutationResult, AccessIndex, AccessCheckTarget, AccessCheckResult, AccessCheckReason, AccessChange, AccessCatalogStore, AccessAssignmentStore };