@contember/engine-tenant-api 2.2.0-alpha.1 → 2.2.0-alpha.10

package/src/model/authorization/PermissionActions.ts

@@ -1,6 +1,50 @@
 import { Authorizator } from '@contember/authorization'
 import { Acl } from '@contember/schema'
 
+export type TargetIdentityPermissionTarget = {
+	readonly id: string
+	readonly globalRoles: readonly string[]
+	readonly hasProjectMemberships: boolean
+}
+
+export type TargetIdentityPermissionMeta = {
+	readonly target: TargetIdentityPermissionTarget | null
+}
+
+export type ProfileField = 'name' | 'email'
+
+export type ChangeProfilePermissionMeta = TargetIdentityPermissionMeta & {
+	readonly fields: readonly ProfileField[]
+}
+
+export type CreateSessionTokenPermissionMeta = {
+	readonly phase: 'preflight' | 'target'
+	readonly target?: TargetIdentityPermissionTarget
+	readonly requestedExpirationMinutes?: number | null
+	readonly trustForwardedClientInfo?: boolean
+}
+
+export type GlobalRoleMutationPermissionMeta = {
+	readonly requestedRoles: readonly string[]
+	readonly target: TargetIdentityPermissionTarget
+	readonly self: boolean
+}
+
+export type GlobalApiKeyPermissionMeta = {
+	readonly requestedRoles: readonly string[]
+	readonly trustForwardedClientInfo: boolean
+}
+
+export type ApiKeyPermissionMeta = {
+	readonly trustForwardedClientInfo: boolean
+}
+
+export type MailTemplatePermissionMeta = {
+	readonly kind: 'global' | 'project'
+	readonly projectSlug: string | null
+	readonly type: string
+}
+
 namespace PermissionActions {
 	export enum Resources {
 		system = 'system',
@@ -11,6 +55,7 @@ namespace PermissionActions {
 		apiKey = 'apiKey',
 		mailTemplate = 'mailTemplate',
 		idp = 'idp',
+		customRole = 'customRole',
 	}
 
 	export const CONFIGURE = Authorizator.createAction(Resources.system, 'configure')
@@ -18,35 +63,42 @@ namespace PermissionActions {
 	export const AUTH_LOG_VIEW = Authorizator.createAction(Resources.system, 'viewAuthLog')
 
 	export const IDENTITY_VIEW_PERMISSIONS = Authorizator.createAction(Resources.identity, 'viewPermissions')
-	export const IDENTITY_ADD_GLOBAL_ROLES = (roles?: readonly string[]) => Authorizator.createAction(Resources.identity, 'addGlobalRoles', { roles })
-	export const IDENTITY_REMOVE_GLOBAL_ROLES = (roles?: readonly string[]) =>
-		Authorizator.createAction(Resources.identity, 'removeGlobalRoles', { roles })
+	export const IDENTITY_ADD_GLOBAL_ROLES = (meta?: GlobalRoleMutationPermissionMeta) =>
+		Authorizator.createAction(Resources.identity, 'addGlobalRoles', meta)
+	export const IDENTITY_REMOVE_GLOBAL_ROLES = (meta?: GlobalRoleMutationPermissionMeta) =>
+		Authorizator.createAction(Resources.identity, 'removeGlobalRoles', meta)
 
-	export const PERSON_DISABLE = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'disable', { roles })
-	export const PERSON_FORCE_SIGN_OUT = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'forceSignOut', { roles })
-	export const PERSON_RESET_MFA = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'resetMfa', { roles })
+	export const PERSON_DISABLE = (target: TargetIdentityPermissionTarget | null) => Authorizator.createAction(Resources.person, 'disable', { target })
+	export const PERSON_FORCE_SIGN_OUT = (target: TargetIdentityPermissionTarget | null) =>
+		Authorizator.createAction(Resources.person, 'forceSignOut', { target })
+	export const PERSON_RESET_MFA = (target: TargetIdentityPermissionTarget | null) =>
+		Authorizator.createAction(Resources.person, 'resetMfa', { target })
 	export const PERSON_REVOKE_SESSION = Authorizator.createAction(Resources.person, 'revokeSession')
-	export const PERSON_VIEW_SESSIONS = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'viewSessions', { roles })
+	export const PERSON_VIEW_SESSIONS = (target: TargetIdentityPermissionTarget | null) =>
+		Authorizator.createAction(Resources.person, 'viewSessions', { target })
 
 	export const PERSON_VIEW = Authorizator.createAction(Resources.person, 'view')
 	export const PERSON_LIST = Authorizator.createAction(Resources.person, 'list')
 	export const PERSON_SIGN_IN = Authorizator.createAction(Resources.person, 'signIn')
