@flowdular/sdk 0.2.4 → 0.3.1

package/modules/users/spec/module.yaml

@@ -1,6 +1,6 @@
-schemaVersion: 1
+schemaVersion: 2
 id: users.core
-specVersion: 0.6.0
+specVersion: 0.9.8
 status: approved
 name: User Management Core
 description: Provides the tenant-scoped user directory and member administration (creation, display name, role assignment, per-member scopes, account status, password reset, session revocation, removal) through the public auth administration port.
@@ -11,23 +11,40 @@ capabilities:
   - translations
 dependencies:
   - id: system.core
-    range: 0.5.0
+    range: ^0.7.0
   - id: auth.core
-    range: 0.10.0
+    range: ^0.13.0
+  - id: search.core
+    range: ^0.1.0
+  - id: import.core
+    range: ^0.1.0
+  - id: exports.core
+    range: ^0.2.0
+requires:
+  - id: search.providers.v1
+    optional: true
+  - id: import.ports.v1
+    optional: true
+  - id: exports.lists.v1
+    optional: true
 tenancy: required
 locales:
   - en
   - pl
 invariants:
+  - Member status is per workspace. Disabling a member through users.core disables only that membership through the auth administration port, revoking its sessions and API tokens in this workspace and leaving the person's other workspaces and the global account status untouched; re-enabling restores sign-in without restoring revoked tokens.
   - Every directory query and mutation is restricted to the authenticated tenant.
   - Password hashes, session tokens, and CSRF tokens are never returned by user administration APIs.
   - Roles are selected from the platform role catalog and determine server-side scope grants.
   - The module contributes separate user-directory and role-catalog screens through its client contribution without editing the application shell.
   - A tenant must retain at least one active owner.
-  - Account creation requires an explicit initial password and never logs it.
+  - Account creation through the user administration API requires an explicit initial password and never logs it; a member created by the members import target receives no credential at all instead, through the auth administration port's credential-less entry point, so that member holds no password until an administrator sets a temporary one or the member completes the public reset flow, and nothing was ever drawn that could be guessed or leaked.
   - Only an owner may create or promote an owner, change another owner, or hand out scopes it does not hold itself.
   - Disabling, removing, or demoting a member never leaves the tenant without an active owner, and never targets the acting principal.
   - Every member administration write is recorded in the auth audit trail with the acting principal.
+  - The member search provider registered with search.providers.v1 reads members only through the auth administration port, under the tenant of the searching principal and behind users.members.read; it holds no index and no copy of a membership. The predicate and the bound are pushed into the port, which answers at most the documented number of members whose display name or whose normalised address starts with the term. Because that rule is a prefix, the provider pushes the terms of the query in the order they were typed, one read each, stops at the first term that answers rows and makes at most three reads for one query, so a request never reads a workspace of unknown size and the same set is found whichever order the terms were typed in; every term and the ranking are then applied to the rows that came back, and a member no term of the first three opens is not found.
+  - The members import target registered with import.ports.v1 as users.core.members accepts email (required), displayName (required) and role (optional, a role key of the workspace, defaulting to member), keys rows by the address folded the way auth.core stores one, trimmed, NFKC normalised and lower cased, so import.core refuses a repeat spelled in another case wherever in the file it stands, resolves that natural key per batch by asking the auth administration port about the addresses the batch names rather than by listing the workspace, and is behind users.members.manage; create-only creates an absent member and refuses an existing one with ALREADY_EXISTS, update-existing creates an absent member and applies the display name and then the role of an existing one, so the write that can only be refused for its own shape lands first and a role auth.core refuses afterwards leaves the row updated with the reason ROLE_UNCHANGED:<code> rather than denying a change that already happened, skip-existing leaves an existing member untouched; every write goes through the auth administration port with the principal that started the job, a refused row never fails another row, and a deployment without import.core still composes users.core.
+  - The members list export registered with exports.lists.v1 as users.core.members declares the e-mail, display name, role, workspace status and joined-at columns, is behind users.members.read, and is walked by exports.core under the principal that started the job through the auth administration port, so a file can never carry a member of another workspace or a column the Members screen would not have shown. The walk is the administration port's own paged member listing, one bounded page per call, so an export of M members reads M rows rather than one roll per page. Its keyset is the account id and not the display name the unpaged roll is ordered by, so a member renamed while a long walk runs cannot cross a page boundary and be written twice or skipped, and a member removed mid-walk does not strand the cursor. The Members screen starts a job through exports.core's own start route and links to the Exports screen, and a deployment without exports.core still composes users.core and registers nothing.
 permissions:
   - id: users.members.read
     description: Read memberships in the active tenant.
