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

package/src/schema/tenant.graphql.ts

@@ -16,21 +16,57 @@ const schema: DocumentNode = gql`
 	type Query {
 		me: Identity!
 		personById(id: String!): Person
+		"""
+		List persons across the tenant. SUPER_ADMIN sees every person; otherwise
+		the result is scoped to persons who are members of a project the caller may
+		view members of (i.e. the same persons reachable via \`project.members\`),
+		so a PROJECT_ADMIN sees only their projects' members. \`filter\` matches by
+		e-mail (case-insensitive), \`personId\`, or \`identityId\`; \`limit\`/\`offset\`
+		paginate. Returns an empty list when the caller may not list anyone.
+		"""
+		persons(filter: PersonsFilter, limit: Int, offset: Int): [Person!]!
 		projects: [Project!]!
 		projectBySlug(slug: String!): Project
 		projectMemberships(projectSlug: String!, identityId: String!): [Membership!]!
+		"""
+		List global (project-independent) permanent API keys — those created via
+		\`createGlobalApiKey\`, whose identity carries global roles and no project
+		membership. Requires the \`apiKey:list\` permission — by default granted
+		only to SUPER_ADMIN via the wildcard ALL-resource/ALL-privilege grant.
+		Returns an empty list when the caller may not list them. To list a
+		project's keys use \`project.apiKeys\`.
+		"""
+		globalApiKeys: [ApiKey!]!
 		checkResetPasswordToken(requestId: String!, token: String!): CheckResetPasswordTokenCode!
 
 		identityProviders: [IdentityProvider!]!
+
 		mailTemplates: [MailTemplateData!]!
-		
+
 		configuration: Config!
+
+		"""
+		List configured auth policies (per-role MFA / session policy). Requires the
+		\`system:configure\` permission — by default granted only to SUPER_ADMIN
+		(and PROJECT_ADMIN, like \`configure\`). With no rows configured, MFA
+		enforcement is inert and sign-in behaves exactly as today.
+		"""
+		authPolicies: [AuthPolicy!]!
+
+		"""
+		Read the tenant audit log (\`person_auth_log\`). Requires the
+		\`system:viewAuthLog\` permission — by default granted only to
+		SUPER_ADMIN via the wildcard ALL-resource/ALL-privilege grant.
+		Ordered by created_at DESC. Page size is capped server-side
+		(default 100, max 500); \`hasMore\` indicates a further page exists.
+		"""
+		authLog(filter: AuthLogFilter, limit: Int, offset: Int): AuthLogPage!
 	}
 
 	type Mutation {
-		signUp(email: String!, password: String, passwordHash: String, roles: [String!], name: String): SignUpResponse
-		signIn(email: String!, password: String!, expiration: Int, otpToken: String): SignInResponse
-		createSessionToken(email: String, personId: String, expiration: Int): CreateSessionTokenResponse
+		signUp(email: String!, password: String, passwordHash: String, roles: [String!], name: String, captchaToken: String): SignUpResponse
+		signIn(email: String!, password: String!, expiration: Int, otpToken: String, backupCode: String, options: SignInOptions): SignInResponse
+		createSessionToken(email: String, personId: String, expiration: Int, options: SignInOptions): CreateSessionTokenResponse
 		signOut(all: Boolean): SignOutResponse
 		changeProfile(personId: String!, email: String, name: String): ChangeProfileResponse
 		changeMyProfile(email: String, name: String): ChangeMyProfileResponse
@@ -46,14 +82,15 @@ const schema: DocumentNode = gql`
 			identityProvider: String!,
 			data: Json,
 			expiration: Int
+			options: SignInOptions
 			idpResponse: IDPResponseInput, @deprecated(reason: "pass idpResponse.url as data.url")
 			redirectUrl: String @deprecated(reason: "use data.redirectUrl"),
 			sessionData: Json @deprecated(reason: "use data.sessionData"),
 		): SignInIDPResponse
 		
 		# passwordless sign in
-		initSignInPasswordless(email: String!, options: InitSignInPasswordlessOptions): InitSignInPasswordlessResponse
-		signInPasswordless(requestId: String!, validationType: PasswordlessValidationType!, token: String!, expiration: Int, mfaOtp: String): SignInPasswordlessResponse
+		initSignInPasswordless(email: String!, options: InitSignInPasswordlessOptions, captchaToken: String): InitSignInPasswordlessResponse
+		signInPasswordless(requestId: String!, validationType: PasswordlessValidationType!, token: String!, expiration: Int, mfaOtp: String, backupCode: String, options: SignInOptions): SignInPasswordlessResponse
 		activatePasswordlessOtp(requestId: String!, token: String!, otpHash: String!): ActivatePasswordlessOtpResponse
 
         enableMyPasswordless: ToggleMyPasswordlessResponse
