@flowdular/sdk 0.2.4 → 0.3.0

package/modules/directory/src/domain/scim.ts

@@ -0,0 +1,346 @@
+/**
+ * The SCIM 2.0 wire contract directory.core answers on: schema identifiers,
+ * the error and list envelopes, the supported filter grammar and the PATCH
+ * shape. Nothing here touches persistence or auth.core.
+ */
+import { DIRECTORY_REASONS } from './types.ts';
+
+export const SCIM_SCHEMAS = {
+	error: 'urn:ietf:params:scim:api:messages:2.0:Error',
+	listResponse: 'urn:ietf:params:scim:api:messages:2.0:ListResponse',
+	patchOp: 'urn:ietf:params:scim:api:messages:2.0:PatchOp',
+	user: 'urn:ietf:params:scim:schemas:core:2.0:User',
+	group: 'urn:ietf:params:scim:schemas:core:2.0:Group',
+	serviceProviderConfig:
+		'urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig',
+	resourceType: 'urn:ietf:params:scim:schemas:core:2.0:ResourceType',
+	schema: 'urn:ietf:params:scim:schemas:core:2.0:Schema',
+} as const;
+
+/**
+ * The scimType values this module emits. RFC 7644 pairs each with 400 except
+ * `uniqueness`, which is a 409; the status travels with the error so the two
+ * can never drift apart.
+ */
+export type ScimType =
+	| 'invalidFilter'
+	| 'invalidValue'
+	| 'mutability'
+	| 'noTarget'
+	| 'tooMany'
+	| 'uniqueness';
+
+/**
+ * Every refusal the SCIM surface answers with. `reason` is the module's stable
+ * code: it is what the provisioning log records and what an operator matches
+ * on, because `scimType` is too coarse to tell two refusals apart.
+ */
+export class ScimError extends Error {
+	constructor(
+		readonly status: number,
+		readonly scimType: ScimType | null,
+		readonly reason: string,
+		detail: string,
+	) {
+		super(detail);
+		this.name = 'ScimError';
+	}
+
+	/* A deliberate extension of the RFC envelope: `reason` is additive, and a
+	   client that only knows the standard fields reads the same error. */
+	body(): Record<string, unknown> {
+		return {
+			schemas: [SCIM_SCHEMAS.error],
+			status: String(this.status),
+			...(this.scimType ? { scimType: this.scimType } : {}),
+			detail: this.message,
+			reason: this.reason,
+		};
+	}
+}
+
+export function scimResponse(body: unknown, status = 200): Response {
+	return new Response(status === 204 ? null : JSON.stringify(body), {
+		status,
+		headers: {
+			...(status === 204 ? {} : { 'content-type': 'application/scim+json' }),
+			'cache-control': 'no-store',
+		},
+	});
+}
+
+export function scimErrorResponse(error: ScimError): Response {
+	return scimResponse(error.body(), error.status);
+}
+
+export interface ScimPage {
+	readonly startIndex: number;
+	readonly count: number;
+}
+
+export function listResponse(input: {
+	readonly totalResults: number;
+	readonly startIndex: number;
+	readonly resources: readonly unknown[];
+}): Record<string, unknown> {
+	return {
+		schemas: [SCIM_SCHEMAS.listResponse],
+		totalResults: input.totalResults,
+		startIndex: input.startIndex,
+		itemsPerPage: input.resources.length,
+		Resources: input.resources,
+	};
+}
+
+/**
+ * `startIndex` is 1-based per RFC 7644 and `count` is clamped to the platform
+ * maximum rather than refused, so a provider asking for more than the
+ * deployment allows still makes progress instead of failing every page.
+ */
+export function parsePage(url: URL, pageSizeMax: number): ScimPage {
+	const startIndex = boundedNumber(url.searchParams.get('startIndex'), 1, 1);
+	const count = boundedNumber(
+		url.searchParams.get('count'),
+		pageSizeMax,
+		0,
+		pageSizeMax,
+	);
+	return { startIndex, count };
+}
+
+function boundedNumber(
+	raw: string | null,
+	fallback: number,
+	minimum: number,
+	maximum = Number.MAX_SAFE_INTEGER,
+): number {
+	if (raw === null || raw.trim() === '') return fallback;
+	const value = Number(raw);
+	if (!Number.isSafeInteger(value)) {
+		throw new ScimError(
+			400,
+			'invalidValue',
+			DIRECTORY_REASONS.invalidValue,
+			'startIndex and count must be integers.',
+		);
+	}
+	if (value < minimum) return minimum;
+	return value > maximum ? maximum : value;
+}
+
+export interface ScimFilter {
+	readonly attribute: string;
+	readonly value: string;
+}
+
+/* The attribute and the operator are both case-insensitive per RFC 7644. */
+const FILTER_PATTERN =
+	/^\s*([A-Za-z][A-Za-z0-9_$-]*)\s+(eq)\s+"((?:[^"\\]|\\.)*)"\s*$/i;
+const MAX_FILTER_LENGTH = 512;
+
+/**
+ * Only `<attribute> eq "<value>"` over the attributes a resource declares.
+ * Anything else is refused: answering a full listing to a filter the server
+ * does not understand would hand the provider the wrong resource to act on.
+ */
+export function parseFilter(
+	raw: string | null,
+	allowed: readonly string[],
+): ScimFilter | null {
+	if (raw === null || raw.trim() === '') return null;
+	const unsupported = (): never => {
+		throw new ScimError(
+			400,
+			'invalidFilter',
+			DIRECTORY_REASONS.unsupportedFilter,
+			`Only ${allowed.map((name) => `${name} eq`).join(', ')} filters are supported.`,
+		);
+	};
+	if (raw.length > MAX_FILTER_LENGTH) unsupported();
+	const match = FILTER_PATTERN.exec(raw);
+	if (!match) unsupported();
+	const attribute = allowed.find(
+		(name) => name.toLowerCase() === match![1]!.toLowerCase(),
+	);
+	if (!attribute) unsupported();
+	return {
+		attribute: attribute!,
+		value: match![3]!.replaceAll(/\\(.)/g, '$1'),
+	};
+}
+
+export type ScimPatchOperationKind = 'add' | 'replace' | 'remove';
+
+export interface ScimPatchOperation {
+	readonly op: ScimPatchOperationKind;
+	readonly path: string | null;
+	readonly value: unknown;
+}
+
+const MAX_PATCH_OPERATIONS = 100;
+
+export function parsePatch(
+	body: Record<string, unknown>,
+): readonly ScimPatchOperation[] {
+	const operations = body.Operations ?? body.operations;
+	if (
+		!Array.isArray(operations) ||
+		operations.length === 0 ||
+		operations.length > MAX_PATCH_OPERATIONS
+	) {
+		throw new ScimError(
+			400,
+			'invalidValue',
+			DIRECTORY_REASONS.invalidValue,
+			`Operations must be an array of 1 to ${MAX_PATCH_OPERATIONS} entries.`,
+		);
+	}
+	return operations.map((entry: unknown) => {
+		const record = (entry ?? {}) as Record<string, unknown>;
+		const op = String(record.op ?? '').toLowerCase();
+		if (op !== 'add' && op !== 'replace' && op !== 'remove') {
+			throw new ScimError(
+				400,
+				'invalidValue',
+				DIRECTORY_REASONS.unsupportedOperation,
+				'op must be add, replace or remove.',
+			);
+		}
+		const path = record.path;
+		if (path !== undefined && (typeof path !== 'string' || path.length > 256)) {
+			throw new ScimError(
+				400,
+				'noTarget',
+				DIRECTORY_REASONS.unsupportedPath,
+				'path must be an attribute name.',
+			);
+		}
+		return {
+			op,
+			path: typeof path === 'string' && path.trim() !== '' ? path.trim() : null,
+			value: record.value,
+		};
+	});
+}
+
+export interface ScimMeta {
+	readonly resourceType: 'User' | 'Group';
+	readonly created: string;
+	readonly lastModified: string;
+	readonly location: string;
+}
+
+export function scimMeta(input: {
+	readonly resourceType: 'User' | 'Group';
+	readonly createdAt: number;
+	readonly updatedAt: number;
+	readonly baseUrl: string;
+	readonly id: string;
+}): ScimMeta {
+	return {
+		resourceType: input.resourceType,
+		created: new Date(input.createdAt).toISOString(),
+		lastModified: new Date(input.updatedAt).toISOString(),
+		location: `${input.baseUrl}/${input.resourceType}s/${input.id}`,
+	};
+}
+
+/** The discovery answers; every capability this version does not implement is declared false. */
+export function serviceProviderConfig(
+	baseUrl: string,
+	maxResults: number,
+): Record<string, unknown> {
+	return {
+		schemas: [SCIM_SCHEMAS.serviceProviderConfig],
+		documentationUri: `${baseUrl}/ServiceProviderConfig`,
+		patch: { supported: true },
+		bulk: { supported: false, maxOperations: 0, maxPayloadSize: 0 },
+		filter: { supported: true, maxResults },
+		changePassword: { supported: false },
+		sort: { supported: false },
+		etag: { supported: false },
+		authenticationSchemes: [
+			{
+				type: 'oauthbearertoken',
+				name: 'OAuth Bearer Token',
+				description:
+					'A workspace-scoped SCIM token sent as Authorization: Bearer.',
+				primary: true,
+			},
+		],
+		meta: {
+			resourceType: 'ServiceProviderConfig',
+			location: `${baseUrl}/ServiceProviderConfig`,
+		},
+	};
+}
+
+export function resourceTypes(baseUrl: string): readonly unknown[] {
+	return (['User', 'Group'] as const).map((name) => ({
+		schemas: [SCIM_SCHEMAS.resourceType],
+		id: name,
+		name,
+		endpoint: `/${name}s`,
+		description: `${name} resources of this workspace.`,
+		schema: name === 'User' ? SCIM_SCHEMAS.user : SCIM_SCHEMAS.group,
+		meta: {
+			resourceType: 'ResourceType',
+			location: `${baseUrl}/ResourceTypes/${name}`,
+		},
+	}));
+}
+
+/* The minimal declaration of the attributes this version actually reads and
+   writes. An attribute absent here is one the provider must not expect back. */
+export function schemas(baseUrl: string): readonly unknown[] {
+	const attribute = (
+		name: string,
+		type: 'string' | 'boolean' | 'complex',
+		mutability: 'readWrite' | 'readOnly' | 'immutable',
+		multiValued = false,
+	) => ({
+		name,
+		type,
+		multiValued,
+		required: false,
+		caseExact: false,
+		mutability,
+		returned: 'default',
+		uniqueness: 'none',
+	});
+	return [
+		{
+			schemas: [SCIM_SCHEMAS.schema],
+			id: SCIM_SCHEMAS.user,
+			name: 'User',
+			description: 'A workspace member provisioned by an identity provider.',
+			attributes: [
+				attribute('userName', 'string', 'immutable'),
+				attribute('externalId', 'string', 'readWrite'),
+				attribute('displayName', 'string', 'readWrite'),
+				attribute('name', 'complex', 'readWrite'),
+				attribute('emails', 'complex', 'readOnly', true),
+				attribute('active', 'boolean', 'readWrite'),
+			],
+			meta: {
+				resourceType: 'Schema',
+				location: `${baseUrl}/Schemas/${SCIM_SCHEMAS.user}`,
+			},
+		},
+		{
+			schemas: [SCIM_SCHEMAS.schema],
+			id: SCIM_SCHEMAS.group,
+			name: 'Group',
+			description: 'A provider group, optionally mapped to a workspace role.',
+			attributes: [
+				attribute('displayName', 'string', 'readWrite'),
+				attribute('externalId', 'string', 'readWrite'),
+				attribute('members', 'complex', 'readWrite', true),
+			],
+			meta: {
+				resourceType: 'Schema',
+				location: `${baseUrl}/Schemas/${SCIM_SCHEMAS.group}`,
+			},
+		},
+	];
+}

