Audit trails & data privacy

Declare the policy where the user type is defined

saas-config.backend.ts owns application-authored identity behavior. In Wonder Todos, these are selected settings from the admin.auth object:

passwordPolicy: {
  minLength: 12,
  maxLength: 128,
  requireUppercase: true,
  requireLowercase: true,
  requireNumbers: true,
  requireSpecialChars: true,
  expiryDays: 90,
},
sessionDurationMinutes: 30,
maxConcurrentSessions: 3,
lockoutPolicy: {
  maxLoginAttempts: 3,
  lockoutDurationMinutes: 60,
  progressiveLockout: true,
  maxProgressiveLockoutHours: 24,
},

Password length, composition and expiry govern the credential. lockoutPolicy governs failed attempts. sessionDurationMinutes limits the temporary authentication episode in which sign-in steps are completed; it does not set the issued access token’s expiry. Registration and invitation episodes are created with a 24-hour expiry; idle timeout and subsequent session-store updates also affect how long they remain usable. maxConcurrentSessions limits authenticated sessions. JWT signing keys and access/refresh token lifetimes belong to deployment runtime configuration.

Make the user type available on the frontend

Enabling AuthMethod.PASSWORD is necessary, but the frontend must also admit the type. Wonder Todos declares:

frontendServices: {
  'wonder-todos-app': {
    usersManagement: {
      member: { register: true, auth: true, isDefault: true },
      admin: { register: false, auth: true },
    },
  },
},

An administrator can authenticate on this frontend but cannot register there. registration.allowedMethods separately controls account creation; the enabled sign-in set is not a signup policy.

Let the authentication flow finish

The standard interface identifies the account’s applicable methods and continues authentication. Password verification alone is not necessarily the final result: required email verification, MFA and account status still matter before a usable session is issued. Custom clients should follow the returned authentication state rather than assume that a successful first factor means access has been granted.

Configure the application identity first

Enable AuthMethod.PASSKEY for the relevant user type and configure the passkey relying party and operational settings. Expected origins come from configured runtime public URLs. These values must match the deployed frontend; enabling the flag alone does not make a credential valid for an arbitrary hostname.

Enrollment proves the application’s challenge

The standard interface requests registration options, invokes the browser authenticator and submits its response. The backend consumes the stored registration challenge and verifies it against the relying party and expected origin. This is the verification call in webauthn.backend.service.ts:

const verification = await verifyRegistrationResponse({
  response,
  expectedChallenge,
  expectedOrigin: this.expectedOrigins,
  expectedRPID: this.rpId,
  requireUserVerification: this.passkeyOps.userVerification === 'required',
});

Successful verification stores the credential’s public key, identifier and authenticator metadata. The secret stays with the authenticator. Public signup still requires email proof before passkey enrollment; an authenticator is not proof of an inbox address.

Authentication has its own ceremony

A later sign-in creates a fresh authentication challenge. The backend consumes it once, verifies the assertion and updates the credential’s counter and last-used information. Synced passkeys with a zero counter are supported; a verified assertion whose nonzero counter regresses is refused and recorded as suspicious.

Sensitive-action reauthentication uses a separate passkey challenge and requires user verification. That distinction prevents a login response from being reused for a high-impact action. Enrollment, naming and removal are separate account operations; removing a credential remains subject to account method-management policy.

Enable sign-in and arrange delivery

Wonder Todos enables [AuthMethod.MAGIC_LINK]: true in the member’s authMethodsEnabled. Email delivery and the frontend public URL must also be configured. Passwordless public signup is a separate choice in registration.allowedMethods.

The controller builds the link from the selected frontend and passes it to the transactional email service. Verification checks the declared frontend’s origin, then checks whether the resolved account type may authenticate on that frontend before creating a completed or MFA session. The frontend’s default type is a routing hint; it does not grant a type the account does not hold.

Preserve the authentication continuation

After the link is consumed and its policy checked, the orchestrator evaluates MFA using the effective policy:

await this.updateSession(sessionId, {
  state: AuthenticationSessionState.MFA_REQUIRED,
  requiresMFA: true,
  availableEnrollmentMethods: availableEnrollment,
  requireStrongMFA: mfaResolution.requireStrongMFA,
  availableSecondFactorMethods: mfaResolution.availableMethods,
  enrolledSecondFactorMethods: mfaCheck.enrolledMethods,
  usableSecondFactorMethods: mfaResolution.usableMethods,
});

The standard Auth_MagicLinkVerify screen follows the returned state. A custom screen must do the same: do not treat successful link verification as permission to skip MFA or assume every result contains a final access token.

Keep issuance and redemption consistent

The send path and verification path both enforce whether the method is available. Directory-managed accounts cannot regain a local first-factor route through an older link. Send requests are limited by address and client IP; verification uses an IP-keyed limit so replacing the token value does not reset the guessing budget.

Links are secrets and expire. Keep them out of application logs and avoid presenting successful email submission as proof that the person received the message. The supplied flow owns expiry and refusal; your application owns the delivery configuration and user-facing recovery path.

Establish the phone before using it as proof

Phone enrollment uses phoneVerifySend(phoneNumber) and phoneVerifyConfirm(phoneNumber, code). Confirmation persists the verified phone on the credential record. This enrollment action does not itself sign the person in.

Send and submit the authentication challenge

The standard SmsOtpAuthMethod.tsx receives an authentication sessionId and uses it for both steps. The send handler calls getManualCallsHttpClient().smsOTPSend(sessionId); it does not let the person substitute an arbitrary destination for their verified phone. The submit handler then continues that same authentication session:

const handleVerify = useCallback(async (data: SmsOtpChallengeFormDto) => {
  clearCodeFormError();
  try {
    const response = await handleMfaVerify(sessionId, AuthMethod.SMS_OTP, data.code.trim());
    if (response.success) {
      onSuccess(response);
    } else {
      setCodeFormError(response.error || t(MfaChallengeLabel.ERROR_INVALID_CODE));
    }
  } catch (e: any) {
    setCodeFormError(e?.message || t(MfaChallengeLabel.ERROR_INVALID_CODE));
  }
}, [sessionId, handleMfaVerify, onSuccess, t, clearCodeFormError, setCodeFormError]);

This is the existing frontend challenge handler, not a complete standalone component. handleMfaVerify comes from the authentication flow, while onSuccess hands its response back to the parent. Failed verification stays in the challenge form; a successful code follows the server’s authentication result.

Enable the method and wire the provider

Start with the SMS delivery setup: enable EngineCapability.SMS, select the backend Twilio provider, synchronize its artifacts, supply TWILIO_CREDENTIALS and configure the sender number. Keep the secret in the backend deployment environment. The provider guide contains the complete configuration fragments; choosing an authentication method does not perform those steps.

In backend-api/src/saas-config.backend.ts, merge this policy into the intended userTypes.<type>.auth. Import AuthMethod from @wildo-ai/saas-models; existingMemberAuth is that type’s existing complete policy:

const memberAuth = {
  ...existingMemberAuth,
  authMethodsEnabled: {
    ...existingMemberAuth.authMethodsEnabled,
    [AuthMethod.SMS_OTP]: true,
  },
};

SMS can be a first or second factor. This declaration enables the method; it does not require MFA or weaken an existing MFA requirement. For a password-then-SMS flow, password must also be enabled and the first credential must succeed before the SMS challenge completes the session. If SMS should qualify as a second factor, include AuthMethod.SMS_OTP in mfaPolicy.acceptableMFAMethods and check mfaPolicy.requireStrongMFA within the same user-type authentication policy. Keep the MFA policy consistent with the factors the application intends to accept.

Set the challenge window and sending budgets

Wonder Todos supplies the following backend operational settings under auth.otpOperational.smsOtp. These are explicit example values, not a claim that enabling SMS installs a provider or enrolls a phone. Merge this entry alongside the existing email-OTP settings:

smsOtp: {
  otpLength: 6,
  expiryMinutes: 5,
  rateLimitBurst: 1,
  rateLimitHourly: 5,
},

The burst and hourly limits apply to the resolved phone destination; the SMS-send controller also enforces its own source-IP limit. Increasing a phone budget does not remove the source-IP gate. The phone-enrollment challenge is a separate flow with its own checks; these settings describe authentication SMS codes.

An accepted send is not evidence that the handset received the message. Complete the challenge on a controlled account to verify the real delivery path. A missing or expired authentication session, exhausted budget or provider refusal must not be reported as successful delivery.

The SMS backend service uses the provider’s request builder and response parser, validates the standard result and refuses provider-reported send failures.

Authentication issuance resolves the verified target, checks effective policy and applies delivery budgets. An older outstanding code is revoked when a replacement is created. Verification uses the authentication session and advances the normal flow after a successful comparison.

Respect the customer’s identity authority

An actively directory-managed account has local SMS authentication disabled by the effective policy, just as local passwordless methods are disabled. The phone belongs to the person and is not a revocable IdP secret, so the method’s policy is the barrier. Choose stronger factors when the account’s requirements call for independent device proof; SMS availability is not a claim that every security policy should accept it.

Configure more than the button

Enable AuthMethod.EXTERNAL_OAUTH2 for the user type, supply the provider connection and credentials, and permit social registration separately if new accounts may be created. The provider’s declared scope and supported profile mapping determine which identity is returned.

The connected provider setup joins the backend login declaration, application client ID, server secret, per-user-type method and exact callback address. Use those prerequisites together; a provider button is only the visible entry to that flow.

Choose sign-in and registration separately

Example: allow an existing member to use a social provider, while keeping new-account registration closed. In backend-api/src/saas-config.backend.ts, merge this into the member’s existing auth policy. existingMemberAuth represents that full policy; retain its password, session, lockout and MFA settings. Import AuthMethod and RegistrationMode from @wildo-ai/saas-models.

const memberAuth = {
  ...existingMemberAuth,
  authMethodsEnabled: {
    ...existingMemberAuth.authMethodsEnabled,
    [AuthMethod.EXTERNAL_OAUTH2]: true,
  },
  registration: {
    ...existingMemberAuth.registration,
    mode: RegistrationMode.DISABLED,
    allowedMethods: [],
  },
  autoLinkByEmail: false,
};

This example also disables automatic email-based linking. Existing linked identities can sign in; a matching email alone cannot attach a new identity to the account. This posture is for accounts whose external identity is already linked; it does not establish that first link. If intentional verified-email linking is required, review and enable autoLinkByEmail across the target account’s held user types instead. Registration policy governs new accounts; it does not remove existing identity links.

The initiating frontend must also allow the same member type in frontendServices.<service>.usersManagement with auth: true. To offer public social registration instead, use RegistrationMode.OPEN, include AuthMethod.EXTERNAL_OAUTH2 in registration.allowedMethods, and enable register for that frontend/user-type pair. These are additional admissions, not consequences of displaying a provider button.

Let the standard flow carry the proof

The standard authentication flow stores one-time state and, where supported, a PKCE verifier before redirecting. OIDC requests also carry a nonce. On return, Wildo consumes the state, exchanges the authorization code and binds the verified identity to the request. A returned ID token must pass validation even when the profile also comes from a user-info endpoint.

A custom frontend should start and finish this flow through the authentication client. A browser-supplied profile, matching email or successful redirect is not authentication evidence.

Link only after identity has been established

The service first looks for the external subject’s existing link. Verified email is required for email-based linking and new social provisioning. Unverified provider email is not treated as account ownership. Existing-account linking and new-account registration are different decisions; configure both intentionally.

Profile and pending-invitation reconciliation run through the account/provisioning services. Enterprise SSO remains a separate tenant-owned connection model. A social provider button does not by itself satisfy a customer’s requirement to control its organization’s identity provider.

Choose acceptable factors, not just an MFA switch

The factor must be enabled as well as accepted by the MFA policy. Put both declarations under userTypes.<type>.auth in backend-api/src/saas-config.backend.ts; changing only acceptableMFAMethods does not enable an authenticator.

Example: require an authenticator app after password sign-in. existingAdminAuth is the application’s existing complete policy. Import AuthMethod from @wildo-ai/saas-models and merge this result back into that user type.

const adminAuth = {
  ...existingAdminAuth,
  authMethodsEnabled: {
    ...existingAdminAuth.authMethodsEnabled,
    [AuthMethod.PASSWORD]: true,
    [AuthMethod.TOTP]: true,
  },
  mfaPolicy: {
    ...existingAdminAuth.mfaPolicy,
    requireMFA: true,
    requireStrongMFA: true,
    acceptableMFAMethods: [AuthMethod.TOTP],
    enrollmentGracePeriodDays: 0,
    passkeyExemptFromMFA: false,
  },
};

This example preserves other enabled first factors. Review those deliberately if the application must require password specifically. TOTP is a second factor, not an alternative first-factor login. The account must enroll it through the standard setup flow; enabling the method does not create a secret for anyone.

Decide what an external login must demonstrate

The same user type can receive social logins, whose evidence is assessed separately from native challenges. Set externalAssuranceEnforcement: ExternalAssuranceEnforcement.STRICT inside its mfaPolicy to refuse missing or insufficient required assurance; import the enum from @wildo-ai/saas-models. Omission means warn and audit, not strict refusal.

The TOTP-specific policy above cannot be satisfied merely by a provider saying “MFA happened.” Generic upstream MFA does not establish that a particular local factor was used. A configured enterprise OIDC connection instead delegates MFA enforcement to the customer’s IdP. It still must pass identity and token validation. Organization overrides can tighten the applicable policy; they cannot weaken strict enforcement.

Enrollment and verification are different steps

The TOTP setup service creates a secret, a QR-code URI and recovery codes. The person must prove a generated code before setup is marked verified. Recovery codes are shown for the person to retain; stored recovery values are hashed. TOTP acceptance atomically claims its absolute time step in Redis. Recovery-code consumption uses a conditional credential update, so a concurrent second consumption cannot also succeed.

The engine uses resolveAcceptedSecondFactorMethods for both offered and accepted methods. This prevents a flow from asking someone to enroll a factor that the next challenge refuses. In the native sign-in flow, the orchestrator carries the first-factor state into the second-factor step and issues the session after the required proof completes.

Registration completion is also distinct from a returning user’s login challenge. It can complete with an already-enrolled factor or under configured enrollment grace; otherwise it directs the person to enrollment.

Plan the recovery route

An enrolled TOTP code and an unused recovery code are checked through the same verification service. A used recovery code is removed from the stored set. The standard flow supplies enrollment and challenge interfaces; the application still decides which account types require protection and which factors are appropriate for their users.

Put the requirement on the operation

The engine’s user-deletion API variant declares both who may call it and the additional proof it requires. Selected fields from users.shared.resources-config.schemas.ts:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
admitsCrossSubjectUserAdministration: true,
riskLevel: ResourceOperationRiskLevel.CRITICAL,
requiresStepUpAuthentication: true,

riskLevel controls how danger is presented; it is not the reauthentication gate. requiresStepUpAuthentication is the explicit requirement. The role gate remains in force.

Exchange a fresh factor for an operation proof

The reauthentication service accepts password, an enrolled TOTP or recovery code, or a passkey assertion. Passkey step-up uses its own challenge and requires user verification, so a normal login assertion cannot be replayed as step-up.

After verifying the factor, AuthMethodManagementBackendService produces this proof:

const token = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.REAUTH,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: 5, unit: DurationUnit.MINUTES },
  userId: userId,
  resourceIdentifier: CoreResourceType.USERS,
  relatedId: userId,
});
return { reAuthToken: token.token };

The standard frontend’s StepUpAuthContext coordinates the challenge and pending action. The backend operation gate consumes the proof for the authenticated person; a custom interface needs the same continuation rather than treating the challenge as an independent login screen.

Keep policy and enrolled methods compatible

When the effective stepUpAuth policy is enabled, its methods constrains which factors may mint the proof. The resolver includes the actual subject’s organization memberships, so organization restrictions participate rather than reading only the raw user-type policy.

An operation’s explicit requiresStepUpAuthentication can require proof even when the policy-level switch is disabled; in that case the enabled-policy method restriction does not apply. The resource-operation gate covers direct user requests, with exemptions for worker execution, nested service calls and its declared read-operation set.

A person must have a factor the minting path accepts enrolled locally; an SSO identity alone is not a password, TOTP or passkey proof. A proof already minted remains usable until its short expiry even if the accepted-method policy changes in the meantime.

Start from the user-type policy

These overrides are authored in application configuration, not a per-customer settings record. Separately managed SSO connection settings govern provider routing and enforcement.

organizationTypes[type].authOverrides can describe authentication methods, MFA, password requirements and step-up policy. Registration, lockout and session length are not organization-overridable fields in this contract.

The pure resolveAuthConfig function resolves each organization’s override against the base and then combines the results. For password bounds, the actual merge uses:

function mergePasswordMostRestrictive(a: PasswordPolicyConfig, b: PasswordPolicyConfig): PasswordPolicyConfig {
  return normalizePasswordPolicyBounds({
    minLength: Math.max(a.minLength, b.minLength),
    maxLength: Math.min(a.maxLength, b.maxLength),
    requireUppercase: a.requireUppercase || b.requireUppercase,
    requireLowercase: a.requireLowercase || b.requireLowercase,
    requireNumbers: a.requireNumbers || b.requireNumbers,
    requireSpecialChars: a.requireSpecialChars || b.requireSpecialChars,
    expiryDays: mergeExpiryDays(a.expiryDays, b.expiryDays),
  });
}

Longer minimum length and shorter maximum/expiry represent different directions numerically but the same stricter intent. MFA requirement uses true-wins; a shorter enrollment grace period wins.

Decide how method changes are allowed

Across multiple organizations the resolved method sets are intersected. Do not assume that a method available in one membership remains available when another organization’s requirements are included.

Keep the effective policy at the point of use

The backend gathers relevant memberships and resolves policy for authentication and credential changes. Active directory management additionally disables local first-factor methods that would bypass the directory. Step-up methods can be narrowed and freshness shortened where a base step-up policy exists. Custom flows should use the effective policy rather than reading the user-type defaults alone.

Establish the connection and routing authority

The user type must enable AuthMethod.ORG_OPENID_CONNECT. The organization also needs an enabled SSO connection, client configuration and verified domain routing. Claiming a domain is not verification; DNS verification grants the routing authority. The application-scope connection has its own authorize path.

Connect the method, tenant and identity provider

Example: permit OIDC for a user type whose other authentication policy already exists. Merge into userTypes.<type>.auth in backend-api/src/saas-config.backend.ts. Import AuthMethod from @wildo-ai/saas-models.

const customerAuth = {
  ...existingCustomerAuth,
  authMethodsEnabled: {
    ...existingCustomerAuth.authMethodsEnabled,
    [AuthMethod.ORG_OPENID_CONNECT]: true,
  },
};

This permits the method; it does not create an IdP connection, verify a domain or grant membership. The initiating frontend must admit the same user type. Organization method policy can further restrict or expand available methods within the application’s declared rules.

Use the standard scoped connection configuration service for manual metadata, provider templates or discovery. Those modes supply issuer, endpoints and keys; they are not three different trust policies. Keep client secrets in the backend configuration/secret path and register the callback supplied for the selected scope and deployment.

Verify the returned identity

Wildo validates the ID-token signature, expected issuer, client audience, expiry and issuance time before trusting its claims. It binds the nonce to the request and the identity to the returned profile. Missing verification metadata refuses ID-token processing; an unverified decode is not a fallback.

If the connection declares acrValues, the verified token must contain an accepted acr. Requesting a value does not prove it was returned, and a generic amr list does not substitute for the requested authentication context. Delegated enterprise MFA does not bypass this explicit demand.

Connect authentication to provisioning

The enterprise provisioning service resolves the external subject, local account, profile and membership. Just-in-time creation follows configured provisioning rules; directory provisioning is a separate lifecycle channel for joiners and leavers. Enterprise OIDC accepts delegated MFA assurance from the configured customer identity provider; it does not claim Wildo observed individual factors. The customer owns the IdP’s authentication policy, while Wildo retains token validation, identity binding and local access checks. Callback completion uses its own admission path and does not enter the native second-factor continuation.

Keep local access policy deliberate

Enforced SSO, migration grace and named emergency accounts are policy choices on the scope’s configuration. Active directory management disables local first-factor paths that would bypass the customer’s directory. These decisions belong beside connection setup, not in a custom callback that silently falls back to a local password.

This capability makes Wildo a client of the customer’s identity provider. Wildo’s own OAuth authorization-server and delegated-agent access surfaces answer a different question.

Prepare both sides of the connection

Enable AuthMethod.ORG_SAML for the relevant user type and configure the scope’s SAML connection. Exchange the application’s service-provider metadata and the identity provider’s settings, including certificates and endpoints. The configured runtime must provide the XML-validation helper used by the SAML implementation.

Create the organization-owned SSO connection with protocol: SsoProtocol.SAML, a displayName, and the provider’s saml settings. The following excerpt from sso-connection.shared.schemas.ts shows the connection fields the settings form and request contract use:

