@flowdular/sdk 0.2.4 → 0.3.1

package/modules/access/src/server/runtime.ts

@@ -0,0 +1,105 @@
+import type {
+	DatabaseAdapterLease,
+	DatabaseProvider,
+	DatabaseProviderRequest,
+} from '@flowdular/sdk/database';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+} from '@flowdular/sdk/database';
+import { AccessService } from '../services/access-service.ts';
+import {
+	DatabaseAccessRepository,
+	migrateAccessDatabase,
+} from '../services/database-repository.ts';
+import type { AccessDirectory } from '../services/directory.ts';
+import type { AccessRepository } from '../services/repository.ts';
+
+export interface AccessRuntimeOptions {
+	/** Platform-owned provider. Modules never receive a DSN or a pool. */
+	readonly databases: DatabaseProvider;
+	readonly purpose: Exclude<DatabaseProviderRequest['purpose'], 'migration'>;
+	/** Where who-holds-what is read from; auth.core in a composed platform. */
+	readonly directory: AccessDirectory;
+	readonly now?: () => number;
+	/** Supplied by tests that own the lease themselves. */
+	readonly repository?: AccessRepository;
+}
+
+export interface AccessRuntime {
+	service(): Promise<AccessService>;
+	dispose(): Promise<void>;
+}
+
+export function createAccessRuntime(
+	options: AccessRuntimeOptions,
+): AccessRuntime {
+	let disposed = false;
+	let runtimeLeasePromise: Promise<DatabaseAdapterLease> | undefined;
+	let servicePromise: Promise<AccessService> | undefined;
+
+	const build = (repository: AccessRepository): AccessService =>
+		new AccessService({
+			repository,
+			directory: options.directory,
+			...(options.now ? { now: options.now } : {}),
+		});
+
+	/* Schema work runs on the migrator role and that lease is released before the
+	   runtime one is taken, so request handling never holds a schema owner. */
+	const initialize = async (): Promise<AccessService> => {
+		if (options.repository) return build(options.repository);
+		const migrationLease = await options.databases.acquire({
+			namespace: 'access.core',
+			purpose: 'migration',
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.MIGRATION_LOCK,
+					DATABASE_CAPABILITY_IDS.SCHEMA_INTROSPECTION,
+					DATABASE_CAPABILITY_IDS.TRANSACTIONAL_DDL,
+				],
+			},
+		});
+		try {
+			await migrateAccessDatabase(migrationLease.database);
+		} finally {
+			await migrationLease.release();
+		}
+		runtimeLeasePromise = options.databases.acquire({
+			namespace: 'access.core',
+			purpose: options.purpose,
+			requirements: {
+				dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+				capabilities: [
+					DATABASE_CAPABILITY_IDS.TRANSACTIONS,
+					DATABASE_CAPABILITY_IDS.TENANT_CONTEXT,
+				],
+			},
+		});
+		const lease = await runtimeLeasePromise;
+		return build(new DatabaseAccessRepository(lease.database));
+	};
+
+	return {
+		service: () => {
+			if (disposed) {
+				return Promise.reject(new Error('Access runtime is disposed.'));
+			}
+			servicePromise ??= initialize();
+			return servicePromise;
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			if (!runtimeLeasePromise) {
+				await servicePromise?.catch(() => undefined);
+			}
+			if (!runtimeLeasePromise) return;
+			const lease = await runtimeLeasePromise;
+			await lease.release();
+			runtimeLeasePromise = undefined;
+			servicePromise = undefined;
+		},
+	};
+}

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