-	export const PERSON_SIGN_UP = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'signUp', { roles })
+	export const PERSON_SIGN_UP = (requestedRoles?: readonly string[]) => Authorizator.createAction(Resources.person, 'signUp', { requestedRoles })
 	export const PERSON_SIGN_OUT = Authorizator.createAction(Resources.person, 'signOut')
 	export const PERSON_SETUP_OTP = Authorizator.createAction(Resources.person, 'setupOtp')
-	export const PERSON_CHANGE_PROFILE = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'changeProfile', { roles })
+	export const PERSON_CHANGE_PROFILE = (target: TargetIdentityPermissionTarget | null, fields: readonly ProfileField[]) =>
+		Authorizator.createAction(Resources.person, 'changeProfile', { target, fields })
 	export const PERSON_CHANGE_MY_PROFILE = Authorizator.createAction(Resources.person, 'changeMyProfile')
 	export const PERSON_TOGGLE_PASSWORDLESS = Authorizator.createAction(Resources.person, 'togglePasswordless')
-	export const PERSON_CHANGE_PASSWORD = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'changePassword', { roles })
+	export const PERSON_CHANGE_PASSWORD = (target: TargetIdentityPermissionTarget | null) =>
+		Authorizator.createAction(Resources.person, 'changePassword', { target })
 	export const PERSON_CHANGE_MY_PASSWORD = Authorizator.createAction(Resources.person, 'changeMyPassword')
 	export const PERSON_RESET_PASSWORD = Authorizator.createAction(Resources.person, 'resetPassword')
 	export const PERSON_CREATE_IDP_URL = Authorizator.createAction(Resources.person, 'createIdPUrl')
 	export const PERSON_SIGN_IN_IDP = Authorizator.createAction(Resources.person, 'signInIdp')
-	export const PERSON_VIEW_IDP = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'viewIdp', { roles })
+	export const PERSON_VIEW_IDP = (target: TargetIdentityPermissionTarget | null) => Authorizator.createAction(Resources.person, 'viewIdp', { target })
 	export const PERSON_DISCONNECT_MY_IDP = Authorizator.createAction(Resources.person, 'disconnectMyIdp')
 	export const PERSON_REQUEST_PASSWORDLESS_SIGN_IN = Authorizator.createAction(Resources.person, 'requestPasswordlessSignIn')
 	export const PERSON_PASSWORDLESS_SIGN_IN = Authorizator.createAction(Resources.person, 'passwordlessSignIn')
-	export const PERSON_CREATE_SESSION_KEY = (roles?: readonly string[]) => Authorizator.createAction(Resources.person, 'createSessionToken', { roles })
+	export const PERSON_CREATE_SESSION_KEY = (meta: CreateSessionTokenPermissionMeta) =>
+		Authorizator.createAction(Resources.person, 'createSessionToken', meta)
 
 	export const PERSON_INVITE = (memberships: readonly Acl.Membership[]) => Authorizator.createAction(Resources.person, 'invite', { memberships })
 	export const PERSON_INVITE_UNMANAGED = (memberships: readonly Acl.Membership[]) =>