@@ -65,15 +102,45 @@ const schema: DocumentNode = gql`
 		disableIDP(identityProvider: String!): DisableIDPResponse
 		enableIDP(identityProvider: String!): EnableIDPResponse
 
+		"""
+		Disconnect one of the authenticated person's own external IdP connections,
+		addressed by the connection id (see PersonIdentityProvider.id) so a specific
+		connection can be removed even when the person has several to one provider.
+		"""
+		disconnectMyIdentityProvider(id: String!): DisconnectIDPResponse
+
 		prepareOtp(label: String): PrepareOtpResponse
 		confirmOtp(otpToken: String!): ConfirmOtpResponse
 		disableOtp: DisableOtpResponse
+		regenerateBackupCodes: RegenerateBackupCodesResponse
+
+		initEmailOtp: InitEmailOtpResponse
+		confirmEmailOtp(otpToken: String!): ConfirmEmailOtpResponse
+		disableEmailOtp: DisableEmailOtpResponse
 
 		disablePerson(personId: String!): DisablePersonResponse
+		forceSignOutPerson(personId: String!, reason: String): ForceSignOutPersonResponse
+		resetPersonMfa(personId: String!): ResetPersonMfaResponse
+		revokeSession(sessionId: String!): RevokeSessionResponse
 
-		createResetPasswordRequest(email: String!, options: CreateResetPasswordRequestOptions): CreatePasswordResetRequestResponse
+		createResetPasswordRequest(email: String!, options: CreateResetPasswordRequestOptions, captchaToken: String): CreatePasswordResetRequestResponse
 		resetPassword(token: String!, password: String!): ResetPasswordResponse
 
+		"""
+		(Re)send the e-mail verification link for the given address. Always
+		reports ok regardless of whether the address exists or is already
+		verified, to avoid leaking account existence.
+		"""
+		requestEmailVerification(email: String!, options: EmailVerificationOptions, captchaToken: String): RequestEmailVerificationResponse
+		verifyEmail(token: String!): VerifyEmailResponse
+		"""
+		Confirm a pending e-mail change (see changeMyProfile when
+		config.signup.requireEmailVerification is enabled). Consumes the token
+		that was mailed to the new address, swaps the address, and signs out all
+		existing sessions.
+		"""
+		confirmEmailChange(token: String!): ConfirmEmailChangeResponse
+
 		invite(email: String!, name: String, projectSlug: String!, memberships: [MembershipInput!]!, options: InviteOptions): InviteResponse
 		unmanagedInvite(
 			email: String!,
@@ -89,8 +156,8 @@ const schema: DocumentNode = gql`
 
 		updateProjectMember(projectSlug: String!, identityId: String!, memberships: [MembershipInput!]!): UpdateProjectMemberResponse
 
-		createApiKey(projectSlug: String!, memberships: [MembershipInput!]!, description: String!, tokenHash: String): CreateApiKeyResponse
-		createGlobalApiKey(description: String!, roles: [String!], tokenHash: String): CreateApiKeyResponse
+		createApiKey(projectSlug: String!, memberships: [MembershipInput!]!, description: String!, tokenHash: String, options: CreateApiKeyOptions): CreateApiKeyResponse
+		createGlobalApiKey(description: String!, roles: [String!], tokenHash: String, options: CreateApiKeyOptions): CreateApiKeyResponse
 		disableApiKey(id: String!): DisableApiKeyResponse
 		addGlobalIdentityRoles(identityId: String!, roles: [String!]!): AddGlobalIdentityRolesResponse
 		removeGlobalIdentityRoles(identityId: String!, roles: [String!]!): RemoveGlobalIdentityRolesResponse
@@ -111,6 +178,11 @@ const schema: DocumentNode = gql`
 		
 		configure(config: ConfigInput!): ConfigureResponse
 
+		# === auth policy (per-role MFA / session policy) ===
+		createAuthPolicy(policy: AuthPolicyInput!): CreateAuthPolicyResponse
+		updateAuthPolicy(id: String!, policy: AuthPolicyInput!): UpdateAuthPolicyResponse
+		deleteAuthPolicy(id: String!): DeleteAuthPolicyResponse
+
 		addProjectMailTemplate(template: MailTemplate!): AddMailTemplateResponse
 		@deprecated(reason: "use addMailTemplate")
 
@@ -122,17 +194,43 @@ const schema: DocumentNode = gql`
 	# === configure ===
 	
 	type Config {
+		signup: ConfigSignup!
+		emailChange: ConfigEmailChange!
 		passwordless: ConfigPasswordless!
 		password: ConfigPassword!
 		login: ConfigLogin!
+		captcha: ConfigCaptcha!
+		rateLimits: ConfigRateLimits!
 	}
-	
+
+	type ConfigSignup {
+		"""
+		When true, new accounts must verify their e-mail address before they can
+		sign in. The requirement is captured per account at sign-up, so toggling
+		this only affects accounts created afterwards. Defaults to false (no
+		change vs. previous behavior). E-mail changes are governed separately by
+		ConfigEmailChange.requireVerification.
+		"""
+		requireEmailVerification: Boolean!
+	}
+
+	type ConfigEmailChange {
+		"""
+		When true, a user-initiated changeMyProfile e-mail change does not swap
+		the address immediately: it goes through a confirmation flow
+		(confirmEmailChange) against a token mailed to the new address, and the
+		old address stays active until the new one is confirmed. Independent of
+		ConfigSignup.requireEmailVerification. Defaults to false.
+		"""
+		requireVerification: Boolean!
+	}
+
 	type ConfigPasswordless {
 		enabled: ConfigPolicy!
 		url: String
 		expiration: Interval!
 	}