@@ -36,11 +53,261 @@ permissions:
 dataOwnership:
   - auth.core owns accounts, memberships, roles, scopes, credentials, and sessions.
   - users.core owns the administration use cases and UI but writes only through the public auth administration port.
+entities:
+  - id: member
+    name: Workspace member
+    description: One membership of the active workspace as the auth administration port answers it; auth.core owns the row and users.core reads and writes it only through the port, never through a table of its own.
+    fields:
+      - id: accountId
+        type: string
+        required: true
+        maxLength: 128
+        description: The auth.core account id; the record reference every member action names.
+      - id: email
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 254
+        description: Shown read-only; auth.core owns the address and folds it for uniqueness.
+      - id: displayName
+        type: string
+        required: true
+        maxLength: 80
+      - id: role
+        type: string
+        required: true
+        maxLength: 32
+        description: A role key of the workspace, selected from the role catalog the context read answers.
+      - id: membershipStatus
+        type: enum
+        required: true
+        values:
+          - active
+          - disabled
+        description: This workspace's own status for the member; the single membership status path changes it.
+      - id: status
+        type: enum
+        required: true
+        values:
+          - active
+          - disabled
+        description: The account's platform-level status; shown read-only, changed by the deployment operator outside this module's screens.
+      - id: scopes
+        type: json
+        required: true
+        description: Array of scope identifiers granted to this membership; the list shows the count and the drawer edits the set.
+      - id: passwordChangeRequired
+        type: boolean
+        required: true
+        description: True after an administrator set a temporary password and until the member chose a new one.
+    states:
+      field: membershipStatus
+      values:
+        - active
+        - disabled
+      transitions:
+        - from: active
+          to: disabled
+          permission: users.members.manage
+        - from: disabled
+          to: active
+          permission: users.members.manage
+  - id: role
+    name: Workspace role
+    description: One role of the platform role catalog as auth.core's role routes answer it; users.core contributes the screen and owns nothing of the role.
+    fields:
+      - id: key
+        type: string
+        required: true
+        unique: tenant
+        maxLength: 32
+      - id: name
+        type: string
+        required: true
+        maxLength: 80
+      - id: scopes
+        type: json
+        required: true
+        description: Array of the effective permission scopes the role grants.
+      - id: builtin
+        type: boolean
+        required: true
+        description: True for Owner and Member, which are immutable.
+screens:
+  - id: members
+    kind: list
+    entity: member
+    title: Members
+    columns:
+      - displayName
+      - email
+      - role
+      - membershipStatus
+      - status
+      - passwordChangeRequired
+      - scopes
+    filters:
+      - displayName
+      - email
+      - membershipStatus
+    navigationGroup: Administration
+  - id: member
+    kind: record
+    entity: member
+    title: Member
+    columns:
+      - displayName
+      - email
+      - role
+      - scopes
+      - membershipStatus
+      - status
+    navigationGroup: Administration
+  - id: new-member
+    kind: form
+    entity: member
+    title: New account
+    columns:
+      - email
+      - displayName
+      - role
+    navigationGroup: Administration
+  - id: invite-member
+    kind: form
+    title: Invite member
+    navigationGroup: Administration
+  - id: roles
+    kind: list
+    entity: role
+    title: Roles
+    columns:
+      - key
+      - name
+      - scopes
+      - builtin
+    navigationGroup: Administration
+actions:
+  - id: list-members
+    entity: member
+    permission: users.members.read
+    kind: custom
+    risk: read
+    idempotent: true
+    description: Answer one page of the active workspace's members, sorted by display name or e-mail in either direction, narrowed by a name or address prefix and by membership status, cut by a signed keyset cursor bound to the workspace, the sort, the direction and the filters, with a page limit of at most 200.
+  - id: read-context
+    entity: member
+    permission: users.members.read
+    kind: custom
+    risk: read
+    idempotent: true
+    description: Answer what the Members screen needs beside the page, namely the workspace roles, the grantable scopes, the acting principal's account id and role, the shared password minimum length and the member count.
+  - id: create-member
+    entity: member
+    permission: users.members.manage
+    kind: create
+    risk: workspace-write
+    idempotent: false
+    description: Create the account and the tenant membership atomically with the role scope template from an e-mail, a display name, a role key and an explicit initial password that is never logged.
+  - id: rename-member
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Change the display name of one member through the auth administration port.
+  - id: assign-role
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Assign a role key of the workspace to one member through the single role assignment path; an owner or the owner role touched by a non-owner is refused.
+  - id: set-status
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Set the account-level status of one member to active or disabled through the auth administration port; no workspace screen calls it, since the account block reaches every workspace the account belongs to.
+  - id: set-status-many
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Deactivate selected, one of the two bulk actions the Members screen offers behind users.members.manage, taking between 1 and 100 unique account ids the screen selected on the page and never the acting principal; the server applies the status one id at a time through the single membership status path of the auth administration port, so every row keeps its own audit event and its own refusal (the acting principal, the last owner, an owner touched by a non-owner), a missing or another workspace's id is answered not-found, and the response carries one outcome per id in the order sent (updated, not-found or refused with its code) rather than failing the call.
+  - id: assign-role-many
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Assign role, the second bulk action the Members screen offers behind users.members.manage, taking between 1 and 100 unique account ids the screen selected on the page and never the acting principal; the server applies the role one id at a time through the single role assignment path of the auth administration port, so every row keeps its own audit event and its own refusal (the acting principal, the last owner, an owner or the owner role touched by a non-owner), a missing or another workspace's id is answered not-found, and the response carries one outcome per id in the order sent (updated, not-found or refused with its code) rather than failing the call.
+  - id: remove-member
+    entity: member
+    permission: users.members.manage
+    kind: delete
+    risk: destructive
+    idempotent: true
+    description: Remove one membership from the workspace through the auth administration port; never the acting principal or the last active owner.
+  - id: reset-password
+    entity: member
+    permission: users.members.manage
+    kind: custom
+    risk: workspace-write
+    idempotent: false
+    description: Set a temporary password for one member; every earlier session is gone and the member must choose a new password before using the workspace.
+  - id: set-scopes
+    entity: member
+    permission: users.members.manage
+    kind: update
+    risk: workspace-write
+    idempotent: true
+    description: Replace the scopes of one membership with at most 256 scope identifiers; a non-owner cannot grant a scope it does not hold.
+widgets:
+  - id: access
+    slot: dashboard.metrics
+    entity: member
+    description: The member count of the workspace from the context read with a link to the Users screen; behind users.members.read.
+  - id: setup
+    slot: dashboard.main
+    entity: member
+    description: A setup step that links to the Users screen; behind users.members.manage.
+settings: []
+agentTools: []
+outOfScope:
+  - The account-level block is not offered by the Members screen; the drawer shows the account status read-only and workspace access changes through the membership status route.
+  - Role creation, editing and deletion happen through auth.core's role routes behind auth.roles.manage; users.core contributes the Roles screen only.
+decisions:
+  - id: D-USERS-ENTITIES
+    question: Does users.core own a table for the member or the role entity?
+    answer: No. Both entities describe records auth.core owns and answers through its public administration port and role routes; the module declares no database capability and no migration.
+    decidedBy: default
+  - id: D-USERS-BULK-ACTIONS
+    question: How are the two bulk actions of the Members screen declared?
+    answer: As the actions set-status-many and assign-role-many, each behind users.members.manage and each applied one id at a time through the single-row path, with the USERS-STATUS-MANY and USERS-ROLE-MANY scenarios as their evidence.
+    decidedBy: default
+  - id: D-USERS-JOINED-AT
+    question: Why does the member entity not declare the joined-at instant the export carries?
+    answer: The instant is auth.core's createdAt column, and createdAt is a field id every tenant table owns, so the specification cannot declare it; the export list still carries it as documented in the invariants.
+    decidedBy: default
 acceptanceScenarios:
   - id: USERS-LIST
     given: An authenticated principal has users.members.read in an active tenant.
     when: The principal requests the user directory.