saml: z.object({
  entityId: z.string().min(1).isAuditEvidence(),
  ssoUrl: z.url().isAuditEvidence(),
  sloUrl: z.url().optional().isAuditEvidence(),
  x509CertificatePem: z.string().min(1).optional(),
  x509Certificates: z.array(z.string()).min(1).isBackendOnly(),
  attributeMapping: z.object({
    email: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'),
    firstName: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'),
    lastName: z.string().default('http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'),
    roles: z.string().optional(),
    department: z.string().optional(),
    employeeId: z.string().optional(),
    groups: z.string().optional(),
  }),
  signRequests: z.boolean().default(true).isAuditEvidence(),
  wantAssertionsSigned: z.boolean().default(true).isAuditEvidence(),

This is the relevant portion of the existing schema, not a complete connection payload. Enter the IdP’s entity identifier and SSO endpoint, supply its signing certificate through x509CertificatePem, and align attribute names with the assertions it sends. The backend derives the internal certificate array; clients do not write that backend-only field. Connection-level allowedDomains, defaultRole and autoCreateUsers govern who can enter and how new local accounts are provisioned.

On the provider side, use Wildo’s service-provider metadata for the intended organization. The metadata endpoint supplies that configuration; the assertion-consumer endpoint receives the provider’s response. Enable the connection and start sign-in through it: a valid assertion then enters the local account and membership resolution flow.

Bind the assertion before selecting the customer

SP-initiated sign-in carries request correlation. For IdP-initiated sign-in, the engine validates candidate connections against their configured certificates before selecting a scope. If several tenants share an identity provider and certificate, the signed audience must identify one intended tenant; unresolved ambiguity is refused.

Assertion conditions and replay protection are handled by the validator and replay guard. An unsigned issuer label is not tenant authority. Multiple configured certificates support certificate rollover without disabling validation.

Complete the account and logout lifecycle

After validation, the enterprise provisioning path resolves the local account and membership under the connection’s policy. SAML completion checks the local account and issues tokens on its callback path; it does not automatically enter the native MFA challenge continuation. Set the customer’s provider assurance requirements deliberately rather than assuming local mfaPolicy is translated into a SAML demand. Separate SAML logout paths manage the federated session behavior. Test the customer’s configured login direction and logout path with its provider; protocol support alone does not establish that a particular customer’s metadata and certificates are correct.

Configure session policy at the right level

Wonder Todos’ administrator type declares:

sessionDurationMinutes: 30,
maxConcurrentSessions: 3,

sessionDurationMinutes is the lifetime of the temporary sign-in episode, not the duration of the access JWT it eventually produces. Registration and invitation episodes are created with a 24-hour expiry; idle timeout and subsequent session-store updates also affect how long they remain usable. maxConcurrentSessions controls the number of authenticated sessions. JWT signing material and access/refresh token lifetimes are deployment-authored runtime settings.

Keep the refresh credential in its cookie

The standard client sends the refresh request with the HTTP-only refresh cookie. The endpoint takes an empty body; a JavaScript client should not read, store or submit the refresh token itself. Access-token updates are propagated to API clients and coordinated between same-origin tabs.

The controller reads the cookie after validating the request shape. Selected code from authentication-controller.backend.service.ts:

const ec = await this._getPreAuthExecutionContext();
RefreshTokenBodySchema.parse(req.body || {});
const refreshTokenValue = AuthControllerUtils.extractRefreshTokenFromCookie(req);
if (!refreshTokenValue) {
  throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
    customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_REFRESH_TOKEN_REQUIRED,
  });
}

Follow the order of the backend checks

AuthTokenIssuerBackendService.refreshAccessToken returns a cached successor when the predecessor is already marked as rotated and its grace entry exists. Concurrent refreshes select one successor in a Redis transaction that also records the retired credential and applies the winner’s session-limit effects. Losing requests receive the stored successor; they do not register extra sessions. If a response is lost after that transaction, a retry can recover the same tokens during the grace window. After the grace window expires, reuse of the retired credential writes the account-wide invalidation fence and reports a distinct reuse event. The raw token is not part of that signal.

Concurrent-session enforcement uses the shared session store and eviction path. A custom authentication integration must preserve these issuance and refresh paths; manually signing a replacement JWT would bypass the session lifecycle that makes the policy meaningful.

Use the account-wide revocation path

The authentication controller exposes logoutAll for the current user. Credential-reset services also use the issuer’s account-wide invalidation method. This is its current implementation:

public async invalidateAllTokensForUser(userId: string): Promise<void> {
  const nowSeconds = Math.floor(Date.now() / 1000);
  const refreshTokenDays = this.appConfigService.config.jwt.refreshTokenExpirationDays;
  await this.redisService.set(
    `${AUTH_REDIS_KEYS.TOKEN_INVALID_BEFORE}${userId}`,
    nowSeconds,
    { ttl: refreshTokenDays * 86400 },
  );
  this.logDebug('All tokens invalidated for user', { userId, invalidBefore: nowSeconds });
}

The fence expresses which earlier tokens are no longer admissible. The JWT guard, execution-context creation and refresh path consult it. A custom credential-changing flow must use the owning service rather than update the password hash and leave existing sessions untouched.

Choose the scope of logout deliberately

invalidateSession(sessionId) is the sibling for one login session. Account-wide invalidation affects the user’s earlier sessions; per-session invalidation withdraws only the selected one. Cross-tab logout separately clears the current browser’s visible state and client credentials.

Treat the revocation second as part of the boundary

The shared evaluateUserTokenInvalidationFence compares whole-second issuance times with the stored revocation second. It deliberately uses an inclusive comparison:

return { isRevoked: issuedAtSeconds <= invalidBefore, invalidBefore };

A token issued before the boundary is refused, and so is one issued in the same second. A login racing the revocation can therefore obtain a token that is immediately rejected: those timestamps cannot distinguish issuance just before the revocation from issuance just after it. Sign in again after that second has passed; do not relax the comparison or keep retrying the withdrawn token.

The atomic refresh publication path repeats the inclusive comparison inside Redis, so a revocation arriving while a successor is being signed is checked again before publication. Timestamp revocation, authorization-version changes and individual-session withdrawal are distinct checks; passing one does not bypass another. Test the equality case alongside an older token and a genuinely later issuance.

Understand the observed result

The next guarded request or refresh with a withdrawn token is refused. This does not reverse requests that already completed. Refresh checks revocation before returning a cached successor, so its short retry window cannot preserve access past a revocation. Keep the distinction between local interface cleanup, one-session logout and account-wide token withdrawal explicit in custom security controls.

The standard authentication provider coordinates tabs

AuthSessionContext uses the wildo-auth-tokens BroadcastChannel. Logout calls the backend, broadcasts LOGOUT, disconnects the live connection and clears local credentials. The receiver performs this selected cleanup from AuthSessionContext.tsx:

if (type === 'LOGOUT') {
  logDebug('Received logout signal from another tab');
  disconnect();
  tokenStorage.clear();
  getManualCallsHttpClient().setConsumableToken(null);
  setResourcesConsumableToken(null);
  storeAuthTokens(null);
  getManualCallsHttpClient().setAuthToken(null);
  setResourcesAuthToken(null);
  setAuth(EMPTY_AUTH_STATE);
}

Clearing both the manual HTTP client and resource client matters: an empty React account display alone would leave requests carrying an old credential. Consumable-token state is cleared as well. The receiving tab does not rebroadcast logout.

Use the shared provider in custom screens

Call the provider’s logout operation rather than removing a storage item yourself. Token refresh is coordinated on the same channel so tabs can adopt the new access token; the HTTP-only refresh cookie remains outside JavaScript.

Know the browser boundary

BroadcastChannel coordinates same-origin tabs where the browser supports it. It does not reach another device or unrelated domain. Backend logout is still the credential authority, and sign-out-everywhere is the separate account-wide mechanism. The sender clears its local state even if the network logout call fails, so a visibly signed-out tab is not by itself proof of server-side revocation.

Declare what the token is for

The password-reset service is a concrete consumer of the shared token mechanism. It mints this token before building the email link:

const resetToken = await this.consumableTokenService.createToken({
  tokenType: CoreConsumableTokenTypes.PASSWORD_RESET,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: PASSWORD_RESET_TOKEN_TTL_HOURS, unit: DurationUnit.HOURS },
  userId: user._id,
  resourceIdentifier: CoreResourceType.USERS,
  relatedId: user._id,
  metadata: { email: user.email },
});

Purpose, subject, related resource and expiration travel together. The reset handler later checks that the consumed token is a PASSWORD_RESET token before changing the credential. The token value is a secret, not a record identifier to display publicly.

Select the right lifecycle

Validation checks the current record. Consumption performs a conditional atomic mutation so two callers cannot both claim the last permitted use. Revocation is also guarded and makes an outstanding token unusable.

Reach it through the owning operation

Standard flows already supply their token consumers. Application operations can use declarative token generation, which reaches the same mint service. Define the intended resource/action target and the point of consumption; do not use a generic token as an implicit permission to call unrelated operations. Session-establishing links and upload grants add their own bounds above this shared lifecycle.

Connect generation to the action that needs proof

Wonder Todos pairs ASSIGN and CHANGE_STATUS in tasks.resources-config.ts. Its application-owned TasksManager_ConsumableTokenType.TASK_APPROVAL names the purpose (task_approval). The following is the generation block inside the existing ASSIGN API variant; its request declares assignedToUserId, and the operation requires ORG_MEMBER:

tokenGeneration: {
  tokenType: TasksManager_ConsumableTokenType.TASK_APPROVAL,
  consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
  expiresIn: { value: 12, unit: DurationUnit.HOURS },
  grantedRoles: [{ roles: [CORE_ORG_ROLES.ORG_MEMBER], relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS }],
  userIdField: 'assignedToUserId',
  revokeExistingForSameRelated: true,
  createsOneOffSession: true,
  consumeAt: 'TARGET_OPERATION',
  targetingFields: { taskId: '_id' },
},

ConsumableToken_ConsumptionMode, DurationUnit, CORE_ORG_ROLES and ResourcePrimaryScope come from @wildo-ai/saas-models; the token-purpose enum belongs to the application. The generation helper reads the updated task: _id supplies the related record, assignedToUserId supplies the recipient and organizationId supplies the tenant. Reassignment replaces outstanding tokens of this purpose for that related record.

The matching CHANGE_STATUS variant already has its update request and organization-member role requirement. Its additional declaration is:

tokenAuthentication: {
  types: [TasksManager_ConsumableTokenType.TASK_APPROVAL],
  policy: TokenAuthenticationPolicy.ADDITIVE,
},

TokenAuthenticationPolicy is also exported by @wildo-ai/saas-models. ADDITIVE requires normal authentication plus the token; the token’s purpose, state and recipient are checked, and normal operation authorization still applies. ALTERNATIVE is a separate authoring choice that authenticates from the token context. Do not substitute it just to avoid supplying a signed-in session. In this ADDITIVE path, the recipient check does not compare the token’s task target with the task addressed by the request. An application that requires approval for exactly one record must enforce that match in its operation; targetingFields alone is not that authorization check.

Register the resource and deliver the generated secret

The task factory is registered under TasksManager_ResourceType.TASKS in tasks-manager.resource-configs.ts. The shared tasks-manager module contributes that map through resourceConfigurations, alongside resourceFieldIdentifiers and resourceRelationships. These declarations participate in the normal resource pipeline; they are not a second standalone token router.

Token generation also supplies additionalContext.tokenValue to configured notification dispatch. An authored notification/template must consume that value and deliver it to the intended recipient through a configured channel. Declaring generation does not by itself author an approval email, and the ordinary task-update response is not a secret-retrieval API. Keep the recipient selection, template and delivery configuration aligned with the generation branch.

This particular example opts into a one-off session and therefore uses the engine’s twelve-hour mint ceiling. With TARGET_OPERATION, exchange retains the consumable token for the target action. The exchanged session uses the account’s normal authorization; the targeting fields do not make its access JWT record-only. See one-off session links for that separate session contract. A workflow that does not need login should not opt into session creation merely to carry an action token.

Invoke the paired operations

For an existing task, use the application API base, organization/task IDs and an authorized member session. The assignment request supplies the recipient ID:

curl --fail-with-body -X PUT "$BACKEND_URL/organizations/$ORGANIZATION_ID/tasks/$TASK_ID/assign" \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"assignedToUserId\":\"$ASSIGNEE_ID\"}"

After the configured delivery reaches the assignee, APPROVAL_TOKEN is that generated secret and ASSIGNEE_ACCESS_TOKEN is their authenticated session. BACKEND_URL includes the API prefix. Change the same task’s status with both credentials:

curl --fail-with-body -X PUT "$BACKEND_URL/organizations/$ORGANIZATION_ID/tasks/$TASK_ID/change-status" \
  -H "Authorization: Bearer $ASSIGNEE_ACCESS_TOKEN" \
  -H "x-consumable-token: $APPROVAL_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"status":"completed","reason":"Approved by the assignee"}'

For ADDITIVE, put the secret in x-consumable-token; a consumable_token query parameter does not satisfy that requirement. Inspect the persisted status after success, then repeat with the spent token: it must no longer authorize a second consumption. Also check a missing token and a different recipient, alongside the successful authorized request. A failed attempt is only meaningful after the positive path has established that the task, session and delivery are valid.

Opt the account type in

Wonder Todos declares oneOffSessionAllowed: true for members. The create endpoint separately requires an application super-administrator, rejects self-issuance and checks that the target account is active. It is not a general organization-member impersonation permission.

Name the target and lifetime

Selected fields from the controller’s actual request schema:

userId: z.string().min(1),
tokenType: ConsumableTokenTypesSchema,
consumeAt: z.enum(['EXCHANGE', 'TARGET_OPERATION']),
consumptionMode: z.enum(ConsumableToken_ConsumptionMode).optional().default(ConsumableToken_ConsumptionMode.SINGLE_USE),
maxUses: z.number().int().min(1).optional(),
expiresIn: z.object({
  value: z.number().int().min(1),
  unit: z.enum(['minutes', 'hours', 'days']),
}).optional().default({ value: 1, unit: 'hours' }),
resourceIdentifier: z.string().optional(),
relatedId: z.string().optional(),

Single use is the default; the contract also supports explicit consumption mode and use bounds. consumeAt selects exchange or target-operation consumption. Resource and related-record fields belong to the consumable token’s redemption contract. With TARGET_OPERATION, the response retains that token for the operation that consumes it. They do not become resource or record restrictions on the exchanged access JWT: that session uses the account’s normal authorization. Choose the consumption path for the intended operation rather than treating a targeted link as a record-only login.

Bound the session as well as the link

The create path limits duration to the smaller of the account type’s configured ceiling and the engine’s twelve-hour absolute ceiling. The shared token mint enforces the absolute maximum for every session-establishing path. Exchange rechecks the target’s eligibility and anchors the session lifetime at consumption. The issuer caps the initial access token at that deadline and carries the same deadline through refresh rotation, so a late refresh does not extend the one-off session.

Link validity and session lifetime answer different questions: how long the invitation to enter may be used, and how long the resulting session may last. One-off sessions do not consume the person’s ordinary concurrent-session slots. The revoke path withdraws outstanding one-off tokens without treating an arbitrary password-reset or invitation token as a support link.

Keep request and completion separate

The request handler returns the same response for unknown, eligible and ineligible accounts. ACTIVE and PENDING_VERIFICATION accounts can receive a single-use password-reset token by transactional email; suspended, inactive and deleted accounts do not receive it. Auth_PasswordLost supplies the standard request and completion interface.

Apply the current account policy

The completion service consumes the token, verifies its purpose and resolves the account’s effective password policy. After validation, the actual credential-changing sequence is:

const newPasswordHash = await this.credentialVerifier.hashPassword(newPassword, this.appConfigService.config.auth.passwordHashing);
await this.tokenIssuer.invalidateAllTokensForUser(userId);
await this.credentialVerifier.updatePasswordHash(ec, userId, newPasswordHash);
await this.consumableTokenService.revokeTokensByRelatedId(userId, CoreConsumableTokenTypes.PASSWORD_RESET);

The hash is derived using configured password hashing. Earlier account tokens are withdrawn before the credential is written, and sibling password-reset links are revoked. A custom recovery screen should submit to this completion operation rather than update a user record directly.

Make the retry behavior understandable

The token is consumed before password-policy validation. A rejected replacement can therefore require another recovery email; the same link is not a reusable validation session. Present the known password requirements before submission and preserve the resend path.

A pending-verification account can receive recovery mail without becoming active. Restoring a suspended or deactivated account remains a separate lifecycle action. The completion endpoint limits requests to 10 per minute per IP before parsing or hashing; the request endpoint has its own throttles.

Use the dedicated administrative operation

The FORCE_PASSWORD_RESET variant is application-super-admin gated and explicitly admits a different target user. Its request and response contracts are selected here from users.shared.resources-config.schemas.ts:

requestDto: z.object({
  reason: z.string().min(1).max(500)
}),
customResponseDto: z.object({
  expiresAt: z.date(),
  sessionsRevoked: z.boolean()
}),

The custom implementation requires one addressed account, an attributable caller and a non-empty reason. Self-reset is refused here; the account owner’s normal password-change path proves their current credential instead.

Observe what the operation actually returns

expiresAt describes the emailed link and sessionsRevoked confirms withdrawal. Neither the reset token nor URL is returned to the administrator. The shared password-reset service sends to the target user’s email using the transactional template and resolved locale.

Separate containment from completion

Existing tokens are invalidated before the forced-reset flow completes. The user then follows the mail and chooses a password that meets their effective policy. Starting the reset is not evidence that the owner has received the email or changed the password yet. Delivery configuration and operational monitoring therefore remain necessary alongside the account action.

The backend refuses a deleted target. Reset initiation does not reactivate a suspended account or assign new roles; those are separate lifecycle decisions.

Choose the lifecycle action rather than patching status

The user resource declares separate operations for role assignment/revocation, suspension, unsuspension, reactivation and forced password reset. Generic updates do not stand in for those transitions.

Keep the actor and subject distinct

Administrative variants combine their role requirement with admitsCrossSubjectUserAdministration: true. That flag allows the target to be another user; it does not itself grant administrative authority. The same operation still has to satisfy its declared roles and any fresh-proof requirement.

The destructive user operation makes the combination explicit:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
admitsCrossSubjectUserAdministration: true,
riskLevel: ResourceOperationRiskLevel.CRITICAL,
requiresStepUpAuthentication: true,

These are selected fields from the real user-deletion variant, with comments omitted. Presentation risk and step-up enforcement are separate settings.

Preserve continuity and the record of change

The shared transition machinery owns status changes and scheduled reactivation cleanup. Administrative floors prevent removing the last usable administrator. reactivate_user requires a reason because it reverses the owner’s chosen departure, while unsuspension has a different contract. Custom administration screens should invoke these operations and display their outcomes, not write the underlying status and role fields directly.

Use the self-service resource for the current person

userSelf provides own-account reads and lifecycle actions over the user records. It does not expose arbitrary user-row updates. Profile and preference changes belong to their dedicated self-service resources.

The deactivation operation’s current request and availability condition are:

requestDto: z.object({
  reason: z.string().max(500).optional(),
}),
enabledCondition: ({ currentObject }) => {
  return currentObject.status === UserStatus.ACTIVE;
}

The shared transition moves ACTIVE to INACTIVE. The administrative continuity floor still applies, so the last usable administrator cannot bypass that protection by choosing the self-service route.

Explain the return path before deactivation

Normal authentication admits active accounts. Once deactivated, a person cannot simply sign back in to invoke self-reactivation. The administrative reactivate_user operation restores INACTIVE accounts with a documented reason. An imposed SUSPENDED account uses the distinct unsuspend operation.

Keep data-rights actions explicit

Account deactivation is not data erasure. This resource does not provide a self-delete or subject-export endpoint. Applications that offer those journeys need to connect their authorized data-rights process to the relevant services rather than relabel deactivation as deletion. This distinction preserves the user’s expectation and the lifecycle behavior behind the control.

Register custom roles in the application role configuration. inheritFrom supplies the existing responsibilities; relatedPrimaryScope selects the role table in which they are meaningful. Wonder Todos declares both an application manager and an organization supervisor:

This implementation excerpt from roles.ts shows the decision in context; explanatory source comments are omitted.

import { RolesConfiguration, ResourcePrimaryScope, CORE_APP_ROLES, CORE_ORG_ROLES } from "@wildo-ai/saas-models";

export const CUSTOM_ROLES_CONFIGURATION: RolesConfiguration = {
  'CUSTOM_APP_MANAGER': {
    role: 'CUSTOM_APP_MANAGER',
    inheritFrom: CORE_APP_ROLES.APP_USER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.APPLICATION
  },
  'CUSTOM_ORG_SUPERVISOR': {
    role: 'CUSTOM_ORG_SUPERVISOR',
    inheritFrom: CORE_ORG_ROLES.ORG_MANAGER,
    isSystemRole: false,
    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS
  }
};

Register the role map with the shared application module

A role map must reach startup before operations can use its hierarchy. Wonder Todos’ shared-lib/src/engine/index.ts contributes it through the existing engine module:

import type { SharedSaaSModule } from '@wildo-ai/saas-models';
import { CUSTOM_ROLES_CONFIGURATION } from './roles';

const engineSharedModule: SharedSaaSModule = {
  moduleId: 'engine',
  kind: 'engine',
  customRoles: CUSTOM_ROLES_CONFIGURATION,
  // Keep the module's existing feature, milestone and product contributions.
};

export default engineSharedModule;

This selected module excerpt is the contribution point. In Wonder Todos, shared-lib/src/modules-registry.shared.ts includes engineSharedModule in sharedModules and passes that list to buildSharedSaaSModulesRegistry. Retain that existing assembly. Declaring the constant in an unreferenced file does not register roles. Membership assignment and an operation’s required roles are separate choices: registration makes the hierarchy available, it does not grant it to every account.