-	
+
 	type ConfigPassword {
 		minLength: Int!
 		requireUppercase: Int!
@@ -141,36 +239,132 @@ const schema: DocumentNode = gql`
 		requireSpecial: Int!
 		pattern: String
 		checkBlacklist: Boolean!
+		checkHibp: Boolean!
     }
-	
+
 	type ConfigLogin {
 		baseBackoff: Interval!
 		maxBackoff: Interval!
 		attemptWindow: Interval!
 		revealUserExists: Boolean!
+		"""
+		If false, signIn collapses NO_PASSWORD_SET / INVALID_PASSWORD into a
+		generic INVALID_CREDENTIALS and signUp omits the recommendedAction
+		hint on EMAIL_ALREADY_EXISTS errors. UNKNOWN_EMAIL and existence-level
+		signals are still controlled by revealUserExists. Defaults to true
+		(no change vs. previous behavior).
+		"""
+		revealLoginMethod: Boolean!
 		defaultTokenExpiration: Interval!
 		maxTokenExpiration: Interval
+		mfaGraceDuration: Interval!
+		anomalyDetection: ConfigLoginAnomalyDetection!
     }
-	
+
+	"""
+	Sign-in anomaly detection (A03). Opt-in, disabled by default. When enabled,
+	each successful password verification is scored against the person's last
+	historySize successful logins using signals derived from the trusted client
+	info (country from a reverse-proxy geo header, a user-agent fingerprint, and
+	the IP / IP prefix). The cumulative score then drives an action:
+	  - score >= emailThreshold  → an informational UNUSUAL_LOGIN email is sent.
+	  - score >= stepUpThreshold → a second factor (email OTP) is additionally
+	    required before a session is issued (reuses the existing step-up flow).
+	Country is only ever read through the same trusted-proxy gate as the
+	forwarded IP / User-Agent — never from an untrusted client.
+	"""
+	type ConfigLoginAnomalyDetection {
+		enabled: Boolean!
+		historySize: Int!
+		emailThreshold: Int!
+		stepUpThreshold: Int!
+	}
+
+	"""
+	Captcha config. The secret is never exposed; only the provider and (where
+	applicable) the threshold are readable.
+	"""
+	type ConfigCaptcha {
+		provider: CaptchaProvider
+		threshold: Float
+		protect: ConfigCaptchaProtect!
+	}
+
+	"""
+	Per-flow captcha enforcement. The captcha provider/secret is shared; these
+	flags decide which mutations actually require a captcha token when a provider
+	is configured.
+	"""
+	type ConfigCaptchaProtect {
+		signUp: Boolean!
+		passwordReset: Boolean!
+		passwordlessInit: Boolean!
+		emailVerification: Boolean!
+	}
+
+	enum CaptchaProvider {
+		turnstile
+		hcaptcha
+		recaptchaV3
+	}
+
+	"""
+	Configurable per-IP rate-limit windows. Each value bounds the number of
+	attempts allowed from the same client IP in the configured window. Per-email
+	throttling for password-reset and passwordless-init flows reuses the
+	exponential backoff from ConfigLogin (baseBackoff / maxBackoff /
+	attemptWindow) against person_auth_log entries.
+	"""
+	type ConfigRateLimits {
+		signUpPerIp: ConfigRateLimitWindow!
+		loginPerIp: ConfigRateLimitWindow!
+		passwordResetPerIp: ConfigRateLimitWindow!
+		passwordlessInitPerIp: ConfigRateLimitWindow!
+		"""
+		Caps how many email-OTP codes may be dispatched per person within the
+		window (a brute-force / email-bomb backstop). Unlike the per-IP limits it
+		ships enabled by default. Set limit to 0 to disable.
+		"""
+		emailOtpPerPerson: ConfigRateLimitWindow!
+		emailVerificationPerIp: ConfigRateLimitWindow!
+	}
+
+	type ConfigRateLimitWindow {
+		limit: Int!
+		window: Interval!
+	}
+
 	input ConfigInput {
+		signup: ConfigSignupInput
+		emailChange: ConfigEmailChangeInput
 		passwordless: ConfigPasswordlessInput
 		password: ConfigPasswordInput
 		login: ConfigLoginInput
+		captcha: ConfigCaptchaInput
+		rateLimits: ConfigRateLimitsInput
 	}
-	
+
+	input ConfigSignupInput {
+		requireEmailVerification: Boolean
+	}
+
+	input ConfigEmailChangeInput {
+		requireVerification: Boolean
+	}
+
 	enum ConfigPolicy {
 		always
 		never
 		optIn
 		optOut
 	}
-	
+
 	input ConfigPasswordlessInput {
 		enabled: ConfigPolicy
 		url: String
 		expiration: Interval
 	}
-	
+
 	input ConfigPasswordInput {
 		minLength: Int
 		requireUppercase: Int
@@ -179,16 +373,59 @@ const schema: DocumentNode = gql`
 		requireSpecial: Int
 		pattern: String
 		checkBlacklist: Boolean
+		checkHibp: Boolean
     }
