@contember/engine-tenant-api 2.1.0-beta.2 → 2.2.0-alpha.1

package/src/model/queries/project/ProjectSecretKeysQuery.ts

@@ -0,0 +1,29 @@
+import { DatabaseQuery, DatabaseQueryable, SelectBuilder } from '@contember/database'
+
+export interface ProjectSecretInfoRow {
+	readonly key: string
+	readonly created_at: Date
+	readonly updated_at: Date
+}
+
+/**
+ * Lists a project's secret KEYS (and timestamps) without ever reading the
+ * encrypted values — used to show which secrets exist. For reading values use
+ * {@link ProjectSecretsQuery} via SecretsManager.readSecrets.
+ */
+export class ProjectSecretKeysQuery extends DatabaseQuery<ProjectSecretInfoRow[]> {
+	constructor(private readonly projectId: string) {
+		super()
+	}
+
+	async fetch({ db }: DatabaseQueryable): Promise<ProjectSecretInfoRow[]> {
+		return await SelectBuilder.create<ProjectSecretInfoRow>()
+			.from('project_secret')
+			.where({ project_id: this.projectId })
+			.select('key')
+			.select('created_at')
+			.select('updated_at')
+			.orderBy('key')
+			.getResult(db)
+	}
+}

package/src/model/queries/project/ProjectSecretsQuery.ts

@@ -1,5 +1,5 @@
 import { DatabaseQuery, DatabaseQueryable, SelectBuilder } from '@contember/database'
-import { Providers } from '../../providers'
+import { Providers } from '../../providers.js'
 
 type ProjectSecretsQueryResult = { key: string; value: Buffer; needsReEncrypt: boolean }[]
 

package/src/model/queries/project/ProjectsByIdentityQuery.ts

@@ -1,7 +1,7 @@
 import { DatabaseQuery, DatabaseQueryable, SelectBuilder } from '@contember/database'