Follow the declaration into authorization

Application startup registers this configuration with initializeRolesWithCustom. The authorizer expands the caller’s role through the configured inheritance chain before comparing it with an operation’s roles. This means an inherited manager responsibility remains available without copying the entire role list onto every member.

A matching role is one part of admission. Tenant confinement and reference eligibility still apply. APP_PUBLIC is an operation declaration that removes a role requirement; it is not a role to grant to an account. Use role grants to control who may assign the roles you define.

The OAuth-client mint handler checks the caller-authored roles before generating secret material. The core create still performs persistence, and the postfix returns the plaintext secret once:

This implementation excerpt from oauth-clients.custom-impl.backend.service.ts shows the decision in context; explanatory source comments are omitted.

export function buildOAuthClientMintHandlers(scope: ApiKeyScope, roleHierarchyResolver: RoleHierarchyResolver): OAuthClientImplHandlers {
  return {
    prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
      assertRequestedRolesWithinCallerCeiling(executionContext, (input as { roles?: string[] }).roles, utils.errorBuilder, roleHierarchyResolver);
      const { plainSecret, secretPrefix, hashedSecret } = generateOAuthClientSecretMaterial(scope);
      PLAINTEXT_SECRET_BY_EC.set(executionContext, plainSecret);
      return { ...(input as Record<string, unknown>), secretPrefix, hashedSecret };
    },
    postfixCoreOperations: async (_id, createdClient, executionContext, _operationPath, _utils) => {
      if (!createdClient || typeof createdClient !== 'object') return createdClient;
      const plainSecret = PLAINTEXT_SECRET_BY_EC.get(executionContext);
      PLAINTEXT_SECRET_BY_EC.delete(executionContext);
      if (!plainSecret) return createdClient;
      return { ...(createdClient as Record<string, unknown>), plainSecret };
    },
  };
}

Extend the same check to application resources

The framework wires assertRequestedRolesWithinCallerCeiling into its membership, unit-assignment, application-role and credential creation paths. If an application introduces another resource whose caller-settable roles confer authority, call the assertion from its create and roles-changing update handlers too.

Use createRoleHierarchyResolver to read the live, application-configured hierarchy. Pass the roles as the caller authored them, before adding policy defaults. Otherwise a default role supplied by the framework would be mistaken for a privilege the person asked to grant.

Keep scope and privilege checks separate

The ceiling compares effective roles across the caller’s organization-wide memberships. A unit-scoped administrator role does not become organization-wide grant authority. The surrounding operation authorization answers where the caller may write; this check answers how high they may grant.

Internally initiated provisioning and an application-scoped super-administrator are deliberate exceptions. Credential roles are fixed at creation: rotation changes secret material, not the roles the credential carries.

Role and account-status changes use the transition guard; removals use the removal guard. Both reach the same population check. This part of that check shows how it excludes the accounts being changed:

This implementation excerpt from super-admin-floor.backend.utils.ts shows the decision in context; explanatory source comments are omitted.

export async function assertSuperAdminFloorPreserved(params: {

  subjectUserIds: readonly string[];
  cause: SuperAdminFloorReductionCause;
  executionContext: ExecutionContext<any>;
  repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
  errorBuilder: ErrorBuilderBackendService;
  conferringRoles: readonly string[];
  operationIdentifier: string;
}): Promise<void> {
  const { subjectUserIds, cause, executionContext, repositoriesRegistry, errorBuilder, conferringRoles, operationIdentifier } = params;

  const remainingUsableSuperAdmins = await countOtherUsableSuperAdmins({
    excludedSubjectIds: subjectUserIds,
    executionContext,
    repositoriesRegistry,
    errorBuilder,
    conferringRoles,
    operationIdentifier,
  });

  if (remainingUsableSuperAdmins >= SUPER_ADMIN_FLOOR_MINIMUM) return;

  throw errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
    context: {
      code: AdministrativeContinuityErrorCode.LAST_APPLICATION_SUPER_ADMIN,
      reason: SUPER_ADMIN_FLOOR_REFUSAL_REASON,
      message:
        'Refused: this would leave the application with no usable super-administrator. '
        + SUPER_ADMIN_FLOOR_REMEDY,
      cause,
      operationIdentifier,
      subjectUserIds: [...subjectUserIds],
      remainingUsableSuperAdmins,
      requiredUsableSuperAdmins: SUPER_ADMIN_FLOOR_MINIMUM,
      conferringRoles: [...conferringRoles],
      usableStatuses: [...ADMINISTRATIVELY_USABLE_USER_STATUSES],
    },
  });
}

Treat the refusal as a state conflict

The caller may have all the required permissions and still be unable to perform this change. The response is a conflict with LAST_APPLICATION_SUPER_ADMIN, because the problem is the resulting administrator population. Promoting another usable account is the remedy; acquiring another permission is not.

Custom roles that confer super-administrator authority participate through the live role hierarchy. A disabled or otherwise unusable account must not be counted as the fallback simply because its stored roles still look powerful.

Preserve continuity on the right lifecycle path

The account-role administration handlers call the guard when authority or usability decreases. Subject erasure has a separate continuity path: do not replace a privacy erasure workflow with a blanket refusal. Organization ownership has its own last-owner rule, because tenant ownership and application administration are different responsibilities.

ResourcePrimaryScope names the resolved scope. Application authors declare ownership through relationships; the resource factory derives resourcePrimaryScope from that declaration. Scope-root resources anchor themselves, and polymorphic resources receive the relationship for their selected scope variant. Operation roles then decide who can act within the resolved scope.

Declare the ownership that determines the scope

Wonder Todos registers this relationship alongside its resource definitions. The parent is an organization, the child is a todo, and isPrimaryScope identifies the ownership relationship used to derive the child’s scope. Source: tasks-manager.relationships.ts; source comments omitted.

createResourcesRelationship(
  CoreResourceType.ORGANIZATIONS, TasksManager_ResourceType.TODOS,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'organizationId',
    contextPolicy: {}
  }
)

With this registered relationship, the factory resolves organization ownership and its foreign-key field. Another relationship, such as the todo’s assignee, remains a reference; it does not replace the primary owner. An ordinary resource without a resolvable primary scope is rejected during configuration instead of silently receiving a broader scope.

Let a draft belong to a person or a visitor

Wonder Todos’ draft notes demonstrate USER_SELF and ANONYMOUS without changing the business object. The schema declares nullable userId and anonymousUserId foreign keys, both excluded from ordinary updates. The resource opts into anonymous ownership with isAnonymizable: true and chooses transpositionPolicy: ResourceTranspositionPolicy.ADD for the later account handoff.

Its authored relationship starts from the signed-in person. This is the relevant declaration from tasks-manager.relationships.ts, including the child lifecycle decision:

createResourcesRelationship(
  CoreResourceType.USERS, TasksManager_ResourceType.DRAFT_NOTES,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'userId',
    parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
    accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT,
    childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE } } },
    contextPolicy: {},
  }
)

The relationship helper and enum vocabularies come from @wildo-ai/saas-models; TasksManager_ResourceType is application-owned. OPTIONAL accommodates a visitor-owned row without a userId; it does not make another person’s records public. The anonymizable resource factory supplies the anonymous ownership relationship. Application authors do not hand-author a second unrelated draft resource.

The draftNotes_ResourceConfiguration_InitializationFactory is registered in the tasks-manager resource factory map, and the shared module contributes that map together with its relationships and field identifiers. Its ordinary create/read/list/update/delete API variants accept APP_USER and APP_ANONYMOUS; ownership confinement still applies to each caller. Allowing both roles does not merge their records.

Observe the two ownership paths

With BACKEND_URL including the API prefix, an authenticated person lists their drafts using their own user ID and Bearer session:

curl --fail-with-body "$BACKEND_URL/users/$USER_ID/draft-notes" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

For an already established anonymous session, use its UUID in the path and its signed session token in the header. The UUID is an identifier, not a credential:

curl --fail-with-body "$BACKEND_URL/anonymous-users/$ANONYMOUS_UUID/draft-notes" \
  -H "x-anonymous-session: $ANONYMOUS_SESSION_TOKEN"

The standard client establishes and carries that session; anonymous sessions and transposition explains its lifecycle. Supply the application’s frontend-service header where its deployment requires it. Neither call turns a user-supplied owner field into authority.

Verify isolation using existing disposable drafts: each owner can read their own record; substituting another user or visitor’s path/record must not expose or mutate that record. Check the allowed read first so an unavailable route cannot masquerade as successful isolation. The existing scope-isolation-user-anon-hostile.e2e.ts exercises these separate ownership paths and re-reads storage after denied mutations.

Carry the scope through the operation

The framework resolves the scope root and contextual identifier, builds the caller’s execution context and uses the matching authorization path. A user-scoped resource is not made accessible to everyone merely because it sits in the same application database.

Organization units narrow authority inside an organization; they do not introduce a fifth primary scope. Likewise, a directory of users is an application administration surface, not the same interaction as reading one person’s own preferences.

Plan the visitor-to-account transition

Anonymous ownership can support work before registration. A resource’s transposition policy determines whether that work is reassigned, replaces existing work or is discarded when ownership moves. Treat that transition as a separate product decision from who may operate on the visitor’s data now.

See tenant confinement for organization records and anonymous sessions for the registration handoff.

Register the primary ownership relationship with the application’s resource relationships. The resource factory derives organization scope from it; resourcePrimaryScope is not a second author-maintained setting. In Wonder Todos, tasks-manager.relationships.ts contains this declaration (source comments omitted):

createResourcesRelationship(
  CoreResourceType.ORGANIZATIONS, TasksManager_ResourceType.TODOS,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'organizationId',
    contextPolicy: {}
  }
)

The todo schema supplies the organizationId foreign-key field. The relationship connects that field to the organization parent and makes it the primary ownership axis. Register it before initializing the resource configuration, alongside the resource’s operations and other relationships.

When an authorized caller lists todos through the organization’s contextual resource operation, the framework resolves that organization in the execution context and carries confinement into the repository query. The same declaration serves both persistence adapters. Application code still supplies the operation’s roles and business filters; it does not infer tenant authority from a submitted organization ID.

The shared confinement function checks the authenticated organization and the operation’s declared crossing policy before adding the top-level ownership predicate:

This implementation excerpt from initiator-organization-confinement.backend.ts shows the decision in context; explanatory source comments are omitted.

export function assignInitiatorOrganizationConfinementToFilter<TFilter extends object>(params: {
  readonly filter: TFilter;
  readonly executionContext: InitiatorOrganizationConfinementSignal;
  readonly blacklistedFields: ReadonlySet<string>;
  readonly mainSchema: unknown;
  readonly schemaPaths: InitiatorOrganizationConfinementPathResolver;
  readonly isFieldPersisted: (fieldName: string) => boolean;
}): boolean {
  const initiatorOrganizationId = params.executionContext.initiatorIds?.organizationId;
  if (!initiatorOrganizationId) {
    return false;
  }

  if (params.executionContext.operation?.admitsCrossTenantPlatformAdministration === true) {
    return false;
  }

  if (
    params.blacklistedFields.has(INITIATOR_ORGANIZATION_CONFINEMENT_FIELD)
    || !params.isFieldPersisted(INITIATOR_ORGANIZATION_CONFINEMENT_FIELD)
  ) {
    return false;
  }

  const organizationPaths = params.schemaPaths.findNestedFieldPathsFromZodSchema(
    params.mainSchema,
    INITIATOR_ORGANIZATION_CONFINEMENT_FIELD,
  ).filter((fullPath) => !fullPath.includes('.'));

  let applied = false;
  organizationPaths.forEach((fullPath) => {
    if (!params.schemaPaths.hasNestedPath(params.filter, fullPath)) {
      params.schemaPaths.setNestedValue(params.filter, fullPath, initiatorOrganizationId);
      applied = true;
    }
  });

  return applied;
}

Follow authority, rather than trusting a payload

The execution-context creator obtains memberships and removes authority from organizations that are no longer operational. The normal create path supplies contextual ownership fields; client data is not the authority for which tenant owns the new record.

Both persistence adapters call the shared confinement authority. A nested field that happens to be named organizationId is ordinary data unless it is the declared top-level ownership axis; filtering every matching field name would hide legitimate records.

Use the declared exceptional path

A deliberately admitted cross-tenant platform operation can step outside normal confinement. That is an operation-level declaration with its own admission requirements, not a global super-administrator shortcut. Arbitrary direct database access is outside the resource path and must not be mistaken for an authorized resource operation.

Organization listings need an additional rule because the organization is the scope root itself: see account-list confinement.

A machine token names its scope. The execution-context creator compares the addressed scope with that authenticated value before constructing the request context:

This implementation excerpt from execution-context-creator.backend.service.ts shows the decision in context; explanatory source comments are omitted.

const urlScopeId = machineScope === ResourcePrimaryScope.ORGANIZATIONS
          ? initiatorCriticalParamsValue.organizationId
          : initiatorCriticalParamsValue.applicationId;
        if (urlScopeId && urlScopeId !== machineToken.scopeId) {
          throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined,
            { customMessageReference: ErrorCustomMessageReference.AUTHORIZATION_MACHINE_SCOPE_MISMATCH,
              context: { reason: 'machine_scope_url_mismatch', tokenScope: machineScope } });
        }

        const machineCredential = { authMethod: MachineAuthMethod.OAUTH_CLIENT, credentialId: machineToken.clientId };
        const initiatorIds: ExecutionContext_InitiatorIds = machineScope === ResourcePrimaryScope.ORGANIZATIONS
          ? { ...this.extractInitiatorIds(initiatorCriticalParamsValue), organizationId: machineToken.scopeId, machineCredential }
          : { ...this.extractInitiatorIds(initiatorCriticalParamsValue), applicationId: machineToken.scopeId, machineCredential };

Keep ownership fields server-authored

Generated operation input shapes exclude contextual ownership fields from normal caller-controlled data. The resource operation path then enriches the write using its resolved context. Build scoped API calls with the intended organization in the route and ordinary business fields in the payload; do not rely on a payload organizationId to establish authority.

The exact refusal depends on the stage: invalid identity, inaccessible scope and disallowed input are different cases. Do not interpret an ignored extra property as proof that it was trusted.

A reference inside the payload still has its own eligibility question. Membership-constrained relationships prevent a valid tenant write from linking an ineligible person or partner.

This is the task-assignee declaration in Wonder Todos. scopeMembership: true asks the registry to resolve the organization-membership junction. The context settings separately control the related information returned with the task:

This implementation excerpt from tasks-manager.relationships.ts shows the decision in context; explanatory source comments are omitted.

createResourcesRelationship(
    TasksManager_ResourceType.TODOS, CoreResourceType.USERS,
    ResourceRelationshipCardinality.MANY, ResourceRelationshipCardinality.ONE,
    {
      nature: RelationshipNature.REFERENCE,
      foreignKeyField: 'assignedToUserId', // Explicit for Edge Case #1 - multiple FKs to same type
      parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
      accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.OPTIONAL_CONTEXT,
      scopeMembership: true,
      contextPolicy: {
        objectMode: ContextPolicy_ObjectMode.SUMMARY,
        operationOverrides: {
          [CoreResourceOperation.READ]: { objectMode: ContextPolicy_ObjectMode.FULL },
          [CoreResourceOperation.LIST]: { enabled: false },
          [CoreResourceOperation.SEARCH]: { enabled: false },
        }
      }
    }
  ),

Use an explicit junction when membership means something else

For a rota or partnership, set scopeMembership to an object naming the junction. junctionScopeField and junctionTargetField identify its columns when they cannot be inferred. The target’s existence and the junction’s existence answer different questions; both matter.

Create and update integrity checks evaluate referenced foreign keys before storing the write. An operation can add referenceConstraints to tighten eligibility, such as requiring a particular membership status. Related-record resolution uses the declared membership semantics as well.

Separate who may assign from who may be assigned

Wonder Todos’ assign-lead operation uses the same assignedToUserId relationship shown above and declares an active organization administrator as its eligible target. The caller must also be an administrator. The example below uses built-in organization roles: permission to make the change does not make every selected person eligible.

This is the operation declaration from todos.resources-config.ts, with comments omitted. Todos_Operations belongs to the application; the other enums come from @wildo-ai/saas-models, and z comes from zod.

[Todos_Operations.ASSIGN_LEAD]: {
  variants: [
    {
      variantType: ResourceOperationVariantType.API_CALL,
      isDefault: true,
      roles: [CORE_ORG_ROLES.ORG_ADMIN],
      riskLevel: ResourceOperationRiskLevel.MEDIUM,
      resourceOperationLike: CoreResourceOperation.UPDATE,
      requestDto: z.object({
        assignedToUserId: z.string().min(1),
      }),
      referenceConstraints: {
        assignedToUserId: {
          qualifyingStatuses: [OrganizationMemberStatus.ACTIVE],
          requiredRoles: { scope: ResourcePrimaryScope.ORGANIZATIONS, roles: [CORE_ORG_ROLES.ORG_ADMIN] },
        },
      },
    },
  ],
},

Place this inside the resource’s operationsConfiguration. The shared tasks-manager module contributes its factory map through resourceConfigurations and its relationship list through resourceRelationships. Both are needed: the relationship identifies the membership junction; this operation adds the eligibility criteria. Merely adding an input field does not declare that relationship.

For an existing todo, call the addressed operation with the organization’s administrator session. API_BASE includes the backend API prefix; ASSIGNEE_USER_ID is the selected user’s ID, not their membership ID.

curl --fail-with-body --request PUT "$API_BASE/organizations/$ORGANIZATION_ID/todos/$TODO_ID/assign-lead" \
  --header "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"assignedToUserId\":\"$ASSIGNEE_USER_ID\"}"

Run the permitted case before testing refusals, and confirm refused writes leave the previous assignee unchanged. The ordinary assign operation on this resource does not add these status/role criteria: it retains the relationship’s membership check. If several operations must enforce the stricter policy, declare it on each applicable variant.

Target roles are resolved against the application’s current role definitions in the declared scope. A custom role can qualify through its inheritance; an unknown role grants nothing. Related-record search can offer members who do not meet a stricter write policy, so handle an assignment refusal even when the person appeared in a picker.

Make exceptions deliberate

This policy is opt-in on the relationship. An organization-less target without it may receive an existence check rather than a membership check. A variant that explicitly waives membership changes the contract for that variant; do not use that escape hatch to make an ordinary assignment work around an incomplete declaration.

The same scope-root authority is used by authorization and repository filtering. After identifying a governed organization collection operation, it derives the allowed IDs from the caller’s organization-wide role entries and intersects the requested IDs:

This implementation excerpt from scope-root-collection-confinement.backend.ts shows the decision in context; explanatory source comments are omitted.

function intersectRequestedIdsWithMembership(requested: unknown, membershipIds: readonly string[]): string[] {
  if (requested === undefined || requested === null) return [...membershipIds];

  const membership = new Set(membershipIds);

  if (typeof requested === 'string') {
    return membership.has(requested) ? [requested] : [];
  }

  if (Array.isArray(requested)) {
    return requested.map(String).filter((id) => membership.has(id));
  }

  if (typeof requested === 'object') {
    const operators = Object.keys(requested as Record<string, unknown>);
    const inValue = (requested as { $in?: unknown }).$in;
    if (operators.length === 1 && operators[0] === '$in' && Array.isArray(inValue)) {
      return inValue.map(String).filter((id) => membership.has(id));
    }
    return [];
  }

  return [];
}

Know which operations are set-shaped

The confinement covers list, search, count, update-many and delete-many operations on the organization root. Addressed reads have a separate per-record authorization path. A unit-only role does not become permission to enumerate the whole organization.

The portable empty-set predicate produces no results on either database adapter. A caller-supplied condition is never a reason to drop the membership restriction.

Distinguish tenant lists from application directories

Other scope roots have explicit dispositions: the deployment application row, the person directory and anonymous sessions do not share the same tenant-membership filter. Application-wide directory admission has its own elevation policy. Internally initiated work, verified callbacks and deliberately admitted cross-tenant operations also have distinct handling; an empty membership list must not silently empty a framework maintenance sweep.

Role checks that do not depend on the row can refuse before resolving it. A missing or scope-invisible addressed record uses the same outward not-found treatment. Internal storage faults remain faults rather than being rewritten as evidence that a record is absent.

Keep a useful refusal trail

authorization-denial-audit.backend.utils.ts classifies authorizer-origin not-found outcomes as authorization refusals while excluding unrelated application 404s. The audit policy emits the first refusal and escalating occurrence counts, rather than writing an attacker-controlled number of rows.

The resource-operation authorization path uses this classifier to distinguish a concealed subject from an unrelated application failure. Exact excerpt from authorization-denial-audit.backend.utils.ts:

export function classifyAuthorizationDenial(
  error: unknown,
  phaseDefaultReason: ResourceOperationDenialReason,
): ResourceOperationDenialReason | undefined {
  if (!isWildoBackendError(error)) return undefined;

  if (error.type === ErrorType.AUTHORIZATION) {
    return error.customMessageReference === ErrorCustomMessageReference.AUTHORIZATIONS_MISSING_INITIATOR
      ? ResourceOperationDenialReason.MISSING_INITIATOR
      : phaseDefaultReason;
  }

  if (
    error.type === ErrorType.NOT_FOUND &&
    error.customMessageReference === ErrorCustomMessageReference.AUTHORIZATIONS_VALIDATION_FAILED
  ) {
    return ResourceOperationDenialReason.SUBJECT_NOT_RESOLVABLE;
  }

  return undefined;
}

