@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -0,0 +1,311 @@
+import type {
+	DataClassExportSink,
+	DataClassExportSummary,
+} from '@flowdular/sdk/kernel';
+import type { AuthActor } from '@flowdular/sdk/modules/auth';
+import { AuthServiceError } from '@flowdular/sdk/modules/auth/server';
+import type {
+	GroupListQuery,
+	ListPage,
+	ProvisioningEvent,
+	ProvisioningEventQuery,
+	ScimGroupMapping,
+} from '../domain/types.ts';
+import type { DirectoryAuthPort } from './auth-port.ts';
+import { DirectoryUniqueViolation } from './database-repository.ts';
+import type { DirectoryRepository } from './repository.ts';
+import { bounded, DirectoryServiceError } from './service-error.ts';
+import { MAX_LIST_PAGE } from './token-service.ts';
+
+/** Rows one export query holds, so a long history costs bounded memory. */
+export const EXPORT_PAGE = 500;
+
+/** Rows one sweep call may remove, whatever limit the caller asks for. */
+export const MAX_SWEEP_BATCH = 100_000;
+
+/** What the mapping form needs beside the rows: read once, not per page. */
+export interface GroupMappingContext {
+	/** The workspace roles a mapping may point at, for the screen's select. */
+	readonly roles: readonly string[];
+	readonly defaultRole: string;
+}
+
+export interface MapGroupInput {
+	readonly id: string;
+	/** Empty clears the mapping: the group is tracked but grants nothing. */
+	readonly roleKey: string | null;
+	readonly precedence: number;
+}
+
+/**
+ * The administration side of directory.core: what an owner reads and changes in
+ * the workspace screens. SCIM operations live in `ScimProvisioningService`.
+ */
+export class DirectoryAdministrationService {
+	constructor(
+		private readonly repository: DirectoryRepository,
+		private readonly auth: DirectoryAuthPort,
+		private readonly now: () => number = Date.now,
+	) {}
+
+	listGroupMappings(
+		tenantId: string,
+		query: GroupListQuery,
+	): Promise<ListPage<ScimGroupMapping>> {
+		return this.repository.listGroupPage(tenantId, {
+			...query,
+			limit: Math.min(Math.max(query.limit, 1), MAX_LIST_PAGE),
+		});
+	}
+
+	async groupMappingContext(
+		tenantId: string,
+		defaultRole: string,
+	): Promise<GroupMappingContext> {
+		return { roles: await this.auth.listRoleKeys(tenantId), defaultRole };
+	}
+
+	/**
+	 * Sets or clears the role of one group and re-derives the role of every
+	 * member it affects. A refusal from auth.core, such as the last owner rule,
+	 * puts the mapping and every role already changed back.
+	 */
+	async mapGroup(
+		actor: AuthActor,
+		input: MapGroupInput,
+		defaultRole: string,
+	): Promise<ScimGroupMapping> {
+		const tenantId = actor.tenantId;
+		const group = await this.repository.findGroupById(
+			tenantId,
+			bounded(input.id, 'id', 1, 128),
+		);
+		if (!group) {
+			throw new DirectoryServiceError(
+				'GROUP_NOT_FOUND',
+				'The group does not exist in this workspace.',
+				404,
+			);
+		}
+		const roleKey =
+			input.roleKey === null || input.roleKey.trim() === ''
+				? null
+				: bounded(input.roleKey, 'roleKey', 2, 64);
+		const roles = new Set(await this.auth.listRoleKeys(tenantId));
+		if (roleKey !== null && !roles.has(roleKey)) {
+			throw new DirectoryServiceError(
+				'ROLE_UNKNOWN',
+				'The role does not exist in this workspace.',
+			);
+		}
+		if (
+			!Number.isSafeInteger(input.precedence) ||
+			input.precedence < 0 ||
+			input.precedence > 10_000
+		) {
+			throw new DirectoryServiceError(
+				'INVALID_INPUT',
+				'precedence must be an integer between 0 and 10000.',
+			);
+		}
+		if (roleKey === group.roleKey && input.precedence === group.precedence) {
+			return group;
+		}
+		await this.#write(tenantId, group, roleKey, input.precedence);
+		try {
+			await this.#recalculate(actor, group.id, roles, defaultRole);
+		} catch (error) {
+			await this.#write(tenantId, group, group.roleKey, group.precedence).catch(
+				() => undefined,
+			);
+			throw error;
+		}
+		return (await this.repository.findGroupById(tenantId, group.id)) ?? group;
+	}
+
+	listEvents(
+		tenantId: string,
+		query: ProvisioningEventQuery,
+	): Promise<readonly ProvisioningEvent[]> {
+		return this.repository.listEvents(tenantId, {
+			...query,
+			limit: Math.min(Math.max(query.limit, 1), MAX_LIST_PAGE),
+		});
+	}
+
+	/**
+	 * The retention sweep of `directory.core.provisioning-events`. Events that
+	 * occurred strictly before the cutoff go, at most `limit` of them, so one
+	 * pass is bounded however long the workspace has been provisioning.
+	 */
+	sweepEvents(
+		tenantId: string,
+		cutoff: Date,
+		limit: number,
+	): Promise<{ readonly removed: number }> {
+		return this.repository.sweepEvents(
+			bounded(tenantId, 'tenantId', 1, 128),
+			cutoff.getTime(),
+			Math.min(Math.max(Math.trunc(limit), 1), MAX_SWEEP_BATCH),
+		);
+	}
+
+	/**
+	 * Every provisioning event of one workspace, walked by the storage sequence
+	 * so no page holds more than `pageSize` rows whatever the history is.
+	 */
+	async exportEvents(
+		tenantId: string,
+		sink: DataClassExportSink,
+		pageSize = EXPORT_PAGE,
+	): Promise<DataClassExportSummary> {
+		const owner = bounded(tenantId, 'tenantId', 1, 128);
+		let afterSequence = 0;
+		let rows = 0;
+		let from: number | null = null;
+		let to: number | null = null;
+		for (;;) {
+			const page = await this.repository.exportEventsPage(
+				owner,
+				afterSequence,
+				pageSize,
+			);
+			for (const event of page) {
+				await sink.write({
+					id: event.id,
+					sequence: event.sequence,
+					tokenId: event.tokenId,
+					operation: event.operation,
+					subject: event.subject,
+					outcome: event.outcome,
+					reason: event.reason,
+					occurredAt: new Date(event.occurredAt).toISOString(),
+				});
+				rows += 1;
+				if (from === null || event.occurredAt < from) from = event.occurredAt;
+				if (to === null || event.occurredAt > to) to = event.occurredAt;
+			}
+			if (page.length < pageSize) break;
+			afterSequence = page[page.length - 1]!.sequence;
+		}
+		return {
+			rows,
+			from: from === null ? null : new Date(from),
+			to: to === null ? null : new Date(to),
+		};
+	}
+
+	async #write(
+		tenantId: string,
+		group: ScimGroupMapping,
+		roleKey: string | null,
+		precedence: number,
+	): Promise<void> {
+		try {
+			await this.repository.updateGroup({
+				tenantId,
+				id: group.id,
+				externalId: group.externalId,
+				displayName: group.displayName,
+				roleKey,
+				precedence,
+				updatedAt: this.now(),
+			});
+		} catch (error) {
+			if (error instanceof DirectoryUniqueViolation) {
+				throw new DirectoryServiceError(
+					'GROUP_EXISTS',
+					'A group with this name already exists in the workspace.',
+					409,
+				);
+			}
+			throw error;
+		}
+	}
+
+	/* One query resolves the winning role of every member of the group, so the
+	   pass costs one read plus one write per member whose role actually moves. */
+	async #recalculate(
+		actor: AuthActor,
+		groupId: string,
+		roles: ReadonlySet<string>,
+		defaultRole: string,
+	): Promise<void> {
+		const members = await this.repository.resolvedRolesForGroup(
+			actor.tenantId,
+			groupId,
+		);
+		if (members.length === 0) return;
+		/* A disabled membership holds no role anyone can act on, and auth.core
+		   counts it out of the owner tally, so recomputing it would refuse a
+		   change the workspace can make. */
+		const held = new Map(
+			(await this.auth.listMembers(actor.tenantId))
+				.filter((member) => member.membershipStatus === 'active')
+				.map((member) => [member.accountId, member.role]),
+		);
+		const applied: { accountId: string; previous: string }[] = [];
+		try {
+			for (const member of members) {
+				const target = member.roleKey ?? defaultRole;
+				if (!roles.has(target)) {
+					throw new DirectoryServiceError(
+						'ROLE_UNKNOWN',
+						`The role "${target}" does not exist in this workspace.`,
+					);
+				}
+				const current = held.get(member.accountId);
+				if (current === undefined || current === target) continue;
+				await this.auth.assignRole(actor, member.accountId, target);
+				applied.push({ accountId: member.accountId, previous: current });
+			}
+		} catch (error) {
+			for (const change of applied.reverse()) {
+				await this.auth
+					.assignRole(actor, change.accountId, change.previous)
+					.catch(() => undefined);
+			}
+			throw translateAuthError(error);
+		}
+	}
+}
+
+/**
+ * Every auth.core refusal this module reports, and the code it reports it as.
+ * The set is closed: a screen translates the codes listed here, and a code
+ * auth.core adds later must not reach a reader as untranslated server text.
+ */
+const AUTH_REFUSALS: Readonly<
+	Record<string, readonly [code: string, message: string, status: number]>
+> = {
+	LAST_OWNER: [
+		'LAST_OWNER',
+		'A workspace must keep at least one active owner.',
+		409,
+	],
+	ROLE_NOT_FOUND: [
+		'ROLE_UNKNOWN',
+		'The role does not exist in this workspace.',
+		400,
+	],
+	ACCOUNT_NOT_FOUND: [
+		'MEMBER_NOT_FOUND',
+		'The account is no longer a member of this workspace.',
+		404,
+	],
+};
+
+/** auth.core refusals reach the screen as this module's own stable codes. */
+export function translateAuthError(error: unknown): unknown {
+	if (!(error instanceof AuthServiceError)) return error;
+	/* A fault of auth.core stays a fault: answering it as a refusal would tell
+	   the reader their change was rejected when nothing decided it. */
+	if (error.status >= 500) return error;
+	const known = AUTH_REFUSALS[error.code];
+	if (known) return new DirectoryServiceError(known[0], known[1], known[2]);
+	return new DirectoryServiceError(
+		'DIRECTORY_REFUSED',
+		'The workspace directory refused the change.',
+		error.status,
+	);
+}

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