@@ -69,20 +121,25 @@ namespace PermissionActions {
 	export const PROJECT_UPDATE_MEMBER = (memberships: readonly Acl.Membership[]) =>
 		Authorizator.createAction(Resources.project, 'updateMember', { memberships })
 
-	export const API_KEY_CREATE = Authorizator.createAction(Resources.apiKey, 'create')
-	export const API_KEY_CREATE_GLOBAL = (roles?: readonly string[]) => Authorizator.createAction(Resources.apiKey, 'createGlobal', { roles })
+	export const API_KEY_CREATE = (meta?: ApiKeyPermissionMeta) => Authorizator.createAction(Resources.apiKey, 'create', meta)
+	export const API_KEY_CREATE_GLOBAL = (meta?: GlobalApiKeyPermissionMeta) => Authorizator.createAction(Resources.apiKey, 'createGlobal', meta)
 	export const API_KEY_DISABLE = Authorizator.createAction(Resources.apiKey, 'disable')
 	export const API_KEY_LIST = Authorizator.createAction(Resources.apiKey, 'list')
 
-	export const MAIL_TEMPLATE_ADD = Authorizator.createAction(Resources.mailTemplate, 'add')
-	export const MAIL_TEMPLATE_REMOVE = Authorizator.createAction(Resources.mailTemplate, 'remove')
-	export const MAIL_TEMPLATE_LIST = Authorizator.createAction(Resources.mailTemplate, 'list')
+	// meta is optional only so a grant can be registered without one — `Permissions.allow`
+	// keys on resource + privilege and never reads it. Every check site passes it.
+	export const MAIL_TEMPLATE_ADD = (meta?: MailTemplatePermissionMeta) => Authorizator.createAction(Resources.mailTemplate, 'add', meta)
+	export const MAIL_TEMPLATE_REMOVE = (meta?: MailTemplatePermissionMeta) => Authorizator.createAction(Resources.mailTemplate, 'remove', meta)
+	export const MAIL_TEMPLATE_LIST = (meta?: MailTemplatePermissionMeta) => Authorizator.createAction(Resources.mailTemplate, 'list', meta)
 
 	export const IDP_ADD = Authorizator.createAction(Resources.idp, 'add')
 	export const IDP_UPDATE = Authorizator.createAction(Resources.idp, 'update')
 	export const IDP_DISABLE = Authorizator.createAction(Resources.idp, 'disable')
 	export const IDP_ENABLE = Authorizator.createAction(Resources.idp, 'enable')
 	export const IDP_LIST = Authorizator.createAction(Resources.idp, 'list')
+
+	export const CUSTOM_ROLE_MANAGE = Authorizator.createAction(Resources.customRole, 'manage')
+	export const CUSTOM_ROLE_VIEW = Authorizator.createAction(Resources.customRole, 'view')
 }
 
 export { PermissionActions }

package/src/model/authorization/PermissionContextFactory.ts

@@ -4,17 +4,53 @@ import { PermissionContext } from './PermissionContext.js'
 import { ProjectScopeFactory } from './ProjectScopeFactory.js'
 import { ProjectSchemaResolver } from '../type/index.js'
 import { DatabaseContext } from '../utils/index.js'