The second branch recognizes only a not-found outcome marked by the authorizer. Other failures return undefined here; they keep their own error handling rather than entering the access-refusal series.

The counter is associated with the available user identity, resource, operation, variant and reason; calls without a user identity share the fallback bucket. Walking different target IDs therefore does not create an independent audit bucket for every guessed record.

Do not confuse observation with prevention

The normal authorization decision refuses the request. The audit volume policy does not rate-limit or lock the caller, and it does not normalize response timing. Security monitoring can act on the recorded pattern; application access rules remain the preventive control.

The resource exposes requestAccess, approve, deny and revoke. The request supplies justification and requested duration; operator identity, status and expiry are server-authored. Default duration is one hour and the server caps requests at four hours.

Admission checks the actual expiry, not whether a background process has relabelled the row:

This implementation excerpt from platform-access-grants.shared.schemas.ts shows the decision in context; explanatory source comments are omitted.

export function isPlatformAccessGrantUsable(
  grant: Pick<PlatformAccessGrant, 'status' | 'expiresAt'> | undefined,
  now: Date,
): boolean {
  if (!grant) return false;
  if (grant.status !== PlatformAccessGrantStatus.ACTIVE) return false;
  return grant.expiresAt instanceof Date
    ? grant.expiresAt.getTime() > now.getTime()
    : new Date(grant.expiresAt).getTime() > now.getTime();
}

Declare the operation that support may use

The crossing flag belongs to an API operation variant. The built-in ownership-repair operation keeps the role, scope permission and request together:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
riskLevel: ResourceOperationRiskLevel.CRITICAL,
resourceOperationLike: CoreResourceOperation.UPDATE,
admitsCrossTenantPlatformAdministration: true,
requestDto: z.object({ justification: z.string().min(1).max(1000) }),

This is a selected variant fragment from organization-members.shared.resources-config.schemas.ts, not a standalone resource. Its operation enums and roles come from @wildo-ai/saas-models, with z from zod. The existing membership resource registers this operation. A custom support action needs its own registered resource operation, API variant and implementation; copying the flag alone creates neither a route nor business behavior.

Choose whether the customer must approve

platformAccessApprovalRequired is a field on the organization record, with a default of false. It is not an organization-type authentication override or a caller-supplied grant status. Set it through the authorized organization configuration path before support requests arrive. The request handler reads the stored organization posture and checks whether a usable owner can approve.

Request, decide, then perform the action

The following sequence follows Wonder Todos’ platform-access-grant lifecycle example. ORG_ID comes from the customer support case; ordinary organization listing is not a platform-wide customer directory. OPERATOR_TOKEN belongs to an application super-administrator. CUSTOMER_ADMIN_TOKEN belongs to a tenant administrator with authority to decide the request. Use a customer with approval required and a usable owner for this pending-approval example.

curl "$BACKEND_URL/organizations/$ORG_ID/platform-access-grants/request-access" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"justification":"Investigate support case SUP-42","requestedDurationMinutes":30}'

curl -X PUT "$BACKEND_URL/organizations/$ORG_ID/platform-access-grants/$GRANT_ID/approve" \
  -H "Authorization: Bearer $CUSTOMER_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"decisionReason":"Verified support case SUP-42"}'

Take GRANT_ID from the created grant record’s _id. Check its returned status and expiry: accepting the request does not mean access is active. With the example’s posture it waits for the tenant decision, and the operator’s crossing is refused while pending. The request operation itself has a narrow bootstrap exemption so an operator can ask without already holding the grant.

Approval uses the customer’s authority, not the operator’s platform crossing. For a refused request use the grant’s deny operation; to withdraw an existing grant use revoke. These are lifecycle operations, not edits to status or expiresAt. A usable grant is looked up when the operator calls the target operation; it is not a replacement login token to send as a Bearer credential.

Continue with the ownership-repair invocation for an actual declared target operation. The grant remains limited to its operator, organization and time window; it does not admit undeclared actions.

Apply both admission requirements

The target operation must declare that it admits cross-tenant platform administration, and the operator must have a usable grant for the target account. A grant does not turn every operation into a support door. Grant lookup failures do not restore standing access.

The last case prevents an ownerless account from becoming impossible to repair. Approval posture and owner usability are checked on the request path, not copied from the caller.

Separate account support from global administration

Approval and denial use the tenant’s own authority; the platform crossing declaration does not let an operator approve on that basis. Application-wide directory access has a separate grant and two-person approval policy because no single tenant can authorize reading a deployment-wide directory.

The settings hub selects an organisation; its registered resource operations keep that owner in the request path and execution context. The backend validates who may use those operations. Selecting a customer in the interface does not itself grant authority over that customer’s resources.

For SSO, configuration and connections are separate resources under the same owner. Domain verification establishes who controls the sign-in domain; connection settings describe how the identity provider participates. Neither should be copied into an application-wide credential merely because the application hosts both customers.

Exercise an organization-owned configuration operation

For example, the SSO domain-claim operation lets the organization’s administrator begin proving a domain it controls. The organization already has its seeded SSO configuration; claiming a domain does not require creating a second configuration row.

This request follows sso-domain-ownership.e2e.ts. Set BACKEND_URL, ORGANIZATION_ID and the organization’s administrator ACCESS_TOKEN; replace the illustrative domain with one the customer controls.

curl -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/claim-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

The claim response names the domain, reports pending and returns dnsName plus the one-time dnsRecordValue. Publish that exact value as a TXT record at the returned name. Do not invent the challenge value or assume that the domain’s presence in the stored list means it is verified.

After publishing the record, ask the same scoped operation family to verify it:

curl --fail-with-body -X PUT \
  "$BACKEND_URL/organizations/$ORGANIZATION_ID/organization-sso-config/verify-domain" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"domain":"customer.example"}'

Read the response’s status, not only the HTTP status code. A completed verification request can return HTTP 200 with failed; --fail-with-body cannot detect that business result. The backend checks DNS and rechecks competing ownership at verification time, before granting routing authority. A claim alone does not authorize sign-on routing.

This illustrates the ownership contract: a public, named operation changes the selected organization’s configuration and returns the next action its administrator needs. Provider connection details and SSO enforcement remain separate settings; the general configuration update is an internal operation, not a public catch-all HTTP endpoint.

Configure the correct integration owner

Enable the relevant feature and configure the provider through its declared resource. A page appearing in settings is a consumer of that configuration, not proof that a provider is already connected or operating.

Preserve the distinction between personal and organization connections

A person’s connected account and an organization-owned credential represent different authority. Use the appropriate resource and runtime context rather than copying credential material into generic application settings.

This capability describes the integrations with organization-owned configuration. It does not imply that every external provider supports every ownership mode. See the individual sign-on, provisioning and machine-access guides for their setup and operation contracts.

Framework producers call AuditLogsBackendService. The central writer assigns a stable eventId, resolves category and severity, adds available request context and persists the event through the audit repository. The same event identity is used by optional provider sinks.

The selected record construction in _createAuditLog shows the shared envelope:

Selected source from audit-logs.backend.service.ts:

const auditLogData = {
  ...auditEvent,
  eventId,
  ...(correlationId ? { correlationId } : {}),
  ...(frontendServiceName ? { frontendServiceName } : {}),
  ...(clientInstanceId ? { clientInstanceId } : {}),
  eventData: auditEvent.eventData as Record<string, any>,
  eventCategory: classification.category,
  severity: classification.severity,
  createdAt: new Date(),
  updatedAt: new Date()
};

Core events already have typed payloads, classifications and emitting callers. For application behavior, prefer the resource operation’s inherited event when it describes the change; add a purpose-built event when a distinct business fact needs its own payload and meaning.

Keep the subject distinct from the writer

An internal audit write is performed by the framework, but the row retains the person and organization the event concerns. The originating execution context supplies correlation and delivery authority; the temporary repository-write context must not replace the event’s subject.

Choose the additional destinations

The primary audit resource supplies immutable product operations: read and search are present, update and delete are absent. Customer security exports and an optional tamper-evident provider add separate destinations around that primary store.

Post-commit evidence failure does not turn a completed business change into a failed response. Audit failures have their own diagnostics and counters so operators can distinguish an evidence-pipeline problem from the operation that already succeeded. Infrastructure access to the database is a separate control; use the verified sink where independent integrity checks are needed.

HIGH and CRITICAL write variants meet the automatic audit floor. A lower-risk write can opt in with auditableEvent.auditBelowRiskFloor. Risk is an audit and interaction signal; roles and step-up authentication remain separate declarations.

The actual API-key creation variant combines its administrative gate, risk and one-time response contract:

Selected source from api-keys-organization.shared.resources-config.schemas.ts:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_ORG_ROLES.ORG_ADMIN], // Only org admins can create keys
riskLevel: ResourceOperationRiskLevel.HIGH,
// requestDto auto-derived from decorators
customResponseDto: ApiKeyOrganizationSchema.extend({
  plainKey: z.string().min(1).isEphemeral()
}),

This selected variant lives inside the API-key resource’s CREATE operation. When the resource service completes persistence, its post-commit lane calls emitResourceOperationAudit. Custom operations reach the same mechanism through their declared operation path.

Choose which values the trail retains

The shared API-key schema marks authority explicitly:

roles: z.array(RolesSchema).default([]).isAuditEvidence(),

The changedFields list identifies submitted field names, including a value submitted unchanged; it is not a before/after diff. Only marked evidence fields contribute retained values. Choose authority and lifecycle fields deliberately; marking an entire object can retain every nested value it contains.

Single-record changes have a before-image; bulk changes do not promise a per-row prior value. A created record has no prior state. A custom response that reshapes the result still uses the fetched subject as the identity fallback.

Read-shaped operations do not emit this generic performed event, regardless of risk. One-time response disclosure is a separate mechanism for backend-only fields returned at creation and ephemeral response fields. .isAuditEvidence() selects write-evidence values; ordinary business reads need an appropriate explicit audit event when their access must be recorded. A purpose-built business event may coexist with the generic operation event: one explains the business fact, the other preserves the operation, roles and execution context.

Keep authentication methods, password policy, MFA, session and step-up settings in the user-type configuration. The authentication-serving startup path calls emitApplicationAuthPolicyChangeIfChanged; ordinary restarts with the same recorded posture do not create a new change.

The decisive portion compares the normalized snapshot with the latest policy event:

Selected source from audit-logs.backend.service.ts:

const currentSnapshot = buildApplicationAuthPolicySnapshot(data.userTypes);
const currentDigest = computeApplicationAuthPolicySnapshotDigest(currentSnapshot);
const prior = await this._readMostRecentApplicationAuthPolicyEvent();

const effectiveAuditReadAccess = data.auditApplicationReadAccess ?? AuditApplicationReadAccess.ROLE_BASED;
const previousAuditReadAccess = prior?.auditApplicationReadAccess?.after ?? null;
if (prior && prior.snapshotDigest === currentDigest && previousAuditReadAccess === effectiveAuditReadAccess) {
  // Unchanged since the last recorded snapshot — the trail already reflects it. Emit nothing.
  return;
}

const before = prior?.after ?? null;
const changedUserTypes = diffChangedApplicationAuthPolicyUserTypes(before, currentSnapshot);

await this.logApplicationAuthPolicyChanged({
  changedUserTypes,
  snapshotDigest: currentDigest,
  before,
  after: currentSnapshot,
  auditApplicationReadAccess: { before: previousAuditReadAccess, after: effectiveAuditReadAccess },
});

This selected implementation segment is inside the startup reconciliation method. A first observation records a baseline with no prior posture. A changed snapshot records before, after and changedUserTypes; the trail itself supplies the previous state. auditApplicationReadAccess separately records the effective audit-reader policy. An older event without that field is treated as an unknown baseline; omitted and explicit role-based configuration are equivalent.

Attribute a deployment honestly

The event is system-attributed because no signed-in person changed it through the product. Connect it to deployment and source history when reviewing who authored and released the change. Background hosts that do not serve authentication do not independently report the same boot policy.

This contract covers the normalized authentication posture, not every setting in the application. A resource-managed security setting follows its own change event; adding a new authored policy dimension should include it in the snapshot and its meaningful comparison.

API-key creation uses an ephemeral field in its custom response:

Selected source from api-keys-organization.shared.resources-config.schemas.ts:

variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_ORG_ROLES.ORG_ADMIN], // Only org admins can create keys
riskLevel: ResourceOperationRiskLevel.HIGH,
// requestDto auto-derived from decorators
customResponseDto: ApiKeyOrganizationSchema.extend({
  plainKey: z.string().min(1).isEphemeral()
}),

The resource is registered with this response DTO, and the create handler adds plainKey only to that response. The controller’s shared disclosure helper examines the output schema and actual result before recording FIELD_ACCESS.

The two markers answer different questions. Backend-only handling takes precedence; an ephemeral response value should not also be declared as a stored backend-only field. Ordinary masked write-only credentials use a different display contract.

Put the marker at the returned field

The helper inspects the top-level output shape and handles returned records individually. Mark a one-time secret where that field is actually returned; do not assume a marker buried inside an arbitrary nested object becomes a disclosure event.

The same disclosure semantics are used by the HTTP and outbound-webhook boundaries. The event records field names, record identity and actor; the secret value is never an event payload. A receiver’s handling of the credential remains separate from proving that the application disclosed it.

A deletion handler receives utils.currentObject, the subject fetched before persistence. The deletion and configured cascade complete before the postfix emits the event. The snapshot supplies identity and descriptive fields that cannot be reread after removal.

The organization hook preserves the original operation result:

Selected source from organization-deletion-audit.custom-impl.backend.service.ts:

operationPath: {
  resourceIdentifier: CoreResourceType.ORGANIZATIONS,
  operationIdentifier: CoreResourceOperation.DELETE,
  variantType,
  isOperationDefault: variantKey === undefined,
  variantKey,
},
debugLabel: `organizations.delete${variantKey ? `.${variantKey}` : ''}.audit`,
handlers: {
  postfixCoreOperations: async (_id, result, executionContext, _operationPath, utils) => {
    await emitOrganizationDeletedAudit(container, _id, executionContext, utils);
    return result;
  },
},

This selected registration is inside createOrganizationDeletionAuditFactory. The factory is registered for both the internal scheduled-purge variant and the administrator API variant, so the same physical deletion fact is observed through either declared path.

Keep lifecycle facts distinct

A request for deletion marks the lifecycle transition and starts its configured window. A deletion event records the later physical removal. Restoring during the window is therefore not contradictory evidence: request, restore and completed destruction are different facts.

The organization-to-audit relationship excludes audit rows from parent deletion. Access to surviving evidence follows the audit viewing contract; it does not recreate the removed customer account. Apply the application’s evidence-retention and privacy decisions to those surviving records.

Post-commit recording errors are reported separately rather than telling the caller a completed deletion was rolled back. When adding a destructive application operation, preserve the pre-state needed for evidence and register its observation on every declared execution variant.

The authorization service observes refusals at its operation and subject gates. It records the operation identity, variant, required and held roles, attempted identifiers and denial reason. Internal application faults keep their own error handling.

A concealed record still produces useful evidence: the outward not-found response does not disclose whether the record exists, while the authorizer’s internal reason can identify a subject-resolution refusal.

Preserve the pattern without unbounded event volume

The source escalation rule is small because the behavior is precise:

Selected source from authorization-denial-audit.backend.utils.ts:

export function isDenialAuditEscalationMilestone(count: number): boolean {
  if (!Number.isInteger(count) || count < 1) return false;
  for (let rung = 1; rung <= count; rung *= 10) {
    if (rung === count) return true;
  }
  return false;
}

Within the configured window, counts 1, 10, 100 and later powers of ten emit observations. The bucket includes the available user identity, resource, operation, variant and reason; it deliberately excludes the target record ID. Userless calls use a shared fallback bucket.

When the counter is unavailable, the event can still be emitted with an inexact count. The receiver should use the count’s precision flag instead of interpreting every observation as an exact total.

Keep prevention and observation separate

The authorization decision denies access. This volume policy neither rate-limits the caller nor replaces endpoint authorization. Application extensions must reach the normal authorization boundary; an internal service call with deliberately borrowed authority is not an ordinary customer request.

Resource lifecycle emitters use resolveAuditActorId. They pass the originating execution context instead of inventing a user for background work. Explicit on-behalf-of attribution has priority, then a signed-in user, then a machine or system sentinel.

Selected source from audit-actor.backend.utils.ts:

export function resolveAuditActorId(executionContext: ExecutionContext<any> | undefined): string {
  const onBehalfOfUserId = executionContext?.auditActorUserId;
  if (typeof onBehalfOfUserId === 'string' && onBehalfOfUserId.length > 0) {
    return onBehalfOfUserId;
  }

  const initiatorIds = executionContext?.initiatorIds;

  const userId = initiatorIds?.userId;
  if (typeof userId === 'string' && userId.length > 0) {
    return userId;
  }

  if (initiatorIds?.machineCredential) {
    return AuditActorSentinel.MACHINE;
  }

  return isSystemInitiatedExecution(executionContext?.executionType)
    ? AuditActorSentinel.SYSTEM
    : AuditActorSentinel.UNATTRIBUTED;
}

The resolved value is a user ID or a named AuditActorSentinel. A machine sentinel describes the actor category; the execution context and machine-authentication events identify its credential. Do not query it as though it were a user ID.

Preserve the initiating person across internal work

The internal context’s auditActorUserId carries attribution without granting that person’s permissions to the service. The service still runs under its explicitly authorized execution context. Application extensions should preserve that separation when a user action starts background work.

An UNATTRIBUTED result remains distinguishable from routine system work. Monitoring policy decides how to investigate it; an empty identity should never silently become “the system did it.”

The HTTP boundary establishes request context. _createAuditLog prefers the explicitly supplied execution context’s correlation ID, then the ambient request frame:

const requestFrame = getRequestContextFrame();
const correlationId = requestExecutionContext?.correlationId ?? requestFrame?.correlationId;
const frontendServiceName = requestFrame?.frontendServiceName;

These exact source lines are selected from audit-logs.backend.service.ts. Available fields are added to the record and the export envelope. Internal jobs can carry their own correlation context; a request-only surface field need not exist for background activity.

Use the declared correlationId filter on audit list/search to collect related events. Preserve the execution context through custom service work rather than creating an unrelated context for each child action.

Choose browser correlation deliberately

The shared application configuration accepts this selected fragment:

compliance: {
  clientInstanceIdScope: ClientInstanceIdScope.SESSION,
},

ClientInstanceIdScope comes from the shared model vocabulary. DISABLED collects no installation identifier; SESSION uses session storage; PERSISTENT survives browser restarts and sign-outs. The request-ingestion boundary enforces the configured choice before the field reaches audit consumers.

Choose the mode according to the application’s privacy and investigation policy. Correlation is supporting evidence, not proof that two requests came from the same human, and it never supplies authorization.

AUDIT_EVENT_CLASSIFICATION_MAP covers the core event vocabulary. These two actual entries show why successful activity does not always carry the same severity:

[CoreAuditableEventType.USER_LOGIN]: { category: AuditEventCategory.AUTHENTICATION, severity: AuditEventSeverity.INFO },
[CoreAuditableEventType.USER_APP_ROLES_CHANGED]: { category: AuditEventCategory.AUTHORIZATION, severity: AuditEventSeverity.WARNING },

These are selected entries from security-audit-event-envelope.shared.schema.ts, not a complete map. The central audit writer and exported envelope resolve classification from the event type, keeping the interpretation consistent across destinations.

Tune review without changing what happened

Customer export configuration can choose categories, a minimum severity and specific event types. A delivery filter selects events; it does not reclassify them. Correlation and event-specific fields let analysts narrow a noisy pattern without discarding the meaning of each event.

When extending core events, provide the classification and typed payload alongside a wired producer. Application-specific event types use the classification resolver’s documented default when they have no core entry; do not assume adding a string alone gives it a particular severity.

The central writer preserves the organization an event is about. Its tenant-delivery decision instead takes verified membership destinations or the originating authenticated organization:

const ecOrg = requestExecutionContext?.initiatorIds?.organizationId;
const routeToOrgs: string[] = routingOrgIds ?? (ecOrg ? [ecOrg] : []);

These are exact lines from _createAuditLog in audit-logs.backend.service.ts. The following dispatch iterates that resolved set, reading each destination in its own organization context. An empty set creates no tenant delivery. A disagreement between event data and authenticated scope does not let the data win.

Apply the boundary at each viewing door

The organization audit resource adds the authenticated organization filter. Its bounded export constructs the same scope without a body override. The application audit resource shares persistence but has separate super-administrator access and records cross-tenant reads; it is not a customer shortcut into another organization’s trail.

A targeted event can be visible to the organization it concerns even when it did not originate from an authenticated customer session. Viewing evidence about a subject and sending it to a configured endpoint remain distinct operations.

Keep application evidence available

Events without a tenant delivery route remain part of the primary trail and can reach configured application-level ledger providers. A customer’s security export is therefore the selected tenant stream, not a promise that it contains every event the application records.