-	
+
 	input ConfigLoginInput {
 		baseBackoff: Interval
 		maxBackoff: Interval
 		attemptWindow: Interval
 		revealUserExists: Boolean
+		revealLoginMethod: Boolean
 		defaultTokenExpiration: Interval
 		maxTokenExpiration: Interval
+		mfaGraceDuration: Interval
+		anomalyDetection: ConfigLoginAnomalyDetectionInput
     }
+
+	input ConfigLoginAnomalyDetectionInput {
+		enabled: Boolean
+		historySize: Int
+		emailThreshold: Int
+		stepUpThreshold: Int
+	}
+
+	"""
+	Provider null disables captcha verification. Secret is write-only.
+	Pass null secret to leave the stored value unchanged; pass empty string to clear.
+	"""
+	input ConfigCaptchaInput {
+		provider: CaptchaProvider
+		secret: String
+		threshold: Float
+		protect: ConfigCaptchaProtectInput
+	}
+
+	input ConfigCaptchaProtectInput {
+		signUp: Boolean
+		passwordReset: Boolean
+		passwordlessInit: Boolean
+		emailVerification: Boolean
+	}
+
+	input ConfigRateLimitsInput {
+		signUpPerIp: ConfigRateLimitWindowInput
+		loginPerIp: ConfigRateLimitWindowInput
+		passwordResetPerIp: ConfigRateLimitWindowInput
+		passwordlessInitPerIp: ConfigRateLimitWindowInput
+		emailOtpPerPerson: ConfigRateLimitWindowInput
+		emailVerificationPerIp: ConfigRateLimitWindowInput
+	}
+
+	input ConfigRateLimitWindowInput {
+		limit: Int
+		window: Interval
+	}
 	
 	type ConfigureResponse {
 		ok: Boolean!
@@ -215,6 +452,11 @@ const schema: DocumentNode = gql`
 	type SignUpError {
 		code: SignUpErrorCode!
         weakPasswordReasons: [WeakPasswordReason!]
+		"""
+		For EMAIL_ALREADY_EXISTS, the recommended next action client UIs should
+		offer to the visitor. Null for unrelated error codes.
+		"""
+		recommendedAction: SignUpRecommendedAction
 		developerMessage: String!
 		endPersonMessage: String @deprecated
 	}
@@ -223,6 +465,13 @@ const schema: DocumentNode = gql`
 		EMAIL_ALREADY_EXISTS
 		INVALID_EMAIL_FORMAT
 		TOO_WEAK
+		INVALID_CAPTCHA
+		RATE_LIMIT_EXCEEDED
+	}
+
+	enum SignUpRecommendedAction {
+		SIGN_IN
+		RESET_PASSWORD
 	}
 
 	type SignUpResult {
@@ -237,6 +486,22 @@ const schema: DocumentNode = gql`
 	}
 
 	# === signIn ===
+	input SignInOptions {
+		"""
+		If true, and the calling api_key has trust_forwarded_info=true,
+		the resulting session token will trust X-Contember-Client-IP and
+		X-Contember-Client-User-Agent headers on subsequent requests.
+		Silently ignored when the caller's api_key does not have the flag.
+
+		Security: a proxy that sets these headers MUST strip any
+		incoming X-Contember-Client-IP / X-Contember-Client-User-Agent
+		from upstream traffic and re-inject values it trusts. Without
+		that, any client holding a session token minted with this flag
+		could spoof its own IP/User-Agent.
+		"""
+		trustForwardedClientInfo: Boolean
+	}
+
 	type SignInResponse {
 		ok: Boolean!
 		errors: [SignInError!]! @deprecated
@@ -249,6 +514,18 @@ const schema: DocumentNode = gql`
 		developerMessage: String!
 		endUserMessage: String @deprecated
 		retryAfter: Int
+		"""
+		Set only on a MFA_ENROLLMENT_REQUIRED error: the freshly provisioned
+		pending TOTP secret the client must enroll (show the QR / secret, then
+		retry signIn with otpToken). Additive — clients that don't read it are
+		unaffected.
+		"""
+		mfaEnrollment: MfaEnrollment
+	}
+
+	type MfaEnrollment {
+		otpUri: String!
+		otpSecret: String!
 	}
 
 	enum SignInErrorCode {
@@ -259,12 +536,19 @@ const schema: DocumentNode = gql`
 		NO_PASSWORD_SET
 		OTP_REQUIRED
 		INVALID_OTP_TOKEN
+		MFA_ENROLLMENT_REQUIRED
+		EMAIL_NOT_VERIFIED
 		RATE_LIMIT_EXCEEDED
 	}
 
 	type SignInResult implements CommonSignInResult {
 		token: String!
 		person: Person!
+		"""
+		Set only when this sign-in completed an MFA enrollment (A06): the freshly
+		generated backup codes, shown exactly once. Null on a normal sign-in.
+		"""
+		backupCodes: [String!]
 	}
 
 	# == createSessionToken ==
@@ -297,6 +581,13 @@ const schema: DocumentNode = gql`
 		ok: Boolean!
 		errors: [SignOutError!]! @deprecated
 		error: SignOutError
+		"""
+		When the session was federated via an OIDC identity provider that supports RP-initiated
+		(front-channel) logout, the URL the client should redirect the browser to so the user is
+		also signed out at the IdP (Single Logout). Null for plain sessions or legacy IdPs without
+		an end-session endpoint, in which case only a local logout happened.
+		"""
+		logoutUrl: String
 	}
 
 	type SignOutError {
@@ -344,7 +635,8 @@ const schema: DocumentNode = gql`
 		NOT_A_PERSON
 		INVALID_EMAIL_FORMAT
 		EMAIL_ALREADY_EXISTS
-	}	
+		RATE_LIMIT_EXCEEDED
+	}
 
 	# === changePassword ===
 
@@ -374,6 +666,7 @@ const schema: DocumentNode = gql`
 		MISSING_SPECIAL
 		INVALID_PATTERN
 		BLACKLISTED
+		COMPROMISED
     }
 
 