+import { CustomRoleAuthorizator } from './CustomRoleAuthorizator.js'
+import { Identity } from './Identity.js'
 
 export class PermissionContextFactory {
 	constructor(
-		private readonly authorizator: Authorizator,
+		private readonly authorizator: Authorizator<Identity>,
 		private readonly identityFactory: IdentityFactory,
 		private readonly projectScopeFactory: ProjectScopeFactory,
 		private readonly schemaResolver: ProjectSchemaResolver,
 	) {}
 
-	public create(db: DatabaseContext, args: { id: string; roles: readonly string[] }): PermissionContext {
+	public create(
+		db: DatabaseContext,
+		args: { id: string; roles: readonly string[] },
+		requestAuthorizator?: Authorizator<Identity>,
+	): PermissionContext {
+		const authorizator = this.createAuthorizator(db, requestAuthorizator)
+		return this.buildContext(db, args, authorizator)
+	}
+
+	/**
+	 * Same as `create`, but resolves the custom-role definitions before returning, so
+	 * the request never has to query for them while holding a transaction open.
+	 */
+	public async createPreloaded(
+		db: DatabaseContext,
+		args: { id: string; roles: readonly string[] },
+		requestAuthorizator?: Authorizator<Identity>,
+	): Promise<PermissionContext> {
+		const authorizator = this.createAuthorizator(db, requestAuthorizator)
+		await authorizator.preload(args.roles)
+		return this.buildContext(db, args, authorizator)
+	}
+
+	private createAuthorizator(db: DatabaseContext, requestAuthorizator?: Authorizator<Identity>): CustomRoleAuthorizator {
+		const customRoleCache = requestAuthorizator instanceof CustomRoleAuthorizator
+			? requestAuthorizator.customRoleCache
+			: undefined
+		return new CustomRoleAuthorizator(this.authorizator, db, customRoleCache)
+	}
+
+	private buildContext(
+		db: DatabaseContext,
+		args: { id: string; roles: readonly string[] },
+		authorizator: CustomRoleAuthorizator,
+	): PermissionContext {
 		const identity = this.identityFactory.create(db, args)
-		return new PermissionContext(identity, this.authorizator, this.projectScopeFactory, this.schemaResolver)
+		return new PermissionContext(identity, authorizator, this.projectScopeFactory, this.schemaResolver)
 	}
 }

package/src/model/authorization/PermissionsFactory.ts

@@ -1,18 +1,44 @@
 import { Permissions } from '@contember/authorization'
-import { PermissionActions } from './PermissionActions.js'
-import { TenantRole } from './Roles.js'
-
-const allowedRoles = new Set<string>([TenantRole.LOGIN, TenantRole.PROJECT_ADMIN, TenantRole.ENTRYPOINT_DEPLOYER])
-
-const projectAdminAllowedInputRoles = ({ roles }: { roles?: readonly string[] }) => {
-	return roles === undefined || roles.every(it => allowedRoles.has(it))
-}
-
-const forbiddenRoles = new Set<string>([TenantRole.SUPER_ADMIN, TenantRole.PROJECT_CREATOR])
-
-const projectAdminUseRolesVerifier = ({ roles }: { roles?: readonly string[] }) => {
-	return roles === undefined || roles.every(it => !forbiddenRoles.has(it))
-}
+import {
+	ApiKeyPermissionMeta,
+	ChangeProfilePermissionMeta,
+	CreateSessionTokenPermissionMeta,
+	GlobalApiKeyPermissionMeta,
+	GlobalRoleMutationPermissionMeta,
+	PermissionActions,
+	TargetIdentityPermissionMeta,
+} from './PermissionActions.js'
+import { NON_DELEGABLE_TENANT_ROLES, TenantRole } from './Roles.js'
+
+const projectAdminAllowsRoles = (roles: readonly string[] | undefined): boolean =>
+	roles === undefined || roles.every(role => !NON_DELEGABLE_TENANT_ROLES.has(role))
+
+const projectAdminAllowedSignUpRoles = (meta: { readonly requestedRoles?: readonly string[] }) => projectAdminAllowsRoles(meta.requestedRoles)
+
+/**
+ * A key minted with trust-forwarded-info decides what lands in the audit log and what per-IP rate limits key on,
+ * so delegated authority may not mint one — same rule the custom-role grants apply via `allowTrustForwardedClientInfo`.
+ */
+const projectAdminAllowsTrustForwardedClientInfo = (meta: { readonly trustForwardedClientInfo?: boolean } | undefined) =>
+	meta?.trustForwardedClientInfo !== true
+
+const projectAdminAllowedApiKey = (meta: ApiKeyPermissionMeta | undefined) => projectAdminAllowsTrustForwardedClientInfo(meta)
+
+const projectAdminAllowedGlobalApiKeyRoles = (meta: GlobalApiKeyPermissionMeta | undefined) =>
+	projectAdminAllowsRoles(meta?.requestedRoles) && projectAdminAllowsTrustForwardedClientInfo(meta)
+
+const projectAdminAllowedRoleMutation = (meta: GlobalRoleMutationPermissionMeta | undefined) =>
+	meta === undefined
+	|| (
+		projectAdminAllowsRoles(meta.requestedRoles)
+		&& meta.target.globalRoles.every(role => !NON_DELEGABLE_TENANT_ROLES.has(role))
+	)
+
+const projectAdminMayTarget = (meta: TargetIdentityPermissionMeta) =>
+	meta.target === null || meta.target.globalRoles.every(role => !NON_DELEGABLE_TENANT_ROLES.has(role))
+
+const projectAdminMayCreateSession = (meta: CreateSessionTokenPermissionMeta) =>
+	meta.phase === 'preflight' || meta.target?.globalRoles.every(role => !NON_DELEGABLE_TENANT_ROLES.has(role)) === true
 
 class PermissionsFactory {
 	public create(): Permissions {
@@ -41,21 +67,27 @@ class PermissionsFactory {
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PROJECT_VIEW)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDENTITY_VIEW_PERMISSIONS)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_VIEW)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_CREATE)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_LIST)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_CREATE(), projectAdminAllowedApiKey)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_DISABLE)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_CREATE_GLOBAL(), projectAdminAllowedInputRoles)
-
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_SIGN_UP(), projectAdminAllowedInputRoles)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDENTITY_ADD_GLOBAL_ROLES(), projectAdminAllowedInputRoles)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDENTITY_REMOVE_GLOBAL_ROLES(), projectAdminAllowedInputRoles)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_CREATE_SESSION_KEY(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_DISABLE(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_FORCE_SIGN_OUT(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_RESET_MFA(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_VIEW_SESSIONS(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_VIEW_IDP(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_CHANGE_PROFILE(), projectAdminUseRolesVerifier)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_CHANGE_PASSWORD(), projectAdminUseRolesVerifier)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_LIST)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.API_KEY_CREATE_GLOBAL(), projectAdminAllowedGlobalApiKeyRoles)
+
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_SIGN_UP(), projectAdminAllowedSignUpRoles)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDENTITY_ADD_GLOBAL_ROLES(), projectAdminAllowedRoleMutation)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDENTITY_REMOVE_GLOBAL_ROLES(), projectAdminAllowedRoleMutation)
+		permissions.allow(
+			TenantRole.PROJECT_ADMIN,
+			PermissionActions.PERSON_CREATE_SESSION_KEY({ phase: 'preflight' }),
+			projectAdminMayCreateSession,
+		)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_DISABLE(null), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_FORCE_SIGN_OUT(null), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_RESET_MFA(null), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_VIEW_SESSIONS(null), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_VIEW_IDP(null), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_CHANGE_PROFILE(null, []), projectAdminMayTarget)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_CHANGE_PASSWORD(null), projectAdminMayTarget)
 
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PROJECT_VIEW_MEMBER([]))
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PROJECT_ADD_MEMBER([]))
@@ -66,9 +98,9 @@ class PermissionsFactory {
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_INVITE([]))
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.PERSON_INVITE_UNMANAGED([]))
 
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_ADD)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_REMOVE)
-		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_LIST)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_ADD())
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_REMOVE())
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.MAIL_TEMPLATE_LIST())
 
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDP_ADD)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDP_UPDATE)
@@ -76,6 +108,8 @@ class PermissionsFactory {
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDP_ENABLE)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.IDP_LIST)
 
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.AUTH_LOG_VIEW)
+		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.CUSTOM_ROLE_VIEW)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.ENTRYPOINT_DEPLOY)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.CONFIGURE)
 		permissions.allow(TenantRole.PROJECT_ADMIN, PermissionActions.CONFIG_VIEW)