@@ -0,0 +1,298 @@
+import { randomUUID } from 'node:crypto';
+import type { DataClassExportSink } from '@flowdular/sdk/kernel';
+import {
+	ACCESS_LIMITS,
+	type AccessAttestation,
+	type AccessChangePage,
+	type AccessReview,
+	type AccessReviewMemberPage,
+	type AccessWindow,
+	type AttestationPage,
+	type AttestationPosition,
+	type AuditPosition,
+} from '../domain/types.ts';
+import { walkAuditWindow } from './audit-window.ts';
+import type { AccessReportKind } from './changes.ts';
+import type { AccessDirectory } from './directory.ts';
+import type { AccessRepository } from './repository.ts';
+import { buildReview, reviewMembers } from './review.ts';
+
+export class AccessServiceError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly status = 400,
+	) {
+		super(message);
+		this.name = 'AccessServiceError';
+	}
+}
+
+const DAY_MS = 86_400_000;
+const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Rows one export page reads; the walk repeats until the ledger is done. */
+const EXPORT_PAGE = 200;
+
+function bounded(
+	value: string,
+	field: string,
+	minimum: number,
+	maximum: number,
+): string {
+	const normalized = typeof value === 'string' ? value.trim() : '';
+	if (normalized.length < minimum || normalized.length > maximum) {
+		throw new AccessServiceError(
+			'INVALID_INPUT',
+			`${field} must contain between ${minimum} and ${maximum} characters.`,
+		);
+	}
+	if (normalized.includes('\u0000')) {
+		throw new AccessServiceError(
+			'INVALID_INPUT',
+			`${field} contains an unsupported character.`,
+		);
+	}
+	return normalized;
+}
+
+/**
+ * A reported window is two UTC calendar dates with an inclusive end, bounded
+ * before anything is read so a report can never ask the trail for a decade.
+ */
+export function parseWindow(from: string, to: string): AccessWindow {
+	if (!CALENDAR_DATE.test(from) || !CALENDAR_DATE.test(to)) {
+		throw new AccessServiceError(
+			'INVALID_INPUT',
+			'from and to must be calendar dates in the form YYYY-MM-DD.',
+		);
+	}
+	const start = Date.parse(`${from}T00:00:00.000Z`);
+	const end = Date.parse(`${to}T23:59:59.999Z`);
+	/* A day past the end of its month parses by rolling over, so the parsed
+	   instant is compared back against the text: 2026-02-30 is not a date the
+	   reader meant and is refused rather than silently read as 2 March. */
+	if (
+		!Number.isSafeInteger(start) ||
+		!Number.isSafeInteger(end) ||
+		new Date(start).toISOString().slice(0, 10) !== from ||
+		new Date(end).toISOString().slice(0, 10) !== to
+	) {
+		throw new AccessServiceError(
+			'INVALID_INPUT',
+			'from and to must be real calendar dates.',
+		);
+	}
+	if (end < start) {
+		throw new AccessServiceError(
+			'RANGE_REVERSED',
+			'The end of the period is before its start.',
+		);
+	}
+	if (end - start > ACCESS_LIMITS.rangeDays * DAY_MS) {
+		throw new AccessServiceError(
+			'RANGE_TOO_LONG',
+			`A period covers at most ${ACCESS_LIMITS.rangeDays} days.`,
+		);
+	}
+	return { from: start, to: end };
+}
+
+export interface AccessServiceOptions {
+	readonly repository: AccessRepository;
+	readonly directory: AccessDirectory;
+	readonly now?: () => number;
+}
+
+export interface AttestInput {
+	readonly window: AccessWindow;
+	readonly note: string | null;
+}
+
+export interface Reviewer {
+	readonly accountId: string;
+	readonly label: string;
+}
+
+export class AccessService {
+	readonly #repository: AccessRepository;
+	readonly #directory: AccessDirectory;
+	readonly #now: () => number;
+
+	constructor(options: AccessServiceOptions) {
+		this.#repository = options.repository;
+		this.#directory = options.directory;
+		this.#now = options.now ?? (() => Date.now());
+	}
+
+	/** Who holds what right now, computed per call and never stored. */
+	review(tenantId: string): Promise<AccessReview> {
+		return buildReview(this.#directory, this.#tenant(tenantId), this.#now());
+	}
+
+	/**
+	 * One page of the review's memberships, walked by account id. The review
+	 * itself lists at most `ACCESS_LIMITS.members` and says it was capped, which
+	 * is honest for a screen and wrong for a file: a workspace past that bound
+	 * would export a truncated roll. This reads the uncapped paged surface
+	 * instead, so the number of pages grows with the workspace and what reaches
+	 * the file never depends on a listing bound.
+	 */
+	async memberPage(
+		tenantId: string,
+		cursor: string | null,
+		limit: number,
+	): Promise<AccessReviewMemberPage> {
+		const owner = this.#tenant(tenantId);
+		const [page, roles] = await Promise.all([
+			this.#directory.memberPage(
+				owner,
+				cursor,
+				this.#pageLimit(limit, ACCESS_LIMITS.memberPage),
+			),
+			this.#directory.roles(owner),
+		]);
+		return {
+			members: reviewMembers(page.members, roles),
+			nextCursor: page.nextCursor,
+		};
+	}
+
+	changes(
+		tenantId: string,
+		kind: AccessReportKind,
+		window: AccessWindow,
+		page: { readonly limit: number; readonly after: AuditPosition | null },
+	): Promise<AccessChangePage> {
+		return walkAuditWindow(this.#directory, this.#tenant(tenantId), {
+			window,
+			kind,
+			limit: this.#pageLimit(page.limit, ACCESS_LIMITS.reportLimit),
+			after: page.after,
+		});
+	}
+
+	/**
+	 * Records that someone reviewed the access of a period. The counts are the
+	 * server's own reading of the workspace at this moment: a caller supplies
+	 * the period and the note, never the evidence.
+	 */
+	async attest(
+		tenantId: string,
+		reviewer: Reviewer,
+		input: AttestInput,
+	): Promise<AccessAttestation> {
+		const owner = this.#tenant(tenantId);
+		const review = await this.review(owner);
+		return this.#repository.append({
+			id: randomUUID(),
+			tenantId: owner,
+			reviewerAccountId: bounded(
+				reviewer.accountId,
+				'reviewerAccountId',
+				1,
+				ACCESS_LIMITS.accountId,
+			),
+			reviewerLabel: bounded(
+				reviewer.label,
+				'reviewerLabel',
+				1,
+				ACCESS_LIMITS.label,
+			),
+			periodFrom: new Date(input.window.from).toISOString(),
+			periodTo: new Date(input.window.to).toISOString(),
+			memberCount: review.counts.members,
+			activeMemberCount: review.counts.activeMembers,
+			roleCount: review.counts.roles,
+			extraScopeCount: review.counts.extraScopeGrants,
+			tokenCount: review.counts.tokens,
+			providerCount: review.counts.providers,
+			note:
+				input.note === null
+					? null
+					: bounded(input.note, 'note', 1, ACCESS_LIMITS.note),
+			createdAt: this.#now(),
+		});
+	}
+
+	async attestations(
+		tenantId: string,
+		query: {
+			readonly limit: number;
+			readonly after: AttestationPosition | null;
+		},
+	): Promise<AttestationPage> {
+		const limit = this.#pageLimit(query.limit, ACCESS_LIMITS.attestationLimit);
+		const items = await this.#repository.list(this.#tenant(tenantId), {
+			limit,
+			after: query.after,
+		});
+		const last = items.at(-1);
+		return {
+			items,
+			/* A full page may still be the last one; a client stops when the
+			   cursor stops, which costs one empty page at most. */
+			next:
+				last && items.length === limit
+					? { createdAt: last.createdAt, id: last.id }
+					: null,
+		};
+	}
+
+	/** The data class export: the whole ledger of one workspace, oldest first. */
+	async exportAttestations(
+		tenantId: string,
+		sink: DataClassExportSink,
+	): Promise<{ rows: number; from: Date | null; to: Date | null }> {
+		const owner = this.#tenant(tenantId);
+		let after: AttestationPosition | null = null;
+		let rows = 0;
+		let from: number | null = null;
+		let to: number | null = null;
+		for (;;) {
+			const page: readonly AccessAttestation[] =
+				await this.#repository.exportPage(owner, after, EXPORT_PAGE);
+			for (const record of page) {
+				await sink.write({
+					id: record.id,
+					reviewerAccountId: record.reviewerAccountId,
+					reviewerLabel: record.reviewerLabel,
+					periodFrom: record.periodFrom,
+					periodTo: record.periodTo,
+					memberCount: record.memberCount,
+					activeMemberCount: record.activeMemberCount,
+					roleCount: record.roleCount,
+					extraScopeCount: record.extraScopeCount,
+					tokenCount: record.tokenCount,
+					providerCount: record.providerCount,
+					note: record.note,
+					createdAt: new Date(record.createdAt).toISOString(),
+				});
+				rows += 1;
+				if (from === null || record.createdAt < from) from = record.createdAt;
+				if (to === null || record.createdAt > to) to = record.createdAt;
+			}
+			if (page.length < EXPORT_PAGE) break;
+			const last = page[page.length - 1]!;
+			after = { createdAt: last.createdAt, id: last.id };
+		}
+		return {
+			rows,
+			from: from === null ? null : new Date(from),
+			to: to === null ? null : new Date(to),
+		};
+	}
+
+	#tenant(tenantId: string): string {
+		return bounded(tenantId, 'tenantId', 1, ACCESS_LIMITS.tenantId);
+	}
+
+	#pageLimit(limit: number, maximum: number): number {
+		if (!Number.isSafeInteger(limit) || limit < 1 || limit > maximum) {
+			throw new AccessServiceError(
+				'INVALID_INPUT',
+				`limit must be a whole number between 1 and ${maximum}.`,
+			);
+		}
+		return limit;
+	}
+}

