@flowdular/sdk 0.2.4 → 0.3.0

package/modules/access/src/services/database-repository.ts

@@ -0,0 +1,185 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import { runDatabaseMigrations } from '@flowdular/sdk/database';
+import { keysetWhere } from '@flowdular/sdk/server';
+import type {
+	AccessAttestation,
+	AttestationPosition,
+} from '../domain/types.ts';
+import { databaseMigrations } from './migration.ts';
+import type { AccessRepository, AttestationQuery } from './repository.ts';
+
+interface AttestationRow {
+	id: string;
+	tenant_id: string;
+	reviewer_account_id: string;
+	reviewer_label: string;
+	period_from: Date | string;
+	period_to: Date | string;
+	member_count: number | bigint | string;
+	active_member_count: number | bigint | string;
+	role_count: number | bigint | string;
+	extra_scope_count: number | bigint | string;
+	token_count: number | bigint | string;
+	provider_count: number | bigint | string;
+	note: string | null;
+	created_at: number | bigint | string;
+}
+
+const COLUMNS = `id, tenant_id, reviewer_account_id, reviewer_label,
+	 period_from, period_to, member_count, active_member_count, role_count,
+	 extra_scope_count, token_count, provider_count, note, created_at`;
+
+/* The page order and the keyset predicate are one decision: both columns run
+   descending, which is the order access_attestations_tenant_created_idx
+   carries. The export walks the same index backwards, oldest first. */
+const PAGE_KEYSET = keysetWhere(['created_at', 'id'], ['', ''], {
+	direction: 'desc',
+	parameterOffset: 1,
+}).text;
+
+const EXPORT_KEYSET = keysetWhere(['created_at', 'id'], ['', ''], {
+	direction: 'asc',
+	parameterOffset: 1,
+}).text;
+
+/* Queries stay explicit. Values always travel in the adapter's parameter
+   channel; nothing from a request is concatenated into SQL. There is no
+   update and no delete: the ledger only grows. */
+const SQL = {
+	append: `INSERT INTO access_attestations (${COLUMNS})
+	 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14)`,
+	list: `SELECT ${COLUMNS} FROM access_attestations
+	 WHERE tenant_id = $1
+	 ORDER BY created_at DESC, id DESC
+	 LIMIT $2`,
+	listPage: `SELECT ${COLUMNS} FROM access_attestations
+	 WHERE tenant_id = $1 AND ${PAGE_KEYSET}
+	 ORDER BY created_at DESC, id DESC
+	 LIMIT $4`,
+	exportFirst: `SELECT ${COLUMNS} FROM access_attestations
+	 WHERE tenant_id = $1
+	 ORDER BY created_at, id
+	 LIMIT $2`,
+	exportPage: `SELECT ${COLUMNS} FROM access_attestations
+	 WHERE tenant_id = $1 AND ${EXPORT_KEYSET}
+	 ORDER BY created_at, id
+	 LIMIT $4`,
+} as const;
+
+/* PostgreSQL returns BIGINT as a string, so every numeric read is normalized
+   before it reaches the domain. */
+function whole(value: number | bigint | string, field: string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized) || normalized < 0) {
+		throw new Error(`The access database returned an invalid ${field}.`);
+	}
+	return normalized;
+}
+
+/* The driver returns a timestamp as a Date; the domain keeps ISO text. */
+function isoText(value: Date | string): string {
+	return value instanceof Date ? value.toISOString() : value;
+}
+
+function fromRow(row: AttestationRow): AccessAttestation {
+	return {
+		id: row.id,
+		tenantId: row.tenant_id,
+		reviewerAccountId: row.reviewer_account_id,
+		reviewerLabel: row.reviewer_label,
+		periodFrom: isoText(row.period_from),
+		periodTo: isoText(row.period_to),
+		memberCount: whole(row.member_count, 'member count'),
+		activeMemberCount: whole(row.active_member_count, 'member count'),
+		roleCount: whole(row.role_count, 'role count'),
+		extraScopeCount: whole(row.extra_scope_count, 'scope count'),
+		tokenCount: whole(row.token_count, 'token count'),
+		providerCount: whole(row.provider_count, 'provider count'),
+		note: row.note,
+		createdAt: whole(row.created_at, 'timestamp'),
+	};
+}
+
+/** A repository over a platform-owned PostgreSQL handle. */
+export class DatabaseAccessRepository implements AccessRepository {
+	constructor(private readonly database: DatabaseHandle) {}
+
+	async append(record: AccessAttestation): Promise<AccessAttestation> {
+		await this.database.transaction(
+			(transaction) =>
+				transaction.execute({
+					text: SQL.append,
+					parameters: [
+						record.id,
+						record.tenantId,
+						record.reviewerAccountId,
+						record.reviewerLabel,
+						record.periodFrom,
+						record.periodTo,
+						record.memberCount,
+						record.activeMemberCount,
+						record.roleCount,
+						record.extraScopeCount,
+						record.tokenCount,
+						record.providerCount,
+						record.note,
+						record.createdAt,
+					],
+				}),
+			{ access: 'write', tenantId: record.tenantId },
+		);
+		return record;
+	}
+
+	async list(
+		tenantId: string,
+		query: AttestationQuery,
+	): Promise<readonly AccessAttestation[]> {
+		const result = await this.database.transaction(
+			(transaction) =>
+				query.after === null
+					? transaction.query<AttestationRow>({
+							text: SQL.list,
+							parameters: [tenantId, query.limit],
+						})
+					: transaction.query<AttestationRow>({
+							text: SQL.listPage,
+							parameters: [
+								tenantId,
+								query.after.createdAt,
+								query.after.id,
+								query.limit,
+							],
+						}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+
+	async exportPage(
+		tenantId: string,
+		after: AttestationPosition | null,
+		limit: number,
+	): Promise<readonly AccessAttestation[]> {
+		const result = await this.database.transaction(
+			(transaction) =>
+				after === null
+					? transaction.query<AttestationRow>({
+							text: SQL.exportFirst,
+							parameters: [tenantId, limit],
+						})
+					: transaction.query<AttestationRow>({
+							text: SQL.exportPage,
+							parameters: [tenantId, after.createdAt, after.id, limit],
+						}),
+			{ access: 'read', tenantId },
+		);
+		return result.rows.map(fromRow);
+	}
+}
+
+export async function migrateAccessDatabase(
+	database: DatabaseHandle,
+): Promise<void> {
+	await runDatabaseMigrations(database, 'access.core', databaseMigrations);
+}

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

@@ -0,0 +1,102 @@
+import type { AccessWindow, AuditPosition } from '../domain/types.ts';
+
+/**
+ * Everything access.core reads about who holds what, declared as the narrow
+ * shape this module actually needs. auth.core owns the rows; the adapter in
+ * auth-directory.ts is the only place that knows that, so the service and its
+ * tests never depend on another module's service surface.
+ */
+export interface DirectoryMember {
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly role: string;
+	readonly roleId: string | null;
+	readonly status: string;
+	readonly membershipStatus: string;
+	readonly scopes: readonly string[];
+}
+
+export interface DirectoryMemberPage {
+	readonly members: readonly DirectoryMember[];
+	/** The account id the next page walks on from; null on the last page. */
+	readonly nextCursor: string | null;
+}
+
+export interface DirectoryRole {
+	readonly id: string;
+	readonly key: string;
+	readonly name: string;
+	readonly builtin: boolean;
+	readonly scopes: readonly string[];
+}
+
+export interface DirectoryToken {
+	readonly id: string;
+	readonly label: string;
+	readonly prefix: string;
+	readonly accountId: string;
+	readonly scopes: readonly string[];
+	readonly createdAt: number;
+	readonly expiresAt: number | null;
+	readonly lastUsedAt: number | null;
+	readonly revokedAt: number | null;
+}
+
+export interface DirectoryProvider {
+	readonly id: string;
+	readonly key: string;
+	readonly label: string;
+	readonly issuer: string;
+	readonly status: string;
+	readonly scope: string;
+	readonly jitEnabled: boolean;
+	readonly jitRole: string;
+	readonly allowedDomains: readonly string[];
+	readonly updatedAt: number;
+}
+
+export interface DirectoryAuditEvent {
+	readonly id: number;
+	readonly occurredAt: number;
+	readonly action: string;
+	readonly actorLabel: string;
+	readonly actorAccountId: string | null;
+	readonly actorKind: string;
+	readonly subjectType: string;
+	readonly subjectId: string;
+	readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+export interface AccessDirectory {
+	members(tenantId: string): Promise<readonly DirectoryMember[]>;
+	/**
+	 * One bounded page of the workspace's memberships, ordered by account id and
+	 * starting strictly after `cursor`. A review lists at most its declared bound
+	 * and says it was capped; this is what a walk that must carry every member
+	 * reads instead, so the size of the workspace decides the number of pages
+	 * rather than what reaches the file.
+	 */
+	memberPage(
+		tenantId: string,
+		cursor: string | null,
+		limit: number,
+	): Promise<DirectoryMemberPage>;
+	roles(tenantId: string): Promise<readonly DirectoryRole[]>;
+	/** Every token of the workspace, revoked ones included. */
+	tokens(tenantId: string): Promise<readonly DirectoryToken[]>;
+	providers(tenantId: string): Promise<readonly DirectoryProvider[]>;
+	/**
+	 * At most `limit` recorded events of the inclusive window, newest first and
+	 * strictly before `after`. A null `after` starts at the newest event inside
+	 * the window. The window is a predicate of the read itself, so an event at
+	 * its first or last millisecond is part of the page and nothing outside it
+	 * is ever answered.
+	 */
+	auditPage(
+		tenantId: string,
+		window: AccessWindow,
+		after: AuditPosition | null,
+		limit: number,
+	): Promise<readonly DirectoryAuditEvent[]>;
+}

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

@@ -0,0 +1,33 @@
+export {
+	AccessService,
+	AccessServiceError,
+	parseWindow,
+} from './access-service.ts';
+export type {
+	AccessServiceOptions,
+	AttestInput,
+	Reviewer,
+} from './access-service.ts';
+export { authDirectory } from './auth-directory.ts';
+export { walkAuditWindow } from './audit-window.ts';
+export type { WindowRequest } from './audit-window.ts';
+export { ACTION_CATEGORIES, changeCategory, changeDetail } from './changes.ts';
+export type { AccessReportKind } from './changes.ts';
+export { accessDataClasses } from './data-classes.ts';
+export { accessListExports, EXPORT_LISTS_CAPABILITY } from './list-exports.ts';
+export type { ExportListRegistry } from './list-exports.ts';
+export type {
+	AccessDirectory,
+	DirectoryAuditEvent,
+	DirectoryMember,
+	DirectoryProvider,
+	DirectoryRole,
+	DirectoryToken,
+} from './directory.ts';
+export type { AccessRepository, AttestationQuery } from './repository.ts';
+export {
+	DatabaseAccessRepository,
+	migrateAccessDatabase,
+} from './database-repository.ts';
+export { buildReview } from './review.ts';
+export { ACCESS_TENANT_TABLES, databaseMigrations } from './migration.ts';

package/modules/access/src/services/list-exports.ts

@@ -0,0 +1,150 @@
+import { randomBytes } from 'node:crypto';
+import {
+	decodeCursor,
+	defineListExport,
+	encodeCursor,
+	type DefinedListExport,
+} from '@flowdular/sdk/server';
+import {
+	ACCESS_LIMITS,
+	type AccessAttestation,
+	type AccessReviewMember,
+	type AttestationPosition,
+} from '../domain/types.ts';
+import { ACCESS_PERMISSIONS } from '../acl/permissions.ts';
+import type { AccessService } from './access-service.ts';
+
+/**
+ * exports.core's public registry. Only the identifier couples access.core to
+ * that module: the shape is declared here, so a deployment without exports.core
+ * composes exactly the same and registers nothing.
+ */
+export const EXPORT_LISTS_CAPABILITY = 'exports.lists.v1';
+
+export interface ExportListRegistry {
+	register(moduleId: string, exports: readonly DefinedListExport[]): void;
+}
+
+/**
+ * The two lists access.core offers a file of. The review is a live read walked
+ * by account id through the uncapped member page, so a workspace larger than
+ * the review's own listing bound exports every member rather than the first
+ * page of them, and a member renamed or removed mid-export cannot be written
+ * twice or dropped. The attestation ledger is append-only, so its walk can
+ * never skew at all.
+ */
+export function accessListExports(
+	service: () => Promise<AccessService>,
+): readonly DefinedListExport[] {
+	/* Module-owned and never stored: an export cursor names a position in one
+	   workspace's own walk and a restart costs the job its first page. */
+	const secret = randomBytes(32);
+
+	const review = defineListExport<AccessReviewMember>({
+		id: 'access.core.review',
+		label: 'Access review',
+		permission: ACCESS_PERMISSIONS.read,
+		columns: [
+			{ key: 'member', header: 'Member', value: (row) => row.displayName },
+			{ key: 'email', header: 'E-mail', value: (row) => row.email },
+			{ key: 'role', header: 'Role', value: (row) => row.role },
+			{
+				key: 'accountStatus',
+				header: 'Account status',
+				value: (row) => row.accountStatus,
+			},
+			{
+				key: 'membershipStatus',
+				header: 'Workspace status',
+				value: (row) => row.membershipStatus,
+			},
+			{ key: 'scopes', header: 'Scopes', value: (row) => row.scopeCount },
+			{
+				key: 'extraScopes',
+				header: 'Beyond the role',
+				value: (row) => row.extraScopes.join(' '),
+			},
+		],
+		page: async (principal, cursor, limit) => {
+			const page = await (
+				await service()
+			).memberPage(
+				principal.tenantId,
+				cursor,
+				Math.min(limit, ACCESS_LIMITS.memberPage),
+			);
+			return { rows: page.members, nextCursor: page.nextCursor };
+		},
+	});
+
+	const attestations = defineListExport<AccessAttestation>({
+		id: 'access.core.attestations',
+		label: 'Access attestations',
+		permission: ACCESS_PERMISSIONS.read,
+		columns: [
+			{
+				key: 'periodFrom',
+				header: 'Period from',
+				value: (row) => row.periodFrom,
+			},
+			{ key: 'periodTo', header: 'Period to', value: (row) => row.periodTo },
+			{
+				key: 'reviewer',
+				header: 'Reviewer',
+				value: (row) => row.reviewerLabel,
+			},
+			{ key: 'members', header: 'Members', value: (row) => row.memberCount },
+			{
+				key: 'activeMembers',
+				header: 'Active members',
+				value: (row) => row.activeMemberCount,
+			},
+			{ key: 'roles', header: 'Roles', value: (row) => row.roleCount },
+			{
+				key: 'extraScopes',
+				header: 'Beyond a role',
+				value: (row) => row.extraScopeCount,
+			},
+			{ key: 'tokens', header: 'API tokens', value: (row) => row.tokenCount },
+			{
+				key: 'providers',
+				header: 'Identity providers',
+				value: (row) => row.providerCount,
+			},
+			{ key: 'note', header: 'Note', value: (row) => row.note },
+			{
+				key: 'recordedAt',
+				header: 'Recorded at',
+				value: (row) => new Date(row.createdAt),
+			},
+		],
+		page: async (principal, cursor, limit) => {
+			let after: AttestationPosition | null = null;
+			if (cursor !== null) {
+				const value = decodeCursor(cursor, secret);
+				if (
+					!Number.isSafeInteger(value.createdAt) ||
+					typeof value.id !== 'string'
+				) {
+					throw new Error('The export cursor is not a ledger position.');
+				}
+				after = { createdAt: value.createdAt as number, id: value.id };
+			}
+			/* The ledger pages at its own ceiling; a page smaller than the one the
+			   job asked for is the contract, a page larger would break it. */
+			const page = await (
+				await service()
+			).attestations(principal.tenantId, {
+				limit: Math.min(limit, ACCESS_LIMITS.attestationLimit),
+				after,
+			});
+			return {
+				rows: page.items,
+				nextCursor:
+					page.next === null ? null : encodeCursor({ ...page.next }, secret),
+			};
+		},
+	});
+
+	return [review, attestations];
+}

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

@@ -0,0 +1,54 @@
+import type { DatabaseMigration } from '@flowdular/sdk/database';
+import { postgresTenantTableState } from '@flowdular/sdk/database';
+
+/* Mirrors migrations/0001_access_core.up.sql byte for byte;
+   tests/migrations.test.ts fails on drift. */
+export const ACCESS_MIGRATION_001 = `-- One row per recorded attestation: someone reviewed who held what for one
+-- period, and these are the counts the server computed at that moment. The
+-- table is append-only, so no statement in this module updates or deletes a
+-- row and the index below serves the only read there is: newest first.
+CREATE TABLE IF NOT EXISTS access_attestations (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  reviewer_account_id TEXT NOT NULL CHECK (length(reviewer_account_id) BETWEEN 1 AND 64),
+  reviewer_label TEXT NOT NULL CHECK (length(reviewer_label) BETWEEN 1 AND 254),
+  period_from TIMESTAMPTZ NOT NULL,
+  period_to TIMESTAMPTZ NOT NULL,
+  member_count BIGINT NOT NULL CHECK (member_count >= 0),
+  active_member_count BIGINT NOT NULL CHECK (active_member_count >= 0),
+  role_count BIGINT NOT NULL CHECK (role_count >= 0),
+  extra_scope_count BIGINT NOT NULL CHECK (extra_scope_count >= 0),
+  token_count BIGINT NOT NULL CHECK (token_count >= 0),
+  provider_count BIGINT NOT NULL CHECK (provider_count >= 0),
+  note TEXT CHECK (note IS NULL OR length(note) <= 2000),
+  created_at BIGINT NOT NULL,
+  CHECK (period_to >= period_from)
+);
+CREATE INDEX IF NOT EXISTS access_attestations_tenant_created_idx
+  ON access_attestations (tenant_id, created_at DESC, id DESC);
+ALTER TABLE access_attestations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE access_attestations FORCE ROW LEVEL SECURITY;
+CREATE POLICY access_attestations_tenant_policy ON access_attestations
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+/** Every tenant table of this module, with the policy each one must carry. */
+export const ACCESS_TENANT_TABLES = ['access_attestations'] as const;
+
+export const databaseMigrations: readonly DatabaseMigration[] = [
+	{
+		id: '0001_access_core',
+		sql: { postgresql: ACCESS_MIGRATION_001 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'access_attestations',
+				'access_attestations_tenant_policy',
+				[
+					() =>
+						database.schema.hasIndex('access_attestations_tenant_created_idx'),
+				],
+			),
+	},
+];

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

@@ -0,0 +1,30 @@
+import type {
+	AccessAttestation,
+	AttestationPosition,
+} from '../domain/types.ts';
+
+export interface AttestationQuery {
+	readonly limit: number;
+	/** Keyset of the last row of the previous page, newest first. */
+	readonly after: AttestationPosition | null;
+}
+
+/**
+ * The attestation ledger, and nothing else: memberships, roles, tokens,
+ * providers and the audit trail belong to auth.core and are read through the
+ * directory port instead. There is no update and no delete, because the ledger
+ * is append-only.
+ */
+export interface AccessRepository {
+	append(record: AccessAttestation): Promise<AccessAttestation>;
+	list(
+		tenantId: string,
+		query: AttestationQuery,
+	): Promise<readonly AccessAttestation[]>;
+	/** Oldest first, for the data class export walk. */
+	exportPage(
+		tenantId: string,
+		after: AttestationPosition | null,
+		limit: number,
+	): Promise<readonly AccessAttestation[]>;
+}