package/modules/directory/src/domain/types.ts

@@ -0,0 +1,166 @@
+export const SCIM_TOKEN_STATUSES = ['active', 'revoked'] as const;
+
+export type ScimTokenStatus = (typeof SCIM_TOKEN_STATUSES)[number];
+
+/** A SCIM credential as anyone may read it: the secret is never part of it. */
+export interface ScimToken {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly label: string;
+	/** Truncated SHA-256 of the token, also the authentication lookup key. */
+	readonly tokenFingerprint: string;
+	readonly status: ScimTokenStatus;
+	readonly createdBy: string;
+	readonly createdAt: number;
+	readonly lastUsedAt: number | null;
+	readonly expiresAt: number | null;
+	readonly revokedAt: number | null;
+}
+
+/** The one moment the token value exists outside the provider's configuration. */
+export interface IssuedScimToken {
+	readonly record: ScimToken;
+	readonly token: string;
+}
+
+export const LIST_DIRECTIONS = ['asc', 'desc'] as const;
+
+export type ListDirection = (typeof LIST_DIRECTIONS)[number];
+
+/**
+ * Where a screen page ends: the sort value of its last row, then the id. The
+ * sort value is the column as the database ordered it, so a case-folded label
+ * travels folded and a page resumes exactly where the previous one stopped.
+ */
+export interface ListPosition {
+	readonly key: string | number;
+	readonly id: string;
+}
+
+export interface ListPage<Record> {
+	readonly items: readonly Record[];
+	/** Null when the page was short: nothing follows it. */
+	readonly next: ListPosition | null;
+}
+
+export const TOKEN_SORT_KEYS = ['label'] as const;
+
+export type TokenSortKey = (typeof TOKEN_SORT_KEYS)[number];
+
+export interface TokenListQuery {
+	readonly status?: ScimTokenStatus | undefined;
+	/** A label substring, matched without case. */
+	readonly search?: string | undefined;
+	readonly sort: TokenSortKey;
+	readonly direction: ListDirection;
+	readonly limit: number;
+	readonly after?: ListPosition | undefined;
+}
+
+export const GROUP_SORT_KEYS = ['precedence', 'displayName'] as const;
+
+export type GroupSortKey = (typeof GROUP_SORT_KEYS)[number];
+
+export interface GroupListQuery {
+	/** A display name substring, matched without case. */
+	readonly search?: string | undefined;
+	readonly sort: GroupSortKey;
+	readonly direction: ListDirection;
+	readonly limit: number;
+	readonly after?: ListPosition | undefined;
+}
+
+export interface ScimUserMapping {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly externalId: string | null;
+	readonly userName: string;
+	readonly accountId: string;
+	readonly active: boolean;
+	readonly createdAt: number;
+	readonly lastSyncedAt: number;
+}
+
+export interface ScimGroupMapping {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly externalId: string | null;
+	readonly displayName: string;
+	/** Empty means the group is tracked but grants nothing. */
+	readonly roleKey: string | null;
+	readonly precedence: number;
+	/** Derived from the membership rows; no counter is stored. */
+	readonly memberCount: number;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+}
+
+export const PROVISIONING_OPERATIONS = [
+	'user-create',
+	'user-update',
+	'user-deactivate',
+	'user-reactivate',
+	'group-create',
+	'group-update',
+	'group-delete',
+	'membership-change',
+] as const;
+
+export type ProvisioningOperation = (typeof PROVISIONING_OPERATIONS)[number];
+
+export const PROVISIONING_OUTCOMES = [
+	'applied',
+	'unchanged',
+	'refused',
+] as const;
+
+export type ProvisioningOutcome = (typeof PROVISIONING_OUTCOMES)[number];
+
+export interface ProvisioningEvent {
+	readonly id: string;
+	/** Storage order within one millisecond; the log is read by it. */
+	readonly sequence: number;
+	readonly tenantId: string;
+	readonly tokenId: string;
+	readonly operation: ProvisioningOperation;
+	readonly subject: string;
+	readonly outcome: ProvisioningOutcome;
+	readonly reason: string | null;
+	readonly occurredAt: number;
+}
+
+/** The keyset of the last row of a page: `(occurredAt, sequence)` descending. */
+export interface ProvisioningEventCursor {
+	readonly occurredAt: number;
+	readonly sequence: number;
+}
+
+export interface ProvisioningEventQuery {
+	readonly operation?: ProvisioningOperation | undefined;
+	readonly outcome?: ProvisioningOutcome | undefined;
+	readonly limit: number;
+	readonly cursor?: ProvisioningEventCursor | undefined;
+}
+
+/** Stable reason codes. They travel in the log and in every SCIM refusal. */
+export const DIRECTORY_REASONS = {
+	accountInUse: 'ACCOUNT_IN_USE',
+	defaultRoleUnknown: 'DEFAULT_ROLE_UNKNOWN',
+	groupExists: 'GROUP_EXISTS',
+	groupNotFound: 'GROUP_NOT_FOUND',
+	immutableEmail: 'IMMUTABLE_EMAIL',
+	immutableUserName: 'IMMUTABLE_USER_NAME',
+	invalidValue: 'INVALID_VALUE',
+	lastOwner: 'LAST_OWNER',
+	memberNotFound: 'MEMBER_NOT_FOUND',
+	noEnabledProvider: 'NO_ENABLED_PROVIDER',
+	rateLimited: 'RATE_LIMITED',
+	rollbackFailed: 'ROLLBACK_FAILED',
+	roleUnknown: 'ROLE_UNKNOWN',
+	unauthorized: 'UNAUTHORIZED',
+	unsupportedFilter: 'UNSUPPORTED_FILTER',
+	unsupportedOperation: 'UNSUPPORTED_OPERATION',
+	unsupportedPath: 'UNSUPPORTED_PATH',
+	userExists: 'USER_EXISTS',
+	userNotFound: 'USER_NOT_FOUND',
+} as const;