package/modules/access/src/services/audit-window.ts

@@ -0,0 +1,78 @@
+import {
+	ACCESS_LIMITS,
+	type AccessChange,
+	type AccessChangePage,
+	type AccessWindow,
+	type AuditPosition,
+} from '../domain/types.ts';
+import {
+	changeCategory,
+	changeDetail,
+	type AccessReportKind,
+} from './changes.ts';
+import type { AccessDirectory, DirectoryAuditEvent } from './directory.ts';
+
+export interface WindowRequest {
+	readonly window: AccessWindow;
+	readonly kind: AccessReportKind;
+	readonly limit: number;
+	/** Where the previous request stopped scanning, not what it last showed. */
+	readonly after: AuditPosition | null;
+}
+
+function change(
+	event: DirectoryAuditEvent,
+	category: AccessChange['category'],
+): AccessChange {
+	return {
+		id: event.id,
+		occurredAt: event.occurredAt,
+		category,
+		action: event.action,
+		actor: event.actorLabel,
+		actorAccountId: event.actorAccountId,
+		actorKind: event.actorKind,
+		subjectType: event.subjectType,
+		subjectId: event.subjectId,
+		detail: changeDetail(event.metadata),
+	};
+}
+
+/**
+ * The bounded walk both reports run on. The window is the read's own predicate,
+ * so every event a page answers is inside it and the walk only has to bound
+ * itself: one call reads at most `ACCESS_LIMITS.auditPages` pages of the trail
+ * and answers the position it stopped scanning at, so a workspace with a long
+ * trail is paged rather than walked whole, and a page that matched nothing still
+ * moves the reader on. `next` is null once the window is exhausted, which is how
+ * a client knows to stop rather than by counting rows.
+ */
+export async function walkAuditWindow(
+	directory: AccessDirectory,
+	tenantId: string,
+	request: WindowRequest,
+): Promise<AccessChangePage> {
+	const items: AccessChange[] = [];
+	let position = request.after;
+	for (let page = 0; page < ACCESS_LIMITS.auditPages; page += 1) {
+		const events = await directory.auditPage(
+			tenantId,
+			request.window,
+			position,
+			ACCESS_LIMITS.auditPage,
+		);
+		for (const event of events) {
+			position = { occurredAt: event.occurredAt, id: event.id };
+			const category = changeCategory(event.action, request.kind);
+			if (category === null) continue;
+			items.push(change(event, category));
+			if (items.length === request.limit) {
+				return { items, window: request.window, next: position };
+			}
+		}
+		if (events.length < ACCESS_LIMITS.auditPage) {
+			return { items, window: request.window, next: null };
+		}
+	}
+	return { items, window: request.window, next: position };
+}

