@flowdular/sdk 0.1.0

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

@@ -0,0 +1,92 @@
+import { t, type ModuleClientContribution } from '@flowdular/sdk/client';
+import { USER_PERMISSIONS } from '../acl/permissions.ts';
+import translationsEn from '../../translations/en.json';
+import translationsPl from '../../translations/pl.json';
+import { RolesView } from './RolesView.tsrx';
+import {
+	UsersDashboardWidget,
+	UsersSetupStep,
+	UsersView,
+} from './UsersView.tsrx';
+
+export interface UsersClientContributionOptions {
+	readonly csrfToken: string;
+	readonly scopes: readonly string[];
+}
+
+const ROLES_READ = 'auth.roles.read';
+const ROLES_MANAGE = 'auth.roles.manage';
+
+export function createUsersClientContribution(
+	options: UsersClientContributionOptions,
+): ModuleClientContribution {
+	const has = (scope: string) => options.scopes.includes(scope);
+	return {
+		moduleId: 'users.core',
+		translations: { en: translationsEn, pl: translationsPl },
+		navigation: [
+			{
+				id: 'users.navigation',
+				viewId: 'users',
+				group: 'Administration',
+				get label() {
+					return t('users.navigation.users');
+				},
+				glyph: 'users',
+				get description() {
+					return t('users.navigation.usersDescription');
+				},
+				scope: USER_PERMISSIONS.read,
+				order: 5,
+			},
+			{
+				id: 'users.roles.navigation',
+				viewId: 'roles',
+				group: 'Administration',
+				get label() {
+					return t('users.navigation.roles');
+				},
+				glyph: 'shield',
+				get description() {
+					return t('users.navigation.rolesDescription');
+				},
+				scope: ROLES_READ,
+				order: 10,
+			},
+		],
+		views: [
+			{
+				id: 'users',
+				render: () =>
+					<UsersView
+						csrfToken={options.csrfToken}
+						canManage={has(USER_PERMISSIONS.manage)}
+					/>,
+			},
+			{
+				id: 'roles',
+				render: () =>
+					<RolesView
+						csrfToken={options.csrfToken}
+						canManage={has(ROLES_MANAGE)}
+					/>,
+			},
+		],
+		widgets: [
+			{
+				id: 'users.dashboard.access',
+				slot: 'dashboard.metrics',
+				scope: USER_PERMISSIONS.read,
+				order: 30,
+				render: () => <UsersDashboardWidget />,
+			},
+			{
+				id: 'users.dashboard.setup',
+				slot: 'dashboard.main',
+				scope: USER_PERMISSIONS.manage,
+				order: 30,
+				render: () => <UsersSetupStep />,
+			},
+		],
+	};
+}

package/modules/users/src/client/index.ts

@@ -0,0 +1,19 @@
+export { createUsersClientContribution } from './contribution.tsrx';
+export type { UsersClientContributionOptions } from './contribution.tsrx';
+export { RolesView } from './RolesView.tsrx';
+export { UsersDashboardWidget, UsersView } from './UsersView.tsrx';
+import type {
+	ModuleClientContext,
+	ModuleClientContribution,
+} from '@flowdular/sdk/client';
+import { createUsersClientContribution as canonicalContribution } from './contribution.tsrx';
+
+/* Canonical entry used by the generated platform composition. */
+export function createClientContribution(
+	context: ModuleClientContext,
+): ModuleClientContribution {
+	return canonicalContribution({
+		csrfToken: context.csrfToken,
+		scopes: context.scopes,
+	});
+}

package/modules/users/src/client/member-columns.tsrx