package/modules/directory/src/index.ts

@@ -0,0 +1,44 @@
+import type { ModuleManifest, RegisteredModule } from '@flowdular/sdk/contracts';
+import manifest from '../module.json' with { type: 'json' };
+import { DIRECTORY_PERMISSIONS } from './acl/permissions.ts';
+
+export const moduleDefinition = {
+	manifest: manifest as ModuleManifest,
+	navigation: [
+		{
+			id: 'directory.navigation',
+			label: 'SCIM tokens',
+			href: '/directory-tokens',
+			order: 70,
+			permission: DIRECTORY_PERMISSIONS.read,
+		},
+	],
+	permissions: Object.values(DIRECTORY_PERMISSIONS),
+} satisfies RegisteredModule;
+
+export { DIRECTORY_PERMISSIONS } from './acl/permissions.ts';
+export {
+	DIRECTORY_MODULE_ID,
+	DIRECTORY_MODULE_SETTINGS,
+	directoryDefaultRole,
+	directoryPageSizeMax,
+} from './settings.ts';
+export { SCIM_SCHEMAS, ScimError } from './domain/scim.ts';
+export {
+	DIRECTORY_REASONS,
+	PROVISIONING_OPERATIONS,
+	PROVISIONING_OUTCOMES,
+	SCIM_TOKEN_STATUSES,
+} from './domain/types.ts';
+export type {
+	IssuedScimToken,
+	ProvisioningEvent,
+	ProvisioningEventQuery,
+	ProvisioningOperation,
+	ProvisioningOutcome,
+	ScimGroupMapping,
+	ScimToken,
+	ScimTokenStatus,
+	ScimUserMapping,
+} from './domain/types.ts';
+export { DirectoryServiceError } from './services/service-error.ts';