package/modules/access/src/services/auth-directory.ts

@@ -0,0 +1,72 @@
+import type { AuthRuntime } from '@flowdular/sdk/modules/auth/server';
+import type { AuditPosition } from '../domain/types.ts';
+import type {
+	AccessDirectory,
+	DirectoryAuditEvent,
+	DirectoryMember,
+	DirectoryMemberPage,
+	DirectoryProvider,
+	DirectoryRole,
+	DirectoryToken,
+} from './directory.ts';
+
+/* The auth service as the platform hands it over. Its class is not exported,
+   and access.core needs no more of it than the runtime's own signature says. */
+type AuthService = Awaited<ReturnType<AuthRuntime['service']>>;
+
+/**
+ * auth.core's audit query carries the window as an inclusive `from` and `to`
+ * over `occurredAt`, applied in SQL beside the keyset, and pages on a cursor of
+ * `${occurredAt}:${id}` that selects rows strictly before it, newest first.
+ * This adapter states the window and hands the position over; it never seeds a
+ * cursor at a ceiling or watches for a floor.
+ */
+function cursorOf(after: AuditPosition | null): string | null {
+	return after === null ? null : `${after.occurredAt}:${after.id}`;
+}
+
+/**
+ * The one place access.core depends on auth.core's read surface. Everything
+ * here is a read of the acting principal's own workspace; access.core opens no
+ * auth table and holds no copy of what it reads.
+ */
+export function authDirectory(auth: AuthRuntime): AccessDirectory {
+	const service = (): Promise<AuthService> => auth.service();
+	return {
+		async members(tenantId): Promise<readonly DirectoryMember[]> {
+			return (await service()).listTenantMembers(tenantId);
+		},
+		async memberPage(tenantId, cursor, limit): Promise<DirectoryMemberPage> {
+			const page = await (
+				await service()
+			).listTenantMembers(tenantId, { cursor, limit });
+			return { members: page.members, nextCursor: page.nextCursor };
+		},
+		async roles(tenantId): Promise<readonly DirectoryRole[]> {
+			return (await service()).listRoles(tenantId);
+		},
+		async tokens(tenantId): Promise<readonly DirectoryToken[]> {
+			return (await service()).listApiTokens(tenantId);
+		},
+		async providers(tenantId): Promise<readonly DirectoryProvider[]> {
+			return (await service()).identityProviders.list(tenantId);
+		},
+		async auditPage(
+			tenantId,
+			window,
+			after,
+			limit,
+		): Promise<readonly DirectoryAuditEvent[]> {
+			const page = await (
+				await service()
+			).queryAudit({
+				tenantId,
+				from: window.from,
+				to: window.to,
+				limit,
+				cursor: cursorOf(after),
+			});
+			return page.events;
+		},
+	};
+}