@@ -515,6 +808,40 @@ const schema: DocumentNode = gql`
 		NOT_FOUND
 	}
 
+	""" A single external IdP connection of the currently authenticated person. """
+	type PersonIdentityProvider {
+		id: String!
+		createdAt: DateTime!
+		externalIdentifier: String!
+		identityProvider: IdentityProviderListItem!
+	}
+
+	""" Public view of an identity provider, exposed in personal IdP connection listings. """
+	type IdentityProviderListItem {
+		slug: String!
+		type: String!
+		disabledAt: DateTime
+	}
+
+	type DisconnectIDPResponse {
+		error: DisconnectIDPError
+		ok: Boolean!
+	}
+
+	type DisconnectIDPError {
+		code: DisconnectIDPErrorCode!
+		developerMessage: String!
+	}
+
+	enum DisconnectIDPErrorCode {
+		""" The authenticated person has no IdP connection with the given id. """
+		NOT_FOUND
+		""" The caller is not a person (e.g. an API key) and so has no IdP connections to disconnect. """
+		NOT_A_PERSON
+		""" The person is not allowed to disconnect their last remaining sign-in method. """
+		LAST_AUTH_METHOD
+	}
+
 	type IdentityProvider {
 		slug: String!
 		type: String!
@@ -527,12 +854,26 @@ const schema: DocumentNode = gql`
 		autoSignUp: Boolean!
 		exclusive: Boolean!
 		initReturnsConfig: Boolean!
+		"""
+		When true, a non-exclusive provider may only auto-link to / sign in an
+		existing account by e-mail if the provider asserts the e-mail is verified.
+		Defaults to false.
+		"""
+		requireVerifiedEmail: Boolean!
+		"""
+		When true, e-mail addresses asserted by this provider are treated as verified
+		even without an "email_verified" claim. Use only for trusted providers.
+		Defaults to false.
+		"""
+		assumeEmailVerified: Boolean!
 	}
 
 	input IDPOptions {
 		autoSignUp: Boolean
 		exclusive: Boolean
 		initReturnsConfig: Boolean
+		requireVerifiedEmail: Boolean
+		assumeEmailVerified: Boolean
 	}
 
 	# === passwordless sign in ===
@@ -550,8 +891,10 @@ const schema: DocumentNode = gql`
 	
 	enum InitSignInPasswordlessErrorCode {
 		PERSON_NOT_FOUND
-		
+
 		PASSWORDLESS_DISABLED
+		INVALID_CAPTCHA
+		RATE_LIMIT_EXCEEDED
 	}
 	
 	type InitSignInPasswordlessResult {
@@ -588,8 +931,9 @@ const schema: DocumentNode = gql`
 		PERSON_DISABLED
 		OTP_REQUIRED
 		INVALID_OTP_TOKEN
+		MFA_ENROLLMENT_REQUIRED
 	}
-	
+
 	type SignInPasswordlessResult implements CommonSignInResult {
 		token: String!
 		person: Person!
@@ -747,6 +1091,17 @@ const schema: DocumentNode = gql`
 
 	# === createApiKey ===
 
+	input CreateApiKeyOptions {
+		"""
+		If true, the created api_key trusts X-Contember-Client-IP and
+		X-Contember-Client-User-Agent headers on subsequent requests.
+		Intended for backend services that proxy user requests; the customer's
+		proxy must strip these headers from incoming traffic and re-inject
+		them with the real user values.
+		"""
+		trustForwardedClientInfo: Boolean
+	}
+
 	type CreateApiKeyResponse {
 		ok: Boolean!
 		errors: [CreateApiKeyError!]! @deprecated
@@ -881,14 +1236,53 @@ const schema: DocumentNode = gql`
 		name: String
 		otpEnabled: Boolean!
 		passwordlessEnabled: Boolean
+		"""
+		Whether e-mail based one-time-password 2FA is enabled for this person
+		(see \`initEmailOtp\` / \`confirmEmailOtp\` / \`disableEmailOtp\`). Independent
+		of \`otpEnabled\` (TOTP authenticator), so a UI can show each MFA method's
+		state separately.
+		"""
+		emailOtpEnabled: Boolean!
+		emailVerified: Boolean!
 		identity: Identity!
+
+		"""
+		External IdP connections of this person. Always visible for the calling
+		person (e.g. via \`me { person { identityProviders } }\`). For other
+		persons, visible to callers holding the \`person:viewIdp\` permission
+		against the target's roles — SUPER_ADMIN sees everyone; PROJECT_ADMIN
+		sees members whose roles fall within their allowed-input-roles. Returns
+		an empty list rather than throwing when the viewer lacks visibility.
+		"""
+		identityProviders: [PersonIdentityProvider!]!
+	}
+
+	""" Filter for the \`persons\` query. Fields are combined with AND. """
+	input PersonsFilter {
+		email: String
+		personId: String
+		identityId: String
 	}
 
 	# === api key ===
 