@@ -0,0 +1,43 @@
+export {
+	authPortFromRuntime,
+	scimActor,
+	type DirectoryAuthPort,
+} from './auth-port.ts';
+export {
+	DatabaseDirectoryRepository,
+	DirectoryUniqueViolation,
+	DIRECTORY_UNIQUE_INDEXES,
+	migrateDirectoryDatabase,
+} from './database-repository.ts';
+export {
+	DirectoryAdministrationService,
+	translateAuthError,
+	type GroupMappingContext,
+	type MapGroupInput,
+} from './directory-service.ts';
+export {
+	ScimProvisioningService,
+	type ScimRequestContext,
+} from './provisioning-service.ts';
+export { ScimRateLimiter } from './rate-limiter.ts';
+export type {
+	DirectoryRepository,
+	GroupMemberChange,
+	GroupMemberRow,
+	GroupMemberStep,
+	ResolvedGroupMember,
+	ScimGroupFilter,
+	ScimPageRequest,
+	ScimSlice,
+	ScimTokenSecret,
+	ScimUserFilter,
+} from './repository.ts';
+export { bounded, DirectoryServiceError } from './service-error.ts';
+export {
+	hashScimToken,
+	MAX_LIST_PAGE,
+	ScimTokenService,
+	scimTokenFingerprint,
+	SCIM_TOKEN_PREFIX,
+	type CreateScimTokenInput,
+} from './token-service.ts';