-    then: Only memberships from the active tenant are returned without credential or session material.
+    then: Only memberships from the active tenant are returned without credential or session material, one page at a time, and the roles, grantable scopes, acting principal and member count the screen needs come from the separate context read.
+  - id: USERS-PAGE
+    given: A workspace holding more members than one page carries, and another workspace with members of its own.
+    when: A screen lists the members with a page limit of at most 200, follows the cursor it receives to the end sorted by display name or by e-mail in either direction, narrows by a name or address prefix and by membership status, and presents a cursor this server did not sign, one of the other workspace, or one issued for another sort or filter.
+    then: Every member of the workspace is answered exactly once across the pages in the order asked, the cursor is answered only on a full page and is opaque and bound to the workspace, the sort, the direction and the filters, the prefix and the status are applied by the query rather than by the screen, an unknown sort key or direction is refused, and every mismatched or forged cursor is refused with CURSOR_INVALID.
+  - id: USERS-STATUS-MANY
+    given: A principal holding users.members.manage selects several members on the Members screen, and the request also names an id that does not exist, an id of another workspace and the acting principal's own id.
+    when: The principal deactivates them in one call naming the selected ids.
+    then: A list of no ids, of more than 100, or one repeating an id is refused with INVALID_INPUT before any membership is touched; otherwise each named member of the workspace is disabled through the single membership status path with its own audit event, the missing and the foreign id are answered not-found, the acting principal is answered refused with SELF_TARGET, an owner named by a non-owner is refused with OWNER_REQUIRED and the last active owner with LAST_OWNER, every other id is updated, the response carries one outcome per id in the order sent, and a call without the permission or the CSRF proof is refused first.
+  - id: USERS-ROLE-MANY
+    given: A principal holding users.members.manage selects several members and picks a role of the workspace.
+    when: The principal assigns the role in one call naming the selected ids.
+    then: The same bounds and refusals apply as for the bulk status change, each member of the workspace receives the role through the single assignment path with its own audit event, a non-owner naming an owner or the owner role is refused per id with OWNER_REQUIRED, and the screen reloads the listing and reports the updated, missing and refused counts.
   - id: USERS-CREATE
     given: An authenticated principal has users.members.manage and supplies valid account details and a supported role.
     when: The principal creates a tenant member.
