@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -2,6 +2,7 @@ import type {
 	ActorKind,
 	ModuleSettingRecord,
 	ModuleSettingValue,
+	UserActor,
 } from '@flowdular/sdk/kernel';
 import type {
 	ApiTokenRecord,
@@ -9,9 +10,12 @@ import type {
 	AuditQuery,
 	AuthSession,
 	AuthTenantAccess,
+	IdentityProviderStatus,
+	MembershipStatus,
 	SessionSummary,
 	TenantRole,
 } from '../domain/types.ts';
+import type { SealedMfaSecret } from './totp.ts';
 
 export interface AccountCredential {
 	readonly accountId: string;
@@ -21,11 +25,22 @@ export interface AccountCredential {
 	readonly passwordHash: string;
 	readonly role: string;
 	readonly roleId: string | null;
+	/** The account's platform-level status, set by the deployment operator. */
 	readonly status: 'active' | 'disabled';
+	/** This workspace's own status for the account. */
+	readonly membershipStatus: MembershipStatus;
 	readonly passwordChangeRequired: boolean;
 	readonly scopes: readonly string[];
 }
 
+/** One account, before any workspace is chosen. */
+export interface AccountIdentity {
+	readonly accountId: string;
+	readonly email: string;
+	readonly displayName: string;
+	readonly status: 'active' | 'disabled';
+}
+
 export interface CreateAccountRecord {
 	readonly accountId: string;
 	readonly tenantId: string;
@@ -77,6 +92,66 @@ export interface MfaChallengeRecord {
 	readonly createdAt: number;
 }
 
+/* The identity an external provider asserts. The pair is what the provider
+   promises to keep stable; the address it reports may change at any time. A
+   tenant-owned provider asserts it inside one workspace, which the row names;
+   a platform provider carries none, as it always has. */
+export interface ExternalIdentityRecord {
+	readonly provider: string;
+	readonly subject: string;
+	readonly accountId: string;
+	readonly tenantId?: string | null;
+	readonly now: number;
+}
+
+/**
+ * One binding as a reader sees it: the account it signs in, the provider key
+ * that asserted it, the subject that provider promises to keep stable, and
+ * when the binding was first recorded. No secret, ciphertext or fingerprint is
+ * part of it, and neither is the address the provider reported.
+ */
+export interface ExternalIdentityBinding {
+	readonly accountId: string;
+	readonly provider: string;
+	readonly subject: string;
+	readonly linkedAt: number;
+}
+
+export interface ExternalIdentityPage {
+	readonly identities: readonly ExternalIdentityBinding[];
+	/** `${provider}:${subject}` of the last binding of this page. */
+	readonly nextCursor: string | null;
+}
+
+/** A tenant-owned identity provider row, sealed client secret included. */
+export interface IdentityProviderRecord {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly key: string;
+	readonly label: string;
+	readonly issuer: string;
+	readonly authorizationEndpoint: string;
+	readonly tokenEndpoint: string;
+	readonly userInfoEndpoint: string;
+	readonly clientId: string;
+	readonly secretCiphertext: string;
+	readonly secretKeyId: string;
+	readonly secretFingerprint: string;
+	readonly scopes: readonly string[];
+	readonly jitEnabled: boolean;
+	readonly allowedDomains: readonly string[];
+	readonly jitRole: string;
+	readonly status: IdentityProviderStatus;
+	readonly createdAt: number;
+	readonly updatedAt: number;
+}
+
+/** Everything a provider row carries except the columns the row owns itself. */
+export type IdentityProviderPatch = Omit<
+	IdentityProviderRecord,
+	'id' | 'tenantId' | 'key' | 'createdAt' | 'updatedAt'
+>;
+
 export interface CreateAccountInTenantRecord {
 	readonly accountId: string;
 	readonly tenantId: string;
@@ -119,12 +194,50 @@ export interface TenantMember {
 	readonly displayName: string;
 	readonly role: string;
 	readonly roleId: string | null;
+	/** The account's platform-level status. */
 	readonly status: 'active' | 'disabled';
+	/** This workspace's own status for the member. */
+	readonly membershipStatus: MembershipStatus;
 	readonly scopes: readonly string[];
 	readonly passwordChangeRequired: boolean;
 	readonly createdAt: number;
 }
 
+export interface TenantMemberPage {
+	readonly members: readonly TenantMember[];
+	/** The account id of the last member of this page. */
+	readonly nextCursor: string | null;
+}
+
+export type TenantMemberSort = 'displayName' | 'email';
+
+/**
+ * Where a sorted member page ends. `sortValue` is the sort column as the
+ * database compares it, lower(display_name) or email_normalized, so the next
+ * page continues on the database's own order rather than a JavaScript fold.
+ */
+export interface TenantMemberKeyset {
+	readonly sortValue: string;
+	readonly accountId: string;
+}
+
+export interface TenantMemberSortedRead {
+	readonly sort: TenantMemberSort;
+	readonly direction: 'asc' | 'desc';
+	readonly limit: number;
+	/** Folded and LIKE-escaped prefix of the display name or the address; null narrows nothing. */
+	readonly term: string | null;
+	readonly membershipStatus: MembershipStatus | null;
+	/** The keyset of the last member of the previous page; null starts the walk. */
+	readonly after: TenantMemberKeyset | null;
+}
+
+export interface TenantMemberSortedPage {
+	readonly members: readonly TenantMember[];
+	/** The keyset of the last member when the page is full; a shorter page ends the walk. */
+	readonly next: TenantMemberKeyset | null;
+}
+
 export interface TenantSummary {
 	readonly tenantId: string;
 	readonly name: string;
@@ -154,6 +267,9 @@ export interface AuditRecord {
 	readonly actorKind: ActorKind;
 	/* The agent run the entry is traceable to; null for a user. */
 	readonly actorRunId: string | null;
+	/* The user who configured a service actor; null for every other kind and
+	   for a service whose configuring user is not stored. */
+	readonly configuredBy?: UserActor | null;
 	readonly action: string;
 	readonly subjectType: string;
 	readonly subjectId: string;
@@ -166,6 +282,8 @@ export interface AuditRecord {
 export interface AuditActorEvent extends AuditEvent {
 	readonly actorKind: ActorKind;
 	readonly actorRunId: string | null;
+	/** The user who configured a service actor; null for every other kind. */
+	readonly configuredBy: UserActor | null;
 }
 
 /**
@@ -188,6 +306,9 @@ export interface AuthRepository {
 	findAccountByEmail(
 		normalizedEmail: string,
 	): Promise<AccountCredential | null>;
+	/* The account row alone, without a membership: what an external sign-in
+	   needs before it knows whether the workspace already holds the person. */
+	findAccountIdentity(normalizedEmail: string): Promise<AccountIdentity | null>;
 	findAccountCredentialById(
 		accountId: string,
 	): Promise<AccountCredential | null>;
@@ -219,6 +340,53 @@ export interface AuthRepository {
 	): Promise<AccountCredential | null>;
 	listTenantAccess(accountId: string): Promise<readonly AuthTenantAccess[]>;
 	listTenantMembers(tenantId: string): Promise<readonly TenantMember[]>;
+	/**
+	 * One page of the workspace's members, keyset ordered by account id after
+	 * `afterAccountId` (`''` starts the walk) and cut to `limit` in the
+	 * database, for a caller that must not read a workspace of unknown size at
+	 * once. Migration 0030 indexes the pair, so a page is the rows it returns.
+	 */
+	listTenantMembersPage(
+		tenantId: string,
+		afterAccountId: string,
+		limit: number,
+	): Promise<readonly TenantMember[]>;
+	/**
+	 * One page of the workspace's members ordered by display name or by
+	 * address, keyset on that column and the account id in the direction asked,
+	 * narrowed by a prefix and a membership status in SQL and cut to `limit`.
+	 * Migration 0033 indexes both sort pairs on auth_accounts.
+	 */
+	listTenantMembersSorted(
+		tenantId: string,
+		read: TenantMemberSortedRead,
+	): Promise<TenantMemberSortedPage>;
+	/** How many memberships the workspace holds, an index range over 0030. */
+	countTenantMembers(tenantId: string): Promise<number>;
+	/** One member, for a caller that needs a single account rather than the roll. */
+	findTenantMember(
+		tenantId: string,
+		accountId: string,
+	): Promise<TenantMember | null>;
+	/**
+	 * The members of one workspace whose stored address is in the list. The
+	 * caller normalizes and bounds the list; the comparison is against
+	 * `email_normalized`, which is the same folded form.
+	 */
+	findTenantMembersByEmail(
+		tenantId: string,
+		normalizedEmails: readonly string[],
+	): Promise<readonly TenantMember[]>;
+	/**
+	 * The members of one workspace whose display name or address starts with
+	 * `term`, ordered as `listTenantMembers` orders and cut to `limit` in the
+	 * database. `term` arrives already folded and LIKE-escaped.
+	 */
+	searchTenantMembers(
+		tenantId: string,
+		term: string,
+		limit: number,
+	): Promise<readonly TenantMember[]>;
 	listTenantScopes(tenantId: string): Promise<readonly string[]>;
 	createAccountWithTenant(
 		record: CreateAccountRecord,
@@ -293,8 +461,18 @@ export interface AuthRepository {
 	): Promise<readonly SessionSummary[]>;
 	deleteSession(tokenHash: string): Promise<void>;
 	deleteSessionById(accountId: string, id: string): Promise<boolean>;
-	deleteExpiredSessions(now: number): Promise<number>;
+	/**
+	 * Removes sessions that expired before `now` in bounded batches, at most
+	 * `maxBatches` of them, and answers how many rows went. What the bound leaves
+	 * behind is the next pass's work; a live session is never touched.
+	 */
+	deleteExpiredSessions(now: number, maxBatches?: number): Promise<number>;
 	createPasswordResetToken(record: PasswordResetTokenRecord): Promise<void>;
+	/** The account a live token names, without spending it. */
+	findPasswordResetTokenAccount(
+		tokenHash: string,
+		now: number,
+	): Promise<string | null>;
 	consumePasswordResetToken(
 		tokenHash: string,
 		now: number,
@@ -311,14 +489,23 @@ export interface AuthRepository {
 	} | null>;
 	upsertMfaTotp(
 		accountId: string,
-		secretCiphertext: string,
+		secret: SealedMfaSecret,
 		createdAt: number,
 	): Promise<void>;
 	findMfaTotp(accountId: string): Promise<{
 		readonly secretCiphertext: string;
+		/* Null on a row sealed before 0017 added the column; the ring opens it by
+		   trying every key it holds. */
+		readonly keyId: string | null;
 		readonly confirmedAt: number | null;
 	} | null>;
+	/* Answers the enrolment question without reading the enrolled secret, which
+	   an authorization decision has no reason to hold. */
+	hasConfirmedMfaTotp(accountId: string): Promise<boolean>;
 	confirmMfaTotp(accountId: string, confirmedAt: number): Promise<void>;
+	/* Removes the factor and every recovery code together, so an administrative
+	   reset can never leave a code redeemable for a secret that is gone. */
+	deleteMfaEnrolment(accountId: string): Promise<void>;
 	replaceMfaRecoveryCodes(
 		accountId: string,
 		codeHashes: readonly string[],
@@ -333,6 +520,69 @@ export interface AuthRepository {
 		readonly accountId: string;
 		readonly tenantId: string;
 	} | null>;
+	/* `tenantId` selects the binding space: null is the platform space a
+	   provider from the environment binds in, a workspace id is that
+	   workspace's own space. */
+	findExternalIdentity(
+		provider: string,
+		subject: string,
+		tenantId?: string | null,
+	): Promise<string | null>;
+	findExternalIdentitySubject(
+		provider: string,
+		accountId: string,
+		tenantId?: string | null,
+	): Promise<string | null>;
+	linkExternalIdentity(record: ExternalIdentityRecord): Promise<void>;
+	/**
+	 * One page of the bindings this workspace owns, keyset ordered by
+	 * (provider, subject) after the pair given (`''`, `''` starts the walk).
+	 * The unique workspace index covers exactly that order, so a page is the
+	 * rows it returns. A binding a platform provider made carries no workspace
+	 * and is none of these.
+	 */
+	listExternalIdentitiesPage(
+		tenantId: string,
+		after: { readonly provider: string; readonly subject: string },
+		limit: number,
+	): Promise<readonly ExternalIdentityBinding[]>;
+	deleteExternalIdentitiesOfProvider(
+		tenantId: string,
+		provider: string,
+	): Promise<void>;
+	listIdentityProviders(
+		tenantId: string,
+	): Promise<readonly IdentityProviderRecord[]>;
+	findIdentityProvider(
+		tenantId: string,
+		id: string,
+	): Promise<IdentityProviderRecord | null>;
+	findIdentityProviderByKey(
+		tenantId: string,
+		key: string,
+	): Promise<IdentityProviderRecord | null>;
+	createIdentityProvider(
+		record: IdentityProviderRecord,
+	): Promise<IdentityProviderRecord>;
+	updateIdentityProvider(
+		tenantId: string,
+		id: string,
+		patch: IdentityProviderPatch,
+		updatedAt: number,
+	): Promise<IdentityProviderRecord | null>;
+	deleteIdentityProvider(tenantId: string, id: string): Promise<boolean>;
+	/** Revokes the membership's live tokens; a revoked one stays revoked. */
+	revokeMembershipApiTokens(
+		tenantId: string,
+		accountId: string,
+		revokedAt: number,
+		revokedBy: string,
+	): Promise<number>;
+	setMembershipStatus(
+		accountId: string,
+		tenantId: string,
+		status: MembershipStatus,
+	): Promise<boolean>;
 	findSignInFailure(
 		normalizedEmail: string,
 	): Promise<SignInFailureRecord | null>;
@@ -362,9 +612,56 @@ export interface AuthRepository {
 	countRoleMemberships(tenantId: string, roleId: string): Promise<number>;
 	appendAudit(record: AuditRecord): Promise<void>;
 	queryAudit(query: AuditQuery): Promise<readonly AuditActorEvent[]>;
-	/* The stored module settings of one tenant and module. The synchronous
-	   kernel ModuleSettingsStore is served from a snapshot over these three;
-	   see services/settings-store.ts. */
+	/* The data class operations. Every page is a keyset read of one workspace,
+	   every sweep a bounded delete of rows a workspace no longer needs; the
+	   caller decides the cutoff from the workspace's retention period. */
+	exportSessionsPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly SessionExportRecord[]>;
+	/** Removes sessions that expired before `before`; a live one is never touched. */
+	deleteSessionsExpiredBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	exportApiTokensPage(
+		tenantId: string,
+		afterId: string,
+		limit: number,
+	): Promise<readonly ApiTokenRecord[]>;
+	/** Removes tokens that were revoked or expired before `before`; a usable one stays. */
+	deleteApiTokensRetiredBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	exportAuditEventsPage(
+		tenantId: string,
+		afterId: number,
+		limit: number,
+	): Promise<readonly AuditEvent[]>;
+	deleteAuditEventsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number>;
+	/* The erasure operations. Each removes at most `limit` rows one account owns
+	   inside one workspace, so a subject erased in one workspace keeps what
+	   another workspace holds about them. */
+	deleteMembershipSessionsOf(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number>;
+	deleteMembershipApiTokensOf(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number>;
+	/* The stored module settings of one tenant and module; the kernel
+	   ModuleSettingsStore in services/settings-store.ts is built on these three. */
 	loadSettings(
 		tenantId: string,
 		moduleId: string,
@@ -373,6 +670,18 @@ export interface AuthRepository {
 	clearSetting(tenantId: string, moduleId: string, key: string): Promise<void>;
 }
 
+/* What a session export carries. It names no secret: a session is known by its
+   id, and the hash that authenticates it stays in the database. An API token
+   export carries ApiTokenRecord, which already omits the hash. */
+export interface SessionExportRecord {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly accountId: string;
+	readonly createdAt: number;
+	readonly expiresAt: number;
+	readonly lastSeenAt: number;
+}
+
 export class DuplicateAccountError extends Error {
 	constructor() {
 		super('An account with this email already exists.');
@@ -387,6 +696,13 @@ export class DuplicateTenantSlugError extends Error {
 	}
 }
 
+export class DuplicateProviderKeyError extends Error {
+	constructor() {
+		super('A provider with this key already exists in the workspace.');
+		this.name = 'DuplicateProviderKeyError';
+	}
+}
+
 export class DuplicateRoleKeyError extends Error {
 	constructor() {
 		super('A role with this key already exists in the workspace.');

package/modules/auth/src/services/session-sweep-runner.ts

@@ -0,0 +1,73 @@
+import {
+	createJobRunner,
+	createJobTraceSink,
+	jobBackoff,
+	serverLogger,
+	type JobRunner,
+	type Logger,
+	type Tracer,
+} from '@flowdular/sdk/server';
+
+/** Stable id of the loop: the `module` field of every line it logs. */
+export const SESSION_SWEEP_JOB = 'auth.core.sessions';
+
+/** What the sweep needs of the service: the bounded delete and nothing else. */
+export interface ExpiredSessionSweep {
+	deleteExpiredSessions(): Promise<number>;
+}
+
+export interface SessionSweepRunnerOptions {
+	readonly sweep: () => Promise<ExpiredSessionSweep>;
+	readonly intervalMs: number;
+	/** Defaults to the process tracer, which is the one `context.tracer` carries. */
+	readonly tracer?: Tracer | undefined;
+}
+
+/* A repository error can carry the SQL parameters of the statement that raised,
+   and a session token hash is one of them. The sweep publishes what kind of
+   value was thrown and never the value itself, so the runner's own error line
+   is written through this logger rather than the process one. */
+function sweepLogger(): Logger {
+	const logger = serverLogger();
+	return {
+		...logger,
+		error: (message, event) =>
+			logger.error(message, {
+				module: event?.module ?? SESSION_SWEEP_JOB,
+				fields: { error: event?.err instanceof Error ? 'Error' : 'non-error' },
+			}),
+	};
+}
+
+/**
+ * The expired session sweep as the platform runner sees it. The loop, its
+ * interval and unref, the guard against overlapping passes, the backoff and the
+ * drain on dispose are the runner's (`@flowdular/sdk/server`); the row bound on the
+ * delete and every statement it issues stay in the repository behind the
+ * service.
+ */
+export function createSessionSweepRunner(
+	options: SessionSweepRunnerOptions,
+): JobRunner {
+	return createJobRunner<number>({
+		name: SESSION_SWEEP_JOB,
+		intervalMs: options.intervalMs,
+		/* The sweep claims nothing: no row is leased, so no renewal can lapse and
+		   nothing can take the work over while a pass runs. */
+		staleAfterMs: options.intervalMs,
+		backoff: jobBackoff(options.intervalMs),
+		/* One claim per pass, and the claim is the pass itself: the delete it
+		   performs carries its own row bound and leaves the rest to the next. */
+		batchLimit: 1,
+		logger: sweepLogger,
+		/* Spans carry the loop name, the counts and a reason code, never the value
+		   a statement threw, so the sweep's own refusal to serialize it holds. */
+		onEvent: createJobTraceSink(
+			options.tracer ? { tracer: options.tracer } : {},
+		),
+		claim: (at) => Promise.resolve(at),
+		perform: async () => {
+			await (await options.sweep()).deleteExpiredSessions();
+		},
+	});
+}

package/modules/auth/src/services/settings-store.ts

@@ -1,92 +1,19 @@
-import type {
-	ModuleSettingRecord,
-	ModuleSettingValue,
-	ModuleSettingsStore,
-} from '@flowdular/sdk/kernel';
+import type { ModuleSettingsStore } from '@flowdular/sdk/kernel';
 import type { AuthRepository } from './repository.ts';
 
-export interface AuthSettingsStore extends ModuleSettingsStore {
-	/**
-	 * Resolves once every snapshot and write requested so far has reached the
-	 * database, and rejects once with the first failure since the last call.
-	 */
-	ready(): Promise<void>;
-	/** Loads one snapshot and waits for it, so a later read cannot miss it. */
-	prime(tenantId: string, moduleId: string): Promise<void>;
-}
-
 /**
- * The kernel settings runtime reads through a synchronous store and caches the
- * object it gets back. auth.core now stores settings in PostgreSQL, which is
- * asynchronous, so this store hands out the snapshot object for one tenant and
- * module and fills that same object when the read resolves: the runtime's
- * cached reference sees the values without a second call. Until the first read
- * lands a declared default is what a caller sees, so anything that must not
- * observe that window primes the snapshot first. Writes apply to the snapshot
- * immediately and reach the database in call order.
+ * The kernel settings store over auth.core's module_settings table. The
+ * kernel runtime primes a snapshot per tenant through `load` and awaits every
+ * write, so a failure reaches the caller that made it.
  */
 export function createAuthSettingsStore(
 	repository: () => Promise<AuthRepository>,
-): AuthSettingsStore {
-	const snapshots = new Map<string, Record<string, ModuleSettingValue>>();
-	let queue: Promise<void> = Promise.resolve();
-	let failure: unknown;
-
-	const enqueue = (work: () => Promise<void>, label: string): void => {
-		queue = queue.then(async () => {
-			try {
-				await work();
-			} catch (error) {
-				/* The kernel write path is synchronous and returns nothing, so this
-				   is the only place a failure can be reported. The value never
-				   reaches the log; a stored secret would end up in it. */
-				failure ??= error;
-				console.error(`[auth.core] module settings ${label} failed`);
-			}
-		});
-	};
-
-	const snapshot = (
-		tenantId: string,
-		moduleId: string,
-	): Record<string, ModuleSettingValue> => {
-		const key = `${tenantId} ${moduleId}`;
-		const existing = snapshots.get(key);
-		if (existing) return existing;
-		const values: Record<string, ModuleSettingValue> = {};
-		snapshots.set(key, values);
-		enqueue(async () => {
-			const store = await repository();
-			Object.assign(values, await store.loadSettings(tenantId, moduleId));
-		}, `read of ${moduleId}`);
-		return values;
-	};
-
+): ModuleSettingsStore {
 	return {
-		load: snapshot,
-		save(record: ModuleSettingRecord) {
-			snapshot(record.tenantId, record.moduleId)[record.key] = record.value;
-			enqueue(
-				async () => (await repository()).saveSetting(record),
-				`write of ${record.moduleId}.${record.key}`,
-			);
-		},
-		clear(tenantId: string, moduleId: string, key: string) {
-			delete snapshot(tenantId, moduleId)[key];
-			enqueue(
-				async () => (await repository()).clearSetting(tenantId, moduleId, key),
-				`clear of ${moduleId}.${key}`,
-			);
-		},
-		async ready() {
-			await queue;
-			const pending = failure;
-			failure = undefined;
-			if (pending !== undefined) throw pending;
-		},
-		async prime(tenantId: string, moduleId: string) {
-			snapshot(tenantId, moduleId);
-			await this.ready();
-		},
+		load: async (tenantId, moduleId) =>
+			(await repository()).loadSettings(tenantId, moduleId),
+		save: async (record) => (await repository()).saveSetting(record),
+		clear: async (tenantId, moduleId, key) =>
+			(await repository()).clearSetting(tenantId, moduleId, key),
 	};
 }