package/modules/directory/src/services/migration.ts

@@ -0,0 +1,146 @@
+import type { DatabaseMigration } from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/** Every tenant table the module owns, in creation order. */
+export const DIRECTORY_TENANT_TABLES = [
+	'directory_scim_tokens',
+	'directory_scim_users',
+	'directory_scim_groups',
+	'directory_scim_group_members',
+	'directory_provisioning_events',
+] as const;
+
+/* Mirrors migrations/0001_directory_core.up.sql byte for byte. */
+export const DIRECTORY_MIGRATION_001 = `CREATE TABLE IF NOT EXISTS directory_scim_tokens (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  label TEXT NOT NULL,
+  token_fingerprint TEXT NOT NULL,
+  token_hash TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'revoked')),
+  created_by TEXT NOT NULL,
+  created_at BIGINT NOT NULL,
+  last_used_at BIGINT,
+  expires_at BIGINT,
+  revoked_at BIGINT
+);
+-- Case folded like the group name below: two labels an owner cannot tell apart
+-- in the list must not be two credentials.
+CREATE UNIQUE INDEX IF NOT EXISTS directory_scim_tokens_label_idx
+  ON directory_scim_tokens (tenant_id, lower(label));
+-- Authentication reads one row by this derived prefix and then compares the
+-- full hash in constant time, so an unknown credential costs the same lookup.
+CREATE UNIQUE INDEX IF NOT EXISTS directory_scim_tokens_fingerprint_idx
+  ON directory_scim_tokens (tenant_id, token_fingerprint);
+ALTER TABLE directory_scim_tokens ENABLE ROW LEVEL SECURITY;
+ALTER TABLE directory_scim_tokens FORCE ROW LEVEL SECURITY;
+CREATE POLICY directory_scim_tokens_tenant_policy ON directory_scim_tokens
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS directory_scim_users (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  external_id TEXT,
+  user_name TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  active SMALLINT NOT NULL CHECK (active IN (0, 1)),
+  created_at BIGINT NOT NULL,
+  last_synced_at BIGINT NOT NULL
+);
+-- One provider identity per workspace, and one mapping per account: both are
+-- what makes a repeated create idempotent instead of a second membership.
+CREATE UNIQUE INDEX IF NOT EXISTS directory_scim_users_user_name_idx
+  ON directory_scim_users (tenant_id, user_name);
+CREATE UNIQUE INDEX IF NOT EXISTS directory_scim_users_account_idx
+  ON directory_scim_users (tenant_id, account_id);
+CREATE INDEX IF NOT EXISTS directory_scim_users_external_idx
+  ON directory_scim_users (tenant_id, external_id);
+ALTER TABLE directory_scim_users ENABLE ROW LEVEL SECURITY;
+ALTER TABLE directory_scim_users FORCE ROW LEVEL SECURITY;
+CREATE POLICY directory_scim_users_tenant_policy ON directory_scim_users
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS directory_scim_groups (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  external_id TEXT,
+  display_name TEXT NOT NULL,
+  role_key TEXT,
+  precedence INTEGER NOT NULL,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL
+);
+-- displayName is a caseExact=false attribute, so the uniqueness the provider
+-- sees and the index that enforces it have to fold case the same way.
+CREATE UNIQUE INDEX IF NOT EXISTS directory_scim_groups_display_name_idx
+  ON directory_scim_groups (tenant_id, lower(display_name));
+-- Role resolution walks the mapped groups of one user in precedence order.
+CREATE INDEX IF NOT EXISTS directory_scim_groups_precedence_idx
+  ON directory_scim_groups (tenant_id, precedence, id);
+ALTER TABLE directory_scim_groups ENABLE ROW LEVEL SECURITY;
+ALTER TABLE directory_scim_groups FORCE ROW LEVEL SECURITY;
+CREATE POLICY directory_scim_groups_tenant_policy ON directory_scim_groups
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+CREATE TABLE IF NOT EXISTS directory_scim_group_members (
+  tenant_id TEXT NOT NULL,
+  group_id TEXT NOT NULL REFERENCES directory_scim_groups(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES directory_scim_users(id) ON DELETE CASCADE,
+  added_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, group_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS directory_scim_group_members_user_idx
+  ON directory_scim_group_members (tenant_id, user_id);
+ALTER TABLE directory_scim_group_members ENABLE ROW LEVEL SECURITY;
+ALTER TABLE directory_scim_group_members FORCE ROW LEVEL SECURITY;
+CREATE POLICY directory_scim_group_members_tenant_policy ON directory_scim_group_members
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+
+-- Evidence outlives the credential, so the token id is recorded without a
+-- foreign key: revoking or pruning a token never removes its trail.
+CREATE TABLE IF NOT EXISTS directory_provisioning_events (
+  id TEXT PRIMARY KEY,
+  -- Two operations of one request land in the same millisecond, so the order
+  -- the log is read in comes from storage rather than from the clock.
+  sequence BIGINT GENERATED BY DEFAULT AS IDENTITY,
+  tenant_id TEXT NOT NULL,
+  token_id TEXT NOT NULL,
+  operation TEXT NOT NULL CHECK (operation IN ('user-create', 'user-update', 'user-deactivate', 'user-reactivate', 'group-create', 'group-update', 'group-delete', 'membership-change')),
+  subject TEXT NOT NULL,
+  outcome TEXT NOT NULL CHECK (outcome IN ('applied', 'unchanged', 'refused')),
+  reason TEXT,
+  occurred_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS directory_provisioning_events_time_idx
+  ON directory_provisioning_events (tenant_id, occurred_at DESC, sequence DESC);
+ALTER TABLE directory_provisioning_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE directory_provisioning_events FORCE ROW LEVEL SECURITY;
+CREATE POLICY directory_provisioning_events_tenant_policy ON directory_provisioning_events
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_directory_core',
+		sql: { postgresql: DIRECTORY_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'directory_scim_tokens',
+				'directory_scim_tokens_tenant_policy',
+				[
+					() => database.schema.hasTable('directory_scim_users'),
+					() => database.schema.hasTable('directory_scim_groups'),
+					() => database.schema.hasTable('directory_scim_group_members'),
+					() => database.schema.hasTable('directory_provisioning_events'),
+					() =>
+						database.schema.hasIndex('directory_scim_tokens_fingerprint_idx'),
+				],
+			),
+	},
+];