The organization route selects the customer scope. READ, LIST and structured SEARCH expose the declared filters; exportAuditLogs returns a bounded synchronous JSON result. The export body cannot choose a different organization.

Its actual request contract is:

Selected source from audit-logs.shared.resources-config.schemas.ts:

export const AuditLogs_ExportRequestDto = z.object({
  eventType: z.string().optional(),
  eventCategory: z.enum(AuditEventCategory).optional(),
  severity: z.enum(AuditEventSeverity).optional(),
  userId: z.string().optional(),
  createdAt: Resources_Filter_DateRangeSchema.optional(),
  // This is a bounded, synchronous API response, not an archive job. Keep its
  // ceiling aligned with the resource LIST operation so callers cannot request
  // a window that the repository will silently truncate.
  // Input stays optional and the backend applies 100 when omitted. Record the
  // default as metadata rather than a Zod output default, which would falsely
  // make the request field required in JSON Schema.
  maxRecords: z.number().int().min(1).max(100).optional().meta({ default: 100 }),
}).strict();

For example, submit { "severity": "warning", "maxRecords": 50 } to the generated collection export operation. The response contains records, format: "json" and totalCount. The default and ceiling are 100 records; larger requests are rejected. This is a selected result window, not an archive of all matching history.

Follow the appropriate viewing authority

Organization access is role-gated and confined to that organization’s records. Application-level audit viewing has its own super-administrator resource and admission requirements; it can include events without a selected organization and observes cross-tenant reads.

The same store supports those distinct doors. Keep scope selection in the authenticated operation, and use the generated reference for the exact deployed route rather than constructing an unscoped query against the collection. Repository-only creation is reserved for framework emitters; customer update and deletion are absent.

Separate viewing from exporting

These are the resource’s declared operation roles. They do not authorize choosing an arbitrary tenant or replacing the caller’s scope. Application-wide assurance review uses its separately admitted surface.

Enable the relevant runtime capability and customer entitlement, then connect the application’s authorized administration flow to AuthOrganizationConfigurationService.saveSiemExportConfig. It accepts the administrator’s execution context, AuthScopeType.ORGANIZATION, the organization ID and a configuration patch. The selected payload below uses the actual schema’s fields; its URL and credential are illustrative placeholders.

{
  "enabled": true,
  "webhookUrl": "https://security.customer.example/events",
  "authMethod": "bearer_token",
  "authCredential": "<collector credential>",
  "eventFormat": "json_structured",
  "eventFilter": {
    "categories": ["authorization"],
    "severityMinimum": "warning"
  }
}

The resource’s authCredential is write-only secret material: the standard interface returns a mask and preserves the existing value when that mask is submitted unchanged. To replace the collector credential, submit its new value through that authorized configuration flow and coordinate the change with the receiver.

The configuration service reads the scoped row, then invokes its internal update operation (or creates the row if absent). This is the service integration contract for an application settings screen, not a standalone public update endpoint on the configuration resource.

Understand what reaches the collector

The central audit writer resolves authenticated or explicitly verified tenant destinations. The dispatcher loads that organization’s configuration, checks enabled, applies category/severity/event-type filters and queues the selected envelope. Configuration-change hooks invalidate its cache so subsequent dispatch uses current settings.

Supported authentication choices are bearer token, a named API-key header, HMAC signing and none. The chosen wire format also determines the content type. Delivery attempts and recoverable failures have their own lifecycle.

Confirm setup with a real in-scope security action and a receipt at the customer collector. The tenant stream is distinct from the application’s complete primary history; an event without an authorized tenant destination does not get routed merely because its payload names an organization.

Set eventFormat on the organization’s SIEM configuration. Its shared vocabulary contains JSON_STRUCTURED, CEF, LEEF and OCSF; the stored values are json_structured, cef, leef and ocsf.

The delivery service selects the formatter from that configuration:

Selected source from siem-webhook-delivery.backend.service.ts:

private _formatBody(envelope: SecurityAuditEventEnvelope, eventFormat: string): string {
  switch (eventFormat) {
    case SIEMEventFormat.CEF:
      return this._formatAsCEF(envelope);
    case SIEMEventFormat.LEEF:
      return this._formatAsLEEF(envelope);
    case SIEMEventFormat.OCSF:
      // OCSF is JSON, so there is no escaping/bounding layer here — the projection returns a
      // document and the only transport concern is serialisation.
      return JSON.stringify(buildOcsfEvent(envelope));
    case SIEMEventFormat.JSON_STRUCTURED:
    default:
      return JSON.stringify(envelope);
  }
}

The excerpt is the actual formatting method. Text formats receive their text content type; JSON-native formats receive JSON. Transport authentication and retries operate around the formatted payload.

Map meaning, not just field names

CEF and LEEF projections account for every envelope field, with declared emitted keys and explicit omissions. Dictionaries supply recognized names and value constraints; the formatter handles escaping and bounded text. OCSF uses declared nested targets and derives class/activity identity from the event.

A format’s representation can differ even when the source fact is the same. Configure a receiver parser for the selected format and verify the resulting fields with an actual event. Adding a new envelope field requires a projection decision; it should not silently disappear into an unmaintained formatter.

The organization’s SIEM configuration contains delivery.retryAttempts, retryBackoffSeconds and timeoutSeconds. An illustrative selected configuration is:

delivery: {
  retryAttempts: 3,
  retryBackoffSeconds: 30,
  timeoutSeconds: 10,
},

The dispatcher builds and signs the delivery job; the worker checks its integrity before attempting the configured destination. The worker makes an initial attempt plus the configured retries: retryAttempts: 3 permits up to four HTTP attempts. Failed attempts use the configured backoff. The shared circuit-breaker contract pauses a destination after five consecutive failures for five minutes, protecting delivery capacity for other receivers.

Use the retained failure as the recovery unit

The dead-letter record retains the original event envelope, failure reason and attempt information. It does not freeze the formatted HTTP request. The persisted failure counter starts at one and the last-attempt timestamp records that retained failure; these are not a complete HTTP attempt history. The organization’s retrySingle operation accepts an entryId, loads the current scoped delivery configuration and queues the event before deleting the dead-letter entry. Replay therefore uses the current destination, format and authentication settings. retryAll performs the corresponding scoped sweep.

The implementation’s successful path is explicit:

await enqueueEnvelope(dispatcher, scope, siemConfig, envelope);
await deleteRequeuedRows(repo, executionContext, scope, [entryId], utils.logger);

These selected lines are from siem-delivery-dlq.custom-impl.backend.service.ts. A failed enqueue leaves the record available. Cleanup follows successful queueing; a later delivery failure creates its own retained failure record. Receivers should tolerate replay rather than treating the pipeline as exactly-once delivery.

The original business operation does not wait for the collector. Inspect delivery outcomes, not only the business response, when confirming a customer’s export is operating.

The shared auditTrail configuration declares archiveAfterDays. This illustrative fragment opts into copying events older than 90 days; keep it in the authored application configuration, not a generated environment file.

auditTrail: {
  archiveAfterDays: 90,
},

Configure a reachable file-storage provider and run the application’s batch scheduling path. The registered audit-logs-archive job checks the current horizon on each execution. With no horizon, it performs no archive work and leaves the primary trail intact.

Recover missed days without a separate checkpoint

The batch writes a deterministic artifact per UTC day. It rewrites recent archivable windows and probes older windows for missing artifacts, so retrying the same period does not create a second archive identity. Successful artifact presence is the progress record.

For a first archival run over existing history, the batch input supplies explicit overrides:

Selected source from audit-logs-archive.batch.backend.service.ts:

export const AuditLogsArchiveBatchInputSchema = z.object({
  /** One-shot archival horizon override (days). Falls back to app config. */
  archiveAfterDaysOverride: z.number().int().min(1).max(2555).optional(),
  /** One-shot look-back width override (days) — for cold-start backfills. */
  lookbackDaysOverride: z.number().int().min(1).max(MAX_LOOKBACK_DAYS).optional(),
  /**
   * One-shot width override (days) for the missing-artifact probe sweep that runs BEYOND the
   * look-back. `0` disables the sweep for this run (pure look-back behaviour).
   */
  backfillProbeDaysOverride: z.number().int().min(0).max(MAX_LOOKBACK_DAYS).optional(),
}).strict();

This is the AuditLogsArchiveBatchInputSchema; use its lookbackDaysOverride when dispatching a wider historical run. Inspect error, windowsArchived, recordsArchived and truncatedWindows in the batch result, then check the corresponding storage artifacts. A complete archive interval needs zero truncated windows and the expected dates; artifact presence alone does not prove that every record was copied. A bounded scheduled look-back is recovery for missed runs, not an unlimited historical scan.

Follow one run from input to artifact

This illustrative operator scenario keeps the configured 90-day horizon and scans just the most recent fully archivable UTC day. It disables the older missing-artifact sweep for this invocation.

The following is a backend invocation fragment, not a public endpoint. batchExecutor is the initialized BatchesCronjobsExecutor_BackendService with the engine archive batch registered. Run it only from trusted operator-controlled backend code: the executor creates the batch’s internal context, and this archive is application-wide.

const result = await batchExecutor.executeCustomBatch('audit-logs-archive', {
  lookbackDaysOverride: 1,
  backfillProbeDaysOverride: 0,
});

Ordinary scheduled execution uses the registered batch and its configured defaults. The direct executor call above returns the batch result; a scheduler’s accepted-publication response does not return or prove that result.

Suppose the invocation begins at noon UTC on September 12, 2026, and the selected day contains two eligible records. These are illustrative result values, not an observed production run:

{
  "tickAt": "2026-09-12T12:00:00.000Z",
  "enabled": true,
  "archiveAfterDays": 90,
  "horizonAt": "2026-06-14T12:00:00.000Z",
  "storageConfigured": true,
  "lookbackDays": 1,
  "backfillProbeDays": 0,
  "windowsBackfilled": 0,
  "windowsScanned": 1,
  "windowsArchived": 1,
  "recordsArchived": 2,
  "truncatedWindows": 0,
  "error": null,
  "durationMs": 25
}

The horizon’s own day is not fully eligible, so this run selects June 13. The logical destination is the application-scoped audit-archive folder with the deterministic filename audit-archive-2026-06-13.json; the configured provider determines the physical storage path. A repeated write uses that same daily identity.

The artifact carries the following metadata. This shortened illustration omits the records array, which contains the two audit records in the actual artifact:

{
  "schemaVersion": 1,
  "kind": "audit-log-archive",
  "applicationId": "example-application",
  "dayWindowUtc": "2026-06-13",
  "windowStart": "2026-06-13T00:00:00.000Z",
  "windowEnd": "2026-06-14T00:00:00.000Z",
  "archivedAt": "2026-09-12T12:00:00.000Z",
  "recordCount": 2,
  "truncated": false
}

Check the application, window, record count and truncation flag against the intended run. An unrelated increase in storage object count is not evidence that this archive was written correctly.

Interpret an outcome before retrying

The batch prefers configured Wildo-managed storage, then local-directory storage. A null error alone does not establish a write: disabled and unconfigured runs deliberately return non-error summaries. Failures during scanning or upload return the progress accumulated before the error rather than resetting it to zero.

Bound the historical interval deliberately

Only complete UTC days before the horizon’s day are selected. By default, each run rewrites the newest two eligible days and probes the preceding 90 days for missing artifacts. Existing probe-band artifacts are skipped; empty days intentionally produce no artifact.

The look-back and older probe span are capped together at 2,555 days. Increasing the look-back widens this horizon-relative interval; it is not an arbitrary start-date/end-date export API. A truncated artifact remains incomplete even when a later probe sees that its file exists. Review both coverage and truncation before treating an interval as complete.

Keep archive and retention decisions separate

The audit resource exposes no update or delete operation. Storage lifecycle, access to archived artifacts and the intended retention period remain operator decisions. This copy mechanism does not shrink the database or promise a backup of the rest of the application.

Choose the right audience for the artifact

The archive batch collects application-wide rows and explicitly bypasses contextual organization filtering. Its output is an operator artifact, not a customer-scoped download. For customer handover, use the bounded organization export and inspect its truncation result; do not hand over a raw application archive. Archival copies do not prune the primary rows.

Wonder Todos enables EngineCapability.COMPLIANCE_AUDIT_TRAIL and declares this provider in its backend provider scope:

Selected source from wildo.saas.config.ts:

immudb: {
  engineCapabilities: [EngineCapability.COMPLIANCE_AUDIT_TRAIL],
  providerCapabilities: ['COMPLIANCE_AUDIT_TRAIL'],
  protocols: [],
},

This is a selected provider entry from wildo.saas.config.ts. Provision the immudb backing service and signing material, synchronize provider/runtime configuration and start the responsible backend runtime. The composite sink resolves the declared provider; capability enablement alone is not a connection.

Preserve a stable verification basis

The verified client checks cryptographic proofs and maintains a durable anchor. Retain that anchor across restarts so verification can compare history over time. A proven integrity failure, an unusable verification configuration and degraded assurance have different diagnostics and should drive different operational responses.

Provider failure is isolated from the primary audit write and from other sinks. Monitor the destination’s state as well as the application’s health.

Reconcile using the primary trail

The scheduled reconciler replays events by eventId. Its cursor combines creation time with the event identity, so several events sharing a timestamp are not skipped. Repeated writes are idempotent at the sink.

This gives the operator a recovery path for missed inline deliveries while the authoritative records remain available. It is not a blanket guarantee that every direct database alteration is automatically discovered: use the ledger’s proofs, reconciliation outcomes and retained anchors together when checking a particular event or interval.

Provision the verifier separately from the server

These provider secret-contract entries feed stateDir, statePublicKeyPem and expectedServerUuid in the verified client. Supply them through the provider configuration channel; never put the server’s private signing key into the verifier. A local example path for the state directory is /application/.wildo-saas/local_data/immudb-verifier; a container must mount durable storage there.

Once the sink is configured, an application-side verification caller can inspect an individual event. Usage excerpt with the already-resolved sink and event identity:

const verification = await sink.verifyAuditEvent(eventId);
const { verified, status, detail } = verification;

The result distinguishes Verified, Absent, Tampered and Unverifiable. Inspect the status and diagnostic together: successful inclusion of one event does not prove that every expected event was delivered. Check durable-state and signature-pinning diagnostics as well; a successful read with those protections absent establishes less than a pinned, continuous history.

This actual Wonder CRM contact schema shows category and erasure declarations on two fields. They answer different questions: what the value contains and what an erasure does to it. The source comment explains why the retained contact keeps a replacement name:

Source: contact.schemas.ts (selected excerpt).

  companyId: z.string().min(1).optional().isDBIndexed().isForeignKey().isSummaryField()
    .impersonalizeWith(RedactionType.REMOVE)
    .dataCategories(PersonalDataCategory.PROFESSIONAL),
  /*
   * A contact's NAME is the personal data this resource exists to hold, and it is scrubbed on
   * erasure rather than removed: the row is retained (see `retentionPolicy` on the config), and a
   * retained row whose name is null reads as corrupt where a masked one reads as erased.
   */
  name: z.string().min(1).max(120).isSummaryField()
    .impersonalizeWith(RedactionType.MASK, { maskValue: '[erased]' })
    .dataCategories(PersonalDataCategory.IDENTITY),

PersonalDataCategory is the named vocabulary for identity, contact details, credentials, financial data, usage and the other supported categories. Declare the specific category rather than a general sensitivity level. The factory validates declared members. There is no resource-wide category default because one row can contain several kinds of information.

The inventory derives from declarations, not identifiers such as email. Credential decorators provide their own category signal. Introspection reports fields that already have a privacy declaration but lack a category, and distinguishes those omissions from resources whose personal-data question is unanswered.

These declarations feed the compliance facts consumed by application documentation work. They do not discover personal data hidden in arbitrary free text or verify the lawfulness of collecting it. Review actual fields and purposes, then keep that decision close to the schema as the application evolves.

ConsentPurpose names the purposes. Each person stores the set they granted and the instant they decided. The set is audit evidence, so every change is recorded with its previous and resulting value.

Source: privacy.shared.schemas.ts (selected excerpt).

const consentedPurposesField = (subject: string) => z.array(z.enum(ConsentPurpose)).default([])
  .describe(
    `The optional purposes ${subject} has granted, each independently. A set, not a level: granting one purpose implies nothing about another. Empty means nothing optional was granted.`,
  );

const consentDecidedAtField = (subject: string) => z.date().optional()

The decision instant is written by the server when the set changes, never taken from the caller, so a decision cannot be backdated. Use the preference resource operations — the application’s consent gate already does — so the audit emission records both values. Reset returns the set to empty and clears the instant: a withdrawal of everything, after which the person is asked again.

An application that must not be used without a purpose declares it once, as operatorComplianceIdentity.serviceConsentRequirement.requiredPurposes in wildo.saas.config.ts. wildo config service-consent carries it into the runtime: the backend refuses everything that person initiates — API and MCP operations, queued work, live-update subscriptions, agent tools, conversations and their results, charts and analytics — except their own profile and preferences, where they record the consent, and cancelling work they already started. Updates the server pushes on its own are not held back. Every signed-in page is withheld until they grant it. Signing in and out stay open, so the decision is always reachable. An empty set states that nothing is gated.

Use the inherited analytics consumer

Wildo’s mounted AnalyticsContextProvider starts the configured analytics providers only while the person has granted ANALYTICS, unless the application declares analytics.requiresConsent: false.

Selected source from AnalyticsContext.tsx, inside its configuration-and-consent effect:

const hasConsent = analyticsConfig.requiresConsent === false
  || hasGrantedConsentPurposes(grantedPurposes, [ConsentPurpose.ANALYTICS]);

if (!hasConsent) {
  providersRef.current.forEach(p => p.reset());
  setIsActive(false);
  return;
}

On the marketing website the same rule is enforced where provider code starts: a provider whose capability rests on consent — product analytics — is neither loaded nor scripted until the visitor grants its purpose, and is stopped when they withdraw. Error monitoring and captcha start regardless, because they protect a service the visitor asked for. It does not recall events already sent. Other processing consumers still need their own declared purpose and enforcement.

The authorization endpoint validates and stores the request in a single-use consent token. The frontend sends the decision using that token. This actual component callback shows approval, denial and the optional remembered-grant choice:

Source: Auth_OAuthConsent.tsx (selected excerpt).

  const decide = useCallback(
    async (decision: 'approve' | 'deny') => {
      if (!consent || submittingRef.current) return;
      submittingRef.current = true;
      setStatus('submitting');
      setErrorLabel(null);
      try {
        const { redirect_to } = await getManualCallsHttpClient().oauthConsentDecision(
          consent.consent_token,
          decision,
          // Only an APPROVE meaningfully "remembers"; a deny sends `false` harmlessly.
          decision === 'approve' && remember,
        );
        // Complete the OAuth redirect back to the third-party client (carries `code` or the error).
        window.location.assign(redirect_to);
      } catch {
        // Release the local latch. A lost response may follow server-side token consumption;
        // the error view does not retry this request token. A fresh flow obtains fresh state.
        submittingRef.current = false;
        setStatus('error');
        setErrorLabel(UserOAuthConsentLabel.ERROR_DECISION);
      }
    },
    [consent, remember],
  );

The user must be authenticated before the consent request is shown. The token binds the validated client, redirect, scopes and related request state on the server; the UI does not get to rewrite those values when deciding. A submission latch protects against duplicate decisions.

The screen displays the client, scopes and resource endpoint where present, and resolves through a replaceable public-layout preset for branding. Preserve those meaning-bearing disclosures in a custom preset. A metadata-declared client always requires consent; a registered consent-free client cannot use that setting to skip another organisation’s trust boundary.

Remembered approval is opt-in and is evaluated against the relevant grant context on later requests. Revocation belongs to the grant lifecycle. This is delegated-access authorization, distinct from general data-processing preferences or acceptance of a privacy notice.

The backend SystemAccessService.exportSubjectAsSystem takes explicit subject IDs and a SubjectExportPurpose. Use it from the application’s verified request workflow; receiving, authorizing and delivering the request remain application responsibilities.

Every participating resource needs an explicit systemAccessPolicy.exportSubject decision. The subject also needs system READ. The following actual Wonder Todos declaration makes draft notes exportable and gives their fields a default provenance; surrounding operation declarations are omitted:

Source: draft-notes.resources-config.ts (selected excerpt).

    resourceIdentifier: TasksManager_ResourceType.DRAFT_NOTES,
    resourceFieldIdentifier: TasksManager_ResourceFieldIdentifier[TasksManager_ResourceType.DRAFT_NOTES],
    resourceRelationships: resourcesRelationships,
    isSystemResource: false,
    isAnonymizable: true,
    transpositionPolicy: ResourceTranspositionPolicy.ADD,
    // assurance-control: WILDO.PRIVACY.SUBJECT_DATA_EXPORT — authenticated draft notes are subject-owned data and must be available to the fail-closed export sweep.
    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.SUBJECT_PROVIDED },

Call exportSubjectAsSystem(resourceType, subjectIds, purpose, options) with ACCESS_ART_15 or PORTABILITY_ART_20. Supply the appropriate scopeContext where the resource is scoped. The result separates slices, which contain personal data, from report, which describes the selection. Keep the values out of ordinary logs.

Before collecting rows, the orchestrator checks participating-resource declarations and, for portability, field provenance. An absent export decision refuses collection rather than silently omitting that resource. An explicit FORBIDDEN child is excluded with an explanation; forbidding the subject itself refuses the bundle. Backend-only and write-only fields are withheld and named in the report.