+	enum ApiKeyType {
+		SESSION
+		PERMANENT
+		ONE_OFF
+	}
+
 	type ApiKey {
 		id: String!
 		identity: Identity!
+		""" Human-readable label, stored on the key's identity (\`identity.description\`). """
+		description: String
+		type: ApiKeyType
+		""" False once the key has been disabled (\`disableApiKey\`). """
+		enabled: Boolean
+		createdAt: DateTime
+		lastUsedAt: DateTime
+		expiresAt: DateTime
 	}
 
 	type ApiKeyWithToken {
@@ -907,6 +1301,16 @@ const schema: DocumentNode = gql`
 		projects: [IdentityProjectRelation!]!
 		permissions: IdentityGlobalPermissions
 		roles: [String!]
+		"""
+		Active SESSION-type api keys for this identity. Always visible for
+		the calling identity (e.g. via \`me { sessions }\`). For other identities,
+		visible to callers holding the \`person:viewSessions\` permission against
+		the target's roles — SUPER_ADMIN sees everyone; PROJECT_ADMIN sees
+		members whose roles fall within their allowed-input-roles. Returns an
+		empty list rather than throwing when the viewer lacks visibility, so
+		batched identity queries do not abort on a single forbidden target.
+		"""
+		sessions: [SessionInfo!]!
 	}
 
 	type IdentityGlobalPermissions {
@@ -931,6 +1335,28 @@ const schema: DocumentNode = gql`
 			input: ProjectMembersInput,
 			memberType: MemberType @deprecated(reason: "Use args")
 		): [ProjectIdentityRelation!]!
