@flowdular/sdk 0.2.4 → 0.3.1

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

@@ -0,0 +1,637 @@
+import { randomUUID } from 'node:crypto';
+import {
+	issueApprovalGrant,
+	type ApprovalGrantKeyring,
+} from '@flowdular/sdk/kernel';
+import {
+	APPROVAL_LIMITS,
+	type ApprovalRequestFilter,
+	type ApprovalsRequests,
+	type OpenApprovalInput,
+} from '../domain/capability.ts';
+import {
+	APPROVAL_GRANT_TTL_MS,
+	decodeCapabilitySubjectRef,
+} from '../domain/grant.ts';
+import {
+	APPROVAL_STATUSES,
+	type ApprovalAuditEntry,
+	type ApprovalDecideOutcome,
+	type ApprovalDecision,
+	type ApprovalListPage,
+	type ApprovalMember,
+	type ApprovalRequest,
+	type ApprovalRequestDetail,
+	type ApprovalRouting,
+	type ApprovalViewerRights,
+	type TerminalApprovalStatus,
+} from '../domain/types.ts';
+import {
+	createApprovalCallbackRegistry,
+	type ApprovalCallbackRegistry,
+} from './callbacks.ts';
+import {
+	memberSatisfies,
+	normalizeRequirement,
+	resolveEligible,
+} from './eligibility.ts';
+import {
+	publishApprovalEvent,
+	type NotificationPublisherResolver,
+} from './notifications.ts';
+import type { ApprovalsRepository } from './repository.ts';
+import {
+	ApprovalsServiceError,
+	bounded,
+	boundedInteger,
+	optionalBounded,
+	oneOf,
+} from './service-error.ts';
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+
+/** Requests one page of a list answers with; the platform ceiling is 200. */
+export const APPROVALS_PAGE_LIMIT = 100;
+
+export interface ApprovalsServiceOptions {
+	readonly repository: ApprovalsRepository;
+	/** Active members and their live role and scopes, resolved through auth.core. */
+	readonly members: (tenantId: string) => Promise<readonly ApprovalMember[]>;
+	/**
+	 * One member's live role and scopes. Every path that judges a single account
+	 * asks for that account; the roll is read only when a request opens and the
+	 * whole eligibility snapshot has to be resolved.
+	 */
+	readonly member: (
+		tenantId: string,
+		accountId: string,
+	) => Promise<ApprovalMember | null>;
+	/** Live tenant setting applied when a requirement names no expiry; the caller primes the workspace first. */
+	readonly defaultExpiryDays: (tenantId: string) => number | Promise<number>;
+	readonly notifications?: NotificationPublisherResolver;
+	readonly callbacks?: ApprovalCallbackRegistry;
+	/** Signs the grant an approved capability request yields; absent means none is issued. */
+	readonly grants?: ApprovalGrantKeyring | undefined;
+	readonly now?: () => number;
+}
+
+export class ApprovalsService {
+	readonly #repository: ApprovalsRepository;
+	readonly #members: ApprovalsServiceOptions['members'];
+	readonly #member: ApprovalsServiceOptions['member'];
+	readonly #defaultExpiryDays: ApprovalsServiceOptions['defaultExpiryDays'];
+	readonly #notifications: NotificationPublisherResolver | undefined;
+	readonly #callbacks: ApprovalCallbackRegistry;
+	readonly #grants: ApprovalGrantKeyring | undefined;
+	readonly #now: () => number;
+
+	constructor(options: ApprovalsServiceOptions) {
+		this.#repository = options.repository;
+		this.#members = options.members;
+		this.#member = options.member;
+		this.#defaultExpiryDays = options.defaultExpiryDays;
+		this.#notifications = options.notifications;
+		this.#callbacks = options.callbacks ?? createApprovalCallbackRegistry();
+		this.#grants = options.grants;
+		this.#now = options.now ?? Date.now;
+	}
+
+	async open(input: OpenApprovalInput): Promise<ApprovalRequest> {
+		const tenantId = bounded(input.tenantId, 'tenantId', 1, 128);
+		const subjectModule = bounded(
+			input.subjectModule,
+			'subjectModule',
+			1,
+			APPROVAL_LIMITS.subjectModule,
+		);
+		const subjectRef = bounded(
+			input.subjectRef,
+			'subjectRef',
+			1,
+			APPROVAL_LIMITS.subjectRef,
+		);
+		const requesterAccountId = bounded(
+			input.requesterAccountId,
+			'requesterAccountId',
+			1,
+			APPROVAL_LIMITS.accountId,
+		);
+		const requirement = normalizeRequirement(
+			input.requirement,
+			await this.#defaultExpiryDays(tenantId),
+		);
+		const permission = bounded(
+			input.permission,
+			'permission',
+			1,
+			APPROVAL_LIMITS.permission,
+		);
+		const action = bounded(input.action, 'action', 1, APPROVAL_LIMITS.action);
+		const title = bounded(input.title, 'title', 1, APPROVAL_LIMITS.title);
+		const summary = optionalBounded(
+			input.summary,
+			'summary',
+			APPROVAL_LIMITS.summary,
+		);
+		/* A repeat of an open request asks who may decide nothing at all: the
+		   deciders were named when it opened, and resolving eligibility again
+		   would refuse the repeat once the only eligible member has left. */
+		const open = await this.#repository.findPendingBySubject(
+			tenantId,
+			subjectModule,
+			subjectRef,
+		);
+		if (open) {
+			if (input.onResolved) {
+				this.#callbacks.register(tenantId, open.id, input.onResolved);
+			}
+			return open;
+		}
+		const eligible = resolveEligible(
+			requirement,
+			await this.#members(tenantId),
+			requesterAccountId,
+		);
+		const createdAt = this.#now();
+		const request: ApprovalRequest = {
+			id: randomUUID(),
+			tenantId,
+			subjectModule,
+			subjectRef,
+			permission,
+			action,
+			title,
+			summary,
+			requesterAccountId,
+			requirement,
+			decisionsNeeded: requirement.decisions,
+			status: 'pending',
+			expiresAt: createdAt + requirement.expiresInDays * DAY_MS,
+			resolvedAt: null,
+			createdAt,
+		};
+		const result = await this.#repository.create(request, eligible);
+		if (input.onResolved) {
+			this.#callbacks.register(tenantId, result.request.id, input.onResolved);
+		}
+		/* A repeat of an open request asks nobody a second time: the deciders
+		   already have the notification the first call published. */
+		if (result.created) {
+			await publishApprovalEvent(this.#notifications, {
+				tenantId,
+				kind: 'approval-requested',
+				sourceModule: 'approvals.core',
+				sourceRef: result.request.id,
+				title: result.request.title,
+				...(result.request.summary === null
+					? {}
+					: { body: result.request.summary }),
+				recipients: eligible,
+			});
+		}
+		return result.request;
+	}
+
+	async get(tenantId: string, id: string): Promise<ApprovalRequest | null> {
+		return this.#repository.get(
+			bounded(tenantId, 'tenantId', 1, 128),
+			bounded(id, 'id', 1, 128),
+		);
+	}
+
+	/**
+	 * The grant an approved capability request yields, derived from the row and
+	 * the current key on every read: the same claims sign to the same token
+	 * under the same key, and a rotated key signs a fresh one that verifies the
+	 * same. Nothing is issued for any other state, or once the window closed.
+	 */
+	grantFor(request: ApprovalRequest): string | undefined {
+		if (!this.#grants || request.status !== 'approved') return undefined;
+		if (request.resolvedAt === null) return undefined;
+		const subject = decodeCapabilitySubjectRef(request.subjectRef);
+		if (!subject) return undefined;
+		const expiresAt = request.resolvedAt + APPROVAL_GRANT_TTL_MS;
+		if (expiresAt <= this.#now()) return undefined;
+		return issueApprovalGrant(this.#grants, {
+			tenantId: request.tenantId,
+			capabilityId: subject.capabilityId,
+			inputDigest: subject.inputDigest,
+			requestId: request.id,
+			issuedAt: request.resolvedAt,
+			expiresAt,
+			nonce: request.id,
+		}).token;
+	}
+
+	/* The token reaches only the module that asked the question: a holder of
+	   the capability naming another module's request is answered null. */
+	async grant(
+		tenantId: string,
+		id: string,
+		subjectModule: string,
+	): Promise<string | null> {
+		const module = bounded(
+			subjectModule,
+			'subjectModule',
+			1,
+			APPROVAL_LIMITS.subjectModule,
+		);
+		const request = await this.get(tenantId, id);
+		if (!request || request.subjectModule !== module) return null;
+		return this.grantFor(request) ?? null;
+	}
+
+	async detail(
+		tenantId: string,
+		id: string,
+	): Promise<ApprovalRequestDetail | null> {
+		return this.#repository.detail(
+			bounded(tenantId, 'tenantId', 1, 128),
+			bounded(id, 'id', 1, 128),
+		);
+	}
+
+	async list(
+		tenantId: string,
+		filter: ApprovalRequestFilter,
+	): Promise<readonly ApprovalRequest[]> {
+		return this.#repository.list(
+			bounded(tenantId, 'tenantId', 1, 128),
+			this.#listFilters(filter),
+			boundedInteger(
+				filter.limit ?? APPROVALS_PAGE_LIMIT,
+				'limit',
+				1,
+				APPROVAL_LIMITS.listLimit,
+			),
+		);
+	}
+
+	/** One keyset page of the inbox; the endpoint validated the page itself. */
+	async listPage(
+		tenantId: string,
+		filter: Omit<ApprovalRequestFilter, 'limit'>,
+		page: ApprovalListPage,
+	): Promise<readonly ApprovalRequest[]> {
+		return this.#repository.listPage(
+			bounded(tenantId, 'tenantId', 1, 128),
+			this.#listFilters(filter),
+			{
+				...page,
+				limit: boundedInteger(
+					page.limit,
+					'limit',
+					1,
+					APPROVAL_LIMITS.listLimit,
+				),
+			},
+		);
+	}
+
+	#listFilters(filter: Omit<ApprovalRequestFilter, 'limit'>) {
+		return {
+			status:
+				filter.status === undefined
+					? undefined
+					: oneOf(filter.status, 'status', APPROVAL_STATUSES),
+			subjectModule: filter.subjectModule,
+			subjectRef: filter.subjectRef,
+			requesterAccountId: filter.requesterAccountId,
+			decidableBy: filter.decidableBy,
+		};
+	}
+
+	/**
+	 * Whether an account may see one request at all: the member who asked, a
+	 * member the eligibility snapshot names, or a member holding manage. It is
+	 * a read rule; deciding is re-checked against live membership.
+	 */
+	async canRead(
+		request: ApprovalRequest,
+		accountId: string,
+		manage: boolean,
+	): Promise<boolean> {
+		if (manage || request.requesterAccountId === accountId) return true;
+		return this.#repository.isSnapshotDecider(
+			request.tenantId,
+			request.id,
+			accountId,
+		);
+	}
+
+	/**
+	 * What one member may do with one request. Deciding is answered against live
+	 * membership, the same check the decision itself runs, so a screen and the
+	 * server never disagree about who may act.
+	 */
+	async viewerRights(
+		request: ApprovalRequest,
+		accountId: string,
+		grants: { readonly decide: boolean; readonly manage: boolean },
+	): Promise<ApprovalViewerRights> {
+		const pending = request.status === 'pending';
+		let canDecide = false;
+		if (pending && grants.decide) {
+			const member = await this.#member(request.tenantId, accountId);
+			canDecide =
+				member !== null &&
+				memberSatisfies(
+					request.requirement,
+					member,
+					request.requesterAccountId,
+				);
+		}
+		return {
+			accountId,
+			canDecide,
+			canCancel:
+				pending && (grants.manage || request.requesterAccountId === accountId),
+		};
+	}
+
+	async countDecidable(tenantId: string, accountId: string): Promise<number> {
+		return this.#repository.countDecidable(
+			bounded(tenantId, 'tenantId', 1, 128),
+			bounded(accountId, 'accountId', 1, APPROVAL_LIMITS.accountId),
+		);
+	}
+
+	/**
+	 * Records one approval or rejection. Eligibility is checked against live
+	 * membership, never against the snapshot the request opened with, so a
+	 * member who lost the role since cannot decide. A member who may neither
+	 * read nor decide the request is answered as if it did not exist.
+	 */
+	async decide(
+		tenantId: string,
+		id: string,
+		accountId: string,
+		kind: 'approve' | 'reject',
+		comment?: string | null,
+		options: { readonly manage: boolean } = { manage: false },
+	): Promise<ApprovalRequestDetail> {
+		const request = await this.#existing(tenantId, id);
+		const member = await this.#member(request.tenantId, accountId);
+		const decider =
+			member !== null &&
+			memberSatisfies(request.requirement, member, request.requesterAccountId)
+				? member
+				: null;
+		/* Live eligibility grants the read on its own: the snapshot cannot name a
+		   member who became eligible after the request opened, and that member may
+		   still decide. */
+		if (!decider && !(await this.canRead(request, accountId, options.manage))) {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_FOUND',
+				'The approval request was not found.',
+				404,
+			);
+		}
+		this.#assertPending(request);
+		if (!decider) {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_ELIGIBLE',
+				'You may not decide this request.',
+				403,
+			);
+		}
+		return this.#record(
+			request,
+			{
+				deciderAccountId: decider.accountId,
+				decision: kind,
+				comment: optionalBounded(comment, 'comment', APPROVAL_LIMITS.comment),
+			},
+			(decisions) =>
+				kind === 'reject'
+					? 'rejected'
+					: decisions.filter((entry) => entry.decision === 'approve').length >=
+						  request.decisionsNeeded
+						? 'approved'
+						: null,
+			/* A cancellation is the outcome its requester already knows about; an
+			   approval or a rejection is the one they are waiting for. */
+			true,
+		);
+	}
+
+	/**
+	 * One decision per id through `decide`, so eligibility is re-checked and the
+	 * ledger row written per request. What the single path refuses is one id's
+	 * outcome rather than the whole call's; anything else is a failure and
+	 * stops the loop where it stands.
+	 */
+	async decideMany(
+		tenantId: string,
+		ids: readonly string[],
+		actorAccountId: string,
+		kind: 'approve' | 'reject',
+		comment: string | null,
+		options: { readonly manage: boolean } = { manage: false },
+	): Promise<readonly ApprovalDecideOutcome[]> {
+		const outcomes: ApprovalDecideOutcome[] = [];
+		for (const id of ids) {
+			try {
+				await this.decide(tenantId, id, actorAccountId, kind, comment, options);
+				outcomes.push({ id, outcome: 'decided' });
+			} catch (error) {
+				if (!(error instanceof ApprovalsServiceError)) throw error;
+				outcomes.push(
+					error.code === 'APPROVAL_NOT_FOUND'
+						? { id, outcome: 'not-found' }
+						: { id, outcome: 'refused', reason: error.code },
+				);
+			}
+		}
+		return outcomes;
+	}
+
+	/**
+	 * Cancels a pending request. `manage` is the caller's answer to whether the
+	 * actor holds `approvals.requests.manage`; the requester may always cancel
+	 * their own request without it. A member who may not read the request is
+	 * answered as if it did not exist.
+	 */
+	async cancel(
+		tenantId: string,
+		id: string,
+		actorAccountId: string,
+		options: { readonly manage: boolean } = { manage: false },
+	): Promise<ApprovalRequestDetail> {
+		const actor = bounded(
+			actorAccountId,
+			'actorAccountId',
+			1,
+			APPROVAL_LIMITS.accountId,
+		);
+		const request = await this.#existing(tenantId, id);
+		if (!(await this.canRead(request, actor, options.manage))) {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_FOUND',
+				'The approval request was not found.',
+				404,
+			);
+		}
+		this.#assertPending(request);
+		if (!options.manage && actor !== request.requesterAccountId) {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_CANCELLABLE',
+				'Only the requester or a member who may manage requests can cancel this request.',
+				403,
+			);
+		}
+		return this.#record(
+			request,
+			{ deciderAccountId: actor, decision: 'cancel', comment: null },
+			() => 'cancelled',
+			false,
+		);
+	}
+
+	/**
+	 * Expires one request the cross-tenant routing read named. The row carries
+	 * routing columns only, so the request is read again under its own tenant
+	 * and expired only while it is still pending and still due. One request
+	 * that cannot be read or written is isolated by the job runner, which goes
+	 * on to the next and leaves this one to the next pass.
+	 */
+	async expireRequest(routing: ApprovalRouting): Promise<void> {
+		const now = this.#now();
+		const request = await this.#repository.get(routing.tenantId, routing.id);
+		if (!request || request.status !== 'pending') return;
+		if (request.expiresAt > now) return;
+		await this.#record(
+			request,
+			{ deciderAccountId: null, decision: 'expire', comment: null },
+			() => 'expired',
+			true,
+		);
+	}
+
+	/** The implementation behind `approvals.requests.v1`. */
+	capability(): ApprovalsRequests {
+		return {
+			open: (input) => this.open(input),
+			get: (tenantId, id) => this.get(tenantId, id),
+			grant: (tenantId, id, subjectModule) =>
+				this.grant(tenantId, id, subjectModule),
+			list: (tenantId, filter) => this.list(tenantId, filter),
+			cancel: async (tenantId, id, actorAccountId) =>
+				(await this.cancel(tenantId, id, actorAccountId)).request,
+		};
+	}
+
+	async #existing(tenantId: string, id: string): Promise<ApprovalRequest> {
+		const request = await this.get(tenantId, id);
+		if (!request) {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_FOUND',
+				'The approval request was not found.',
+				404,
+			);
+		}
+		return request;
+	}
+
+	/* The moment a capability request is approved is the moment its grant can
+	   be read, so that is what the ledger records, under the deciding
+	   transaction, with what the grant will say and which key signs it. */
+	#grantIssued(resolved: ApprovalRequest): ApprovalAuditEntry | null {
+		if (!this.#grants || resolved.status !== 'approved') return null;
+		const subject = decodeCapabilitySubjectRef(resolved.subjectRef);
+		if (!subject || resolved.resolvedAt === null) return null;
+		return {
+			id: randomUUID(),
+			tenantId: resolved.tenantId,
+			requestId: resolved.id,
+			action: 'grant.issued',
+			metadata: {
+				capabilityId: subject.capabilityId,
+				inputDigest: subject.inputDigest,
+				keyId: this.#grants.keyId,
+				expiresAt: resolved.resolvedAt + APPROVAL_GRANT_TTL_MS,
+			},
+			occurredAt: resolved.resolvedAt,
+		};
+	}
+
+	/* Only a member who may read the request is told its state; every caller
+	   settles readability before this runs. */
+	#assertPending(request: ApprovalRequest): void {
+		if (request.status !== 'pending') {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_PENDING',
+				`The request is already ${request.status}.`,
+				409,
+			);
+		}
+	}
+
+	async #record(
+		request: ApprovalRequest,
+		decision: Pick<
+			ApprovalDecision,
+			'deciderAccountId' | 'decision' | 'comment'
+		>,
+		resolve: (
+			decisions: readonly ApprovalDecision[],
+		) => TerminalApprovalStatus | null,
+		notifyRequester: boolean,
+	): Promise<ApprovalRequestDetail> {
+		const decidedAt = this.#now();
+		const result = await this.#repository.decide({
+			tenantId: request.tenantId,
+			requestId: request.id,
+			decision: {
+				id: randomUUID(),
+				tenantId: request.tenantId,
+				requestId: request.id,
+				...decision,
+				decidedAt,
+			},
+			resolve,
+			resolvedAt: decidedAt,
+			audit: (resolved) => this.#grantIssued(resolved),
+		});
+		if (result.outcome === 'not-found') {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_FOUND',
+				'The approval request was not found.',
+				404,
+			);
+		}
+		if (result.outcome === 'not-pending') {
+			throw new ApprovalsServiceError(
+				'APPROVAL_NOT_PENDING',
+				`The request is already ${result.request.status}.`,
+				409,
+			);
+		}
+		if (result.outcome === 'duplicate') {
+			throw new ApprovalsServiceError(
+				'APPROVAL_ALREADY_DECIDED',
+				'You already decided this request.',
+				409,
+			);
+		}
+		/* Both happen after the deciding transaction committed, and a failure in
+		   either never changes what the ledger recorded. */
+		if (result.resolved) {
+			if (notifyRequester) {
+				await publishApprovalEvent(this.#notifications, {
+					tenantId: result.request.tenantId,
+					kind: 'approval-decided',
+					sourceModule: 'approvals.core',
+					sourceRef: result.request.id,
+					title: result.request.title,
+					body: `The request is ${result.request.status}.`,
+					recipients: [result.request.requesterAccountId],
+				});
+			}
+			await this.#callbacks.run(result.request);
+		}
+		return { request: result.request, decisions: result.decisions };
+	}
+}
+
+export { ApprovalsServiceError } from './service-error.ts';