The internal scan supports resources without a public LIST operation while still applying retention hiding. Export is not the retained-data review door: an already-erased hidden row stays hidden. Review the report before delivery and implement any controller-reviewed disclosure outside this automated selection deliberately.

Select relationships before selecting fields

The orchestrator examines the subject’s declared neighboring relationships, using the original subject IDs. This is not an unrestricted recursive walk through everything reachable from a record.

For example, a dependent note and an independently owned record referring to its author have different selection contracts even if both contain the same user ID. Relationship semantics decide the edge; resource permission and field provenance then decide what may be disclosed.

The actual Wonder Todos user-to-draft-note declaration demonstrates the owned case. Selected source from tasks-manager.relationships.ts, with comments omitted:

createResourcesRelationship(
  CoreResourceType.USERS, TasksManager_ResourceType.DRAFT_NOTES,
  ResourceRelationshipCardinality.ONE, ResourceRelationshipCardinality.MANY,
  {
    nature: RelationshipNature.COMPOSITION,
    isPrimaryScope: true,
    foreignKeyField: 'userId',
    parentResourceRequirement: ResourceParentResourceRequirement.OPTIONAL,
    accessScopeStrategy: ResourceRelationshipAccessScopeStrategy.REQUIRES_CONTEXT,
    childOperations: { lifecycle: { onParentDelete: { enabled: true, mode: ChildLifecycleMode.IMMEDIATE } } },
    contextPolicy: {},
  }
),

COMPOSITION resolves to dependent ownership. Export includes that edge before its resource/field policies; the parent-delete declaration separately governs erasure and does not determine portability field provenance.

Usage excerpt inside the application’s verified request handler, with its resolved service, subject type, IDs and scope:

const bundle = await systemAccessService.exportSubjectAsSystem(
  subjectResourceType,
  verifiedSubjectIds,
  SubjectExportPurpose.ACCESS_ART_15,
  { scopeContext },
);

const selectionReport = bundle.report;
const personalDataSlices = bundle.slices;

Inspect the report’s exclusions before protected delivery of the slices. An empty slice alone does not explain whether there were no matching rows, an excluded relationship or a withheld field. Do not write personal-data slices to application logs.

Use portabilityPolicy.defaultProvenance on a resource and .portabilityProvenance(...) on fields that differ. This is independent of personal-data categories and erasure treatments. The actual draft-note configuration supplies a resource-wide default:

Source: draft-notes.resources-config.ts (selected excerpt).

    resourceIdentifier: TasksManager_ResourceType.DRAFT_NOTES,
    resourceFieldIdentifier: TasksManager_ResourceFieldIdentifier[TasksManager_ResourceType.DRAFT_NOTES],
    resourceRelationships: resourcesRelationships,
    isSystemResource: false,
    isAnonymizable: true,
    transpositionPolicy: ResourceTranspositionPolicy.ADD,
    // assurance-control: WILDO.PRIVACY.SUBJECT_DATA_EXPORT — authenticated draft notes are subject-owned data and must be available to the fail-closed export sweep.
    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.SUBJECT_PROVIDED },

SUBJECT_PROVIDED covers input the person supplied. OBSERVED covers information generated by their use of the service. DERIVED covers the application’s conclusions, scores and assigned classifications. Do not classify all non-typed values as derived: observed usage has its own meaning.

The field declaration overrides the resource default. In the portability selection, provided and observed values are eligible while derived values are excluded and reported. Access selection is broader, subject to the separate non-disclosable-field rules.

An unresolved provenance refuses portability collection instead of silently dropping a field. Choose a default only when it accurately describes the resource, then inspect exceptions such as computed status fields. Your application still decides which request applies and reviews delivery; the declaration is a selection contract, not a determination of legal entitlement.

Override only the fields with a different origin

Illustrative field declaration using the existing decorator; the surrounding resource uses the SUBJECT_PROVIDED default above:

const preferenceFields = z.object({
  preference: z.string(),
  calculatedScore: z.number()
    .portabilityProvenance(DataPortabilityProvenance.DERIVED),
});

The preference inherits the resource default. The calculated score overrides it and is excluded from portability selection, with that selection reported. Access selection remains distinct. This field decision applies only after the relationship has admitted the row; it does not pull unrelated records into the bundle.

RETAIN_AND_IMPERSONALIZE keeps, hides and freezes a row while scrubbing declared fields. RETAIN_ONLY is for rows with no personal field values to scrub. The actual USERS configuration combines the retained-row decision with the separate session-principal decision:

Source: users.shared.resources-config.schemas.ts (selected declarations; intervening comments omitted).

  retentionPolicy: {
    mode: ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE,
  },
  dataSubjectPolicy: { kind: ResourceDataSubjectKind.SELF_PRINCIPAL },

Fields declare .impersonalizeWith(...): REMOVE clears a clearable field, MASK writes a schema-valid replacement, and RESET restores a supported static default. The factory rejects contradictions such as treatments on RETAIN_ONLY or a scrubbing mode without any effective scrub. A retained row is not an anonymous row, nor proof that re-identification is impossible.

Invoke SystemAccessService.eraseSubjectAsSystem(resourceType, explicitIds, options) through your application’s request workflow. It classifies dependent edges and refuses unclassified destructive decisions before writing. Dependents are handled before the subject, making a retry possible when work cannot finish. IMPERSONALIZE_AND_RETAIN on a relationship is an edge decision; immediate versus lazy execution is a separate timing choice.

Inspect subjectImpersonalized, each edge’s disposition and executed, and external effect outcomes before recording completion. An executed empty edge means there was nothing to remove; a declined destructive edge requires follow-up. Administrative continuity acknowledgements are explicit per-request controller decisions, not defaults to switch on.

Adding retention changes the persisted schema and uniqueness treatment. Register the resource coherently and apply the corresponding database migration. The operator decides why a record is retained and for how long; erasure retention does not itself set an expiry schedule.

Give each personal field a concrete treatment

Illustrative schema fragment using the existing field decorators, paired with RETAIN_AND_IMPERSONALIZE:

const contactFields = z.object({
  name: z.string().impersonalizeWith(RedactionType.MASK, { maskValue: 'Erased contact' }),
  personalNote: z.string().nullish().impersonalizeWith(RedactionType.REMOVE),
});

The replacement must satisfy the field schema; REMOVE writes null, so the receiving field must accept null. These treatments scrub the personal values while the retention policy keeps the row out of ordinary use. The contact’s separate data-subject policy must also state whether it represents an account.

Usage excerpt after the application has verified the request and resolved its service and scope:

const receipt = await systemAccessService.eraseSubjectAsSystem(
  subjectResourceType,
  verifiedSubjectIds,
  { scopeContext },
);

const unresolvedExternalEffects = receipt.externalEffects.filter(effect =>
  isIncompleteSubjectErasureExternalEffect(effect.status),
);

The selector comes from @wildo-ai/saas-models. It includes partial, failed, unregistered and acknowledged-non-erasure outcomes. Controller acknowledgement does not make retained third-party data disappear. Inspect these outcomes alongside subjectImpersonalized, edge execution and session resolution before closing the request; do not turn successful local return into an unconditional completion status.

dataSubjectPolicy answers whose sessions should end. It does not answer whether the record contains personal data. The actual user configuration names the row itself as the principal:

Source: users.shared.resources-config.schemas.ts (selected declarations; intervening comments omitted).

  retentionPolicy: {
    mode: ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE,
  },
  dataSubjectPolicy: { kind: ResourceDataSubjectKind.SELF_PRINCIPAL },

Use SELF_PRINCIPAL when the row ID is the user ID; LINKED_PRINCIPAL when a declared sessionPrincipalField identifies the account; and NO_PRINCIPAL when no login belongs to this subject. A contact or lead can be a person while correctly having NO_PRINCIPAL. A creator or owner foreign key alone is not a session declaration.

The common scrub path resolves principals before values are changed and schedules revocation after commit. This covers orchestrated erasure, direct impersonalization and an impersonalizing parent cascade. Startup supplies the token issuer’s invalidation function through SubjectSessionRevocationBackendService; custom bootstrap code must preserve that registration.

Revocation is post-commit work. A failure cannot restore already-scrubbed data and is logged as an access problem requiring operational follow-up. Treat a local erasure receipt and confirmed session termination as related outcomes, not interchangeable evidence. Monitor the revocation errors and verify an old session is refused in the application’s end-to-end erasure checks.

Choose an account linkage explicitly

Alternative resource-policy fragments, not three simultaneous declarations:

// A subject row that represents a separate account:
dataSubjectPolicy: {
  kind: ResourceDataSubjectKind.LINKED_PRINCIPAL,
  sessionPrincipalField: 'accountId',
},
// A contact with no sign-in account instead uses:
// dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },

For the linked variant, accountId must be the declared field identifying the USERS row, with the resource configuration satisfying its linkage checks. sessionPrincipalField is forbidden for SELF_PRINCIPAL and NO_PRINCIPAL. Never substitute the creator’s ID just because it is available.

The current erasure report includes sessionRevocation.principalUserIds and lookupFailed. An empty principal list with a successful lookup can legitimately mean no account; a failed lookup is a different outcome requiring attention. Keep that receipt alongside operational revocation errors and an end-to-end check that an old session is refused.

For a resource configured with ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE, field declarations decide which attachments the scrub removes. This illustrative schema fragment keeps a required business document while removing a personal identity attachment:

import { z } from 'zod';
import { z_file } from '@wildo-ai/zod-decorators';
import { RedactionType } from '@wildo-ai/saas-models';

const attachmentFields = z.object({
  idDocument: z_file({ allowedMimeTypes: ['application/pdf'] })
    .nullish().impersonalizeWith(RedactionType.REMOVE),

  invoicePdf: z_file({ allowedMimeTypes: ['application/pdf'] })
    .nullish().impersonalizeWith(RedactionType.KEEP),
});

The fields belong in the resource’s schema; the resource’s retention policy and subject-erasure wiring select when this treatment runs. The fragment does not start erasure by itself. REMOVE writes null, so the personal attachment field must accept a cleared value.

For these declarations, buildImpersonalizeScrubPatch(attachmentFields) produces { idDocument: null }. The handler receives that field name and follows the existing file links before their attachment lifecycle is completed.

Keeping the invoice is an application decision about that document’s contents and retention purpose. KEEP does not redact personal information inside a PDF. Nor does hiding the retained parent automatically block every file route: resource-scoped serving checks the parent, while global file serving checks the file’s own access scope.

Withdraw the file and scrub its own identifying values

processFileFieldsForImpersonalize invokes the privacy-specific eraseFile path for the scrubbed fields. This actual repository update shows why ordinary lifecycle deletion is not equivalent:

Source: files.backend.service.ts (selected excerpt).

    const erasedFile = await this.filesRepository.update<File>(
      internalContext,
      { _id: fileId },
      {
        status: FileStatus.DELETED,
        deletedAt: new Date(),
        updatedAt: new Date(),
        filename: ERASED_FILE_NAME_PLACEHOLDER,
        originalFilename: ERASED_FILE_NAME_PLACEHOLDER,
        uploadedBy: undefined,
        uploadedByEntityType: undefined,
      } as Partial<File>,
      options
    );

eraseFile marks DELETED and removes the file row’s filename/uploader attribution. Serving checks the downloadable status set; storage cleanup handles physical bytes through the normal cleanup lifecycle. Do not describe the soft-delete write as immediate destruction of every stored copy.

An untreated or KEEP field is not erased by this scrub path. That allows an intentionally preserved artifact to remain usable; it also means the application must classify personal file fields carefully. When at least one field is being scrubbed, a linked file without a usable linkedFieldName is also erased and a warning is logged. With no scrubbed fields, this handler returns without querying files.

Owner context is derived from the authoritative resource/file during internal cascade work, while normal requests retain their own authorization checks. Direct file erasure also removes associated extracted RAG content through the file-binding removal seam. Physical cleanup follows the configured soft-delete retention period (30 days by default). For remote references such as Google Drive, this does not promise deletion of the external original. Storage-provider deletion and backup retention remain separate from the file-row scrub.

An external effect declares a stable effectRef, an appliesTo(subjectResourceType) predicate and an async run(context) returning an outcome. Register it with SubjectErasureExternalEffectsRegistryBackendService during backend setup. Billing demonstrates the contract: the effect declares exactly which subject resources it owns before its run method does any provider work.

Source: billing-subject-erasure-effect.backend.ts, effect opening; the remaining provider work is omitted.