+		"""
+		Permanent API keys scoped to this project — keys whose identity is a member
+		of the project (excludes SESSION tokens and global keys). Each key's
+		project memberships are reachable via \`apiKey.identity.projects\` for
+		cloning when (re)issuing a key. Requires \`project.view members\` permission;
+		returns an empty list otherwise.
+		"""
+		apiKeys: [ApiKey!]!
+		"""
+		Names of the project's secrets (see \`setProjectSecret\`). Secret VALUES are
+		never returned — only the keys and their timestamps — so a UI can show which
+		secrets exist. Requires the \`project:viewSecrets\` permission (project admins
+		+ SUPER_ADMIN by default); returns an empty list otherwise.
+		"""
+		secrets: [ProjectSecretInfo!]!
+	}
+
+	""" Metadata about a project secret — never its value. """
+	type ProjectSecretInfo {
+		key: String!
+		createdAt: DateTime!
+		updatedAt: DateTime!
 	}
 
 	input ProjectMembersInput {
@@ -995,6 +1421,11 @@ const schema: DocumentNode = gql`
 		ok: Boolean!
 		errors: [ConfirmOtpError!]! @deprecated
 		error: ConfirmOtpError
+		result: ConfirmOtpResult
+	}
+
+	type ConfirmOtpResult {
+		backupCodes: [String!]!
 	}
 
 	type ConfirmOtpError {
@@ -1022,6 +1453,77 @@ const schema: DocumentNode = gql`
 
 	enum DisableOtpErrorCode {
 		OTP_NOT_ACTIVE
+		MFA_REQUIRED
+	}
+
+	type RegenerateBackupCodesResponse {
+		ok: Boolean!
+		error: RegenerateBackupCodesError
+		result: RegenerateBackupCodesResult
+	}
+
+	type RegenerateBackupCodesError {
+		code: RegenerateBackupCodesErrorCode!
+		developerMessage: String!
+	}
+
+	enum RegenerateBackupCodesErrorCode {
+		OTP_NOT_ACTIVE
+	}
+
+	type RegenerateBackupCodesResult {
+		backupCodes: [String!]!
+	}
+
+	# ==== email otp (A05) ====
+
+	type InitEmailOtpResponse {
+		ok: Boolean!
+		error: InitEmailOtpError
+	}
+
+	type InitEmailOtpError {
+		code: InitEmailOtpErrorCode!
+		developerMessage: String!
+	}
+
+	enum InitEmailOtpErrorCode {
+		NO_EMAIL
+		RATE_LIMITED
+	}
+
+	type ConfirmEmailOtpResponse {
+		ok: Boolean!
+		error: ConfirmEmailOtpError
+		result: ConfirmEmailOtpResult
+	}
+
+	type ConfirmEmailOtpResult {
+		backupCodes: [String!]!
+	}
+
+	type ConfirmEmailOtpError {
+		code: ConfirmEmailOtpErrorCode!
+		developerMessage: String!
+	}
+
+	enum ConfirmEmailOtpErrorCode {
+		INVALID_OTP_TOKEN
+	}
+
+	type DisableEmailOtpResponse {
+		ok: Boolean!
+		error: DisableEmailOtpError
+	}
+
+	type DisableEmailOtpError {
+		code: DisableEmailOtpErrorCode!
+		developerMessage: String!
+	}
+
+	enum DisableEmailOtpErrorCode {
+		EMAIL_OTP_NOT_ACTIVE
+		MFA_REQUIRED
 	}
 
 	type DisablePersonResponse {
@@ -1039,6 +1541,158 @@ const schema: DocumentNode = gql`
 		PERSON_NOT_FOUND
 	}
 
+	# === forceSignOutPerson ===
+
+	type ForceSignOutPersonResponse {
+		ok: Boolean!
+		error: ForceSignOutPersonError
+	}
+
+	type ForceSignOutPersonError {
+		code: ForceSignOutPersonErrorCode!
+		developerMessage: String!
+	}
+
+	enum ForceSignOutPersonErrorCode {
+		PERSON_NOT_FOUND
+	}
+
+	# === resetPersonMfa ===
+
+	type ResetPersonMfaResponse {
+		ok: Boolean!
+		error: ResetPersonMfaError
+	}
+
+	type ResetPersonMfaError {
+		code: ResetPersonMfaErrorCode!
+		developerMessage: String!
+	}
+
+	enum ResetPersonMfaErrorCode {
+		PERSON_NOT_FOUND
+	}
+
+	# === auth policy (per-role MFA / session policy) ===
+
+	type AuthPolicy {
+		id: String!
+		scope: AuthPolicyScope!
+		"""Project slug, present only for project-scoped policies."""
+		project: String
+		roles: [String!]!
+		mfaRequired: Boolean
+		tokenExpiration: Interval
+		idleTimeout: Interval
+		mfaGraceDuration: Interval
+		rememberMeAllowed: Boolean
+	}
+
+	enum AuthPolicyScope {
+		global
+		project
+	}
+
+	input AuthPolicyInput {
+		scope: AuthPolicyScope!
+		"""Project slug. Required for scope=project, forbidden for scope=global."""
+		project: String
+		roles: [String!]!
+		mfaRequired: Boolean
+		tokenExpiration: Interval
+		idleTimeout: Interval
+		mfaGraceDuration: Interval
+		rememberMeAllowed: Boolean
+	}
+
+	type CreateAuthPolicyResponse {
+		ok: Boolean!
+		error: CreateAuthPolicyError
+		result: CreateAuthPolicyResult
+	}
+
+	type CreateAuthPolicyResult {
+		id: String!
+	}
+
+	type CreateAuthPolicyError {
+		code: CreateAuthPolicyErrorCode!
+		developerMessage: String!
+	}
+
+	enum CreateAuthPolicyErrorCode {
+		PROJECT_REQUIRED
+		PROJECT_NOT_ALLOWED
+		PROJECT_NOT_FOUND
+	}
+
+	type UpdateAuthPolicyResponse {
+		ok: Boolean!
+		error: UpdateAuthPolicyError
+	}
+
+	type UpdateAuthPolicyError {
+		code: UpdateAuthPolicyErrorCode!
+		developerMessage: String!
+	}
+
+	enum UpdateAuthPolicyErrorCode {
+		NOT_FOUND
+		PROJECT_REQUIRED
+		PROJECT_NOT_ALLOWED
+		PROJECT_NOT_FOUND
+	}
+
+	type DeleteAuthPolicyResponse {
+		ok: Boolean!
+		error: DeleteAuthPolicyError
+	}
+
+	type DeleteAuthPolicyError {
+		code: DeleteAuthPolicyErrorCode!
+		developerMessage: String!
+	}
+
+	enum DeleteAuthPolicyErrorCode {
+		NOT_FOUND
+	}
+
+	# === sessions ===
+
+	type SessionInfo {
+		id: String!
+		createdAt: DateTime!
+		expiresAt: DateTime
+		lastUsedAt: DateTime
+		lastIp: String
+		lastUserAgent: String
+		createdIp: String
+		createdUserAgent: String
+		isCurrent: Boolean!
+		"""
+		Whether this session honors X-Contember-Client-IP /
+		X-Contember-Client-User-Agent headers on subsequent requests. Set when
+		the session was minted via \`SignInOptions.trustForwardedClientInfo\`
+		from an api_key that was itself created with the flag.
+		"""
+		trustForwardedClientInfo: Boolean!
+	}
+
+	type RevokeSessionResponse {
+		ok: Boolean!
+		error: RevokeSessionError
+	}
+
+	type RevokeSessionError {
+		code: RevokeSessionErrorCode!
+		developerMessage: String!
+	}
+
+	enum RevokeSessionErrorCode {
+		SESSION_NOT_FOUND
+		NOT_A_PERSON
+	}
+
 	# === mails ===
 	
 	type MailTemplateData {
@@ -1067,6 +1721,13 @@ const schema: DocumentNode = gql`
 		NEW_USER_INVITED
 		RESET_PASSWORD_REQUEST
 		PASSWORDLESS_SIGN_IN
+		FORCED_SIGN_OUT
+		EMAIL_OTP
+		BACKUP_CODES_EXHAUSTED
+		EMAIL_VERIFICATION
+		EMAIL_CHANGE_VERIFY
+		EMAIL_CHANGE_NOTIFY
+		UNUSUAL_LOGIN
 	}
 
 	input MailTemplateIdentifier {
@@ -1138,6 +1799,8 @@ const schema: DocumentNode = gql`
 
 	enum CreatePasswordResetRequestErrorCode {
 		PERSON_NOT_FOUND
+		INVALID_CAPTCHA
+		RATE_LIMIT_EXCEEDED
 	}
 
 	type ResetPasswordResponse {
@@ -1166,6 +1829,64 @@ const schema: DocumentNode = gql`
 		mailVariant: String
 	}
 
+	# === email verification ===
+
+	input EmailVerificationOptions {
+		mailProject: String
+		mailVariant: String
+	}
+
+	type RequestEmailVerificationResponse {
+		ok: Boolean!
+		error: RequestEmailVerificationError
+	}
+
+	type RequestEmailVerificationError {
+		code: RequestEmailVerificationErrorCode!
+		developerMessage: String!
+	}
+
+	enum RequestEmailVerificationErrorCode {
+		RATE_LIMIT_EXCEEDED
+		INVALID_CAPTCHA
+	}
+
+	type VerifyEmailResponse {
+		ok: Boolean!
+		error: VerifyEmailError
+	}
+
+	type VerifyEmailError {
+		code: VerifyEmailErrorCode!
+		developerMessage: String!
+	}
+
+	enum VerifyEmailErrorCode {
+		TOKEN_NOT_FOUND
+		TOKEN_INVALID
+		TOKEN_USED
+		TOKEN_EXPIRED
+	}
+
+	type ConfirmEmailChangeResponse {
+		ok: Boolean!
+		error: ConfirmEmailChangeError
+	}
+
+	type ConfirmEmailChangeError {
+		code: ConfirmEmailChangeErrorCode!
+		developerMessage: String!
+	}
+
+	enum ConfirmEmailChangeErrorCode {
+		TOKEN_NOT_FOUND
+		TOKEN_INVALID
+		TOKEN_USED
+		TOKEN_EXPIRED
+		EMAIL_ALREADY_EXISTS
+		INVALID_EMAIL_FORMAT
+	}
+
 	# === project ===
 
 	input ProjectSecret {
@@ -1225,6 +1946,91 @@ const schema: DocumentNode = gql`
 	enum UpdateProjectErrorCode {
 		PROJECT_NOT_FOUND
 	}
+
+	# === auth log ===
+
+	"""
+	A single \`person_auth_log\` row. Mirrors the columns described in
+	docs/.../audit-log.md.
+	"""
+	type AuthLogEntry {
+		id: String!
+		createdAt: DateTime!
+		"""
+		One of the values listed in \`auth_log_type\` (see audit-log docs).
+		Kept as String rather than a GraphQL enum because a few legacy values
+		(\`2fa_enable\`, \`2fa_disable\`) start with a digit and aren't valid
+		enum names, and the set is expected to keep growing.
+		"""
+		type: String!
+		success: Boolean!
+		"""
+		Identity that performed the action. May be null for entries created
+		before this column was populated, or when the actor's identity was
+		later deleted (FK is ON DELETE SET NULL semantics-wise).
+		"""
+		invokedByIdentityId: String
+		"""
+		The actor's person (if the actor was a person, not a bare api_key).
+		"""
+		personId: String
+		"""
+		The subject of the action when different from the actor (e.g. force
+		sign-out, role grant, membership change). Resolved from the affected
+		identity so the trail points at the right person even when the actor
+		acts on someone else's identity.
+		"""
+		targetPersonId: String
+		"""
+		Free-form input string — typically the email submitted on a failed
+		login, before any person record was looked up.
+		"""
+		personInputIdentifier: String
+		errorCode: String
+		errorMessage: String
+		"""
+		Effective client IP after \`trust-forwarded-info\` is applied. The
+		raw socket peer is preserved in \`metadata.forwarderIp\` when a
+		trusted proxy was involved.
+		"""
+		ipAddress: String
+		userAgent: String
+		identityProviderId: String
+		"""
+		JSONB — forensic context. Common keys: \`forwarderIp\`,
+		\`forwarderUserAgent\`, \`sessionId\`, \`reason\`.
+		"""
+		metadata: Json
+		"""
+		JSONB — domain payload. For change events this is typically
+		\`{before, after}\`; for creation events it's the snapshot.
+		Secret-bearing inputs are redacted before being stored.
+		"""
+		eventData: Json
+	}
+
+	"""
+	All fields are AND-combined. Omitted fields are unconstrained.
+	"""
+	input AuthLogFilter {
+		"OR-combined: any of the listed \`auth_log_type\` values matches."
+		types: [String!]
+		success: Boolean
+		invokedByIdentityId: String
+		personId: String
+		targetPersonId: String
+		personInputIdentifier: String
+		"Inclusive lower bound (\`created_at >= createdAfter\`)."
+		createdAfter: DateTime
+		"Exclusive upper bound (\`created_at < createdBefore\`)."
+		createdBefore: DateTime
+	}
+
+	type AuthLogPage {
+		entries: [AuthLogEntry!]!
+		"True when more rows exist past \`offset + limit\`."
+		hasMore: Boolean!
+	}
 `
 
 export default schema