@flowdular/sdk 0.2.4 → 0.3.0

package/modules/directory/src/services/rate-limiter.ts

@@ -0,0 +1,103 @@
+/** How many of the oldest windows one eviction drops. */
+const EVICTION_BATCH = 64;
+
+interface Window {
+	count: number;
+	startedAt: number;
+}
+
+/**
+ * Fixed windows over two dimensions of one SCIM surface.
+ *
+ * `allow` budgets the credential itself, keyed by the fingerprint the caller's
+ * own token derives to, so the map never holds a secret. That window alone
+ * gives every invented credential a budget of its own, so `recordRefusal`
+ * budgets the caller behind them, keyed by the workspace and the remote
+ * address: a flood of invented tokens spends one window instead of one each.
+ * The caller window is charged and read only where a credential did not
+ * resolve, so a provider presenting a real token is never held back by someone
+ * else's flood, whatever the two have in common.
+ *
+ * Bounded: the map evicts once it reaches capacity, dropping expired windows
+ * first and the least recently used ones after them, so a flood of invented
+ * credentials cannot grow it without limit or push out a window in use. The
+ * limits are per process, so a deployment running several instances gives one
+ * token that budget on each of them.
+ */
+export class ScimRateLimiter {
+	readonly #windows = new Map<string, Window>();
+
+	constructor(
+		private readonly limit = 600,
+		private readonly windowMs = 60_000,
+		private readonly capacity = 1_000,
+		/** Credentials one caller may present unresolved before it is cut off. */
+		private readonly refusalLimit = 60,
+	) {}
+
+	allow(key: string, now: number): boolean {
+		const current = this.#live(key, now);
+		if (!current) {
+			this.#start(key, now);
+			return true;
+		}
+		current.count += 1;
+		return current.count <= this.limit;
+	}
+
+	/** Whether the caller has refusals left; asking never spends one. */
+	withinRefusalBudget(key: string, now: number): boolean {
+		return (this.#live(key, now)?.count ?? 0) < this.refusalLimit;
+	}
+
+	recordRefusal(key: string, now: number): void {
+		const current = this.#live(key, now);
+		if (current) current.count += 1;
+		else this.#start(key, now);
+	}
+
+	/**
+	 * The window of `key` while it is still open, or null. Insertion order is
+	 * the recency order eviction reads, so a live window is re-inserted on every
+	 * touch and an expired one is dropped where it is found.
+	 */
+	#live(key: string, now: number): Window | null {
+		const current = this.#windows.get(key);
+		if (!current) return null;
+		this.#windows.delete(key);
+		if (now - current.startedAt >= this.windowMs) return null;
+		this.#windows.set(key, current);
+		return current;
+	}
+
+	#start(key: string, now: number): void {
+		if (this.#windows.size >= this.capacity) this.#evict(now);
+		this.#windows.set(key, { count: 1, startedAt: now });
+	}
+
+	/* One pass at most, and only once per batch of new windows after the map is
+	   full, so the amortized cost of an insertion stays a small constant.
+	   Expired windows fill the batch first because they hold no budget anyone
+	   can spend; the least recently used open windows fill whatever is left. */
+	#evict(now: number): void {
+		let dropped = 0;
+		const idle: string[] = [];
+		for (const [key, window] of this.#windows) {
+			if (now - window.startedAt >= this.windowMs) {
+				this.#windows.delete(key);
+				dropped += 1;
+				if (dropped >= EVICTION_BATCH) return;
+			} else if (idle.length < EVICTION_BATCH) {
+				idle.push(key);
+			}
+		}
+		/* `idle` is in least-recently-used order and the map never empties, so
+		   the window of whoever is using the surface right now is the last one
+		   an eviction would ever reach. */
+		for (const key of idle) {
+			if (dropped >= EVICTION_BATCH || this.#windows.size <= 1) return;
+			this.#windows.delete(key);
+			dropped += 1;
+		}
+	}
+}

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