package/src/model/authorization/Roles.ts

@@ -8,3 +8,16 @@ export enum TenantRole {
 	PROJECT_ADMIN = 'project_admin',
 	ENTRYPOINT_DEPLOYER = 'entrypoint_deployer',
 }
+
+/**
+ * Roles no delegated authority may ever grant, hold as a target, or impersonate.
+ * Enforced by the static PROJECT_ADMIN verifiers and by custom-role grants alike —
+ * keep it the single source, so a newly protected role cannot be added to one path only.
+ */
+export const NON_DELEGABLE_TENANT_ROLES: ReadonlySet<string> = new Set([
+	TenantRole.SUPER_ADMIN,
+	TenantRole.PROJECT_CREATOR,
+])
+
+/** Shared by custom-role slug validation and by role references inside grant configuration. */
+export const ROLE_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/

package/src/model/authorization/TargetIdentityPermission.ts

@@ -0,0 +1,37 @@
+import { DatabaseContext } from '../utils/index.js'
+import { IdentityHasProjectMembershipsQuery, IdentityQuery, IdentityQueryResult } from '../queries/index.js'
+import { TargetIdentityPermissionTarget } from './PermissionActions.js'
+import { TenantRole } from './Roles.js'
+import { batchLoader } from '../../utils/batchQuery.js'
+
+const projectMembershipPresenceLoader = batchLoader<string, ReadonlySet<string>, boolean>(
+	async (identityIds, db) => await db.queryHandler.fetch(new IdentityHasProjectMembershipsQuery(identityIds)),
+	(identityId, identitiesWithMemberships) => identitiesWithMemberships.has(identityId),
+)
+
+/** Batches the identity lookup that precedes a target-identity permission check. */
+export const targetIdentityLoader = batchLoader<string, Record<string, IdentityQueryResult>, IdentityQueryResult | undefined>(
+	async (identityIds, db) => {
+		const identities = await db.queryHandler.fetch(new IdentityQuery(identityIds))
+		return Object.fromEntries(identities.map(identity => [identity.id, identity]))
+	},
+	(identityId, identities) => identities[identityId],
+)
+
+export const createTargetIdentityPermissionTarget = async (
+	db: DatabaseContext,
+	identity: { readonly id: string; readonly roles: readonly string[] },
+): Promise<TargetIdentityPermissionTarget> => ({
+	id: identity.id,
+	globalRoles: identity.roles,
+	hasProjectMemberships: identity.roles.includes(TenantRole.SUPER_ADMIN)
+		|| identity.roles.includes(TenantRole.PROJECT_ADMIN)
+		|| await db.batchLoad(projectMembershipPresenceLoader, identity.id),
+})
+
+/** Convenience for the common case where the caller already holds the target's person row. */
+export const createPersonPermissionTarget = async (
+	db: DatabaseContext,
+	person: { readonly identity_id: string; readonly roles: readonly string[] } | null,
+): Promise<TargetIdentityPermissionTarget | null> =>
+	person === null ? null : await createTargetIdentityPermissionTarget(db, { id: person.identity_id, roles: person.roles })