-import { ProjectsQuery } from './ProjectsQuery'
-import { PermissionActions, PermissionContext } from '../../authorization'
-import { Project } from '../../type'
+import { ProjectsQuery } from './ProjectsQuery.js'
+import { PermissionActions, PermissionContext } from '../../authorization/index.js'
+import { Project } from '../../type/index.js'
 
 export class ProjectsByIdentityQuery extends DatabaseQuery<Project[]> {
 	constructor(private readonly identityId: string, private readonly permissionContext: PermissionContext) {

package/src/model/queries/project/ProjectsQuery.ts

@@ -1,5 +1,5 @@
 import { DatabaseQuery, DatabaseQueryable, SelectBuilder } from '@contember/database'
-import { Project } from '../../type'
+import { Project } from '../../type/index.js'
 
 export class ProjectsQuery extends DatabaseQuery<Project[]> {
 	async fetch({ db }: DatabaseQueryable): Promise<Project[]> {

package/src/model/queries/project/index.ts

@@ -1,5 +1,6 @@
-export * from './ProjectSecretsQuery'
-export * from './ProjectBySlugQuery'
-export * from './ProjectsByIdentityQuery'
-export * from './ProjectsQuery'
-export * from './ProjectUpdateTimestampQuery'
+export * from './ProjectSecretsQuery.js'
+export * from './ProjectSecretKeysQuery.js'
+export * from './ProjectBySlugQuery.js'
+export * from './ProjectsByIdentityQuery.js'
+export * from './ProjectsQuery.js'
+export * from './ProjectUpdateTimestampQuery.js'

package/src/model/queries/rateLimit/RateLimitCountQuery.ts

@@ -0,0 +1,22 @@
+import { DatabaseQuery, DatabaseQueryable, Literal, SelectBuilder } from '@contember/database'
+import { RateLimitScope } from '../../type/RateLimit.js'
+
+export class RateLimitCountQuery extends DatabaseQuery<number> {
+	constructor(
+		private readonly scope: RateLimitScope,
+		private readonly keyHash: Buffer,
+		private readonly windowStart: Date,
+	) {
+		super()
+	}
+
+	async fetch({ db }: DatabaseQueryable): Promise<number> {
+		const rows = await SelectBuilder.create<{ count: string }>()
+			.from('rate_limit_event')
+			.select(new Literal('count(*)::text as count'))
+			.where({ scope: this.scope, key_hash: this.keyHash })
+			.where(expr => expr.compare('occurred_at', '>=', this.windowStart))
+			.getResult(db)
+		return Number(rows[0]?.count ?? '0')
+	}
+}

package/src/model/queries/rateLimit/index.ts

@@ -0,0 +1 @@
+export * from './RateLimitCountQuery.js'

package/src/model/service/AuthLogService.ts

@@ -1,12 +1,23 @@
-import { DatabaseContext } from '../utils'
-import { CreateAuthLogEntryCommand } from '../commands/authLog/CreateAuthLogEntryCommand'
-import { Response } from '../utils/Response'
-import { AuthActionType } from '../type/AuthLog'
+import { DatabaseContext } from '../utils/index.js'
+import { CreateAuthLogEntryCommand } from '../commands/authLog/CreateAuthLogEntryCommand.js'
+import { Response } from '../utils/Response.js'
+import { AuthActionType } from '../type/AuthLog.js'
+import { JSONValue } from '@contember/schema'
 
 class AuthLogService {
 	async logAuthAction(
 		db: DatabaseContext,
-		ctx: { identityId: string; clientIp?: string; userAgent?: string },
+		ctx: {
+			identityId: string
+			clientIp?: string
+			userAgent?: string
+			forwarderIp?: string
+			forwarderUserAgent?: string
+			/** A03: country from the trusted reverse-proxy geo header, when present. */
+			geoCountry?: string
+			/** A03: hash of the client user-agent, recorded for the next sign-in's history comparison. */
+			deviceFingerprint?: string
+		},
 		data: AuthLogService.LogArgs,
 	): Promise<void> {
 		const dataContainer = data.response.ok
@@ -16,6 +27,17 @@ class AuthLogService {
 			? dataContainer[AuthLogService.Key] as AuthLogService.Bag
 			: undefined
 
+		const baseMetadata = (data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata))
+			? data.metadata as Record<string, JSONValue>
+			: {}
+		const metadata: Record<string, JSONValue> = { ...baseMetadata }
+		if (ctx.forwarderIp !== undefined) {
+			metadata.forwarderIp = ctx.forwarderIp
+		}
+		if (ctx.forwarderUserAgent !== undefined) {
+			metadata.forwarderUserAgent = ctx.forwarderUserAgent
+		}
+
 		await db.commandBus.execute(
 			new CreateAuthLogEntryCommand({
 				success: data.response.ok,
@@ -29,7 +51,41 @@ class AuthLogService {
 				errorMessage: data.response.ok ? undefined : data.response.errorMessage,
 				ipAddress: ctx.clientIp,
 				userAgent: ctx.userAgent,
-				metadata: {},
+				metadata,
+				targetPersonId: data.targetPersonId ?? authData?.data?.targetPersonId,
+				eventData: data.eventData ?? authData?.data?.eventData,
+				geoCountry: ctx.geoCountry,
+				deviceFingerprint: ctx.deviceFingerprint,
+			}),
+		)
+	}
+
+	/**
+	 * Focused, response-agnostic emit for internal auth-path events (A19) that
+	 * originate outside the resolver layer (e.g. `ApiKeyManager` on the HTTP auth
+	 * hot path). Unlike `logAuthAction`, it does not require a GraphQL `Response`.
+	 */
+	async logSessionEvent(
+		db: DatabaseContext,
+		entry: {
+			type: AuthActionType
+			identityId: string
+			personId?: string | null
+			ipAddress?: string
+			userAgent?: string
+			success: boolean
+			eventData?: JSONValue
+		},
+	): Promise<void> {
+		await db.commandBus.execute(
+			new CreateAuthLogEntryCommand({
+				type: entry.type,
+				invokedById: entry.identityId,
+				personId: entry.personId ?? undefined,
+				success: entry.success,
+				ipAddress: entry.ipAddress,
+				userAgent: entry.userAgent,
+				eventData: entry.eventData,
 			}),
 		)
 	}
@@ -42,6 +98,9 @@ namespace AuthLogService {
 		personInput?: string // e.g. email
 		tokenId?: string
 		identityProviderId?: string
+		targetPersonId?: string
+		metadata?: JSONValue
+		eventData?: JSONValue
 	}
 
 	export type LogArgs = {

package/src/model/service/AuthPolicyManager.ts

@@ -0,0 +1,117 @@
+import { DatabaseContext } from '../utils/index.js'
+import { Response, ResponseError, ResponseOk } from '../utils/Response.js'
+import { ProjectManager } from './ProjectManager.js'
+import { AuthPoliciesQuery } from '../queries/index.js'
+import { CreateAuthPolicyCommand, DeleteAuthPolicyCommand, UpdateAuthPolicyCommand } from '../commands/index.js'
+import { AuthPolicyRow, AuthPolicyScope } from '../type/index.js'
+import { CreateAuthPolicyErrorCode, DeleteAuthPolicyErrorCode, UpdateAuthPolicyErrorCode } from '../../schema/index.js'
+
+export type AuthPolicyInputValues = {
+	scope: AuthPolicyScope
+	/** Project slug; resolved to project_id. Required for scope='project', forbidden for scope='global'. */
+	project?: string | null
+	roles: string[]
+	mfaRequired?: boolean | null
+	tokenExpiration?: string | null
+	idleTimeout?: string | null
+	graceDuration?: string | null
+	rememberMeAllowed?: boolean | null
+}
+
+/**
+ * CRUD over the `auth_policy` table (shared infra reused by A19). Project is
+ * always addressed by slug in the API and resolved to project_id here.
+ */
+export class AuthPolicyManager {
+	constructor(
+		private readonly projectManager: ProjectManager,
+	) {}
+
+	async listPolicies(db: DatabaseContext): Promise<AuthPolicyRow[]> {
+		return db.queryHandler.fetch(new AuthPoliciesQuery())
+	}
+
+	async createPolicy(db: DatabaseContext, input: AuthPolicyInputValues): Promise<Response<{ id: string }, CreateAuthPolicyErrorCode>> {
+		const projectResult = await this.resolveProjectId(db, input.scope, input.project ?? null)
+		if (!projectResult.ok) {
+			return new ResponseError(projectResult.error, projectResult.errorMessage)
+		}
+		const id = await db.commandBus.execute(
+			new CreateAuthPolicyCommand({
+				scope: input.scope,
+				projectId: projectResult.projectId,
+				roles: input.roles,
+				mfaRequired: input.mfaRequired ?? null,
+				tokenExpiration: input.tokenExpiration ?? null,
+				idleTimeout: input.idleTimeout ?? null,
+				graceDuration: input.graceDuration ?? null,
+				rememberMeAllowed: input.rememberMeAllowed ?? null,
+			}),
+		)
+		return new ResponseOk({ id })
+	}
+
+	async updatePolicy(db: DatabaseContext, id: string, input: AuthPolicyInputValues): Promise<Response<null, UpdateAuthPolicyErrorCode>> {
+		const projectResult = await this.resolveProjectId(db, input.scope, input.project ?? null)
+		if (!projectResult.ok) {
+			return new ResponseError(projectResult.error, projectResult.errorMessage)
+		}
+		const updated = await db.commandBus.execute(
+			new UpdateAuthPolicyCommand(id, {
+				scope: input.scope,
+				projectId: projectResult.projectId,
+				roles: input.roles,
+				mfaRequired: input.mfaRequired ?? null,
+				tokenExpiration: input.tokenExpiration ?? null,
+				idleTimeout: input.idleTimeout ?? null,
+				graceDuration: input.graceDuration ?? null,
+				rememberMeAllowed: input.rememberMeAllowed ?? null,
+			}),
+		)
+		if (!updated) {
+			return new ResponseError('NOT_FOUND', `Auth policy ${id} not found`)
+		}
+		return new ResponseOk(null)
+	}
+
+	async deletePolicy(db: DatabaseContext, id: string): Promise<Response<null, DeleteAuthPolicyErrorCode>> {
+		const deleted = await db.commandBus.execute(new DeleteAuthPolicyCommand(id))
+		if (!deleted) {
+			return new ResponseError('NOT_FOUND', `Auth policy ${id} not found`)
+		}
+		return new ResponseOk(null)
+	}
+
+	/**
+	 * Validates scope/project consistency and resolves a slug to project_id.
+	 * `scope='project'` requires a project (which must exist); `scope='global'`
+	 * forbids one.
+	 */
+	private async resolveProjectId(
+		db: DatabaseContext,
+		scope: AuthPolicyScope,
+		projectSlug: string | null,
+	): Promise<
+		{ ok: true; projectId: string | null } | {
+			ok: false
+			error: 'PROJECT_REQUIRED' | 'PROJECT_NOT_ALLOWED' | 'PROJECT_NOT_FOUND'
+			errorMessage: string
+		}
+	> {
+		if (scope === 'global') {
+			if (projectSlug !== null) {
+				return { ok: false, error: 'PROJECT_NOT_ALLOWED', errorMessage: 'A global auth policy must not reference a project' }
+			}
+			return { ok: true, projectId: null }
+		}
+		// scope === 'project'
+		if (projectSlug === null) {
+			return { ok: false, error: 'PROJECT_REQUIRED', errorMessage: 'A project-scoped auth policy requires a project' }
+		}
+		const project = await this.projectManager.getProjectBySlug(db, projectSlug)
+		if (!project) {
+			return { ok: false, error: 'PROJECT_NOT_FOUND', errorMessage: `Project ${projectSlug} not found` }
+		}
+		return { ok: true, projectId: project.id }
+	}
+}

package/src/model/service/AuthPolicyResolver.ts

@@ -0,0 +1,101 @@
+import { DatabaseContext } from '../utils/index.js'
+import { AllProjectRolesByIdentityQuery, AuthPoliciesQuery } from '../queries/index.js'
+import { AuthPolicyRow, EffectivePolicy } from '../type/index.js'
+import { IPostgresInterval } from 'postgres-interval'
+import { intervalToSeconds } from '../utils/interval.js'
+
+/**
+ * Resolves the effective auth policy for an identity by aggregating all matching
+ * `auth_policy` rows across the identity's entire role set (global roles + every
+ * project-membership role across all projects).
+ *
+ * Shared by A06 (consumes `mfaRequired`) and A19 (consumes the session fields).
+ *
+ * Aggregation:
+ * - `mfaRequired` = OR of every matched row's `mfa_required` (NULL = no opinion).
+ * - session fields = strictest wins: the shortest `tokenExpiration` / `idleTimeout`
+ *   and the logical AND of `rememberMeAllowed` (any matched `false` wins).
+ *
+ * When nothing matches, the result is the inert baseline
+ * (`mfaRequired=false`, session fields null) — i.e. today's behavior.
+ */
+export class AuthPolicyResolver {
+	async resolveForIdentity(db: DatabaseContext, identityId: string, globalRoles: readonly string[]): Promise<EffectivePolicy> {
+		const policies = await db.queryHandler.fetch(new AuthPoliciesQuery())
+		// Fast path: with no policies configured, enforcement is inert and we skip
+		// the cross-project role query entirely (preserves today's query shape).
+		if (policies.length === 0) {
+			return { mfaRequired: false, tokenExpiration: null, idleTimeout: null, graceDuration: null, rememberMeAllowed: null }
+		}
+		const projectRoles = await db.queryHandler.fetch(new AllProjectRolesByIdentityQuery(identityId))
+
+		// Map of project_id -> set of roles held in that project.
+		const rolesByProject = new Map<string, Set<string>>()
+		for (const { projectId, role } of projectRoles) {
+			let set = rolesByProject.get(projectId)
+			if (!set) {
+				set = new Set<string>()
+				rolesByProject.set(projectId, set)
+			}
+			set.add(role)
+		}
+
+		const globalRoleSet = new Set(globalRoles)
+
+		const matched = policies.filter(policy => this.matches(policy, globalRoleSet, rolesByProject))
+
+		return this.aggregate(matched)
+	}
+
+	private matches(policy: AuthPolicyRow, globalRoles: Set<string>, rolesByProject: Map<string, Set<string>>): boolean {
+		if (policy.scope === 'global') {
+			return policy.roles.some(role => globalRoles.has(role))
+		}
+		if (policy.scope === 'project') {
+			if (policy.project_id === null) {
+				return false
+			}
+			const projectRoles = rolesByProject.get(policy.project_id)
+			if (!projectRoles) {
+				return false
+			}
+			return policy.roles.some(role => projectRoles.has(role))
+		}
+		return false
+	}
+
+	private aggregate(policies: readonly AuthPolicyRow[]): EffectivePolicy {
+		let mfaRequired = false
+		let tokenExpiration: IPostgresInterval | null = null
+		let idleTimeout: IPostgresInterval | null = null
+		let graceDuration: IPostgresInterval | null = null
+		let rememberMeAllowed: boolean | null = null
+
+		for (const policy of policies) {
+			if (policy.mfa_required === true) {
+				mfaRequired = true
+			}
+			tokenExpiration = this.shortest(tokenExpiration, policy.token_expiration)
+			idleTimeout = this.shortest(idleTimeout, policy.idle_timeout)
+			graceDuration = this.shortest(graceDuration, policy.grace_duration)
+			if (policy.remember_me_allowed === false) {
+				rememberMeAllowed = false
+			} else if (policy.remember_me_allowed === true && rememberMeAllowed === null) {
+				rememberMeAllowed = true
+			}
+		}
+
+		return { mfaRequired, tokenExpiration, idleTimeout, graceDuration, rememberMeAllowed }
+	}
+
+	/** Strictest wins: returns the shorter of two intervals (NULL = unconstrained). */
+	private shortest(current: IPostgresInterval | null, candidate: IPostgresInterval | null): IPostgresInterval | null {
+		if (candidate === null) {
+			return current
+		}
+		if (current === null) {
+			return candidate
+		}
+		return intervalToSeconds(candidate) < intervalToSeconds(current) ? candidate : current
+	}
+}

package/src/model/service/BackupCodeManager.ts

@@ -0,0 +1,112 @@
+import { Literal, SelectBuilder } from '@contember/database'
+import { DatabaseContext } from '../utils/index.js'
+import { Providers } from '../providers.js'
+import { ConsumeBackupCodeCommand, CreateBackupCodeCommand, DeleteBackupCodesCommand } from '../commands/index.js'
+import { computeTokenHash } from '../utils/token.js'
+import { UserMailer } from '../mailing/index.js'
+import { PersonRow } from '../queries/index.js'
+
+/** Number of backup codes issued per generation. */
+const BACKUP_CODE_COUNT = 10
+/** Number of significant characters per backup code (before formatting). */
+const BACKUP_CODE_LENGTH = 10
+/**
+ * Unambiguous lowercase alphabet, without the easily confused characters
+ * 0/1/l/o. 32 symbols (base32-style).
+ */
+const ALPHABET = 'abcdefghijkmnpqrstuvwxyz23456789'
+
+/**
+ * Manages MFA backup/recovery codes (the `person_backup_code` table).
+ *
+ * Codes only exist for a person who has enrolled TOTP. Behavior for everyone
+ * else is unchanged. Plaintext codes are shown exactly once (on generation);
+ * only their sha256 hashes are stored.
+ */
+export class BackupCodeManager {
+	constructor(
+		private readonly mailer: UserMailer,
+		private readonly providers: Pick<Providers, 'uuid' | 'now' | 'randomBytes'>,
+	) {}
+
+	/**
+	 * Replaces the whole set: deletes any existing codes for the person, issues
+	 * {@link BACKUP_CODE_COUNT} fresh ones, stores their hashes and returns the
+	 * formatted plaintext codes (to be shown once).
+	 */
+	async generate(dbContext: DatabaseContext, personId: string): Promise<string[]> {
+		const codes: string[] = []
+		for (let i = 0; i < BACKUP_CODE_COUNT; i++) {
+			codes.push(await this.generateCode())
+		}
+		// Replace the whole set atomically: a mid-flow failure must never leave the
+		// person with a partial set that doesn't match the plaintext codes returned
+		// to (and shown once to) the caller.
+		await dbContext.transaction(async tx => {
+			await tx.commandBus.execute(new DeleteBackupCodesCommand(personId))
+			for (const code of codes) {
+				// Hash the normalized form so verification (which normalizes its input) matches.
+				await tx.commandBus.execute(new CreateBackupCodeCommand(personId, this.hash(this.normalize(code))))
+			}
+		})
+		return codes
+	}
+
+	/**
+	 * Normalizes the supplied code, then atomically consumes a single unused
+	 * matching code. Returns whether a code was actually consumed. Safe against
+	 * double-spend (see {@link ConsumeBackupCodeCommand}).
+	 */
+	async verifyAndConsume(dbContext: DatabaseContext, person: PersonRow, code: string): Promise<boolean> {
+		const normalized = this.normalize(code)
+		if (normalized.length === 0) {
+			return false
+		}
+		const consumed = await dbContext.commandBus.execute(new ConsumeBackupCodeCommand(person.id, this.hash(normalized)))
+		if (consumed && (await this.countUnused(dbContext, person.id)) === 0) {
+			// Best-effort: notify the person they have no backup codes left. A failed
+			// email must never block or fail sign-in, so swallow any error.
+			try {
+				await this.mailer.sendBackupCodesExhaustedEmail(dbContext, { email: person.email ?? '' }, { projectId: null, variant: '' })
+			} catch {
+				// ignore
+			}
+		}
+		return consumed
+	}
+
+	async deleteForPerson(dbContext: DatabaseContext, personId: string): Promise<void> {
+		await dbContext.commandBus.execute(new DeleteBackupCodesCommand(personId))
+	}
+
+	/** Number of still-usable backup codes for the person. */
+	async countUnused(dbContext: DatabaseContext, personId: string): Promise<number> {
+		const rows = await SelectBuilder.create<{ count: string }>()
+			.from('person_backup_code')
+			.select(new Literal('count(*)::text as count'))
+			.where({ person_id: personId })
+			.where(expr => expr.isNull('used_at'))
+			.getResult(dbContext.client)
+		return Number(rows[0]?.count ?? '0')
+	}
+
+	/** Strips formatting (hyphens/whitespace) and lowercases — display formatting must not affect verification. */
+	private normalize(code: string): string {
+		return code.replace(/[\s-]/g, '').toLowerCase()
+	}
+
+	private hash(normalizedCode: string): string {
+		return computeTokenHash(normalizedCode)
+	}
+
+	private async generateCode(): Promise<string> {
+		const bytes = await this.providers.randomBytes(BACKUP_CODE_LENGTH)
+		let raw = ''
+		for (let i = 0; i < BACKUP_CODE_LENGTH; i++) {
+			raw += ALPHABET[bytes[i] % ALPHABET.length]
+		}
+		// Single hyphen in the middle for readability, e.g. "abcde-fghij".
+		const mid = Math.floor(BACKUP_CODE_LENGTH / 2)
+		return `${raw.slice(0, mid)}-${raw.slice(mid)}`
+	}
+}

package/src/model/service/ConfigurationManager.ts

@@ -1,7 +1,7 @@
-import { ConfigInput, ConfigureErrorCode } from '../../schema'
-import { Response, ResponseOk } from '../utils/Response'
-import { DatabaseContext } from '../utils'
-import { UpdateConfigurationCommand } from '../commands'
+import { ConfigInput, ConfigureErrorCode } from '../../schema/index.js'
+import { Response, ResponseOk } from '../utils/Response.js'
+import { DatabaseContext } from '../utils/index.js'
+import { UpdateConfigurationCommand } from '../commands/index.js'
 
 export class ConfigurationManager {
 	public async updateConfiguration(db: DatabaseContext, configuration: ConfigInput): Promise<Response<null, ConfigureErrorCode>> {