export function createBillingSubjectErasureEffect(
  dependencies: BillingSubjectErasureDependencies,
): SubjectErasureExternalEffect {
  return {
    effectRef: BILLING_SUBJECT_ERASURE_EFFECT_REF,

    // USERS and USER_SELF share the same user subject; organisation teardown is separate.
    appliesTo(subjectResourceType: ResourceType): boolean {
      return subjectResourceType === CoreResourceType.USERS
        || subjectResourceType === CoreResourceType.USER_SELF;
    },

The shortened comment above summarizes the source comment. Backend startup registers this effect through SAAS_SERVICE_TYPES.SubjectErasureExternalEffectsService when billing is configured. A custom integration supplies its own stable reference, subject predicate and implementation. Re-registering the same reference replaces it rather than appending another effect. The run context contains subject IDs and scope, not the personal fields already scrubbed; resolve provider identifiers from the integration’s own records.

Effects execute sequentially after the local commit. They cannot roll back a remote API call or the completed local erasure. Return step-level outcomes that let the operator distinguish completed work, nothing to erase, partial work and failure. The runner retries clean FAILED outcomes or thrown failures within a bound; it does not automatically replay a reported PARTIAL. Return provider failures as structured outcomes with per-step detail. Throwing loses that detail and can trigger a retry, so external actions must tolerate replay; do not rely on an exception to roll back work already accepted by a provider.

Inspect report.externalEffects with selectIncompleteExternalEffects rather than inventing a status comparison. Persist the outcome needed for follow-up without copying erased personal values into operational logs.

HTTP_API-backed resources declare their own erasure stance and subject link. A declared external erasure operation removes the matching remote rows through the adapter. An acknowledged non-erasure is a per-request controller decision recorded as incomplete, not proof of removal. Integrations that store personal information must register their own responsibility; the registry cannot discover every third-party copy.

Backend startup registers the billing effect when the relevant billing services are available. It resolves billing accounts for the subject and delegates through the configured billing provider. This actual effect fragment shows the ordered actions and the complete-result boundary:

Source: billing-subject-erasure-effect.backend.ts (selected excerpt).

        await cancelSubscriptions(provider, dependencies, variants, account._id, steps);
        await anonymizeCustomer(provider, providerCustomerId, steps);
        await detachPaymentMethods(provider, providerCustomerId, steps);
      }

      const failed = steps.filter((step) => !step.succeeded);
      if (failed.length === 0) {
        return {
          effectRef: BILLING_SUBJECT_ERASURE_EFFECT_REF,
          status: SubjectErasureExternalEffectStatus.COMPLETED,
          detail:
            `Provider-side erasure completed for ${accounts.length} billing account(s): subscriptions cancelled, `
            + `customer anonymized, payment methods detached. The customer record was KEPT (anonymized) so the `
            + `retained invoices remain attributable.`,
          steps,
        };
      }

The effect never calls deleteCustomer. Retaining the provider customer keeps invoice attribution intact; the provider implementation scrubs the supported personal customer fields instead. An absent billing account produces NOTHING_TO_ERASE. An unsynced local account contributes a successful skip-unsynced-billing-account step; the overall result still reflects the other accounts and steps.

The effect applies to USERS and USER_SELF and checks that user billing is registered before reading accounts. It selects the user-scoped billing variant; an employee account is not a reason to cancel an organisation’s shared subscription. Application builders should verify their billing subject ownership before extending the effect.

Each action records its own outcome. A failed provider step produces a partial receipt after local erasure, with details for provider-side follow-up. Verify provider state independently when completing the operational request. Financial retention purposes and periods are operator decisions; this mechanism preserves the relationship needed to implement them.

Opting a resource into retentionPolicy gives it a retention marker. Repository filtering and aggregation consume one predicate authority. This actual operation set limits which read operations may suppress hiding; carrying the flag into a write does not unlock the row:

Source: retention-hide-predicate.backend.ts (selected excerpt).

export const RETENTION_SEE_THROUGH_SUPPRESSIBLE_CORE_OPERATIONS: readonly CoreResourceOperation[] = [
  CoreResourceOperation.READ,
  CoreResourceOperation.LIST,
  CoreResourceOperation.SEARCH,
  CoreResourceOperation.COUNT,
];

Ordinary resource operations inherit the predicate. The MongoDB representation uses a negative comparison that includes records whose marker is missing; PostgreSQL compiles the same meaning with NULL-inclusive semantics. This matters when introducing retention to existing records: unmarked active rows must not disappear.

Use the framework repositories and chart/query mechanisms. A custom raw database read is a separate disclosure surface and must consume the canonical predicate; authoring a similar-looking condition creates a second policy that can drift. The repository guards and check-retention-hide-reach check cover the framework’s known alternate paths.

Treat the marker as lifecycle state, not a UI filter. Hiding a table row in the browser leaves direct requests and aggregates unaffected. For a justified retained-data inspection, use readRetainedAsSystem or its list sibling with human attribution; the exception remains read-only and scoped.

The application must authenticate the reviewer and derive their roles from trusted authorization state. Never accept the following attribution fields as unchecked browser claims. This actual method connects the entry gates, scoped read and audit-before-return sequence:

Source: system-access.backend.service.ts (selected excerpt).

  public async readRetainedAsSystem<T = any>(
    resourceType: ResourceType,
    id_or_ids_or_filter: IdOrIdsOrFilterType,
    auth: { accessingUserId: string; accessingUserRoles: string[]; reason: string },
    options?: ServiceOptions & {
      scopeContext?: { organizationId?: string; applicationId?: string; userId?: string };
    },
  ): Promise<T | null> {
    this.assertSeeRetainedAllowed(resourceType);
    this.assertSeeThroughRole(auth.accessingUserRoles);
    this.assertSeeThroughAttribution(auth.accessingUserId, auth.reason);

    const operationPath: ResourceConfiguration_OperationPath<any, any> = options?.variantKey
      ? this.resourcesRegistry.getServiceOperationPath(resourceType, CoreResourceOperation.READ, options.variantKey)
      : this.resourcesRegistry.getServiceOperationPathDefault(resourceType, CoreResourceOperation.READ);

    const systemContext = await this.executionContextCreator.createForInternalOperation({
      operation: operationPath,
      contextResourcesFieldIdentifier: this.buildSystemScopeContextMap(options?.scopeContext),
      initiatorIds: this.buildSystemInitiatorIds(options?.scopeContext),
      initiatorRoles: [
        {
          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
          relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
        },
      ],
    });
    // M5b: reveal retained rows for THIS read only (suppresses ONLY the retention predicate, not scope).
    systemContext.setSeeRetainedData(true);

    const result = await this.getServicesRegistryHandler().read<T>(resourceType, systemContext, id_or_ids_or_filter, options);

    // M6: HUMAN-attributed, reason-bearing, and ACCOUNTABLE — an unrecordable reveal is refused.
    await this.emitRetainedDataRevealAudit({
      accessingUserId: auth.accessingUserId,
      roles: auth.accessingUserRoles,
      reason: auth.reason,
      resourceType: resourceType as string,
      operationIdentifier: 'readRetainedAsSystem',
      retainedRecordCount: result == null ? 0 : 1,
      organizationId: options?.scopeContext?.organizationId,
    });

    return result;
  }

The resource must allow retained-data access. readRetainedAsSystem accepts an ID, IDs or a filter; listRetainedAsSystem handles collection review. Supply scopeContext where required. The implementation suppresses only the retention filter for the read, not tenant isolation.

After reading, it emits RETAINED_DATA_ACCESS with the human ID, roles, reason and result count before returning the result. Audit failure refuses the reveal. This is stronger than logging a warning after handing over the data.

The exception does not provide an update door and does not make retained records visible to subject exports. Design the application’s review screen and request approval around this backend primitive, and keep investigation reasons useful without copying the sensitive record into the reason.

Authorize the caller before creating the internal context

For a HUMAN caller, this service checks auth.accessingUserRoles for CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN. A custom auditor role alone does not satisfy that guard. The role in the internal execution-context example is the authority used after admission; supplying such an internal context is not a substitute for authorizing the human request.

The resource must separately allow retained review. Preserve subject attribution and scope, and await the access audit before returning retained values. These controls make the exceptional read accountable without reopening ordinary list or read paths.

The actual job payload schema uses an absolute deadline. expireAfterSeconds: 0 means the field itself is the expiry instant; a positive value measures a window from that field:

Source: jobs.shared.schemas.ts (selected excerpt).

  // === Lifecycle ===
  /** When the payload was stored */
  createdAt: z.date().isDBIndexed(),
  /**
   * When the payload expires and can be cleaned up.
   * MongoDB TTL index will automatically delete documents at this time.
   */
  expiresAt: z.date().ttl({ expireAfterSeconds: 0 }),

MongoDB can enforce the TTL index. The shared retention sweep consumes the same .ttl() declaration and supports stores that do not remove rows natively. For an application resource, register a resource-anchored sweep manifest and its batch; a date annotation alone is not a scheduled PostgreSQL worker. Existing engine payload/execution sweeps are registered at startup.

collectResourceRetentionPolicies reads the declaration and resolveRetentionCutoff calculates the due boundary. The batch deletes bounded groups and reports when a run reaches its ceiling. Its schedule and backlog determine the actual cleanup time, so expiry is not a promise of deletion at the exact timestamp.

This is row expiry, not erasure retention’s keep/hide/freeze behavior and not a written retention-policy document. Choose a time field whose meaning matches the commitment, keep the worker operational and verify the stored result. File objects, backups and external services have their own retention paths; a row TTL does not remove every copy of its contents.

Build the authority snapshot from the application

createAssuranceProgramValidationAuthorities accepts the basis, enabled capabilities, application roles and host artifacts. This source excerpt shows the availability decision; omitted snapshot fields carry the same basis’s implementation and evidence expectations.

export function createAssuranceProgramValidationAuthorities(input: {
  readonly basis: unknown;
  readonly hostFacts: AssuranceProgramAuthorityHostFacts;
  readonly evaluatedAt: string;
}): AssuranceProgramValidationAuthorities {
  const basis = assertAssuranceProgramAuthorityBasisIsCoherent(input.basis);
  for (const artifact of input.hostFacts.hostImplementationArtifacts) {
    AssuranceProgramHostImplementationArtifactSchema.parse(artifact);
  }
  const enabledCapabilities = new Set(input.hostFacts.enabledEngineCapabilities);
  const snapshot = AssuranceProgramValidationAuthoritySnapshotSchema.parse({
    schemaVersion: 1,
    snapshotRef: basis.basisRef,
    snapshotVersion: basis.basisVersion,
    evaluatedAt: input.evaluatedAt,
    requestedSourceUses: basis.requestedSourceUses,
    sourceRegistry: basis.sourceRegistry,
    documentAuthorityCatalog: basis.documentAuthorityCatalog,
    objectiveCatalog: basis.objectiveCatalog,
    applicationRoleRefs: [...new Set(input.hostFacts.applicationRoleRefs)].sort(compareCanonicalText),
    capabilityAuthorities: basis.capabilityAuthorityDescriptors
      .filter(({ availability }) => isAssuranceCapabilityAvailable(availability, enabledCapabilities))
      .map(({ authority }) => authority),
    implementationArtifacts: basis.implementationRevision.artifacts,
    hostImplementationArtifacts: [...input.hostFacts.hostImplementationArtifacts].sort(
      (left, right) => compareCanonicalText(left.artifactKindRef, right.artifactKindRef) || compareCanonicalText(left.artifactRef, right.artifactRef),
    ),
    sourceRequirementAuthorities: basis.sourceRequirementAuthorities,
    implementationExpectationAuthorities: basis.implementationExpectationAuthorities,
    evidenceExpectationAuthorities: basis.evidenceExpectationAuthorities,
    verificationExpectationAuthorities: basis.verificationExpectationAuthorities,
  });
  return Object.freeze({ snapshot });
}

The application’s capability selections constrain which framework contributions it can claim. Host artifacts supply application-owned evidence contracts. A basis version identifies the interpretation of those commitments, so a programme can be reviewed against a specific framework generation.

Keep proof stages distinct

The programme uses an explicit ladder:

export enum AssuranceProgramProofStage {
  SELECTED = "SELECTED",
  CONFIGURED = "CONFIGURED",
  OPERATING = "OPERATING",
  EVIDENCED = "EVIDENCED",
  ASSESSED = "ASSESSED",
}

requiredProofStage expresses the programme’s target. It is not an observation that the target was reached. A configuration can establish CONFIGURED; an execution must substantiate operation; evidence must support the claimed period and scope. External assessment has its own authority.

Review the complete obligation

For each objective, read the bound capability references, implementation expectation, evidence requirement body and verification expectation together. A security event can prove an action occurred without proving that a periodic review occurred. Application owners provide the latter contract where it belongs. The intended assurance workflow can collect and evaluate these distinct records without flattening them into a single “compliant” flag.

Start with the named objective

The real privileged-access implementation identifies its objective in the source. Its result deliberately separates application administrators, customer owners and customers that could not be inspected. Selected declarations from privileged-access-review.backend.utils.ts:

// assurance-control: WILDO.ACCESS.PRIVILEGED_REVIEW

export interface PrivilegedAccessPopulation {
  readonly observedAt: string;
  readonly applicationScopeConferringRoles: readonly string[];
  readonly organizationScopeConferringRoles: readonly string[];
  readonly applicationScopeHolders: readonly PrivilegedApplicationAccessHolder[];
  readonly organizationScopeHolders: readonly PrivilegedOrganizationAccessHolder[];
  readonly unreadableOrganizationIds: readonly string[];
}

Review the behavior the marker points to

The backend startup diagnostic is a concrete caller: it resolves conferring roles from the current hierarchy, supplies the observation time and invokes enumeratePrivilegedAccessPopulation. The enumeration reads usable account and membership populations. The resulting population is input to an accountable review, not a declaration that every listed permission is appropriate. Keep the decision, reviewer and follow-up work in the application’s assurance evidence.

Keep the references checkable

The repository checker validates marker syntax and objective membership and separates external mapping terminology from runtime controls. It also checks that its workflow covers its scan roots. Run pnpm check:assurance-control-boundary when changing control markers. Passing this check establishes referential hygiene; behavioral review and evidence establish the control.

Follow the authored evidence body

The security-event requirement identifies an actual durable-record home and a production plane. The excerpt below is from assurance-evidence-requirement-bodies.definitions.ts; the surrounding applicability text conditions the demand on the audit capability being enabled.

clauses: [
  {
    clauseRef: "C1",
    obligation:
      "Authentication, authorization, privilege, credential and security-configuration changes each emit a typed auditable event.",
    home: AssuranceEvidenceHome.EMITTED,
    plane: AssuranceEvidenceExecutionPlane.PRODUCTION,
    homeRationale:
      "The demanded artifact is a per-occurrence row in the engine's own durable event store, so one collector query "
      + "serves every application. Not read off the attesting capability: it is read off the artifact the clause names.",
    requiredAuditEventMembers: [
      // authentication
      CoreAuditableEventType.USER_LOGIN,
      CoreAuditableEventType.USER_LOGIN_FAILED,
      CoreAuditableEventType.USER_LOGOUT,
      CoreAuditableEventType.USER_SESSION_EVICTED,

Its remaining event members, minimum-evidence description and verification steps define the rest of the requested population. A collector must inspect the store of record for that demand; a filtered convenience view is not necessarily the same population.

Match the evidence to the question

The body’s home and execution plane are authoritative. The repository’s older assurance:evidence-homes report derives proxy classifications from bindings and names; use it for exploration, not to override an authored clause.

Separate collection from judgment

The intended independent assurance workflow collects source artifacts before judging satisfaction. An unavailable export and a control that failed are different findings. A review should cite reproducible observations, preserve uncertainty and explain severity separately. This model defines what an evaluator needs; it does not turn an unexecuted demand into evidence.

Start with the operator and its data populations

This configuration excerpt comes from the Wonder CRM demonstration application. The identity and role choices are example operator declarations, not defaults or legal advice.

operatorComplianceIdentity: {
  legalEntityName: 'Wonder Software SAS',
  registeredAddress: '1 rue de la Paix, 75002 Paris, France',
  privacyContact: 'privacy@wonder-crm.example',
  roleAllocations: [
    {
      dataScope: 'customer and contact records a subscribing team stores in its workspace',
      role: OperatorProcessingRole.PROCESSOR,
    },
    {
      dataScope: 'account, authentication and billing data of the team members who administer and use the workspace',
      role: OperatorProcessingRole.CONTROLLER,
    },
  ],

Import the named role vocabulary from @wildo-ai/saas-models; place the declaration under operatorComplianceIdentity in wildo.saas.config.ts. Lawful bases are recorded per purpose in the sibling lawfulBases array, with an assessment note required by the schema for a declared legitimate-interests basis.

Keep service consent separate

serviceConsentRequirement describes an explicit consent gate and what it governs. It is separate from analytics preferences and from the purpose-specific lawful-basis declaration. Declaring NONE is an answer; omission is not a claim that no gate exists. The identity schema permits independent parts to be recorded as they become established while rejecting an empty declaration.

Use the declaration in reviewable documents

The companion composes these values into document-authoring context. outstandingOperatorComplianceIdentityParts identifies which identity fields remain unanswered. The declaration supplies the operator’s stated facts and choices; it does not change request authorization, enact the processing policy or validate a legal conclusion. Product behavior and the published account of it must be reviewed together.

Record the reason beside each jurisdiction

This is the operating declaration from Wonder CRM. It illustrates the configuration shape, not a recommendation about any application’s legal position.

operatingJurisdictions: {
  jurisdictions: [
    {
      jurisdictionSlug: 'eu',
      basis: 'the operator is established in France and subscribing teams and their members are in the EU',
    },
    {
      jurisdictionSlug: 'gb',
      basis: 'teams established in the United Kingdom subscribe and store their customer records here',
    },
  ],
},

The schema requires a nonempty jurisdiction list and a reason per place, and rejects duplicates. Canonical region spelling matters: aliases should not create two identities for one place. A subdivision means a place inside its root; broader regimes are represented by their component places.

Read coverage as source reach

assessAssuranceJurisdictionCoverage compares the declared places with active registered sources. composeOperatingJurisdictionCoverageBrief carries that result into drafting context. It distinguishes law-backed coverage, guidance-only coverage and uncovered reach. Those states say what source material the framework carries; none establishes that the application meets the source’s requirements.

Keep publication and operating scope connected

Operating reach answers where the product acts. A public-document variant answers which exact language and jurisdiction combination a document is prepared for. Use the same canonical jurisdiction vocabulary in both. A reviewer still determines the requirements and statements appropriate to the operator’s actual activities.

Choose the right kind of entry

The canonical schema makes configured providers and separately authored relationships distinct. Both carry the same identity fields; only the provider-backed kind can be joined to application configuration. Selected schema declarations from processor-register.schemas.ts:

const ProcessorIdentityFieldsSchema = z.object({
  legalEntityName: z.string().trim().min(1),
  processingRegions: z.array(z.string().trim().min(1)).min(1),
  subprocessors: z.array(ProcessorSubprocessorSchema),
});

export const ApplicationProcessorDeclarationSchema = z.discriminatedUnion("kind", [
  ProcessorIdentityFieldsSchema.extend({
    kind: z.literal(ProcessorRegisterEntryKind.CONFIGURED_PROVIDER),
    providerRef: z.string().trim().min(1),
    purpose: z.string().trim().min(1).optional(),
  }).strict(),
  ProcessorIdentityFieldsSchema.extend({
    kind: z.literal(ProcessorRegisterEntryKind.AUTHORED),
    subprocessorRef: z.string().trim().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
    purpose: z.string().trim().min(1),
  }).strict(),
]);

Reconcile both directions

The helpers below show the result the drafting lane can inspect. The register is a typed specification family, loaded from the application’s specification exports.

The companion supplies runtime-bound provider references and the operator’s deployment choices. It excludes explicitly self-hosted providers before comparing recipient candidates with the register; an unanswered deployment choice stays visible as a question.

// Selected companion reconciliation; all inputs have already been loaded.
const operatorRunRefs = new Set(
  Object.entries(choices ?? {})
    .filter(([, choice]) => choice.deploymentModel === ProviderDeploymentModel.SELF_HOSTED)
    .map(([providerRef]) => providerRef),
);
const recipientCandidateRefs = configuredProviderRefs.filter((ref) => !operatorRunRefs.has(ref));
const missing = undeclaredProcessorRefs(recipientCandidateRefs, register);
const stale = processorRefsNotConfigured(recipientCandidateRefs, register);
const regions = processorProcessingRegions(register);

The reconciliation helpers are exported from @wildo-ai/saas-specifications. missing identifies candidates without entries, not proof that each is vendor-hosted. stale identifies provider-backed entries outside that candidate set. regions includes declared subprocessors. Profile-only providers never enter the runtime-bound input. Separately authored relationships require their own declaration because configuration cannot establish them.

Record the arrangement, not a brand assumption

A configured-provider entry carries kind, providerRef, legalEntityName, processingRegions and subprocessors; authored entries use subprocessorRef and a required purpose. An empty register records the operator’s declaration of no processor recipients, which must still be reconciled against candidates; an absent register has not made that statement. Provider deployment choices determine whether an external recipient exists at all. Verify the operator’s actual contract and source disclosures before publication; schema validation establishes consistency, not the truth of a vendor’s current arrangements.

Declare policy and provision its scanner

Use the file’s scanPolicy for an explicit requirement or exception. An unspecified field inherits the application’s configured scanner posture. The backend reads this decision in file-scanning.backend.service.ts; the separate global predicate is included, with intervening commentary omitted.

shouldScan(fileMetadata?: FileSchemaMetadata): boolean {
  const scanPolicy = fileMetadata?.scanPolicy;

  if (scanPolicy === 'required') return true;
  if (scanPolicy === 'skip') return false;

  return this.isGlobalScanningEnabled();
}

isGlobalScanningEnabled(): boolean {
  if (!this.appConfigService.isInitialized()) return false;
  return this.clamavScanner.isConfigured() || this.yaraScanner.isEnabled();
}

Move into scanning before dispatching work

The upload handler awaits scan initiation before returning upload acceptance and file metadata. Upload acceptance does not mean the scan has finished: file.readiness reports whether the returned file can be attached. Inside the scan service, the status transition occurs before asynchronous scanner execution. This excerpt omits validation above and the error-logging callback below.

await this.filesService.updateFileStatus(
  fileId,
  FileStatus.SCANNING,
  executionContext,
);

if (onClean) {
  this.onCleanCallbacks.set(fileId, onClean);
}

this.logDebug('File transitioned to SCANNING, dispatching scan', { fileId });

Distinguish a clean result from a failed check

Configured ClamAV signature scanning runs first; enabled YARA pattern scanning follows if the earlier layer has not refused the file. The pipeline requires at least one configured scanner when scanning is requested. Startup validation reports incompatible required-field and scanner configurations, and the runtime also refuses to certify a file clean when no scanner is available.

A clean verdict transitions the file to CLEAN and releases configured follow-on work. An infection moves it through INFECTED toward QUARANTINED; quarantine keeps the stored bytes but blocks normal download. A scanner or storage error moves it to FAILED, requiring recovery or re-scan. The same state checks stop linking while scanning. Standard file controls refresh pending metadata and publish the new reference only after it becomes ready; the form also preserves the processing error through submit validation. Scanning reduces malware risk; it does not validate the business meaning or confidentiality of a document.

Read readiness before attaching a file

Upload responses include file.readiness; the authorized metadata endpoint returns the same FileMetadata contract. The standard single- and multiple-file controls handle this for local files and provider selections. Custom upload interfaces must inspect readiness rather than treat HTTP success as permission to attach.

Readiness describes attachment eligibility, not download authorization. The backend still checks access and lifecycle state when linking or serving a file. Polling observes a scan; it does not start a new scan or automatically retry a failed one. With scanning skipped or inactive, an ordinary completed upload can already report ready.

Match field policy to the startup contract

Use status for current download eligibility and the emitted failure/malware events for investigation. The absence of a clean-event row must not be interpreted as proof that no scan ran.

Connect a required field to the deployed scanner

This illustrative attachment field requires scanning, independently of the inherited application posture:

import { z_file } from '@wildo-ai/zod-decorators';

const attachment = z_file({
  multiple: false,
  allowedMimeTypes: ['application/pdf'],
  scanPolicy: 'required',
});

Provision a ClamAV daemon reachable from the backend, then supply its address through the application’s environment setup. For example, these values assume the backend can resolve a service named clamav; setting them does not install or start the daemon:

CLAMAV_HOST=clamav
CLAMAV_PORT=3310

The configuration loader seeds fileScanning.antivirus; the scanner reads that resolved configuration. Startup validation checks required fields against ClamAV configuration. A configured address is not proof that the scanner is healthy: the upload path still needs the daemon to accept and complete a scan.

For the additional YARA layer, provision the YARA scanning service and its rules, then configure both the enable flag and its reachable address:

YARA_ENABLED=true
YARA_HOST=yara
YARA_PORT=8080

Those names are illustrative deployment addresses. The YARA service consumes fileScanning.yara.enabled and fileScanning.yara.connection; enabling it without a host is a configuration problem. YARA alone does not satisfy the current startup requirement for a field marked required.

Retain the uploaded file ID while observing processing. Repeated metadata reads observe the existing scan; uploading again creates another upload rather than repairing the first scan.

Resolve the source and its permitted use

deriveAssuranceExternalFrameworkMapping joins source requirements to the source registry. Before emitting the citation, it checks the registered permission at the evaluation time. Comments between these lines are omitted.

if (!metadataCitationAuthorized) {
  throw new AssuranceExternalMappingRightsError(
    `Cannot cite "${authority.source.sourceRef}": its rights record does not authorize STORE_METADATA as of ${evaluatedAt}. `
    + "Resolve the rights before publishing a mapping that names it.",
  );
}
const contentUsePermission = source.rights.useDecisions.find((decision) => decision.use === AssuranceSourceUse.EXTRACT_CONTENT)?.permission
  ?? AssuranceSourceUsePermission.UNKNOWN;
attributionNotices.add(source.rights.attributionNotice);
const existing = citationsByObjective.get(authority.objective.objectiveRef as string) ?? [];
existing.push({
  sourceRef: authority.source.sourceRef as string,
  sourceTitle: source.canonicalTitle,
  authorityKind: source.authorityKind,
  requirementRef: authority.requirementRef as string,
  canonicalLocator: authority.canonicalLocator,
  reviewedByRef: authority.reviewedByRef as string,
  reviewedAt: authority.reviewedAt,
  rightsRef: source.rights.rightsRef as string,
  attributionNotice: source.rights.attributionNotice,
  metadataCitationAuthorized,
  contentUsePermission,
});
citationsByObjective.set(authority.objective.objectiveRef as string, existing);

The result keeps the source locator, review attribution and content-use permission. Metadata permission does not automatically authorize copying source text. A source’s status and rights must support the use the report actually makes.

Keep the direction of dependency clear

Runtime code names Wildo objectives. The reporting boundary maps those objectives outward to sources; source names do not select production behavior. The generation lane can emit the mapping beside the basis it was derived from, keeping both tied to the same inputs.

Interpret a mapping as a reference

A mapping helps scope a review. It is not a legal conclusion, a complete assessment of applicability or an external certification. The application programme determines its commitments and supporting evidence; qualified assessment determines what those records establish in the relevant context.

Read each resource through the same projection

readCompliancePrimaryResourceFacts receives the loaded resource configuration. Its result comes directly from named declaration fields and the personal-data category resolver, rather than a language-model inference.

export function readCompliancePrimaryResourceFacts(
  resourceType: string,
  origin: CompliancePrimaryFactOrigin,
  configuration: ComplianceRelevantConfiguration,
): CompliancePrimaryResourceFacts {
  const systemAccessPolicy = configuration.systemAccessPolicy;
  const categoryProfile = resolveResourcePersonalDataCategories(configuration.mainSchema);
  return {
    resourceType,
    origin,
    ...(configuration.retentionPolicy?.mode === undefined ? {} : { erasureRetentionMode: configuration.retentionPolicy.mode }),
    ...(configuration.dataSubjectPolicy?.kind === undefined ? {} : { dataSubjectKind: configuration.dataSubjectPolicy.kind }),
    declaresSubjectExport: systemAccessPolicy?.exportSubject !== undefined,
    declaresRetainedSeeThrough: systemAccessPolicy?.seeRetained !== undefined,
    personalDataCategories: categoryProfile.categories,
    uncategorizedPersonalFields: categoryProfile.uncategorizedPersonalFields,
  };
}

Give each output its proper meaning

erasureRetentionMode answers what happens to the row. dataSubjectKind identifies the session-related subject axis. declaresSubjectExport and declaresRetainedSeeThrough report whether the corresponding declaration is present. Both are also true for an explicit FORBIDDEN declaration: they do not mean the operation is allowed. Read the resource’s actual policy before describing availability; neither flag shows that a request has been exercised. Field categories describe the data declared in the schema, including fields still needing classification.

projectCompliancePrimaryFacts aggregates these values with separate engine/application origins. Stable category ordering avoids changing document prose merely because resource iteration order changes. An undeclared resource is distinct from an explicit declaration of no personal data.

Connect the projection to authoring

The companion requests the backend behavior named compliance-primary-facts. A playbook selecting COMPLIANCE_PRIMARY_FACTS receives that result in its brief. In this required context path, a missing backend or unsuccessful result stops fact drafting instead of replacing source facts with guessed prose. The facts playbook consumes mechanism declarations; the later document drafter consumes the resulting declared facts. Reading the loaded application configuration establishes what it declares, not operating effectiveness.

Give the fact an identity and authority

The document-facts family carries versioned declarations, governance scope, sensitivity, authority and either a known value or a reason it does not apply. This selected Wonder CRM declaration records the service consent setting, its value and source authority. The clause below cites this same fact.

"declarationRef": "document-fact-declaration:service-consent-gate",
"declarationVersion": 1,
"factRef": "document-fact:service-consent-gate",
"factVersion": 1,
"governanceScope": {
  "subjectKind": GovernedDocumentGovernanceSubjectKind.APPLICATION_OPERATOR,
  "subjectRef": "operator:wonder-software-sas",
  "scopeRef": "scope:wonder-software-sas-application",
  "scopeVersion": 1,
  "participantRefs": [],
  "precedenceRuleRefs": []
},
"sensitivityRef": "sensitivity:public",
"authority": {
  "authorityRef": "document-fact-authority:service-consent-gate",
  "authorityVersion": 1,
  "factAuthorityKind": AssuranceDocumentFactAuthorityKind.APPLICATION_SPECIFICATION
},
"resolutionKind": ApplicationAssuranceDocumentFactContributionResolutionKind.KNOWN,
"value": "Use of the service is not gated on consent. This is a service-wide consent-gate configuration and does not state a lawful basis for processing."

A generated specification fact cannot simply claim qualified-review authority. Authored decision/review facts have separate schemas. Qualified-review declarations require different author and reviewer references, qualification references and an independence disclosure. The reference inequality guard does not establish that two references identify different people or that the reviewer is independent. Those substantive checks belong to review; the schema preserves their declared attribution.

Cite the fact from a reader-facing clause

This actual clause in the demonstration notice references the consent-gate fact, with no duplicate policy citation:

{
  "clauseRef": "clause:service-wide-consent-gate",
  "order": 1,
  "bodyMarkdown": "Use of Wonder CRM is not gated on service-wide consent. This configured gate status does not identify a lawful basis for processing.",
  "completeness": ComplianceStatementCompleteness.DERIVED,
  "factRefs": [
    "document-fact:service-consent-gate"
  ],
  "sourcePolicyRefs": [],
  "claimGuardRefs": [
    "claim-guard:no-consent-basis-conflation",
    "claim-guard:known-fact-only"
  ]
},

factRefs names established source facts; sourcePolicyRefs names policy areas when needed. A clause must cite at least one source across those fields. claimGuardRefs records constraints for the reviewer, not an automatic proof of semantic truth.

Validate the connection

The candidate fact-binding validator checks cited facts against declared availability, including both clauses and variant selections. A known fact needs a substantive value; an explicit not-applicable declaration has its own reason. The resulting document remains a reviewable content artifact. Its presence is not publication or approval, and source consistency is not a substitute for checking the prose’s meaning.

Check what the document owes as well as what it cites

A document can cite only valid facts and still omit a required subject. Coverage distinguishes an uncited required fact from one discussed only in an incomplete clause. The landing consumer scopes that check to declared facts; an unavailable blueprint or fact set is not proof of complete coverage.

This illustrative clause records an unresolved operating decision. Its policy and guard references must be chosen for the surrounding candidate:

import { ComplianceStatementCompleteness, type ComplianceDocumentCandidateClause } from '@wildo-ai/saas-specifications';

export const retentionDecision: ComplianceDocumentCandidateClause = {
  clauseRef: 'clause:retention-decision',
  order: 1,
  bodyMarkdown: 'The retention duration requires an operator decision.',
  completeness: ComplianceStatementCompleteness.NEEDS_DECISION,
  incompleteness: {
    needs: 'The retention duration for customer records.',
    closedBy: 'The operator responsible for the retention policy.',
  },
  factRefs: [],
  sourcePolicyRefs: ['policy:retention'],
  claimGuardRefs: ['claim-guard:retention-decision'],
};

A non-derived clause requires incompleteness; a derived clause must not carry it. When a known fact’s arrival would resolve the gap, name it in awaitingFactRefs so stale gap statements can be detected. Keep facts awaiting a human decision or qualified review in their authored family; regenerating application-derived facts must not replace those decisions. A marked draft is useful work for review, not permission to publish an unsupported statement.

Keep structure and source references together

A ComplianceDocumentCandidate names its document and jurisdictions, then contains ordered sections and clauses. Sections identify the concern they address and may declare which blueprint sections they satisfy. Clauses carry prose, fact references, claim guards and completeness. These are the actual document-level fields of the Wonder CRM candidate:

export const applicationComplianceDocumentCandidate: ComplianceDocumentCandidate = {
  "version": ComplianceDocumentCandidateVersion.V1,
  "documentRef": "document:public.privacy-notice",
  "title": "Wonder CRM Privacy Notice Candidate",
  "jurisdictionRefs": [
    "jurisdiction:eu",
    "jurisdiction:gb"
  ],
  "variantSelections": [],
  "sections": [
    {
      "sectionRef": "section:operator-identity",
      "order": 1,
      "title": "Operator identity and privacy contact",
      "concernRef": "operator-identity",
      "satisfiesSectionRefs": [
        "document-section:scope-and-audience",
        "document-section:identity-and-role",
        "document-section:contact"
      ],

The candidate’s own section identity can stay readable while satisfiesSectionRefs links it to required coverage. A corresponding satisfiesClauseRefs field supports clause-level requirements without forcing the writer to copy the blueprint’s structure word for word.

Check coverage as well as valid citations

A document can cite only valid facts and still omit an important subject. validateComplianceDocumentCandidateFactBinding checks its references; fact/blueprint coverage and the required-document set answer different questions. The completeness projection reports concerns that are established, unresolved or unaddressed. Keep those checks separate so internal consistency cannot masquerade as complete coverage.

Carry unresolved statements honestly through review

The content schema distinguishes derived statements from information needing framework support, configuration or an operator decision. Where an unresolved statement names awaitingFactRefs, its arrival can be detected as a stale absence claim. This supports iterative document preparation without silently inventing an answer.

The destination is a document derived from product facts and reviewed decisions, with production evidence supporting claims about operation. The drafting process prepares content. The operator’s release process decides what may be published; qualified review addresses legal interpretation and external assessment retains its own authority.

Keep locale and jurisdiction together

This is the actual typed publication declaration in Wonder Todos, shown without its surrounding design commentary:

export const applicationDocumentPublicationSpecification = ApplicationDocumentPublicationSpecificationSchema.parse({
  schemaVersion: 1,
  authorityRef: "document-publication-variant-authority:wonder-todos",
  authorityVersion: 2,
  variants: [{ locale: "en-GB", jurisdictionRefs: ["jurisdiction:eu", "jurisdiction:is", "jurisdiction:li", "jurisdiction:no"] }],
});

The family is exported by the application’s specification companion exports. The authorityRef and version identify the declaration being reviewed; variants is a set of exact combinations, not two independent lists to cross-multiply.

Validate identity before using it

ApplicationDocumentPublicationSpecificationSchema checks shape, uniqueness and canonical ordering. validateApplicationDocumentPublicationSpecification additionally checks canonical language tags and jurisdiction references through the shared jurisdiction validator. Candidate jurisdiction validation uses that same vocabulary, so aliases and invalid regional shapes cannot acquire a second identity at another boundary.

Keep publication authority explicit

The declaration states intended variants. Content creation, review and publishing are distinct activities; a valid variant does not itself release a notice. The intended delivery contract uses only the declared combinations and the corresponding reviewed content. Preserve that pairing in the application’s publication process, and record audience changes deliberately in version control. The code above is the declaration contract, not a document-serving endpoint.

Derive facts before drafting clauses

The actual refinement.document-facts playbook requests these context sources and declares its own execution policy:

method: {
  contextSources: [MetaWorkflow_ContextSource.COMPLIANCE_PRIMARY_FACTS, MetaWorkflow_ContextSource.DOCUMENT_FACT_OBLIGATIONS],
  skillRefs: ['journey-status'],
},
executor: MetaWorkflow_Executor.COMPANION_AGENT,
approval: MetaWorkflow_ApprovalPolicy.APPROVE_RESULT,
budget: { maxRuns: 3 },
onFailure: MetaWorkflow_FailurePolicy.KEEP_AND_FLAG,

Its output is the document-facts specification family. Vision and requirements explain purpose; resource declarations supply mechanism facts. The companion assembles those inputs and the fact schema constrains the proposed artifact.

Keep the document writer on declared facts

refinement.compliance-document-candidate receives document-facts and requests document_blueprint. Its brief-adequacy mechanism explicitly excludes raw compliance_primary_facts: those belong to the preceding derivation stage. Otherwise the writer could cite behavior that never became a declared document fact.

Let research and evaluation answer different questions

top_down.compliance-research gathers source material. top_down.compliance-evidence-adequacy returns a verdict and specific missing information for the posture stage; it does not author a document. This makes a further research round targeted rather than a repeat of the same broad request.

The intended workflow prioritizes derivation from code, configuration and evidence, using judgment for interpretation and declared operator choices where necessary. Playbook availability defines the work that can be orchestrated; it does not establish that a particular application has completed the programme or undergone assessment.

Use the framework generation command

From a configured Wildo development environment, wildo fwk generate-docs resolves the framework repository and calls FrameworkKnowledgeGenerationService.generate. It reports its output directory, extracted topics and registry files. The generator discovers source anchors and authored knowledge, renders references and packages playbooks and assurance bases.

Preserve the basis identity

This source excerpt shows assurance bases being materialized and registered. A duplicate identity is rejected rather than silently replacing the earlier definition.

const assuranceAuthorityBasisRegistryEntries: Record<string, AssuranceAuthorityBasisRegistryEntryShape> = {};
for (const basisFile of FrameworkKnowledgeGenerationService.discoverAuthoredAssuranceAuthorityBases(frameworkRoot)) {
  const entry = FrameworkKnowledgeGenerationService.materializeAssuranceAuthorityBasis(
    basisFile,
    assuranceAuthorityBasesDirectory,
    frameworkRoot,
    generatedAt,
  );
  const identity = `${entry.ref}@${entry.version}`;
  if (assuranceAuthorityBasisRegistryEntries[identity]) throw new Error(`Duplicate authored assurance-authority basis identity "${identity}".`);
  assuranceAuthorityBasisRegistryEntries[identity] = entry;
}

The resulting payload includes the portable basis and its source mapping. Topic and source-tag registries point back to the extracted reference material; authored skills explain how an application uses it. The output is generated knowledge, so changes belong in the source or authored definition before regeneration.

Keep generated knowledge distinct from operational evidence

A source excerpt can establish an API contract. A packaged assurance basis can establish what an objective demands. Neither demonstrates that a deployed application performed the action successfully. Link operating claims to the appropriate event, execution or review record and its version. The separate knowledge audit checks package/reference coherence; it is not an application assurance assessment.

wildo config sync invokes provisioning for file-backed environments. Each registry material declares its identity keys, generated secret keys, purpose, presence check and provisioning/rotation functions.

The provisioning loop checks each material before and after minting:

Selected source from framework-managed-secrets.ts:

export function provisionFrameworkManagedSecrets(
  secrets: PlatformEnvSecretsDraft,
): FrameworkManagedSecretsProvisioningResult {
  const mintedRefs: FrameworkManagedSecretMaterialRef[] = [];
  const mintedKeys: string[] = [];

  for (const material of FRAMEWORK_MANAGED_SECRET_MATERIALS) {
    if (material.isProvisioned(secrets)) continue;

    material.provision(secrets);

    if (!material.isProvisioned(secrets)) {
      throw new Error(
        `Framework-managed secret material '${material.ref}' did not satisfy its own provisioning check. `
        + 'This is a registry authoring bug in framework-managed-secrets.ts, not an environment problem.',
      );
    }

    mintedRefs.push(material.ref);
    mintedKeys.push(...material.identityKeys, ...material.secretKeys);
  }

  return { secrets: secrets as PlatformEnvSecretsJson, mintedRefs, mintedKeys };
}

The selected source returns the updated structured secrets object together with the material and key names it created. Operational reporting can use those names without displaying credential values. A material that fails its own presence check aborts provisioning instead of saving a falsely complete environment.

Keep backfill distinct from rotation

Normal synchronization provisions missing materials; --rotate-secrets is the explicit rotation choice. The general overwrite flag does not imply rotation. Rotation must be coordinated with the deployed services and published verification keys that use the changed material.

The registry groups keys that belong together. A complete existing material is preserved; repairing a partially missing material follows that material’s own provisioning function. Do not remove one key from a running credential pair as a way to request routine synchronization.

Keep operator choices with the operator

The registry can generate an administrator password when one was not supplied, but it does not invent the administrator’s identity. Vendor credentials and other operator-authored values remain inputs. In a fileless CI lane, the framework reads persisted secret-store material rather than minting new credentials that disappear with the runner.

The CI adapter reads WILDO_SECRET_* variables and validates the reconstructed object with the same schema as file-backed environments. Provider variables use WILDO_SECRET_PROVIDER_ENV_<ENV_VAR_NAME>, retaining their declared runtime name.

Generate the workflow’s variable list from the configured application workspace:

wildo config sync --env=production --domain cicd

Inspect the generated deployment workflow’s env block. It derives required and optional inputs from the secret schema and the selected providers; do not copy a fixed list from another environment.

For example, suppose a configured provider declares EXAMPLE_API_KEY as its runtime secret. The corresponding workflow fragment is:

- name: Generate deployment artifacts
  env:
    WILDO_SECRET_PROVIDER_ENV_EXAMPLE_API_KEY: ${{ secrets.WILDO_SECRET_PROVIDER_ENV_EXAMPLE_API_KEY }}
  run: npx wildo config sync --ci --env=production --domain config

This is a placeholder-only example of one entry, not the complete generated workflow. Store the real value under that secret-store name; never replace the expression with a literal credential.

The adapter validates the reconstructed inputs. Required provider inputs must be supplied; optional inputs are identified separately by the generated list. CI consumes persisted material rather than minting temporary replacements. Generated Kubernetes artifacts are written under .wildo-saas/deploy/production/k8s/ for the deployment step to consume.

Preserve key material across the boundary

The adapter normalizes escaped newlines for key and certificate variables before use. Store the actual material in the deployment’s secret manager and expose it only to the runner steps that need it. Do not replace missing persisted keys by generating fresh ones during an ephemeral deployment.

Separate source hygiene from secret operations

The framework consumes the values; the secret store owns access, rotation and expiry policy. The runner holds them in memory and may render secrets-bearing deployment artifacts, which require their own access and cleanup policy. Local file-backed environments remain a separate supported workflow; their secrets are authored inputs, not disposable generated files.

The application backend uses the application’s provisioned material. Additional runtime principals derive their grants from their declarations. A minion’s resourceAccess.read and write lists govern application data; platform-access scopes are a separate axis.

Database ownership and a scoped table grant use distinct provider operations. Scoped synchronization replaces the previous authority so removing a declared resource can remove the grant instead of leaving an accumulating permission set.

Declare read and write separately

Inside the minion’s entry in wildo.saas.config.ts, an illustrative editing task would declare:

resourceAccess: {
  read: ['todos'],
  write: ['todos'],
},

These identifiers name resource types, not database collection names. User-relative self-resource doors are rejected by this authoring contract. Write permission deliberately does not imply read permission.

Synchronize the changed configuration and inspect the provisioned principal’s grants. Removing a resource must remove the corresponding authority, while a read-only declaration must still refuse a write. The neighboring runtime-topology guide shows the enclosing minion registration. Storage sessions remain scoped to the application’s prefix; a database read-only grant does not also make object storage read-only.

Confine delivery as well as provisioning

The authenticated configuration fetch resolves the presenting principal. Before overlaying a non-backend principal’s material, the manager removes every path that a provider can mint per principal:

Selected source from apps-to-manager.apps-manager.platform.controller.ts:

const isApplicationBackend = principal.kind === ApplicationRuntimePrincipalKind.APPLICATION_BACKEND;

const projected: Record<string, unknown> = structuredClone(rest);
if (!isApplicationBackend) {
  for (const path of collectPerPrincipalSecretBlobPaths()) {
    AppsToPlatformAppsManagerPlatformController.deleteSecretBlobPath(projected, path);
  }
}

if (!section) {
  return projected;
}

// Overlay the principal's own material, by the same JSON paths the provider modules mint into.
for (const [path, value] of Object.entries(section.secretBlobValues)) {
  AppsToPlatformAppsManagerPlatformController.assignSecretBlobPath(projected, path, value);
}
return projected;

This selected section is from the controller’s credential projection. Stripping occurs even when the principal has no credential section. Otherwise an absent narrow grant could accidentally leave the broad application value in place. The application backend is explicitly distinguished by principal kind because that base material is its own.

Match storage access to the application identity

Object storage uses short-lived sessions with a policy tied to the platform-issued application identifier and storage prefix. Bucket provisioning remains a platform operation; a prefix-confined session does not need permission to create the bucket.

Review the resulting principal grants and delivered material when changing a runtime declaration. Credential generation, network reachability and resource-service permissions reinforce one another, but they are distinct controls with distinct consumers.

Wonder Todos selects read-only application data for its marketing-scrapper minion:

Selected source from wildo.saas.config.ts:

minions: {
  marketingScrapper: {
    path: './minions/marketing-scrapper',
    resourceAccess: {
      read: ['todos'],
      write: [],
    },
  },
},

This is a selected minions entry inside the existing wildo.saas.config.ts declaration, not a standalone configuration file. A minion is a separately declared background service with tick-based execution. The example omits its independent platform-access settings. A worker is a different runtime category; do not use the names interchangeably or assume a worker is the backend’s queue consumer.

After editing the declaration, run wildo config sync from the configured application workspace. Inspect the environment generated for ./minions/marketing-scrapper and its deployment network membership. Queue, cache and telemetry are part of the minion service set; database and object-storage topology follow the presence of resourceAccess. Inspect names and grants without printing credential values.

The presence of resourceAccess activates the data-service topology. Omitting it excludes those services; an explicit { read: [], write: [] } still activates the topology but grants no resources through these lists. Reachability and resource grants are separate decisions.

Derive addresses and reachability together

resolveRuntimeBackingServiceAccess evaluates the runtime principal and declaration. The environment builder intersects that access with provisioned services; resolveRuntimeNetworkMembership uses the same result for network membership.

Serving HTTP is a deployment choice. Internet egress is a separate explicit declaration. A connection address does not select the application’s database engine, and network reachability does not replace operation-level permissions.

For a new runtime, inspect the generated environment and network projection together. They should express the same declared access instead of compensating for one another.

Author application and infrastructure choices in their configuration files. Use configuration synchronization to regenerate derived environments; edit the source value instead of patching a generated .env.

Builders return raw values. The local dotenv writer encodes them exactly once for its reader:

Selected source from env-configuration-generator.service.ts:

function writeEnvFile(filePath: string, env: Record<string, string>): void {
  const dir = dirname(filePath);
  if (!existsSync(dir)) {
    mkdirSync(dir, { recursive: true });
  }

  const content = Object.entries(env)
    .map(([key, value]) => `${key}=${encodeDotenvValue(key, value)}`)
    .join('\n');

  writeFileSync(filePath, GENERATED_FILE_HEADER + '\n\n' + content + '\n');
}

For example, take this harmless raw value (two lines, not a real key):

PUBLIC-LINE-ONE
PUBLIC-LINE-TWO

The Node dotenv sink writes one quoted entry with an escaped newline:

EXAMPLE_PUBLIC_MATERIAL="PUBLIC-LINE-ONE\nPUBLIC-LINE-TWO"

The dotenv reader reconstructs PUBLIC-LINE-ONE followed by a newline and PUBLIC-LINE-TWO. The provider passes the original two-line value; it does not add the quotes or the escape sequence itself.

Compose and Kubernetes have their own sink encoders. A value safe for one format is not necessarily correctly escaped for another. This is why providers and runtime builders should supply the raw key or JSON value, not a pre-quoted string.

Keep runtime projections separate

The generator creates environments per process kind. Kubernetes runtime environment Secrets and provider credential Secrets have derived names shared with the workload manifests. A runtime without provider contributions does not need a provider-secret mount; it still needs its required runtime environment.

Generation changes an artifact, not the memory of an already-running process. Restart or roll out the affected runtime so it reads the new projection. Protect local environment files and deployment artifacts as secrets-bearing material; encoding a Kubernetes Secret is not an at-rest encryption policy.

Platform initialization provisions each service’s keypair and publishes the matching public key in platform configuration. The private key belongs to the signing service’s environment. The framework-managed registry makes missing signing materials part of synchronization rather than a manual key-copy task.

On receipt, the manager checks that the token issuer matches the service identity in the request, resolves that service’s published key and verifies the token:

Selected source from apps-to-manager.apps-manager.platform.controller.ts:

await this.jwtService.verifyRaw(token, publicKey, {
  // Validate issuer matches the serviceId
  issuer: jwtServiceId,
  // Audience should be apps-manager for platform-to-platform requests
  audience: PlatformApplicationType.PLATFORM_APPS_MANAGER,
});

This selected verification call is from apps-to-manager.apps-manager.platform.controller.ts. Its surrounding path refuses an unrecognized service or missing public key. The published configuration is the verification authority; it does not silently fall back to a second environment key.

The platform-service credential retrieval route is different: it authenticates a shared platform secret and looks up the supplied registered service ID. Do not extend the signed route’s caller-to-key binding to that shared-secret route.

Keep application authentication separate

An application runtime presents its platform secret through the application door. The manager resolves the presenting runtime principal from that credential rather than trusting a principal name supplied by the caller.

A service token proves service identity and audience. The endpoint still decides what that service may do; it is not a user session or a general authorization grant.

Coordinate a key change

When rotating, distribute the private half to the signing service and publish the corresponding public half for verifiers. A mismatch is an authentication/configuration failure with a republishing remedy, not a reason to weaken verification. In local environments, wildo local init republishes platform configuration from the secret store.