@@ -0,0 +1,52 @@
+import { Tag, type TableColumn } from '@flowdular/sdk/ui';
+import { activeLocale, t } from '@flowdular/sdk/client';
+import type { TenantMember } from '@flowdular/sdk/modules/auth';
+
+export function memberColumns(
+	roleNames: ReadonlyMap<string, string>,
+): readonly TableColumn<TenantMember>[] {
+	return [
+		{
+			key: 'user',
+			header: t('users.table.user'),
+			width: '32%',
+			cell: (user) => <span class="ui-cell">
+				<b>{user.displayName}</b>
+				<small>{user.email}</small>
+			</span>,
+		},
+		{
+			key: 'role',
+			header: t('users.table.role'),
+			width: '18%',
+			cell: (user) =>
+				<Tag tone={user.role === 'owner' ? 'ink' : 'neutral'}>
+					{roleNames.get(user.role) ?? user.role}
+				</Tag>,
+		},
+		{
+			key: 'status',
+			header: t('users.table.status'),
+			width: '28%',
+			cell: (user) => <span class="ui-table__state">
+				<Tag tone={user.status === 'active' ? 'success' : 'neutral'} dot>
+					{user.status === 'active'
+						? t('users.status.active')
+						: t('users.status.disabled')}
+				</Tag>
+				{user.passwordChangeRequired
+					? <small>{t('users.status.passwordResetPending')}</small>
+					: null}
+			</span>,
+		},
+		{
+			key: 'scopes',
+			header: t('users.table.scopes'),
+			width: '12%',
+			numeric: true,
+			cell: (user) => new Intl.NumberFormat(activeLocale()).format(
+				user.scopes.length,
+			),
+		},
+	];
+}

package/modules/users/src/client/roles-api.ts