package/modules/access/src/services/changes.ts

@@ -0,0 +1,91 @@
+import { AUDIT_ACTIONS } from '@flowdular/sdk/modules/auth/server';
+import { ACCESS_LIMITS, type AccessChangeCategory } from '../domain/types.ts';
+
+/**
+ * Which recorded action belongs to which kind of change. This map is the one
+ * place access.core decides what counts as privileged: the diff reads the
+ * categories that change who holds what, the activity report reads every key.
+ * The action strings come from auth.core's own constants, so a renamed action
+ * fails to compile here instead of silently dropping out of both reports.
+ */
+export const ACTION_CATEGORIES: Readonly<Record<string, AccessChangeCategory>> =
+	Object.freeze({
+		[AUDIT_ACTIONS.memberCreated]: 'membership',
+		[AUDIT_ACTIONS.memberUpdated]: 'membership',
+		[AUDIT_ACTIONS.memberStatus]: 'membership',
+		[AUDIT_ACTIONS.memberProvisioned]: 'membership',
+		[AUDIT_ACTIONS.memberRemoved]: 'membership',
+		[AUDIT_ACTIONS.membershipStatus]: 'membership',
+		[AUDIT_ACTIONS.invitationCreated]: 'membership',
+		[AUDIT_ACTIONS.invitationAccepted]: 'membership',
+		[AUDIT_ACTIONS.memberRole]: 'role',
+		[AUDIT_ACTIONS.roleCreated]: 'role',
+		[AUDIT_ACTIONS.roleUpdated]: 'role',
+		[AUDIT_ACTIONS.roleDeleted]: 'role',
+		[AUDIT_ACTIONS.memberScopes]: 'scope',
+		[AUDIT_ACTIONS.tokenIssued]: 'token',
+		[AUDIT_ACTIONS.tokenRevoked]: 'token',
+		[AUDIT_ACTIONS.providerCreated]: 'provider',
+		[AUDIT_ACTIONS.providerUpdated]: 'provider',
+		[AUDIT_ACTIONS.providerStatusChanged]: 'provider',
+		[AUDIT_ACTIONS.providerSecretRotated]: 'provider',
+		[AUDIT_ACTIONS.providerDeleted]: 'provider',
+		[AUDIT_ACTIONS.settingsUpdated]: 'settings',
+		[AUDIT_ACTIONS.settingsFlagChanged]: 'settings',
+		[AUDIT_ACTIONS.memberPasswordReset]: 'security',
+		[AUDIT_ACTIONS.mfaReset]: 'security',
+		[AUDIT_ACTIONS.tenantRenamed]: 'security',
+		[AUDIT_ACTIONS.workspaceProvisioned]: 'security',
+	});
+
+/* What the diff answers: the changes that move access from one holder to
+   another. A settings edit or a password reset is administrative activity but
+   grants nobody anything, so it stays out of the diff and in the report. */
+const DIFF_CATEGORIES: ReadonlySet<AccessChangeCategory> = new Set([
+	'membership',
+	'role',
+	'scope',
+	'token',
+	'provider',
+]);
+
+export type AccessReportKind = 'diff' | 'activity';
+
+/** O(1) per audit row, which is what keeps the bounded walk cheap. */
+export function changeCategory(
+	action: string,
+	kind: AccessReportKind,
+): AccessChangeCategory | null {
+	const category = ACTION_CATEGORIES[action];
+	if (category === undefined) return null;
+	if (kind === 'activity') return category;
+	return DIFF_CATEGORIES.has(category) ? category : null;
+}
+
+/* Metadata keys worth showing beside a change. Everything else recorded with
+   an event stays out of the report: auth.core keeps credentials out of the
+   trail, and a report that forwarded whatever it found would carry whatever a
+   later action starts recording. */
+const DETAIL_KEYS = ['role', 'key', 'label', 'status', 'scopes', 'cleared'];
+
+/**
+ * A bounded, readable summary of one event's metadata: at most one entry per
+ * known key, each value clipped, a list reported by its length because a scope
+ * list belongs on the review rather than in a change line.
+ */
+export function changeDetail(
+	metadata: Readonly<Record<string, unknown>>,
+): string | null {
+	const parts: string[] = [];
+	for (const key of DETAIL_KEYS) {
+		const value = metadata[key];
+		if (value === undefined || value === null) continue;
+		if (Array.isArray(value)) {
+			parts.push(`${key}=${value.length}`);
+			continue;
+		}
+		if (typeof value === 'object') continue;
+		parts.push(`${key}=${String(value).slice(0, ACCESS_LIMITS.detailValue)}`);
+	}
+	return parts.length === 0 ? null : parts.join(', ');
+}

package/modules/access/src/services/data-classes.ts

@@ -0,0 +1,28 @@
+import type { DataClassDeclaration } from '@flowdular/sdk/kernel';
+import type { AccessService } from './access-service.ts';
+
+/**
+ * The one class access.core owns. Attestations are the evidence that someone
+ * reviewed a workspace's access, so they are kept until a person deletes them:
+ * no sweep, and no erase either, which makes an erasure certificate name the
+ * class as not erasable rather than quietly removing the record that a review
+ * happened. Export is supported, because a workspace export is what an auditor
+ * asks for.
+ *
+ * The service arrives as a thunk because declaring happens while the platform
+ * composes, before anything has opened a database.
+ */
+export function accessDataClasses(
+	service: () => Promise<AccessService>,
+): readonly DataClassDeclaration[] {
+	return [
+		{
+			key: 'attestations',
+			label: 'Access attestations',
+			defaultRetentionDays: null,
+			exportable: true,
+			export: async (input) =>
+				(await service()).exportAttestations(input.tenantId, input.sink),
+		},
+	];
+}