package/modules/approvals/src/services/callbacks.ts

@@ -0,0 +1,75 @@
+import { APPROVAL_LIMITS } from '../domain/capability.ts';
+import type { ApprovalRequest } from '../domain/types.ts';
+
+export type ApprovalResolvedCallback = (
+	request: ApprovalRequest,
+) => Promise<void>;
+
+export interface ApprovalCallbackRegistry {
+	register(
+		tenantId: string,
+		requestId: string,
+		callback: ApprovalResolvedCallback,
+	): void;
+	/** Runs the callback for a resolved request, at most once, and forgets it. */
+	run(request: ApprovalRequest): Promise<void>;
+	forget(tenantId: string, requestId: string): void;
+	readonly size: number;
+}
+
+function key(tenantId: string, requestId: string): string {
+	return `${tenantId}::${requestId}`;
+}
+
+/**
+ * In-process callbacks a subject module registered when it opened a request.
+ * A restart loses them, which is why the capability documents reading the
+ * request back as the durable path; this is the fast path, not the contract.
+ */
+export function createApprovalCallbackRegistry(
+	limit = APPROVAL_LIMITS.callbacks,
+): ApprovalCallbackRegistry {
+	const callbacks = new Map<string, ApprovalResolvedCallback>();
+	return {
+		register(tenantId, requestId, callback) {
+			const entry = key(tenantId, requestId);
+			/* Re-registering moves the entry to the end of the eviction order, so a
+			   subject module that reopened its request keeps the newest callback. */
+			callbacks.delete(entry);
+			if (callbacks.size >= limit) {
+				const oldest = callbacks.keys().next();
+				if (!oldest.done) {
+					callbacks.delete(oldest.value);
+					console.warn(
+						`[approvals] dropped the resolution callback for ${oldest.value}: ${limit} callbacks are already pending.`,
+					);
+				}
+			}
+			callbacks.set(entry, callback);
+		},
+		async run(request) {
+			const entry = key(request.tenantId, request.id);
+			const callback = callbacks.get(entry);
+			/* Deleting before the call is what makes this once per terminal state:
+			   a second resolution racing this one finds nothing to run. */
+			callbacks.delete(entry);
+			if (!callback) return;
+			/* Foreign code on the resolution path. A callback that throws is the
+			   subject module's problem, never the recorded decision's. */
+			try {
+				await callback(request);
+			} catch (error) {
+				console.warn(
+					`[approvals] resolution callback for request ${request.id} failed:`,
+					error instanceof Error ? error.message : error,
+				);
+			}
+		},
+		forget(tenantId, requestId) {
+			callbacks.delete(key(tenantId, requestId));
+		},
+		get size() {
+			return callbacks.size;
+		},
+	};
+}