@@ -55,7 +322,7 @@ acceptanceScenarios:
     then: Users and Roles appear as separate Administration navigation entries backed by views from the same module contribution.
   - id: USERS-EDIT
     given: A principal with users.members.manage selects a member of the active tenant.
-    when: The principal changes the display name, assigns a role from the tenant role list, replaces the member's scopes, disables or re-enables the account, sets a temporary password, signs the member out everywhere, or removes the member.
+    when: The principal changes the display name, assigns a role from the tenant role list, replaces the member's scopes, disables or re-enables the membership in this workspace, sets a temporary password, signs the member out everywhere, or removes the member; the account-level block stays a deployment operator action outside this screen and is shown read-only.
     then: The change is applied through auth.core, the member row reflects it, and an audit event names the acting principal.
   - id: USERS-OWNER-CAP
     given: A principal with users.members.manage that is not an owner.
@@ -77,3 +344,19 @@ acceptanceScenarios:
     given: A principal with users.members.manage and a configured auth mail adapter.
     when: The principal sends an invitation to an email address with an assignable workspace role.
     then: Auth core delivers a single-use invitation without creating a membership before acceptance, and the Users screen reports delivery without exposing the token.
+  - id: USERS-MEMBERSHIP-STATUS
+    given: A member with sessions and API tokens in this workspace and an active membership in another workspace.
+    when: A principal with users.members.manage disables the member from the member drawer and later re-enables them.
+    then: This workspace's sessions and tokens are revoked and its sign-in refused while the other workspace keeps working, the drawer shows the membership status with its reason copy in both locales, and re-enabling restores sign-in without restoring revoked tokens.
+  - id: USERS-IMPORT
+    given: import.core composed before users.core and a principal holding users.members.manage that started an import job into users.core.members with rows of email, display name and role.
+    when: The file is written with create-only, repeated with create-only, skip-existing and update-existing, and a row names a role the workspace does not have, an address that is already an account elsewhere, or an address a row above it already carried in another case.
+    then: The first run creates the members with their role, their account id as the record reference and no password at all, so a sign-in is refused and a self-service credential change answers PASSWORD_NOT_SET rather than a wrong-password refusal; the repeat reports ALREADY_EXISTS, then skipped, then updated with the display name and role of the file; the unknown role and the repeated address are refused before any write, a role refused at write time after the display name was already changed leaves the row updated with ROLE_UNCHANGED and the member's new name, the address taken elsewhere fails its own row alone, and no member of another workspace is created or changed.
+  - id: USERS-EXPORT
+    given: exports.core composed either before or after users.core and a principal holding users.members.read in a workspace with more members than one export page carries.
+    when: exports.core walks users.core.members for a job that principal started from the Members screen, while another workspace holds members of its own and a member of the exported workspace is removed mid-walk.
+    then: The file carries the header and every member of the principal's workspace exactly once in account id order with their e-mail, display name, role, workspace status and joined-at instant, no member of the other workspace appears, the removed member's page cursor still answers the members that sort after it rather than ending the job, the list is registered exactly once whichever of the two modules composed first, and a deployment without exports.core composes users.core with no list registered.
+  - id: USERS-SEARCH
+    given: search.core composed before users.core and a principal holding users.members.read.
+    when: The principal searches a term that matches a member's display name or e-mail.
+    then: Only members of the principal's own workspace are returned as hits routed to the Users view, the port is asked for at most the documented bound however large a page the caller wants, the same set is found whichever order the terms were typed in, a principal without users.members.read is never asked, and a deployment without search.core still composes users.core.