package/modules/directory/src/platform.ts

@@ -0,0 +1,43 @@
+import type {
+	PlatformServerComposition,
+	PlatformServerContext,
+} from '@flowdular/sdk/modules/auth/server';
+import {
+	authPortFromRuntime,
+	createDirectoryRoutes,
+	createDirectoryRuntime,
+	createScimRoutes,
+} from './server/index.ts';
+import { directoryDataClasses } from './services/data-classes.ts';
+import { DIRECTORY_MODULE_SETTINGS } from './settings.ts';
+
+export function createServerComposition(
+	context: PlatformServerContext,
+): PlatformServerComposition {
+	const auth = authPortFromRuntime(context.auth);
+	const runtime = createDirectoryRuntime({
+		databases: context.databases,
+		purpose:
+			context.environment.NODE_ENV === 'test'
+				? 'test'
+				: context.environment.NODE_ENV === 'production'
+					? 'runtime'
+					: 'preview',
+		auth,
+	});
+	/* The sweep and the export run here, on this module's own leases and under
+	   its own tenant transaction; the platform only holds the declaration. */
+	context.dataClasses.declare(
+		directoryDataClasses(() => runtime.administration()),
+	);
+	return {
+		routes: [
+			...createDirectoryRoutes(context.auth, runtime, context.settings),
+			...createScimRoutes(auth, runtime, context.settings, {
+				trustProxy: context.auth.trustProxy,
+			}),
+		],
+		settings: DIRECTORY_MODULE_SETTINGS,
+		dispose: () => runtime.dispose(),
+	};
+}

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

@@ -0,0 +1,17 @@
+export { createDirectoryRoutes, endpoints } from '../api/endpoints.ts';
+export {
+	createScimRoutes,
+	scimEndpoints,
+	SCIM_BASE_PATH,
+} from '../api/scim-endpoints.ts';
+export {
+	authPortFromRuntime,
+	scimActor,
+	type DirectoryAuthPort,
+} from '../services/auth-port.ts';
+export {
+	DatabaseDirectoryRepository,
+	migrateDirectoryDatabase,
+} from '../services/database-repository.ts';
+export { createDirectoryRuntime } from './runtime.ts';
+export type { DirectoryRuntime, DirectoryRuntimeOptions } from './runtime.ts';