package/src/model/authorization/index.ts

@@ -3,9 +3,12 @@ export * from './Identity.js'
 export * from './IdentityFactory.js'
 export * from './IdentityScope.js'
 export * from './MembershipMatcher.js'
+export * from './CustomRoleAuthorizator.js'
+export * from './CustomRolePermissions.js'
 export * from './PermissionActions.js'
 export * from './PermissionContext.js'
 export * from './PermissionContextFactory.js'
+export * from './TargetIdentityPermission.js'
 export * from './PermissionsFactory.js'
 export * from './ProjectScope.js'
 export * from './ProjectScopeFactory.js'

package/src/model/commands/apiKey/ApiKeyHelper.ts

@@ -1,9 +1,15 @@
 import { ApiKey } from '../../type/index.js'
 import { Providers } from '../../providers.js'
 import { plusMinutes } from '../../utils/time.js'
+import { Literal } from '@contember/database'
 
 const DEFAULT_EXPIRATION = 30
 export class ApiKeyHelper {
+	/**
+	 * App-clock expiry Date. Kept only for ProlongApiKeyCommand's significance
+	 * throttle (a write-rate optimization, not an auth gate). The value actually
+	 * stored / compared runs on the DB clock — see {@link getExpirationLiteral}.
+	 */
 	public static getExpiration(providers: Providers, type: ApiKey.Type, expiration?: number | null): Date | null {
 		switch (type) {
 			case ApiKey.Type.PERMANENT:
@@ -16,4 +22,21 @@ export class ApiKeyHelper {
 				return null
 		}
 	}
+
+	/** Lifetime of a session key in seconds (`expiration` minutes, default 30). */
+	public static getSessionExpirationSeconds(expiration?: number | null): number {
+		return (expiration || DEFAULT_EXPIRATION) * 60
+	}
+
+	/**
+	 * DB-clock expiry expression for issuance: `now() + <lifetime>` evaluated on the
+	 * database clock, so the expiry gate (ApiKeyByTokenQuery's `is_expired`) compares
+	 * against the same clock and cannot be weakened by app/DB skew. NULL for
+	 * non-session keys (they never expire). See engine-tenant-api/CLAUDE.md.
+	 */
+	public static getExpirationLiteral(type: ApiKey.Type, expiration?: number | null): Literal | null {
+		return type === ApiKey.Type.SESSION
+			? new Literal('now() + make_interval(secs => ?)', [ApiKeyHelper.getSessionExpirationSeconds(expiration)])
+			: null
+	}
 }

package/src/model/commands/apiKey/CreateApiKeyCommand.ts

@@ -1,7 +1,7 @@
 import { Command } from '../Command.js'
 import { ApiKey } from '../../type/index.js'
 import { ApiKeyHelper } from './ApiKeyHelper.js'
-import { InsertBuilder } from '@contember/database'
+import { InsertBuilder, Literal } from '@contember/database'
 import { computeTokenHash, generateToken, TokenHash } from '../../utils/index.js'
 import { ApiKeyRequestInfo } from './ProlongApiKeyCommand.js'
 
@@ -18,7 +18,11 @@ interface CreateSessionApiKeyArgs {
 	 * `idleTimeout` is a Postgres interval literal (e.g. `'15 minutes'`).
 	 */
 	idleTimeout?: string | null
-	maxExpiresAt?: Date | null
+	/**
+	 * Absolute lifetime cap in seconds (A19). Written as `now() + interval` on the DB
+	 * clock so the cap is compared against the same clock. NULL = uncapped.
+	 */
+	maxExpirationSeconds?: number | null
 }
 
 interface CreatePermanentApiKeyArgs {
@@ -51,9 +55,11 @@ export class CreateApiKeyCommand implements Command<CreateApiKeyCommandResult> {
 		const args = this.args
 		const sessionPolicy = args.type === ApiKey.Type.SESSION
 			? {
-				issued_at: providers.now(),
+				issued_at: providers.now(), // display/ordering only, never compared
 				idle_timeout: args.idleTimeout ?? null,
-				max_expires_at: args.maxExpiresAt ?? null,
+				max_expires_at: args.maxExpirationSeconds != null
+					? new Literal('now() + make_interval(secs => ?)', [args.maxExpirationSeconds])
+					: null,
 			}
 			: { issued_at: null, idle_timeout: null, max_expires_at: null }
 		await InsertBuilder.create()
@@ -64,7 +70,8 @@ export class CreateApiKeyCommand implements Command<CreateApiKeyCommandResult> {
 				type: this.args.type,
 				identity_id: this.args.identityId,
 				disabled_at: null,
-				expires_at: ApiKeyHelper.getExpiration(providers, this.args.type, this.args.expiration),
+				// expires_at on the DB clock so the verify gate compares like-for-like.
+				expires_at: ApiKeyHelper.getExpirationLiteral(this.args.type, this.args.expiration),
 				expiration: this.args.expiration || null,
 				created_at: providers.now(),
 				created_ip: this.args.requestInfo?.ip || null,

package/src/model/commands/apiKey/ProlongApiKeyCommand.ts

@@ -1,12 +1,14 @@
 import { Command } from '../Command.js'
 import { ApiKey } from '../../type/index.js'
 import { ApiKeyHelper } from './ApiKeyHelper.js'
-import { QueryBuilder, UpdateBuilder } from '@contember/database'
+import { Literal, QueryBuilder, UpdateBuilder } from '@contember/database'
 
 /**
- * Tracking writes (`last_used_at`) are throttled to at most once per this window, so
- * an idle check must add this slack to avoid prematurely expiring an active session
- * whose `last_used_at` is intentionally stale (see {@link ApiKeyManager.verifyAndProlong}).
+ * Tracking writes (`last_ip`, `last_user_agent`, `last_used_at`) are throttled to at most once per
+ * this window, even when the IP or User-Agent changes: a key shared by several service replicas
+ * alternates between their addresses, and writing every change makes its row a lock hotspot.
+ * An idle check must add this slack to avoid prematurely expiring an active session whose
+ * `last_used_at` is intentionally stale (see {@link ApiKeyManager.verifyAndProlong}).
  */
 export const PROLONG_THROTTLE_MS = 60_000
 
@@ -51,7 +53,7 @@ export class ProlongApiKeyCommand implements Command<void> {
 
 		const requestIp = this.requestInfo?.ip || null
 		const requestUserAgent = this.requestInfo?.userAgent || null
-		const updateTracking = this.shouldUpdateTracking(now, requestIp, requestUserAgent)
+		const updateTracking = this.shouldUpdateTracking(now)
 
 		if (!updateExpiration && !updateTracking) {
 			return
@@ -59,12 +61,21 @@ export class ProlongApiKeyCommand implements Command<void> {
 
 		const values: QueryBuilder.Values = {}
 		if (updateExpiration && newExpiration !== null) {
-			values.expires_at = newExpiration
+			// Write the sliding expiry on the DB clock and clamp to the stored
+			// max_expires_at in SQL (LEAST ignores a NULL cap → uncapped window). The JS
+			// throttle above only decides *whether* to write; the expiry gate itself is
+			// computed on the DB clock. See engine-tenant-api/CLAUDE.md.
+			values.expires_at = new Literal('LEAST(now() + make_interval(secs => ?), "max_expires_at")', [
+				ApiKeyHelper.getSessionExpirationSeconds(this.expiration),
+			])
 		}
 		if (updateTracking) {
 			values.last_ip = requestIp
 			values.last_user_agent = requestUserAgent
-			values.last_used_at = now
+			// last_used_at on the DB clock: it's compared against now() in the idle gate
+			// (ApiKeyByTokenQuery's is_idle_expired), so it must be written on the same
+			// clock. The app-clock `now` above only drives the write-rate throttle. See CLAUDE.md.
+			values.last_used_at = new Literal('now()')
 		}
 
 		const qb = UpdateBuilder.create()
@@ -74,17 +85,14 @@ export class ProlongApiKeyCommand implements Command<void> {
 		await qb.execute(db)
 	}
 
-	private shouldUpdateTracking(now: Date, requestIp: string | null, requestUserAgent: string | null): boolean {
+	private shouldUpdateTracking(now: Date): boolean {
 		if (!this.requestInfo) {
 			return false
 		}
-		const last = this.tracking
-		if (!last || last.lastUsedAt === null) {
+		const lastUsedAt = this.tracking?.lastUsedAt
+		if (!lastUsedAt) {
 			return true
 		}
-		if (requestIp !== last.lastIp || requestUserAgent !== last.lastUserAgent) {
-			return true
-		}
-		return now.getTime() - last.lastUsedAt.getTime() >= PROLONG_THROTTLE_MS
+		return now.getTime() - lastUsedAt.getTime() >= PROLONG_THROTTLE_MS
 	}
 }

package/src/model/commands/authLog/CreateAuthLogEntryCommand.ts

@@ -42,6 +42,7 @@ namespace CreateAuthLogEntryCommand {
 		invokedById?: string
 		personInputIdentifier?: string
 		personId?: string
+		/** A `person_token` id (password reset, e-mail verification, passwordless). FK-checked, so never an `api_key` id: put that in `eventData`. */
 		personTokenId?: string
 		success: boolean
 		errorCode?: string

package/src/model/commands/configuration/UpdateConfigurationCommand.ts

@@ -14,12 +14,11 @@ export class UpdateConfigurationCommand implements Command<void> {
 		const captcha = this.configuration.captcha
 		const rl = this.configuration.rateLimits
 
-		// Encrypt captcha secret at rest. Empty string clears the value;
-		// non-empty re-encrypts so we always rotate to the latest key version.
+		// Null and omission preserve the stored secret; only an empty string clears it.
 		let captchaSecretCol: Buffer | null | undefined
 		let captchaSecretVersionCol: number | null | undefined
-		if (captcha?.secret !== undefined) {
-			if (captcha.secret === '' || captcha.secret === null) {
+		if (captcha?.secret !== undefined && captcha.secret !== null) {
+			if (captcha.secret === '') {
 				captchaSecretCol = null
 				captchaSecretVersionCol = null
 			} else {
@@ -79,6 +78,8 @@ export class UpdateConfigurationCommand implements Command<void> {
 					rate_limit_email_otp_per_person_window: rl?.emailOtpPerPerson?.window ?? undefined,
 					rate_limit_email_verification_per_ip_limit: rl?.emailVerificationPerIp?.limit ?? undefined,
 					rate_limit_email_verification_per_ip_window: rl?.emailVerificationPerIp?.window ?? undefined,
+					panel_global_roles: this.configuration.panel?.globalRoles ?? undefined,
+					panel_project_roles: this.configuration.panel?.projectRoles ?? undefined,
 				} satisfies {
 					[K in keyof ConfigRow]: (IPostgresInterval extends ConfigRow[K] ? string : never) | Exclude<ConfigRow[K], IPostgresInterval> | undefined
 				},

package/src/model/commands/customRole/CreateCustomRoleCommand.ts

@@ -0,0 +1,30 @@
+import { Command } from '../Command.js'
+import { InsertBuilder } from '@contember/database'
+
+/** Inserts a new `custom_role` row. Returns the generated id. */
+export class CreateCustomRoleCommand implements Command<string> {
+	constructor(
+		private readonly values: {
+			slug: string
+			description: string | null
+			grants: unknown
+		},
+	) {}
+
+	async execute({ db, providers }: Command.Args): Promise<string> {
+		const id = providers.uuid()
+		const now = providers.now()
+		await InsertBuilder.create()
+			.into('custom_role')
+			.values({
+				id,
+				slug: this.values.slug,
+				description: this.values.description,
+				grants: JSON.stringify(this.values.grants),
+				created_at: now,
+				updated_at: now,
+			})
+			.execute(db)
+		return id
+	}
+}

package/src/model/commands/customRole/DeleteCustomRoleCommand.ts

@@ -0,0 +1,20 @@
+import { Command } from '../Command.js'
+import { DeleteBuilder } from '@contember/database'
+
+/**
+ * Removes a role definition outright. The slug becomes reusable; the audit log
+ * (`custom_role_change`) is what preserves the trace of what it used to grant.
+ * Callers must strip the slug from every identity in the same transaction —
+ * see `RemoveCustomRoleAssignmentsCommand`.
+ */
+export class DeleteCustomRoleCommand implements Command<boolean> {
+	constructor(private readonly slug: string) {}
+
+	async execute({ db }: Command.Args): Promise<boolean> {
+		const result = await DeleteBuilder.create()
+			.from('custom_role')
+			.where({ slug: this.slug })
+			.execute(db)
+		return result > 0
+	}
+}