@ionite/core 0.0.23 → 0.0.24-beta.20260907.2

package/dist/server.d.ts

@@ -36,6 +36,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 {
@@ -507,85 +513,6 @@ interface Logger {
 }
 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.
-*/
-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[];
-};
-/**
-* 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>;
-	/**
-	* 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>;
-}
-/**
 * SCIM 2.0 User Resource
 * @see https://datatracker.ietf.org/doc/html/rfc7643#section-4.1
 */
@@ -717,7 +644,7 @@ interface Address {
 /**
 * SCIM Group reference (used within User resources)
 */
-interface Group2 {
+interface Group {
 	/**
 	* The identifier of the User's group
 	*/
@@ -753,10 +680,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
@@ -794,10 +721,49 @@ 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
 */
-interface Role2 {
+interface Role {
 	/**
 	* The value of the role
 	*/
@@ -993,7 +959,7 @@ interface User {
 	/**
 	* A list of groups to which the user belongs
 	*/
-	groups?: Group2[];
+	groups?: Group[];
 	/**
 	* A list of entitlements for the User
 	*/
@@ -1006,7 +972,7 @@ interface User {
 	/**
 	* A list of roles for the User
 	*/
-	roles?: Role2[];
+	roles?: Role[];
 	/**
 	* A list of certificates issued to the User
 	*/
@@ -1016,13 +982,310 @@ interface User {
 	*/
 	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"?: EnterpriseExtension;
 	/**
-	* ionite User Extension (ECID + accountClass).
+	* ionite User Extension (ECID + accountClass).
+	*/
+	"urn:ionite:scim:schemas:extension:ion:2.0:User"?: IoniteUserExtension;
+	/**
+	* REQUIRED. The schemas attribute is an array of Strings which allows introspection of the supported schema version
+	*/
+	schemas?: string[];
+}
+/**
+* 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;
+/**
+* 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<Group2> | AsyncIterable<Group2>;
+	roles?: Iterable<Role2> | AsyncIterable<Role2>;
+	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.
 	*/
-	"urn:ionite:scim:schemas:extension:ion:2.0:User"?: IoniteUserExtension;
+	requestAccess(input: AccessRequestCreate): Promise<AccessRequestResult>;
 	/**
-	* REQUIRED. The schemas attribute is an array of Strings which allows introspection of the supported schema version
+	* 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`.
 	*/
-	schemas?: string[];
+	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;
@@ -1103,85 +1366,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:
@@ -1637,6 +1821,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;
@@ -1660,6 +1852,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.
@@ -1676,13 +1881,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
@@ -1690,21 +1910,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;
 };
@@ -1714,6 +1922,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;
@@ -1721,6 +1955,8 @@ type IAMEntitlementRequestUrlContext = {
 type IAMValidators = {
 	user: StandardSchemaV15<unknown, User>;
 	group: StandardSchemaV15<unknown, GroupResource>;
+	workload?: StandardSchemaV15<unknown, ScimWorkload>;
+	customer?: StandardSchemaV15<unknown, ScimCustomer>;
 };
 interface IAMInboundUserContext {
 	/**
@@ -1828,8 +2064,12 @@ interface IAMDiscoveryContext {
 	basePath: string;
 	usersUrl: string;
 	groupsUrl: string;
+	workloadsUrl: string;
+	customersUrl: string;
 	supportsUsers: boolean;
 	supportsGroups: boolean;
+	supportsWorkloads: boolean;
+	supportsCustomers: boolean;
 }
 interface IAMDiscoveryConfig {
 	/**
@@ -1894,6 +2134,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')
@@ -1943,7 +2189,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.
@@ -1968,9 +2220,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. */
@@ -1985,6 +2239,15 @@ type IAM = IAMConfig & {
 	delta?: IamDeltaEmitter;
 };
 /**
+* Enforce subject-type scoping at grant time (fail closed). Rejects a grant whose effective
+* `subjectType` is outside the platform ceiling or outside the target's required
+* `assignableSubjectTypes`. Code ids resolve through the materialized row with code-owned subject
+* scoping. A no-op when no definition source is wired or the target entity is not found (the grant
+* proceeds as before). Shared by SCIM ingress and `ion.authz.grant` so both chokepoints enforce
+* one contract.
+*/
+declare function assertSubjectTypeAssignable(catalogStore: AccessCatalogStore | undefined, codeCatalog: CodeCatalog | undefined, change: AccessChange, cache?: CatalogAdjacencyCache): Promise<void>;
+/**
 * Creates an IAM service instance.
 *
 * - If `url` is configured, enables outbound SCIM operations to external IAM
@@ -2732,100 +2995,6 @@ declare function resolveUser(request: Request, ion: Ionite): Promise<IdentityRes
 declare function initiateLogin(request: Request, ion: Ionite): Promise<Response>;
 declare function callback(request: Request, ion: Ionite): Promise<Response>;
 /**
-* 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;
-/**
-* 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
@@ -3483,9 +3652,9 @@ type AuthzConfig = {
 	* Opt-in transform applied to a group before OAA projection (e.g. computed `custom_properties`,
 	* redaction). Applied identically on incremental push and full sync. Undefined => identity.
 	*/
-	mapGroup?: (group: Group) => Group;
+	mapGroup?: (group: Group2) => Group2;
 	/** Opt-in transform applied to a role before OAA projection. Undefined => identity. */
-	mapRole?: (role: Role) => Role;
+	mapRole?: (role: Role2) => Role2;
 	/** Opt-in transform applied to a resource before OAA projection. Undefined => identity. */
 	mapResource?: (resource: Resource) => Resource;
 	/**
@@ -4167,12 +4336,12 @@ type BaseUser<TExtended = object> = BaseUserFields & {
 	* Optional SCIM roles.
 	* Commonly set by IAM inbound SCIM provisioning flows.
 	*/
-	roles?: Role2[];
+	roles?: Role[];
 	/**
 	* Optional SCIM groups.
 	* Commonly set by IAM inbound SCIM provisioning flows.
 	*/
-	groups?: Group2[];
+	groups?: Group[];
 	/**
 	* Optional SCIM entitlements.
 	* Commonly set by IAM inbound SCIM provisioning flows.
@@ -4307,19 +4476,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[];
 };
@@ -4336,7 +4505,7 @@ type Permission = AuthzEntityBase & SubjectTypeScoping & {
 	/** When true, the permission also applies to a resource's sub-resources (maps to OAA `apply_to_sub_resources`). */
 	applyToSubResources?: boolean;
 };
-type Role = AuthzEntityBase & SubjectTypeScoping & {
+type Role2 = AuthzEntityBase & SubjectTypeScoping & {
 	/** True when this catalog entry should be exposed as requestable access in IAM tooling. */
 	requestable?: boolean;
 	/** IAM-owned deep link where a principal can request this entitlement, when the destination provides one. */
@@ -4344,15 +4513,15 @@ type Role = AuthzEntityBase & SubjectTypeScoping & {
 	/** Permissions this role confers (definitional). Roles are flat bundles — OAA has no nested-role edge. */
 	permissions?: Array<string | Permission>;
 };
-type Group = AuthzEntityBase & SubjectTypeScoping & {
+type Group2 = AuthzEntityBase & SubjectTypeScoping & {
 	/** True when this catalog entry should be exposed as requestable access in IAM tooling. */
 	requestable?: boolean;
 	/** IAM-owned deep link where a principal can request this entitlement, when the destination provides one. */
 	requestUrl?: string;
 	/** Nested child groups composed into this group (definitional). */
-	groups?: Array<string | Group>;
+	groups?: Array<string | Group2>;
 	/** Roles this group confers (group is the principal). Projected as OAA `local_group` role assignments. */
-	roles?: Array<string | Role>;
+	roles?: Array<string | Role2>;
 	/** Permissions this group confers (group is the principal). Projected as OAA `local_group` application permissions. */
 	permissions?: Array<string | Permission>;
 	/**
@@ -4375,7 +4544,7 @@ type OaaAccessTargetType = "group" | "role" | "permission";
 */
 type EntitlementType = OaaAccessTargetType;
 /** A catalog Entitlement: a group, role, or permission (see {@link EntitlementType}). */
-type Entitlement = Group | Role | Permission;
+type Entitlement = Group2 | Role2 | Permission;
 type AccessRef<T> = string | T;
 /**
 * A catalog entry returned synchronously by {@link EntityStore.set}. It is the entity itself,
@@ -4422,18 +4591,18 @@ type CatalogChangeKind = OaaAccessTargetType;
 type CatalogChange = {
 	op: "set";
 	kind: CatalogChangeKind;
-	entity: Group | Role | Permission;
-	previous: Group | Role | Permission | undefined;
+	entity: Group2 | Role2 | Permission;
+	previous: Group2 | Role2 | Permission | undefined;
 } | {
 	op: "delete";
 	kind: CatalogChangeKind;
-	entity: Group | Role | Permission;
+	entity: Group2 | Role2 | Permission;
 };
 /** Listener invoked with a {@link CatalogChange} after a durable catalog write lands. */
 type CatalogChangeListener = (change: CatalogChange) => void;
 type AccessCatalogStore = {
-	groups: EntityStore<Group>;
-	roles: EntityStore<Role>;
+	groups: EntityStore<Group2>;
+	roles: EntityStore<Role2>;
 	permissions: EntityStore<Permission>;
 	/**
 	* Reactive change subscription (the catalog analog of {@link ReactiveHandle}). When implemented,
@@ -4524,8 +4693,8 @@ type SubjectScope = SubjectType | SubjectType[] | "any";
 */
 type AccessChange<
 	TUser = BaseUser,
-	TGroup = Group,
-	TRole = Role,
+	TGroup = Group2,
+	TRole = Role2,
 	TPermission = Permission
 > = {
 	/** Deterministic id derived from `subjectType:subject:targetType:target[:scope]`; assigned by stores/orchestration. */
@@ -4592,7 +4761,7 @@ type SubjectRef = {
 	subjectType: SubjectType;
 };
 /** A single check target, optionally scoped to a resource. */
-type AccessCheckTarget<TTarget = Group | Role | Permission> = {
+type AccessCheckTarget<TTarget = Group2 | Role2 | Permission> = {
 	targetType: OaaAccessTargetType;
 	target: AccessRef<TTarget>;
 	resource?: AccessRef<Resource>;
@@ -4621,9 +4790,9 @@ type EffectiveEdge = {
 * Revoking one role removes only its rows — overlapping permissions from the other role remain.
 */
 interface AccessIndex {
-	has(subject: AccessRef<BaseUser>, targetType: OaaAccessTargetType, target: AccessRef<Group | Role | Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
-	hasGroup(subject: AccessRef<BaseUser>, group: AccessRef<Group>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
-	hasRole(subject: AccessRef<BaseUser>, role: AccessRef<Role>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	has(subject: AccessRef<BaseUser>, targetType: OaaAccessTargetType, target: AccessRef<Group2 | Role2 | Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	hasGroup(subject: AccessRef<BaseUser>, group: AccessRef<Group2>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	hasRole(subject: AccessRef<BaseUser>, role: AccessRef<Role2>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
 	hasPermission(subject: AccessRef<BaseUser>, permission: AccessRef<Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
 	hasAny(subject: AccessRef<BaseUser>, targets: AccessCheckTarget[], subjectType: SubjectType): Promise<AuthzDecision>;
 	hasAll(subject: AccessRef<BaseUser>, targets: AccessCheckTarget[], subjectType: SubjectType): Promise<AuthzDecision>;
@@ -4682,8 +4851,8 @@ type OaaSyncInput<
 	TResource
 > = {
 	users?: Iterable<TUser> | AsyncIterable<TUser>;
-	groups?: Iterable<TGroup | Group> | AsyncIterable<TGroup | Group>;
-	roles?: Iterable<Role> | AsyncIterable<Role>;
+	groups?: Iterable<TGroup | Group2> | AsyncIterable<TGroup | Group2>;
+	roles?: Iterable<Role2> | AsyncIterable<Role2>;
 	permissions?: Iterable<Permission> | AsyncIterable<Permission>;
 	resources?: Iterable<TResource> | AsyncIterable<TResource>;
 	access?: Iterable<AccessChange> | AsyncIterable<AccessChange>;
@@ -4695,13 +4864,13 @@ type OaaAccessChangeBatchItem = {
 };
 interface OaaClient<
 	TUser = BaseUser,
-	TGroup = Group,
-	TRole = Role,
+	TGroup = Group2,
+	TRole = Role2,
 	TPermission = Permission,
 	TResource = Resource
 > {
 	pushUser(user: TUser): Promise<void>;
-	pushGroup(group: TGroup | Group): Promise<void>;
+	pushGroup(group: TGroup | Group2): Promise<void>;
 	pushRole(role: TRole): Promise<void>;
 	pushPermission(permission: TPermission): Promise<void>;
 	pushResource(resource: TResource): Promise<void>;
@@ -4816,9 +4985,9 @@ type Authz = {
 	};
 	/** The wired closure index powering `has*`, when the app provided one via stores. */
 	accessIndex?: AccessIndex;
-	has(subject: AccessRef<BaseUser>, targetType: OaaAccessTargetType, target: AccessRef<Group | Role | Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
-	hasGroup(subject: AccessRef<BaseUser>, group: AccessRef<Group>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
-	hasRole(subject: AccessRef<BaseUser>, role: AccessRef<Role>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	has(subject: AccessRef<BaseUser>, targetType: OaaAccessTargetType, target: AccessRef<Group2 | Role2 | Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	hasGroup(subject: AccessRef<BaseUser>, group: AccessRef<Group2>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
+	hasRole(subject: AccessRef<BaseUser>, role: AccessRef<Role2>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
 	hasPermission(subject: AccessRef<BaseUser>, permission: AccessRef<Permission>, resource: AccessRef<Resource> | undefined, subjectType: SubjectType): Promise<AuthzDecision>;
 	hasAny(subject: AccessRef<BaseUser>, targets: AccessCheckTarget[], subjectType: SubjectType): Promise<AuthzDecision>;
 	hasAll(subject: AccessRef<BaseUser>, targets: AccessCheckTarget[], subjectType: SubjectType): Promise<AuthzDecision>;
@@ -4849,7 +5018,42 @@ 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";
 /** Why an {@link AccessCheckResult} resolved the way it did. */
 type AccessCheckReason = "ok" | "unauthenticated" | "forbidden" | "not_configured";
 /**
@@ -4887,14 +5091,14 @@ type CodeCatalogNamespace<TEntity> = {
 * deep-frozen and id-indexed.
 */
 type CodeCatalog = {
-	groups: CodeCatalogNamespace<Group>;
-	roles: CodeCatalogNamespace<Role>;
+	groups: CodeCatalogNamespace<Group2>;
+	roles: CodeCatalogNamespace<Role2>;
 	permissions: CodeCatalogNamespace<Permission>;
 };
 /** Declarative input for {@link defineCatalog} (plain arrays authored in app code). */
 type CodeCatalogInput = {
-	groups?: readonly Group[];
-	roles?: readonly Role[];
+	groups?: readonly Group2[];
+	roles?: readonly Role2[];
 	permissions?: readonly Permission[];
 };
 /**
@@ -4936,7 +5140,7 @@ declare class CatalogAdjacencyCache {
 	private readonly subResources;
 	private readonly children;
 	constructor(catalog: AccessCatalogStore | undefined, resources?: ResourceProvider | undefined, code?: CodeCatalog | undefined);
-	getNode(kind: "group" | "role" | "permission" | "resource", id: string): Promise<Group | Role | Permission | Resource | undefined>;
+	getNode(kind: "group" | "role" | "permission" | "resource", id: string): Promise<Group2 | Role2 | Permission | Resource | undefined>;
 	/** Memoized direct children of a resource (provider `children()`, else `Resource.resources` refs). */
 	resourceChildren(id: string): Promise<Resource[]>;
 	resourceAndSubResourceIds(resourceId: string): Promise<string[]>;
@@ -4993,8 +5197,8 @@ declare function reconcileSubjectAccess(subject: string, subjectType: SubjectTyp
 * the downstream projection never carries a dangling reference.
 */
 type ReferencedDefinitions = {
-	groups: Group[];
-	roles: Role[];
+	groups: Group2[];
+	roles: Role2[];
 	permissions: Permission[];
 	resources: Resource[];
 };
@@ -5006,7 +5210,7 @@ type ReferencedDefinitions = {
 * inline object references are used directly. Unresolvable string ids are skipped (a later full sync
 * reconciles). Cycle-safe via a per-call visited set.
 */
-declare function collectReferencedDefinitions(root: Group | Role, rootKind: "group" | "role", view: CatalogView): Promise<ReferencedDefinitions>;
+declare function collectReferencedDefinitions(root: Group2 | Role2, rootKind: "group" | "role", view: CatalogView): Promise<ReferencedDefinitions>;
 /**
 * Request-level entitlement check helper (the value-returning "helper mode" layer). Resolves the
 * authenticated principal(s) from `request` per `subjectType` (default `'any'`: resolve every
@@ -5017,13 +5221,13 @@ declare function collectReferencedDefinitions(root: Group | Role, rootKind: "gro
 * Pure APIs/SPAs: `if (!result.allow) return result.response();`. SSR/RPC apps should ignore
 * `response()` and branch on `result.allow`/`result.reason` from their own `require*` helpers.
 */
-declare function has(request: Request, ion: Ionite, targetType: OaaAccessTargetType, target: AccessRef<Group | Role | Permission>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
+declare function has(request: Request, ion: Ionite, targetType: OaaAccessTargetType, target: AccessRef<Group2 | Role2 | Permission>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
 /** Request-level check that a resolved principal holds a permission. See {@link has}. */
 declare function hasPermission2(request: Request, ion: Ionite, permission: AccessRef<Permission>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
 /** Request-level check that a resolved principal holds a role. See {@link has}. */
-declare function hasRole2(request: Request, ion: Ionite, role: AccessRef<Role>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
+declare function hasRole2(request: Request, ion: Ionite, role: AccessRef<Role2>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
 /** Request-level check that a resolved principal is a member of a group. See {@link has}. */
-declare function hasGroup2(request: Request, ion: Ionite, group: AccessRef<Group>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
+declare function hasGroup2(request: Request, ion: Ionite, group: AccessRef<Group2>, resource?: AccessRef<Resource>, subjectType?: SubjectScope): Promise<AccessCheckResult>;
 /** Request-level check that a resolved principal holds ANY of the given targets. See {@link has}. */
 declare function hasAny2(request: Request, ion: Ionite, targets: AccessCheckTarget[], subjectType?: SubjectScope): Promise<AccessCheckResult>;
 /** Request-level check that a resolved principal holds ALL of the given targets. See {@link has}. */
@@ -5320,6 +5524,10 @@ declare function generateAppleClientSecret(options: AppleClientSecretOptions): P
 declare function entitlementToScimGroup(entity: Entitlement, type: EntitlementType, members?: GroupMember[]): GroupResource;
 /** Project a stored user through the default full SCIM User shape used by IAM aggregation. */
 declare function baseUserToScimUser(storedUser: BaseUser): User;
+/** Project a stored workload through the native SCIM Workload shape. */
+declare function baseWorkloadToScim(stored: BaseWorkloadIdentity): ScimWorkload;
+/** Project a stored customer through the native SCIM Customer shape. */
+declare function baseCustomerToScim(stored: BaseCustomer): ScimCustomer;
 type SessionResponse = {
 	sid: string;
 	authType: "sso" | "ciam";
@@ -5364,4 +5572,4 @@ type VerifyUserOptions = {
 *   does not match, or the token is expired.
 */
 declare function verifyUser(jwt: string, options: VerifyUserOptions): Promise<WorkforceUser>;
-export { withSetCookies, verifyUser, verifyLogoutToken, verifyLfvSignature, verifyIdToken, stringifyLfvJwks, sso, signLfvPayload, setJwksRetry, setJwksClock, setDiscoveryClock, sendTenantWebhook, sameOriginRedirectRules, resolveUser, resolveSessionCacheConfig, resolveRedirect, resolveProviderBranding, resolveJwksCacheConfig, resolveJwkForKid, resolveCustomer, resolveCiamProvider, resolveCapturedRedirect, resolveCacheConfig, resolveAfterRedirect, reconcileSubjectAccess, pkceChallengeFromVerifier, parseLfvJwks, orderedEnabledProviders, normalizeOidcIssuer, listSsoClientIdsFromCookies, isRedirectAllowed, initiateLogin, iam, hasScope, hasRole2 as hasRole, hasPermission2 as hasPermission, hasGroup2 as hasGroup, hasAnyScope, hasAny2 as hasAny, hasAllScope, hasAll2 as hasAll, has, getVerificationKeyForKid, getUser, getPublicKeyFromJwks, getPublicKeyForKid, getProviderPreset, getJwks, getDiscoveredSessionUsers, getCustomer, getCachedVerificationKey, generateLfvEd25519KeyPair, generateAppleClientSecret, fetchUserInfo, expandRoot, exchangeAuthorizationCode, entitlementToScimGroup, discoverSessions, discoverSessionRecords, discoverOidcEndpoints, defaultRedirectPolicies, configureJwksCache, collectReferencedDefinitions, clearJwksCache, clearDiscoveryCache, ciam, captureRedirect, callback, buildLfvSigningInput, buildAuthorizationUrl, blockDangerousUrls, baseUserToScimUser, assertTrustedIdTokenClaims, allowSameOrigin, allowRelativePaths, allowOrigins, allowHosts, VerifyUserOptions, VerifyLogoutTokenOptions, VerifyIdTokenOptions, UsersInboundHandlerConfig, StateCookie, SessionResponse, SessionDiscoveryOptions, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimListResponse, ScimError, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfig, SSO, ResolvedSessionReadCacheConfig, ResolvedSessionCacheConfig, ResolvedJwksCacheConfig, ResolvedCacheConfig, ReferencedDefinitions, RedirectVerdict, RedirectRuleContext, RedirectRule, RedirectResult, RedirectPolicy, RedirectContext, ReconcileStores, JWKS, InMemoryTenantStore, IAMValidators, IAMUsersInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfig, IAM, GroupsInboundHandlerConfig, CreateUserOptions, CreateGroupOptions, CatalogView, CatalogAdjacencyCache, CIAM_PROVIDER_PRESETS, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCode, CIAMConfig, CIAM, CACHE_BOUNDS, BeforeLogoutHook, BeforeLogoutContext, BeforeLoginHook, BeforeLoginContext, AssertTrustedIdTokenClaimsOptions, AfterLogoutHook, AfterLogoutContext, AfterLoginHook, AfterLoginContext };
+export { withSetCookies, verifyUser, verifyLogoutToken, verifyLfvSignature, verifyIdToken, stringifyLfvJwks, sso, signLfvPayload, setJwksRetry, setJwksClock, setDiscoveryClock, sendTenantWebhook, sameOriginRedirectRules, resolveUser, resolveSessionCacheConfig, resolveRedirect, resolveProviderBranding, resolveJwksCacheConfig, resolveJwkForKid, resolveCustomer, resolveCiamProvider, resolveCapturedRedirect, resolveCacheConfig, resolveAfterRedirect, reconcileSubjectAccess, pkceChallengeFromVerifier, parseLfvJwks, orderedEnabledProviders, normalizeOidcIssuer, listSsoClientIdsFromCookies, isRedirectAllowed, initiateLogin, iam, hasScope, hasRole2 as hasRole, hasPermission2 as hasPermission, hasGroup2 as hasGroup, hasAnyScope, hasAny2 as hasAny, hasAllScope, hasAll2 as hasAll, has, getVerificationKeyForKid, getUser, getPublicKeyFromJwks, getPublicKeyForKid, getProviderPreset, getJwks, getDiscoveredSessionUsers, getCustomer, getCachedVerificationKey, generateLfvEd25519KeyPair, generateAppleClientSecret, fetchUserInfo, expandRoot, exchangeAuthorizationCode, entitlementToScimGroup, discoverSessions, discoverSessionRecords, discoverOidcEndpoints, defaultRedirectPolicies, configureJwksCache, collectReferencedDefinitions, clearJwksCache, clearDiscoveryCache, ciam, captureRedirect, callback, buildLfvSigningInput, buildAuthorizationUrl, blockDangerousUrls, baseWorkloadToScim, baseUserToScimUser, baseCustomerToScim, assertTrustedIdTokenClaims, assertSubjectTypeAssignable, allowSameOrigin, allowRelativePaths, allowOrigins, allowHosts, VerifyUserOptions, VerifyLogoutTokenOptions, VerifyIdTokenOptions, UsersInboundHandlerConfig, StateCookie, SessionResponse, SessionDiscoveryOptions, ScimServiceProviderConfig, ScimSchemaDefinition, ScimSchemaAttributeDefinition, ScimResult, ScimResourceTypeSchemaExtension, ScimResourceType, ScimListResponse, ScimError, ScimAuthenticationScheme, SSOValidators, SSOHandlerConfig, SSOConfig, SSO, ResolvedSessionReadCacheConfig, ResolvedSessionCacheConfig, ResolvedJwksCacheConfig, ResolvedCacheConfig, ReferencedDefinitions, RedirectVerdict, RedirectRuleContext, RedirectRule, RedirectResult, RedirectPolicy, RedirectContext, ReconcileStores, JWKS, InMemoryTenantStore, IAMValidators, IAMUsersInbound, IAMInboundUsersConfig, IAMInboundUserContext, IAMHandlerConfig, IAMGroupsOutbound, IAMGroupsInbound, IAMDiscoveryHandlerConfig, IAMDiscoveryContext, IAMDiscoveryConfig, IAMConfig, IAMAccessRequestsConfig, IAM, GroupsInboundHandlerConfig, CreateUserOptions, CreateGroupOptions, CatalogView, CatalogAdjacencyCache, CIAM_PROVIDER_PRESETS, CIAMValidators, CIAMProviderType, CIAMProviderDescriptor, CIAMProviderConfig, CIAMProviderColors, CIAMProviderBranding, CIAMConfigFromCode, CIAMConfig, CIAM, CACHE_BOUNDS, BeforeLogoutHook, BeforeLogoutContext, BeforeLoginHook, BeforeLoginContext, AssertTrustedIdTokenClaimsOptions, AfterLogoutHook, AfterLogoutContext, AfterLoginHook, AfterLoginContext, AccessRequestSubmit, AccessRequestResult, AccessRequestCreate };