@@ -0,0 +1,90 @@
+import type { TenantRole } from '@flowdular/sdk/modules/auth';
+import { t } from '@flowdular/sdk/client/i18n';
+import { ApiError } from './api.ts';
+
+interface ErrorEnvelope {
+	readonly error?: { readonly message?: string };
+}
+
+export interface RoleCatalog {
+	readonly roles: readonly TenantRole[];
+	readonly grantableScopes: readonly string[];
+}
+
+export interface RoleDraft {
+	readonly key: string;
+	readonly name: string;
+	readonly description: string;
+	readonly scopes: readonly string[];
+}
+
+async function payload<T>(response: Response): Promise<T> {
+	const value = (await response.json()) as T & ErrorEnvelope;
+	if (!response.ok) {
+		throw new ApiError(
+			response.status,
+			value.error?.message ?? t('users.roles.errorRequest'),
+		);
+	}
+	return value;
+}
+
+async function post<T>(
+	path: string,
+	body: unknown,
+	csrfToken: string,
+): Promise<T> {
+	const response = await fetch(path, {
+		method: 'POST',
+		headers: {
+			'content-type': 'application/json',
+			'x-csrf-token': csrfToken,
+		},
+		credentials: 'same-origin',
+		body: JSON.stringify(body),
+	});
+	return payload<T>(response);
+}
+
+export async function loadRoles(): Promise<RoleCatalog> {
+	const response = await fetch('/api/auth/roles', {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return payload<RoleCatalog>(response);
+}
+
+export async function createRole(
+	draft: RoleDraft,
+	csrfToken: string,
+): Promise<TenantRole> {
+	return (
+		await post<{ readonly role: TenantRole }>(
+			'/api/auth/roles',
+			draft,
+			csrfToken,
+		)
+	).role;
+}
+
+export async function updateRole(
+	id: string,
+	draft: Omit<RoleDraft, 'key'>,
+	csrfToken: string,
+): Promise<TenantRole> {
+	return (
+		await post<{ readonly role: TenantRole }>(
+			'/api/auth/roles/update',
+			{ id, ...draft },
+			csrfToken,
+		)
+	).role;
+}
+
+export async function deleteRole(id: string, csrfToken: string): Promise<void> {
+	await post<{ readonly deleted: boolean }>(
+		'/api/auth/roles/delete',
+		{ id },
+		csrfToken,
+	);
+}

package/modules/users/src/client/state.ts

@@ -0,0 +1,42 @@
+import type { TenantMember } from '@flowdular/sdk/modules/auth';
+import { cell, createStore } from 'segment-state';
+import type { UserDirectory } from '../services/users-service.ts';
+
+export type UsersStatus =
+	| 'idle'
+	| 'loading'
+	| 'submitting'
+	| 'denied'
+	| 'error';
+
+export function createUsersClientState() {
+	const store = createStore({
+		users: cell<readonly TenantMember[]>([]),
+		roles: cell<UserDirectory['roles']>([]),
+		grantableScopes: cell<readonly string[]>([]),
+		actor: cell<UserDirectory['actor'] | null>(null),
+		passwordMinLength: 12,
+		query: '',
+		formOpen: false,
+		formSession: 0,
+		inviteOpen: false,
+		inviteSession: 0,
+		selectedAccountId: cell<string | null>(null),
+		status: cell<UsersStatus>('idle'),
+		error: '',
+		notice: '',
+	});
+	return { store, state: store.state };
+}
+
+export type UsersClientState = ReturnType<typeof createUsersClientState>;
+
+export function replaceMember(
+	users: readonly TenantMember[],
+	member: TenantMember,
+): readonly TenantMember[] {
+	const others = users.filter((user) => user.accountId !== member.accountId);
+	return [...others, member].sort((left, right) =>
+		left.displayName.localeCompare(right.displayName),
+	);
+}

package/modules/users/src/index.ts

@@ -0,0 +1,27 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { USER_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'users.navigation',
+			label: 'Users',
+			href: '/users',
+			order: 5,
+			permission: USER_PERMISSIONS.read,
+		},
+		{
+			id: 'users.roles.navigation',
+			label: 'Roles',
+			href: '/roles',
+			order: 10,
+			permission: USER_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(USER_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { USER_PERMISSIONS } from './acl/permissions.ts';
+export type { CreateUserInput } from './services/users-service.ts';

package/modules/users/src/platform.ts

@@ -0,0 +1,11 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import { createUserRoutes } from './api/endpoints.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	return { routes: createUserRoutes(context.auth) };
+}

package/modules/users/src/services/index.ts

@@ -0,0 +1,2 @@
+export { UsersService } from './users-service.ts';
+export type { CreateUserInput } from './users-service.ts';

package/modules/users/src/services/users-service.ts

@@ -0,0 +1,142 @@
+import type {
+	AuthActor,
+	AuthPrincipal,
+	CreateTenantMemberInput,
+	TenantMember,
+	TenantRole,
+} from '@flowdular/sdk/modules/auth';
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+
+export interface CreateUserInput {
+	readonly email: string;
+	readonly password: string;
+	readonly displayName: string;
+	readonly role: string;
+}
+
+export interface UserDirectory {
+	readonly users: readonly TenantMember[];
+	readonly roles: readonly Pick<
+		TenantRole,
+		'id' | 'key' | 'name' | 'builtin'
+	>[];
+	readonly grantableScopes: readonly string[];
+	/** Who is asking; the screen uses it to keep self-edits off limits. */
+	readonly actor: { readonly accountId: string; readonly role: string };
+	/** Shared auth.core setting, read through the declared dependency. */
+	readonly passwordMinLength: number;
+}
+
+function actor(principal: AuthPrincipal): AuthActor {
+	return {
+		accountId: principal.accountId,
+		tenantId: principal.tenantId,
+		email: principal.email,
+		role: principal.role,
+		scopes: principal.scopes,
+	};
+}
+
+/* Every write goes through the auth administration port with the acting
+   principal, so the owner cap, the last-owner rule, and the audit trail are
+   enforced in one place. */
+export class UsersService {
+	readonly #auth: AuthRuntime;
+
+	constructor(auth: AuthRuntime) {
+		this.#auth = auth;
+	}
+
+	async list(principal: AuthPrincipal): Promise<UserDirectory> {
+		const service = await this.#auth.service();
+		return {
+			users: await service.listTenantMembers(principal.tenantId),
+			roles: (await service.listRoles(principal.tenantId)).map(
+				({ id, key, name, builtin }) => ({ id, key, name, builtin }),
+			),
+			grantableScopes: await service.listGrantableScopes(principal.tenantId),
+			actor: { accountId: principal.accountId, role: principal.role },
+			passwordMinLength: this.#auth.settings.passwordMinLength,
+		};
+	}
+
+	async create(
+		principal: AuthPrincipal,
+		input: CreateUserInput,
+	): Promise<TenantMember> {
+		const record: CreateTenantMemberInput = {
+			...input,
+			tenantId: principal.tenantId,
+		};
+		return (await this.#auth.service()).createTenantMember(
+			record,
+			actor(principal),
+		);
+	}
+
+	async rename(
+		principal: AuthPrincipal,
+		accountId: string,
+		displayName: string,
+	): Promise<TenantMember> {
+		return (await this.#auth.service()).updateMemberDisplayName(
+			actor(principal),
+			accountId,
+			displayName,
+		);
+	}
+
+	async assignRole(
+		principal: AuthPrincipal,
+		accountId: string,
+		roleKey: string,
+	): Promise<TenantMember> {
+		return (await this.#auth.service()).assignMemberRole(
+			actor(principal),
+			accountId,
+			roleKey,
+		);
+	}
+
+	async setStatus(
+		principal: AuthPrincipal,
+		accountId: string,
+		status: 'active' | 'disabled',
+	): Promise<TenantMember> {
+		return (await this.#auth.service()).setMemberStatus(
+			actor(principal),
+			accountId,
+			status,
+		);
+	}
+
+	async remove(principal: AuthPrincipal, accountId: string): Promise<void> {
+		await (
+			await this.#auth.service()
+		).removeMember(actor(principal), accountId);
+	}
+
+	async resetPassword(
+		principal: AuthPrincipal,
+		accountId: string,
+		temporaryPassword: string,
+	): Promise<TenantMember> {
+		return (await this.#auth.service()).resetMemberPassword(
+			actor(principal),
+			accountId,
+			temporaryPassword,
+		);
+	}
+
+	async setScopes(
+		principal: AuthPrincipal,
+		accountId: string,
+		scopes: readonly string[],
+	): Promise<TenantMember> {
+		return (await this.#auth.service()).setMembershipScopes(
+			actor(principal),
+			accountId,
+			scopes,
+		);
+	}
+}

package/modules/users/translations/en.json

@@ -0,0 +1,133 @@
+{
+	"module.name": "User Management Core",
+	"navigation.users": "Users",
+	"navigation.usersDescription": "Accounts and access",
+	"navigation.roles": "Roles",
+	"navigation.rolesDescription": "Permissions and access",
+	"page.eyebrow": "Administration",
+	"page.title": "Users",
+	"page.description": "Accounts, roles, and scopes inside the active workspace.",
+	"action.refresh": "Refresh",
+	"action.newAccount": "New account",
+	"invite.action": "Invite member",
+	"invite.title": "Invite a member",
+	"invite.subtitle": "Email invitation to this workspace",
+	"invite.email": "Email address",
+	"invite.emailHelp": "The invitation link is single-use and expires after seven days.",
+	"invite.footer": "Flowdular sends the invitation through the deployment mail adapter.",
+	"invite.send": "Send invitation",
+	"invite.sending": "Sending…",
+	"invite.sent": "Invitation sent to {email}.",
+	"invite.error": "The invitation could not be sent.",
+	"action.manage": "Manage",
+	"action.cancel": "Cancel",
+	"action.close": "Close",
+	"action.creating": "Creating…",
+	"action.createAccount": "Create account",
+	"action.saving": "Saving…",
+	"action.edit": "Edit",
+	"action.delete": "Delete",
+	"denied.title": "Access denied",
+	"denied.members": "Reading the user directory needs the users.members.read scope.",
+	"table.title": "Members",
+	"table.caption": "Workspace users",
+	"table.count": "{owners} owners · {accounts} accounts",
+	"table.user": "User",
+	"table.role": "Role",
+	"table.status": "Status",
+	"table.scopes": "Scopes",
+	"table.actions": "User actions",
+	"table.loading": "Loading workspace accounts…",
+	"table.emptyTitle": "No accounts yet",
+	"table.emptyHint": "Create the first account for this workspace.",
+	"table.emptyFilteredTitle": "No matching accounts",
+	"table.emptyFilteredHint": "No account in this workspace matches the current filter.",
+	"table.note": "Roles decide what an account may reach. Owners administer the workspace; every other role carries exactly the scopes it lists.",
+	"search.placeholder": "Filter by name or email",
+	"search.label": "Filter members",
+	"status.active": "Active",
+	"status.disabled": "Disabled",
+	"status.passwordResetPending": "Password reset pending",
+	"drawer.newTitle": "New account",
+	"drawer.newSubtitle": "Direct workspace access",
+	"drawer.member": "Member",
+	"form.displayName": "Display name",
+	"form.email": "Email",
+	"form.initialPassword": "Initial password",
+	"form.initialPasswordHelp": "At least {min} characters. The account holder can change it later.",
+	"form.role": "Role",
+	"form.ownerOnly": "Only an owner can create another owner.",
+	"form.footer": "The account gets access to the current workspace only.",
+	"member.ownerLocked": "Only an owner can change another owner.",
+	"member.selfLocked": "Your own role, scopes, and status change through another owner.",
+	"member.scopes": "Scopes",
+	"member.scopesDescription": "Exact scopes of this membership. Assigning a role replaces them.",
+	"member.saveScopes": "Save scopes",
+	"member.identity": "Identity",
+	"member.identityDescription": "The email is the sign-in id and cannot change here.",
+	"member.saveName": "Save name",
+	"member.roleDescription": "A role sets the scopes below; custom roles live on the Roles screen.",
+	"member.assignRole": "Assign role",
+	"member.account": "Account",
+	"member.accountDescription": "Disabling ends every session at once and blocks sign-in.",
+	"member.disable": "Disable account",
+	"member.enable": "Enable account",
+	"member.signOutEverywhere": "Sign out everywhere",
+	"member.temporaryPassword": "Temporary password",
+	"member.temporaryPasswordHelp": "At least {min} characters. The member picks a new one at the next sign-in.",
+	"member.resetPassword": "Reset password",
+	"member.removeTitle": "Remove from workspace",
+	"member.removeDescription": "Ends the membership with its sessions and tokens; the account stays if it belongs to another workspace.",
+	"member.remove": "Remove member",
+	"notice.nameSaved": "Display name saved.",
+	"notice.roleAssigned": "Role assigned.",
+	"notice.scopesSaved": "Scopes saved.",
+	"notice.accountDisabled": "Account disabled.",
+	"notice.accountEnabled": "Account enabled.",
+	"notice.passwordSet": "Temporary password set. The member must change it at sign-in.",
+	"notice.sessionsCount": "Sessions ended: {count}.",
+	"notice.sessionsEnded": "Sessions ended.",
+	"remove.title": "Remove this member?",
+	"remove.fallbackName": "The member",
+	"remove.description": "{name} loses access to this workspace immediately. Sessions and API tokens for this membership are revoked.",
+	"roles.title": "Roles",
+	"roles.description": "Built-in and custom roles with the exact scopes they grant.",
+	"roles.new": "New role",
+	"roles.edit": "Edit role",
+	"roles.drawerSubtitle": "Custom workspace role",
+	"roles.denied": "Reading roles needs the auth.roles.read scope.",
+	"roles.loading": "Loading roles…",
+	"roles.emptyTitle": "No roles yet",
+	"roles.emptyHint": "The built-in roles appear once the workspace is initialised.",
+	"roles.customTitle": "Custom roles",
+	"roles.customCount": "{count} defined",
+	"roles.note": "A role grants a subset of the scopes this workspace can hand out. Assigning it replaces a member's scopes; changing it updates every member that holds it. Roles in use cannot be deleted.",
+	"roles.scopeCount": "{count} scopes",
+	"roles.builtin": "Built-in",
+	"roles.deleteTitle": "Delete role {name}?",
+	"roles.delete": "Delete role",
+	"roles.deleteDescription": "The role is removed from this workspace. Deletion is refused while a member still holds it.",
+	"roles.errorLoad": "Could not load roles.",
+	"roles.errorSave": "Could not save the role.",
+	"roles.errorDelete": "Could not delete the role.",
+	"roles.errorRequest": "The role operation failed.",
+	"roleForm.key": "Key",
+	"roleForm.keyHelp": "Stable identifier used by assignments and the API; cannot change later.",
+	"roleForm.name": "Name",
+	"roleForm.description": "Description",
+	"roleForm.scopeCount": "{selected} of {total} scopes selected. Members holding this role receive exactly these.",
+	"roleForm.editNote": "Changing scopes updates every member that holds this role.",
+	"roleForm.createNote": "Built-in owner and member roles cannot be recreated.",
+	"roleForm.save": "Save role",
+	"roleForm.create": "Create role",
+	"error.load": "Could not load users.",
+	"error.save": "The change could not be saved.",
+	"error.create": "Could not create the user.",
+	"error.remove": "Could not remove the member.",
+	"error.request": "The user operation failed.",
+	"widget.label": "Team",
+	"widget.note": "Accounts with access to the current workspace.",
+	"widget.link": "Manage users",
+	"setup.title": "Invite your team",
+	"setup.description": "Accounts, roles, and scoped access"
+}