package/modules/users/src/api/endpoints.ts

@@ -1,27 +1,165 @@
+import { createHash, randomBytes } from 'node:crypto';
 import {
+	decodeCursor,
 	defineEndpoint,
+	encodeCursor,
 	HttpProblem,
 	jsonResponse,
+	pageResponse,
 	problemResponse,
 	readJsonObject,
+	readPageQuery,
 	requiredString,
 	type EndpointExecutionContext,
 } from '@flowdular/sdk/server';
+import type { TenantMemberSort } from '@flowdular/sdk/modules/auth';
 import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
 import {
 	AuthServiceError,
 	endpointIdentityFromContext,
 	principalFromContext,
 	sessionMutationDenial,
+	TENANT_MEMBER_SEARCH_TERM_LENGTH,
+	TENANT_MEMBER_SORTS,
 } from '@flowdular/sdk/modules/auth/server';
 import { USER_PERMISSIONS } from '../acl/permissions.ts';
 import {
 	UsersService,
+	MEMBER_BULK_LIMIT,
 	type CreateUserInput,
+	type MemberListInput,
+	type MemberStatusFilter,
 } from '../services/users-service.ts';
 
 type Context = EndpointExecutionContext['octane'];
 
+/** The default page of the Members screen, and the most it may ask for. */
+export const MEMBER_PAGE_LIMIT = 50;
+export const MEMBER_PAGE_MAX_LIMIT = 200;
+
+/** The query parameters of one member page read, before the cursor. */
+interface MemberListQuery {
+	readonly sort: TenantMemberSort;
+	readonly direction: 'asc' | 'desc';
+	readonly query: string;
+	readonly status: MemberStatusFilter;
+}
+
+function invalid(message: string): HttpProblem {
+	return new HttpProblem('INVALID_INPUT', message, 400);
+}
+
+function cursorInvalid(): HttpProblem {
+	return new HttpProblem(
+		'CURSOR_INVALID',
+		'The page cursor is not valid.',
+		400,
+	);
+}
+
+function membershipStatus(
+	value: Record<string, unknown>,
+): 'active' | 'disabled' {
+	const status = requiredString(value, 'status', { max: 16 });
+	if (status !== 'active' && status !== 'disabled') {
+		throw invalid('status must be active or disabled.');
+	}
+	return status;
+}
+
+function accountIds(value: Record<string, unknown>): readonly string[] {
+	const raw = value.accountIds;
+	if (!Array.isArray(raw)) throw invalid('accountIds must be an array.');
+	if (raw.length < 1 || raw.length > MEMBER_BULK_LIMIT) {
+		throw invalid(
+			`accountIds must name between 1 and ${MEMBER_BULK_LIMIT} members.`,
+		);
+	}
+	const ids = raw.map((entry) =>
+		requiredString({ accountId: entry }, 'accountId', { max: 128 }),
+	);
+	if (new Set(ids).size !== ids.length) {
+		throw invalid('accountIds must not repeat an id.');
+	}
+	return ids;
+}
+
+function memberListQuery(url: URL): MemberListQuery {
+	const sort = url.searchParams.get('sort') ?? 'displayName';
+	if (!(TENANT_MEMBER_SORTS as readonly string[]).includes(sort)) {
+		throw invalid(`sort must be one of ${TENANT_MEMBER_SORTS.join(', ')}.`);
+	}
+	const direction = url.searchParams.get('direction') ?? 'asc';
+	if (direction !== 'asc' && direction !== 'desc') {
+		throw invalid('direction must be asc or desc.');
+	}
+	const query = url.searchParams.get('q') ?? '';
+	if (query.length > TENANT_MEMBER_SEARCH_TERM_LENGTH) {
+		throw invalid(
+			`q must contain at most ${TENANT_MEMBER_SEARCH_TERM_LENGTH} characters.`,
+		);
+	}
+	const status = url.searchParams.get('status') ?? '';
+	if (status !== '' && status !== 'active' && status !== 'disabled') {
+		throw invalid('status must be active or disabled.');
+	}
+	return {
+		sort: sort as TenantMemberSort,
+		direction,
+		query,
+		status: status === '' ? null : status,
+	};
+}
+
+/* The filters travel as a digest: a term of 200 multibyte characters beside a
+   full-length address would push the signed cursor past its length bound. */
+function filtersDigest(query: MemberListQuery): string {
+	return createHash('sha256')
+		.update(JSON.stringify([query.query, query.status ?? '']))
+		.digest('hex')
+		.slice(0, 32);
+}
+
+/* The cursor names the position and the listing it belongs to: the workspace,
+   the sort, the direction and the filters. A cursor presented with any of them
+   changed would splice two listings, so it is refused rather than reused. */
+function cursorPayload(
+	tenantId: string,
+	query: MemberListQuery,
+	keyset: { readonly sortValue: string; readonly accountId: string },
+): Record<string, string> {
+	return {
+		t: tenantId,
+		s: query.sort,
+		d: query.direction,
+		f: filtersDigest(query),
+		v: keyset.sortValue,
+		id: keyset.accountId,
+	};
+}
+
+function keysetFromCursor(
+	cursor: string,
+	secret: Uint8Array,
+	tenantId: string,
+	query: MemberListQuery,
+): MemberListInput['after'] {
+	const payload = decodeCursor(cursor, secret);
+	const expected = cursorPayload(tenantId, query, {
+		sortValue: '',
+		accountId: '',
+	});
+	for (const key of ['t', 's', 'd', 'f'] as const) {
+		if (payload[key] !== expected[key]) throw cursorInvalid();
+	}
+	const sortValue = payload.v;
+	const accountId = payload.id;
+	if (typeof sortValue !== 'string' || typeof accountId !== 'string') {
+		throw cursorInvalid();
+	}
+	return { sortValue, accountId };
+}
+
 function errorResponse(error: unknown): Response {
 	return error instanceof AuthServiceError
 		? jsonResponse(
@@ -59,6 +197,10 @@ function passwordField(value: Record<string, unknown>, key: string): string {
 
 export function createUserRoutes(auth: AuthRuntime) {
 	const users = new UsersService(auth);
+	/* Module-owned and never stored: a cursor names a position in one
+	   workspace's own list, so a restart invalidating one costs a client the
+	   first page. */
+	const cursorSecret = randomBytes(32);
 
 	const mutation = (
 		id: string,
@@ -91,8 +233,56 @@ export function createUserRoutes(auth: AuthRuntime) {
 		methods: ['GET'],
 		access: { kind: 'permission', permission: USER_PERMISSIONS.read },
 		resolveIdentity: endpointIdentityFromContext,
-		handler: async ({ octane }) =>
-			jsonResponse(await users.list(principalFromContext(octane)!)),
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const url = new URL(octane.request.url);
+				const page = readPageQuery(url, {
+					maxLimit: MEMBER_PAGE_MAX_LIMIT,
+					defaultLimit: MEMBER_PAGE_LIMIT,
+				});
+				const query = memberListQuery(url);
+				const result = await users.list(principal, {
+					...query,
+					limit: page.limit,
+					after: page.cursor
+						? keysetFromCursor(
+								page.cursor,
+								cursorSecret,
+								principal.tenantId,
+								query,
+							)
+						: null,
+				});
+				return pageResponse({
+					items: result.members,
+					limit: page.limit,
+					nextCursor: result.next
+						? encodeCursor(
+								cursorPayload(principal.tenantId, query, result.next),
+								cursorSecret,
+							)
+						: null,
+				});
+			} catch (error) {
+				return errorResponse(error);
+			}
+		},
+	});
+
+	const context = defineEndpoint({
+		id: 'users.members.context',
+		path: '/api/users/context',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: USER_PERMISSIONS.read },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				return jsonResponse(await users.context(principalFromContext(octane)!));
+			} catch (error) {
+				return errorResponse(error);
+			}
+		},
 	});
 
 	const create = mutation(
@@ -141,23 +331,40 @@ export function createUserRoutes(auth: AuthRuntime) {
 	const status = mutation(
 		'users.members.status',
 		'/api/users/status',
-		async (octane, payload) => {
-			const value = requiredString(payload, 'status', { max: 16 });
-			if (value !== 'active' && value !== 'disabled') {
-				throw new HttpProblem(
-					'INVALID_INPUT',
-					'status must be active or disabled.',
-					400,
-				);
-			}
-			return jsonResponse({
+		async (octane, payload) =>
+			jsonResponse({
 				user: await users.setStatus(
 					principalFromContext(octane)!,
 					requiredString(payload, 'accountId', { max: 128 }),
-					value,
+					membershipStatus(payload),
 				),
-			});
-		},
+			}),
+	);
+
+	const statusMany = mutation(
+		'users.members.status-many',
+		'/api/users/status-many',
+		async (octane, payload) =>
+			jsonResponse({
+				outcomes: await users.setMembershipStatusMany(
+					principalFromContext(octane)!,
+					accountIds(payload),
+					membershipStatus(payload),
+				),
+			}),
+	);
+
+	const roleMany = mutation(
+		'users.members.role-many',
+		'/api/users/role-many',
+		async (octane, payload) =>
+			jsonResponse({
+				outcomes: await users.assignRoleMany(
+					principalFromContext(octane)!,
+					accountIds(payload),
+					requiredString(payload, 'role', { max: 32 }),
+				),
+			}),
 	);
 
 	const remove = mutation(
@@ -200,10 +407,13 @@ export function createUserRoutes(auth: AuthRuntime) {
 
 	return [
 		list.serverRoute,
+		context.serverRoute,
 		create.serverRoute,
 		update.serverRoute,
 		role.serverRoute,
 		status.serverRoute,
+		statusMany.serverRoute,
+		roleMany.serverRoute,
 		remove.serverRoute,
 		resetPassword.serverRoute,
 		setScopes.serverRoute,
@@ -212,10 +422,13 @@ export function createUserRoutes(auth: AuthRuntime) {
 
 export const endpoints = [
 	'users.members.list',
+	'users.members.context',
 	'users.members.create',
 	'users.members.update',
 	'users.members.role',
 	'users.members.status',
+	'users.members.status-many',
+	'users.members.role-many',
 	'users.members.remove',
 	'users.members.password-reset',
 	'users.members.scopes',

package/modules/users/src/client/InviteMemberForm.tsrx

@@ -1,9 +1,9 @@
 import { Alert, Button, FormField } from '@flowdular/sdk/ui';
 import { t } from '@flowdular/sdk/client';
-import type { UserDirectory } from '../services/users-service.ts';
+import type { UsersContext } from '../services/users-service.ts';
 
 export interface InviteMemberFormProps {
-	readonly roles: UserDirectory['roles'];
+	readonly roles: UsersContext['roles'];
 	readonly canAssignOwner: boolean;
 	readonly busy: boolean;
 	readonly error: string;