@@ -0,0 +1,208 @@
+import type {
+	GroupListQuery,
+	ListPage,
+	ProvisioningEvent,
+	ProvisioningEventQuery,
+	ScimGroupMapping,
+	ScimToken,
+	ScimUserMapping,
+	TokenListQuery,
+} from '../domain/types.ts';
+
+/** A stored token with the secret material authentication compares against. */
+export interface ScimTokenSecret extends ScimToken {
+	readonly tokenHash: string;
+}
+
+export interface ScimUserFilter {
+	readonly userName?: string | undefined;
+	readonly externalId?: string | undefined;
+	readonly id?: string | undefined;
+}
+
+export interface ScimGroupFilter {
+	readonly displayName?: string | undefined;
+	readonly externalId?: string | undefined;
+	readonly id?: string | undefined;
+}
+
+export interface ScimSlice<Record> {
+	readonly records: readonly Record[];
+	readonly totalResults: number;
+}
+
+export interface ScimPageRequest {
+	/** 1-based, as the SCIM protocol counts. */
+	readonly startIndex: number;
+	readonly count: number;
+}
+
+/** One member of a group with the role its mapped groups currently resolve to. */
+export interface ResolvedGroupMember {
+	readonly userId: string;
+	readonly accountId: string;
+	readonly roleKey: string | null;
+}
+
+export interface GroupMemberRow {
+	readonly groupId: string;
+	readonly userId: string;
+	readonly userName: string;
+}
+
+export interface GroupMemberChange {
+	readonly added: readonly string[];
+	readonly removed: readonly string[];
+}
+
+/**
+ * One membership operation as the provider sent it. `set` replaces the whole
+ * membership; the steps of a request are applied in the order received, which
+ * is what makes two operations on the same member resolve the way SCIM says.
+ */
+export interface GroupMemberStep {
+	readonly kind: 'set' | 'add' | 'remove';
+	readonly members: readonly string[];
+}
+
+/**
+ * Async and database-agnostic. Every method takes the trusted tenant id, which
+ * the transaction binds as the row-security context as well.
+ */
+export interface DirectoryRepository {
+	/** One screen page; the tokens of a workspace are never read whole. */
+	listTokenPage(
+		tenantId: string,
+		query: TokenListQuery,
+	): Promise<ListPage<ScimToken>>;
+	findTokenById(tenantId: string, id: string): Promise<ScimToken | null>;
+	findTokenByFingerprint(
+		tenantId: string,
+		fingerprint: string,
+	): Promise<ScimTokenSecret | null>;
+	insertToken(record: ScimTokenSecret): Promise<void>;
+	replaceTokenSecret(input: {
+		readonly tenantId: string;
+		readonly id: string;
+		readonly tokenFingerprint: string;
+		readonly tokenHash: string;
+		readonly expiresAt: number | null;
+	}): Promise<boolean>;
+	revokeToken(
+		tenantId: string,
+		id: string,
+		revokedAt: number,
+	): Promise<boolean>;
+	touchToken(tenantId: string, id: string, usedAt: number): Promise<void>;
+
+	listUsers(
+		tenantId: string,
+		filter: ScimUserFilter,
+		page: ScimPageRequest,
+	): Promise<ScimSlice<ScimUserMapping>>;
+	findUserById(tenantId: string, id: string): Promise<ScimUserMapping | null>;
+	/** One query for a bounded set of ids, so a member list costs one round trip. */
+	findUsersByIds(
+		tenantId: string,
+		ids: readonly string[],
+	): Promise<readonly ScimUserMapping[]>;
+	findUserByUserName(
+		tenantId: string,
+		userName: string,
+	): Promise<ScimUserMapping | null>;
+	insertUser(record: ScimUserMapping): Promise<void>;
+	updateUser(input: {
+		readonly tenantId: string;
+		readonly id: string;
+		readonly externalId: string | null;
+		readonly active: boolean;
+		readonly lastSyncedAt: number;
+	}): Promise<void>;
+
+	/** The SCIM listing: offset paged with a total, as the protocol reads. */
+	listGroups(
+		tenantId: string,
+		filter: ScimGroupFilter,
+		page: ScimPageRequest,
+	): Promise<ScimSlice<ScimGroupMapping>>;
+	/** The screen listing: one keyset page over the same rows. */
+	listGroupPage(
+		tenantId: string,
+		query: GroupListQuery,
+	): Promise<ListPage<ScimGroupMapping>>;
+	findGroupById(tenantId: string, id: string): Promise<ScimGroupMapping | null>;
+	insertGroup(record: Omit<ScimGroupMapping, 'memberCount'>): Promise<void>;
+	updateGroup(input: {
+		readonly tenantId: string;
+		readonly id: string;
+		readonly externalId: string | null;
+		readonly displayName: string;
+		readonly roleKey: string | null;
+		readonly precedence: number;
+		readonly updatedAt: number;
+	}): Promise<void>;
+	deleteGroup(tenantId: string, id: string): Promise<boolean>;
+
+	listGroupMemberIds(
+		tenantId: string,
+		groupId: string,
+	): Promise<readonly string[]>;
+	/**
+	 * One query for a whole page of groups, bounded per group: a listing must
+	 * not be able to load a workspace's entire membership into one response.
+	 */
+	listMembersOfGroups(
+		tenantId: string,
+		groupIds: readonly string[],
+		perGroupLimit: number,
+	): Promise<readonly GroupMemberRow[]>;
+	/**
+	 * Applies the steps in order inside one transaction and returns what
+	 * actually changed, so a repeat of the same state writes nothing.
+	 */
+	applyGroupMembers(input: {
+		readonly tenantId: string;
+		readonly groupId: string;
+		readonly steps: readonly GroupMemberStep[];
+		readonly now: number;
+	}): Promise<GroupMemberChange>;
+
+	/**
+	 * The winning role of every member of the group, and of every named user,
+	 * from one precedence rule: the mapped group with the lowest precedence, or
+	 * null when none applies. A named user who belongs to no group answers with
+	 * a null role rather than not at all.
+	 */
+	resolvedRolesForGroup(
+		tenantId: string,
+		groupId: string,
+	): Promise<readonly ResolvedGroupMember[]>;
+	resolvedRolesForUsers(
+		tenantId: string,
+		userIds: readonly string[],
+	): Promise<readonly ResolvedGroupMember[]>;
+
+	/** The sequence is assigned by storage, so a caller never supplies one. */
+	appendEvent(event: Omit<ProvisioningEvent, 'sequence'>): Promise<void>;
+	/** One workspace's events in as few statements as the batch size allows. */
+	appendEvents(
+		events: readonly Omit<ProvisioningEvent, 'sequence'>[],
+	): Promise<void>;
+	listEvents(
+		tenantId: string,
+		query: ProvisioningEventQuery,
+	): Promise<readonly ProvisioningEvent[]>;
+
+	/** Removes at most `limit` events that occurred strictly before `before`. */
+	sweepEvents(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<{ readonly removed: number }>;
+	/** One export page, ordered by the storage sequence the log is written in. */
+	exportEventsPage(
+		tenantId: string,
+		afterSequence: number,
+		limit: number,
+	): Promise<readonly ProvisioningEvent[]>;
+}

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

@@ -0,0 +1,42 @@
+/** Refusals of the administration API. The SCIM surface raises `ScimError`. */
+export class DirectoryServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'DirectoryServiceError';
+	}
+}
+
+/* A control character reaching a label or a role key would travel into a table
+   cell, a log line and a SCIM response, so it is refused at the boundary. */
+function printable(value: string): boolean {
+	for (let index = 0; index < value.length; index += 1) {
+		if (value.charCodeAt(index) < 0x20) return false;
+	}
+	return true;
+}
+
+export function bounded(
+	value: string,
+	field: string,
+	minimum: number,
+	maximum: number,
+): string {
+	const normalized = value.trim();
+	if (normalized.length < minimum || normalized.length > maximum) {
+		throw new DirectoryServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${minimum} and ${maximum} characters.`,
+		);
+	}
+	if (!printable(normalized)) {
+		throw new DirectoryServiceError(
+			'INVALID_INPUT',
+			`${field} contains an unsupported character.`,
+		);
+	}
+	return normalized;
+}

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

@@ -0,0 +1,215 @@
+import {
+	createHash,
+	randomBytes,
+	randomUUID,
+	timingSafeEqual,
+} from 'node:crypto';
+import type {
+	IssuedScimToken,
+	ListPage,
+	ScimToken,
+	TokenListQuery,
+} from '../domain/types.ts';
+import { DirectoryUniqueViolation } from './database-repository.ts';
+import type { DirectoryRepository } from './repository.ts';
+import { bounded, DirectoryServiceError } from './service-error.ts';
+
+/** Hard ceiling of one screen page, whatever a caller asks for. */
+export const MAX_LIST_PAGE = 200;
+
+/** Distinct from the member API token prefix, so the two can never be confused. */
+export const SCIM_TOKEN_PREFIX = 'fdscim_';
+
+const SCIM_TOKEN_PATTERN = /^fdscim_[A-Za-z0-9_-]{43}$/;
+const FINGERPRINT_LENGTH = 32;
+const MAX_TOKEN_LIFETIME_MS = 365 * 24 * 60 * 60 * 1_000;
+/** Bounds the write amplification of a busy provider to one row per minute. */
+const TOUCH_INTERVAL_MS = 60_000;
+
+export function hashScimToken(token: string): string {
+	return createHash('sha256').update(token).digest('hex');
+}
+
+export function scimTokenFingerprint(token: string): string {
+	return hashScimToken(token).slice(0, FINGERPRINT_LENGTH);
+}
+
+export interface CreateScimTokenInput {
+	readonly label: string;
+	readonly expiresAt: number | null;
+}
+
+export class ScimTokenService {
+	/* Compared against when no row matched, so an unknown credential costs the
+	   same comparison as a real one and cannot be timed apart. */
+	readonly #decoyHash = randomBytes(32).toString('hex');
+
+	constructor(
+		private readonly repository: DirectoryRepository,
+		private readonly now: () => number = Date.now,
+	) {}
+
+	list(tenantId: string, query: TokenListQuery): Promise<ListPage<ScimToken>> {
+		return this.repository.listTokenPage(tenantId, {
+			...query,
+			limit: Math.min(Math.max(query.limit, 1), MAX_LIST_PAGE),
+		});
+	}
+
+	async create(
+		tenantId: string,
+		createdBy: string,
+		input: CreateScimTokenInput,
+	): Promise<IssuedScimToken> {
+		const label = bounded(input.label, 'label', 2, 120);
+		const createdAt = this.now();
+		const expiresAt = this.#expiry(input.expiresAt, createdAt);
+		const token = mintToken();
+		const record = {
+			id: randomUUID(),
+			tenantId,
+			label,
+			tokenFingerprint: scimTokenFingerprint(token),
+			tokenHash: hashScimToken(token),
+			status: 'active' as const,
+			createdBy,
+			createdAt,
+			lastUsedAt: null,
+			expiresAt,
+			revokedAt: null,
+		};
+		try {
+			await this.repository.insertToken(record);
+		} catch (error) {
+			/* The unique index is the only authority on the label: a pre-read would
+			   answer from a state another request can move before the insert. */
+			if (error instanceof DirectoryUniqueViolation) {
+				throw new DirectoryServiceError(
+					'TOKEN_LABEL_EXISTS',
+					'A token with this label already exists in the workspace.',
+					409,
+				);
+			}
+			throw error;
+		}
+		const { tokenHash: _hash, ...visible } = record;
+		return { record: visible, token };
+	}
+
+	/* Rotation keeps the label and the identity of the credential so the log
+	   stays readable, and replaces the secret, which revokes the old value.
+	   Revocation is terminal: rotating a revoked token would put a working
+	   credential back on a label an owner already stopped. */
+	async rotate(
+		tenantId: string,
+		id: string,
+		expiresAt: number | null,
+	): Promise<IssuedScimToken> {
+		const current = await this.#require(tenantId, id);
+		if (current.status !== 'active') throw this.#revoked();
+		const token = mintToken();
+		const replaced = await this.repository.replaceTokenSecret({
+			tenantId,
+			id: current.id,
+			tokenFingerprint: scimTokenFingerprint(token),
+			tokenHash: hashScimToken(token),
+			expiresAt: this.#expiry(expiresAt, this.now()),
+		});
+		if (!replaced) {
+			/* The statement writes only an active row, so a revoke that landed
+			   between the read and the write answers the same refusal. */
+			const stored = await this.repository.findTokenById(tenantId, current.id);
+			throw stored && stored.status !== 'active'
+				? this.#revoked()
+				: this.#notFound();
+		}
+		const record = await this.repository.findTokenById(tenantId, current.id);
+		if (!record) throw this.#notFound();
+		return { record, token };
+	}
+
+	async revoke(tenantId: string, id: string): Promise<ScimToken> {
+		const current = await this.#require(tenantId, id);
+		if (current.status === 'revoked') return current;
+		await this.repository.revokeToken(tenantId, current.id, this.now());
+		return (await this.repository.findTokenById(tenantId, id)) ?? current;
+	}
+
+	/**
+	 * Resolves a presented credential to the token that authorizes the request,
+	 * or null. Every refusal answers the same way: the caller cannot tell an
+	 * unknown token from a revoked, expired or foreign one.
+	 */
+	async authenticate(
+		tenantId: string,
+		presented: string,
+	): Promise<ScimToken | null> {
+		if (!SCIM_TOKEN_PATTERN.test(presented)) return null;
+		const digest = hashScimToken(presented);
+		const record = await this.repository.findTokenByFingerprint(
+			tenantId,
+			digest.slice(0, FINGERPRINT_LENGTH),
+		);
+		const matches = equalHex(record?.tokenHash ?? this.#decoyHash, digest);
+		if (!record || !matches || record.status !== 'active') return null;
+		const now = this.now();
+		if (record.expiresAt !== null && record.expiresAt <= now) return null;
+		if (
+			record.lastUsedAt === null ||
+			now - record.lastUsedAt > TOUCH_INTERVAL_MS
+		) {
+			await this.repository.touchToken(tenantId, record.id, now);
+		}
+		const { tokenHash: _hash, ...visible } = record;
+		return visible;
+	}
+
+	async #require(tenantId: string, id: string): Promise<ScimToken> {
+		const record = await this.repository.findTokenById(
+			tenantId,
+			bounded(id, 'id', 1, 128),
+		);
+		if (!record) throw this.#notFound();
+		return record;
+	}
+
+	#notFound(): DirectoryServiceError {
+		return new DirectoryServiceError(
+			'TOKEN_NOT_FOUND',
+			'The token does not exist in this workspace.',
+			404,
+		);
+	}
+
+	#revoked(): DirectoryServiceError {
+		return new DirectoryServiceError(
+			'TOKEN_REVOKED',
+			'A revoked token cannot be rotated; create a new one instead.',
+			409,
+		);
+	}
+
+	#expiry(value: number | null, createdAt: number): number | null {
+		if (value === null) return null;
+		if (
+			!Number.isSafeInteger(value) ||
+			value <= createdAt ||
+			value - createdAt > MAX_TOKEN_LIFETIME_MS
+		) {
+			throw new DirectoryServiceError(
+				'INVALID_EXPIRY',
+				'Token expiry must be a future timestamp within one year.',
+			);
+		}
+		return value;
+	}
+}
+
+function mintToken(): string {
+	return SCIM_TOKEN_PREFIX + randomBytes(32).toString('base64url');
+}
+
+function equalHex(left: string, right: string): boolean {
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'));
+}

package/modules/directory/src/settings.ts

@@ -0,0 +1,86 @@
+import {
+	defineModuleSettings,
+	PLATFORM_SETTINGS_TENANT,
+	type ModuleSettingsRuntime,
+} from '@flowdular/sdk/kernel';
+
+export const DIRECTORY_MODULE_ID = 'directory.core';
+
+export const DIRECTORY_DEFAULT_ROLE = 'member';
+export const DIRECTORY_DEFAULT_PAGE_SIZE_MAX = 200;
+
+export const DIRECTORY_MODULE_SETTINGS = defineModuleSettings({
+	moduleId: DIRECTORY_MODULE_ID,
+	settings: {
+		defaultRole: {
+			type: 'string',
+			defaultValue: DIRECTORY_DEFAULT_ROLE,
+			max: 32,
+			visibility: 'shared',
+			client: false,
+			scope: 'tenant',
+			labelKey: 'directory.settings.defaultRole.label',
+			label: 'Default provisioned role',
+			descriptionKey: 'directory.settings.defaultRole.description',
+			description:
+				'The workspace role a provisioned user receives when no mapped group applies. It is checked against the workspace roles at the moment it is used.',
+		},
+		pageSizeMax: {
+			type: 'number',
+			defaultValue: DIRECTORY_DEFAULT_PAGE_SIZE_MAX,
+			min: 1,
+			max: 1_000,
+			visibility: 'shared',
+			client: false,
+			scope: 'platform',
+			labelKey: 'directory.settings.pageSizeMax.label',
+			label: 'Maximum SCIM page size',
+			descriptionKey: 'directory.settings.pageSizeMax.description',
+			description:
+				'Upper bound of the SCIM count parameter. A larger request is clamped to this value rather than refused.',
+		},
+	},
+});
+
+/* A setting read must never take a SCIM request down, so each accessor falls
+   back to the declared default when the runtime has not registered it yet. */
+function value<T extends string | number>(
+	settings: ModuleSettingsRuntime,
+	tenantId: string,
+	key: 'defaultRole' | 'pageSizeMax',
+	fallback: T,
+): T {
+	try {
+		return settings.get<T>(tenantId, DIRECTORY_MODULE_ID, key);
+	} catch {
+		return fallback;
+	}
+}
+
+export function directoryDefaultRole(
+	settings: ModuleSettingsRuntime,
+	tenantId: string,
+): string {
+	const stored = value(
+		settings,
+		tenantId,
+		'defaultRole',
+		DIRECTORY_DEFAULT_ROLE,
+	)
+		.trim()
+		.toLowerCase();
+	return stored === '' ? DIRECTORY_DEFAULT_ROLE : stored;
+}
+
+export function directoryPageSizeMax(settings: ModuleSettingsRuntime): number {
+	const stored = value(
+		settings,
+		PLATFORM_SETTINGS_TENANT,
+		'pageSizeMax',
+		DIRECTORY_DEFAULT_PAGE_SIZE_MAX,
+	);
+	if (!Number.isSafeInteger(stored) || stored < 1) {
+		return DIRECTORY_DEFAULT_PAGE_SIZE_MAX;
+	}
+	return Math.min(stored, 1_000);
+}