@aooth/auth-moost 0.1.18 → 0.1.20

package/dist/index.d.mts

@@ -6,7 +6,7 @@ import { FinishWfOpts, WfFinished, useAtscriptWf } from "@atscript/moost-wf";
 import { MoostWf, WfOutlet, WfOutletTokenConfig, WfStateStrategy } from "@moostjs/event-wf";
 import { FederatedLoginService, NormalizedProfile, OAuthProviderRegistry } from "@aooth/idp";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
-import { AuthCodeStore, ClientRedirectPolicy, IdTokenSigner, OidcClaimsResolver, PendingAuthorizationStore } from "@aooth/auth/authz";
+import { AuthCodeStore, AuthorizationServerMetadata, AuthorizationServerMetadata as AuthorizationServerMetadata$1, BuildAuthorizationServerMetadataOptions, BuildProtectedResourceMetadataOptions, ClientRedirectPolicy, DynamicClientRegistration, DynamicClientRegistration as DynamicClientRegistration$1, DynamicClientRegistrationOptions, IdTokenSigner, OidcClaimsResolver, PendingAuthorizationStore, ProtectedResourceMetadata, WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer } from "@aooth/auth/authz";
 
 //#region src/auth.config.d.ts
 /** Resolved cookie attributes. Same shape is used for both access + refresh. */
@@ -852,6 +852,7 @@ interface OidcDiscoveryDocument {
   authorization_endpoint: string;
   token_endpoint: string;
   jwks_uri: string;
+  registration_endpoint?: string;
   response_types_supported: string[];
   grant_types_supported: string[];
   subject_types_supported: string[];
@@ -860,6 +861,23 @@ interface OidcDiscoveryDocument {
   code_challenge_methods_supported: string[];
   token_endpoint_auth_methods_supported: string[];
 }
+/** RFC 7591 §3.2.1 registration response — public client, so no secret fields. */
+interface ClientRegistrationSuccess {
+  client_id: string;
+  /** Seconds since epoch (the RFC's unit — NOT ms). */
+  client_id_issued_at: number;
+  redirect_uris: string[];
+  token_endpoint_auth_method: string;
+  grant_types: string[];
+  response_types: string[];
+  client_name?: string;
+  scope?: string;
+}
+/** RFC 7591 §3.2.2 registration error response. */
+interface ClientRegistrationFailure {
+  error: string;
+  error_description?: string;
+}
 /**
  * The authorization-server endpoints (AUTH-SERVER.md). Turns the existing login
  * workflow into an OAuth/OIDC authorization server for the app's OWN clients — a
@@ -909,21 +927,75 @@ declare class AuthorizeController {
    * custom login path.
    */
   protected loginPath(): string;
-  authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined, nonce: string | undefined): Promise<string>;
+  /**
+   * The issuer identifier for the RFC 8414 metadata document. Defaults to the
+   * Tier-2 signer's issuer; a SIGNER-LESS deployment that serves MCP connector
+   * clients must **override** this (return `{origin}/auth`-style, byte-exact —
+   * never derived from the Host header, which would let a request inject its
+   * host into a cacheable discovery document). `undefined` ⇒ the
+   * `oauth-authorization-server` endpoint 404s.
+   */
+  protected getIssuer(): string | undefined;
+  /**
+   * The RFC 7591 dynamic-client-registration operation, or `undefined` (the
+   * default) to disable DCR — then `POST /auth/register` 404s and neither
+   * discovery document advertises a `registration_endpoint`. **Override** in a
+   * subclass: inject a `DynamicClientStore` (the `DYNAMIC_CLIENT_STORE_TOKEN`
+   * provider) as a required ctor param, build one `DynamicClientRegistration`
+   * around it, and return it here. Same plain-getter pattern as
+   * {@link getIdTokenSigner} (an optional `@Inject` panics in moost's
+   * route-table pass).
+   */
+  protected getDynamicClientRegistration(): DynamicClientRegistration$1 | undefined;
+  /**
+   * `scopes_supported` for the RFC 8414 document (optional per the RFC; omitted
+   * by default — deliberately NOT inheriting the OIDC document's hardcoded
+   * list, which describes Tier-2 sign-in scopes). Override to advertise what
+   * connector clients may request.
+   */
+  protected scopesSupported(): string[] | undefined;
+  authorize(responseType: string | undefined, redirectUri: string | undefined, clientId: string | undefined, state: string | undefined, codeChallenge: string | undefined, codeChallengeMethod: string | undefined, scope: string | undefined, nonce: string | undefined, resource: string | undefined): Promise<string>;
   token(body: {
     grant_type?: string;
     code?: string;
     code_verifier?: string;
     client_id?: string;
     client_secret?: string;
+    resource?: string | string[];
   } | undefined): Promise<TokenSuccess | TokenError>;
   /**
    * OIDC discovery (Tier 2). Derives every endpoint from the signer's `issuer`
    * (configured as `{origin}/auth`), so a relying `OidcProvider` configured with
    * the same `issuer` resolves `/authorize`, `/token`, and `/jwks` automatically.
-   * 404 when no signer is wired (Tier-1-only deployment).
+   * 404 when no signer is wired (Tier-1-only deployment). When DCR is also
+   * wired, `registration_endpoint` is advertised here too — in a combined
+   * deployment a client that prefers `openid-configuration` over the RFC 8414
+   * document must see the same capability set.
    */
   discovery(): OidcDiscoveryDocument | TokenError;
+  /**
+   * RFC 8414 Authorization Server Metadata — the OAuth-flavored discovery MCP
+   * connector clients fetch (OAUTH.md R1). Served signer-INDEPENDENTLY: it
+   * needs only an issuer ({@link getIssuer} — overridable for a Tier-1-style
+   * deployment with no `IdTokenSigner`). Mounted under the controller this is
+   * the suffix form `{issuer}/.well-known/oauth-authorization-server`; the
+   * RFC-correct path-insertion form at the HTTP-server ROOT
+   * (`/.well-known/oauth-authorization-server/<issuer-path>`) cannot be
+   * registered by a prefix-mounted controller — consumers mount it themselves
+   * from the exported `buildAuthorizationServerMetadata` (re-exported by this
+   * package).
+   */
+  oauthServerMetadata(): AuthorizationServerMetadata$1 | TokenError;
+  /**
+   * RFC 7591 Dynamic Client Registration (OAUTH.md R2) — anonymous by spec;
+   * 404 unless a registration operation is wired ({@link
+   * getDynamicClientRegistration}). A thin HTTP adapter: validation, abuse
+   * knobs (guard / cap / never-used GC) and persistence live in
+   * `DynamicClientRegistration` (`@aooth/auth`). Public clients only — the
+   * response carries NO `client_secret` and NO `client_secret_expires_at`
+   * (RFC 7591 §3.2.1 requires them only when a secret is issued).
+   */
+  register(body: unknown): Promise<ClientRegistrationSuccess | ClientRegistrationFailure | TokenError>;
   /** The signer's public JWKS (Tier 2). 404 when no signer is wired. */
   jwks(): Promise<Awaited<ReturnType<IdTokenSigner["jwks"]>>> | TokenError;
   /** Fail soft: 302 the validated client redirect with an `?error=` (+ echoed `state`). */
@@ -1013,6 +1085,17 @@ declare const AUTH_CODE_STORE_TOKEN = "aooth:AuthCodeStore";
  * `CompositeClientPolicy` of both) under this string.
  */
 declare const CLIENT_REDIRECT_POLICY_TOKEN = "aooth:ClientRedirectPolicy";
+/**
+ * DI token for the {@link import("@aooth/auth/authz").DynamicClientStore}
+ * (RFC 7591 dynamic registrations) — an abstract class, same auto-instantiation
+ * hazard as the store tokens above. The BASE `AuthorizeController` never
+ * injects it (DCR is optional, and an optional `@Inject` panics in moost's
+ * route-table pass): a consumer subclass that enables DCR adds it as a
+ * REQUIRED ctor param, builds a `DynamicClientRegistration` around it, and
+ * overrides `getDynamicClientRegistration()`. The same store instance also
+ * backs the `DynamicClientPolicy` composed into the redirect policy.
+ */
+declare const DYNAMIC_CLIENT_STORE_TOKEN = "aooth:DynamicClientStore";
 //#endregion
 //#region src/workflow/auth-workflow.ctx.d.ts
 type MfaTransport = "sms" | "email" | "totp";
@@ -1147,17 +1230,52 @@ interface AuthWfMfaState {
 }
 /** Channel-onboarding state (login Phase 3). */
 interface AuthWfChannelState {
+  /**
+   * The email address `ask/email` collected and sent the enrollment code to —
+   * the sole enrollment ask→verify target, mirroring `phone`. The enrollment
+   * gates key on it. Deliberately SEPARATE from `notice.email` (the
+   * security-notice recipient): that slot may be seeded from
+   * `getCorrespondenceEmail` / a federated profile without any code ever
+   * being sent, so the enrollment gates must never key on it.
+   */
+  email?: string;
   emailConfirmed?: boolean;
   phone?: string;
   phoneConfirmed?: boolean;
   otpDisclosure?: string;
 }
+/**
+ * Security-notice recipient state (login flow). `email` is the address
+ * `notify-new-device` (and any future security notice) delivers to — owned
+ * by the `credentials` / `seedChannelState` seeding (confirmed email-MFA →
+ * `getCorrespondenceEmail` → provider display email) and refreshed by
+ * `verify/email` once a freshly-proven inbox confirms. Server-only — never
+ * `@wf.context.pass`'d, not mirrored into `ctx.public`. Deliberately
+ * distinct from `channel.email` (the enrollment ask→verify target) and from
+ * the flow-subject `ctx.email` that recovery / invite / signup use.
+ */
+interface AuthWfNoticeState {
+  email?: string;
+}
 /** Device-trust state (login). */
 interface AuthWfTrustState {
   deviceTrustToken?: string;
   newDevice?: boolean;
   rememberDevice?: boolean;
   optIn?: boolean;
+  /**
+   * The ARRIVING request presented a valid recognition cookie (stamped by
+   * `device-recognition` BEFORE any mint — pre-mint arrival state). This is
+   * what the notify-new-device gate reads: recognition suppresses the
+   * notification; it never affects MFA (that's `newDevice` / trust).
+   */
+  recognized?: boolean;
+  /**
+   * Recognition token `issue` must set as a cookie on the finish envelope —
+   * either the re-validated arriving cookie (re-issued with a fresh maxAge)
+   * or a freshly minted one.
+   */
+  seenDeviceToken?: string;
 }
 /** Session-policy state (login). */
 interface AuthWfSessionState {
@@ -1289,12 +1407,32 @@ interface AuthWfRecoveryAltActions {
  */
 interface AuthWfOtpState {
   verified?: boolean;
+  /**
+   * The address the last `pincode-send` ACTUALLY delivered to — login MFA
+   * email/SMS challenge, recovery M1 (typed identifier) / M2 (registered
+   * method), and signup's reuse of the recovery pair. Server-only — never
+   * `@wf.context.pass`'d. The email-channel case is consumed by
+   * `pincode-check` as inbox proof (`users.setVerifiedEmail`).
+   */
+  deliveredTo?: string;
+  /** Wire channel of that delivery — only `email` constitutes an inbox proof. */
+  deliveredChannel?: "email" | "sms";
 }
 /** Invite admin-side (Phase A) state. */
 interface AuthWfAdminState {
   availableRoles?: string[];
   roles?: string[];
   userExtras?: Record<string, unknown>;
+  /**
+   * Re-invite decision stamp — set by `admin-form` when `duplicateInviteCheck`
+   * returns `'reuse'` (the default for a row still parked on
+   * `account.pendingInvitation`). `create-user` then refreshes the existing
+   * row (fresh roles + extras, `pendingInvitation` re-asserted) instead of
+   * creating, and `send-email` mints a fresh magic link. Re-validated in
+   * `create-user` against a fresh read: non-pending row → 409, vanished row →
+   * normal create path.
+   */
+  reuseExisting?: boolean;
   /**
    * Outlet-pause idempotency marker for `send-email`. Flipped to `true`
    * after the first dispatch so the invitee's magic-link resume — which
@@ -1577,18 +1715,26 @@ interface AuthWfPublicState {
   newPasswordRequired?: boolean;
   /**
    * Mirrors the display-only fields of `ctx.authz` — the requesting client's
-   * id/name and granted scope, shown on the authorize-consent form. The
-   * `handle` and the `approved` gate stay server-only (never whitelisted onto
-   * the wire).
+   * id/name, granted scope, and the VALIDATED redirect host (the trustworthy
+   * identity shown next to the attacker-choosable `clientName`), shown on the
+   * authorize-consent form. The `handle` and the `approved` gate stay
+   * server-only (never whitelisted onto the wire).
    */
   authz?: {
     clientName?: string;
     scope?: string;
+    redirectHost?: string;
   };
 }
 /** Unified workflow context shape — one type for all three flows. */
 interface AuthWfCtx {
   subject?: string;
+  /**
+   * Flow-subject address — the typed recovery identifier, the invite target,
+   * or the signup email. The LOGIN flow does NOT use this slot: its
+   * security-notice recipient is `notice.email` and its enrollment
+   * ask→verify target is `channel.email`.
+   */
   email?: string;
   defaults?: AuthWfDefaults;
   pin?: string;
@@ -1630,6 +1776,7 @@ interface AuthWfCtx {
   recoveryAltActions?: AuthWfRecoveryAltActions;
   mfa?: AuthWfMfaState;
   channel?: AuthWfChannelState;
+  notice?: AuthWfNoticeState;
   trust?: AuthWfTrustState;
   session?: AuthWfSessionState;
   altActions?: AuthWfAltActionsState;
@@ -1657,14 +1804,17 @@ interface AuthWfCtx {
    * "Continue with <provider>" detour mid-authorize. Presence routes the login
    * tail to the `authz-consent` → `mint-authz-code` terminal (deliver an auth
    * code to the client) INSTEAD of `issue`/`redirect` — no browser session is
-   * minted. `clientName`/`scope` are staged by `authz-consent` for the consent
-   * form's display copy; `approved` is the explicit user-consent gate the
-   * `mint-authz-code` terminal requires before it will mint a code.
+   * minted. `clientName`/`scope`/`redirectHost` are staged by `authz-consent`
+   * for the consent form's display copy (`redirectHost` is parsed from the
+   * VALIDATED redirect — the trustworthy identity next to the registrant-chosen
+   * name); `approved` is the explicit user-consent gate the `mint-authz-code`
+   * terminal requires before it will mint a code.
    */
   authz?: {
     handle: string;
     clientName?: string;
     scope?: string;
+    redirectHost?: string;
     approved?: boolean;
   };
   /**
@@ -1698,6 +1848,24 @@ interface AuthWorkflowOpts {
     ttlMs?: number;
     bindsTo?: "cookie" | "cookie+ip";
   };
+  /**
+   * Device RECOGNITION infra — the always-on `seenDevices` ledger + cookie
+   * that suppress the "new sign-in" notification on devices the user has
+   * already logged in from. Strictly a notification suppressor, NOT an MFA
+   * bypass (that is `deviceTrust`, which stays opt-in and strict).
+   * Cookie-only binding by design — recognition is pure noise control, so it
+   * never binds to IP (IP churn must not re-trigger the email).
+   *
+   * `cookieName` defaults to `<deviceTrust.cookieName>_seen` so a consumer
+   * renaming the trust cookie gets a matching recognition name for free.
+   * No policy flags here — the on/off gate is the existing
+   * `resolveFinalize().notifyNewDevice` policy.
+   */
+  deviceRecognition?: {
+    cookieName?: string;
+    ttlMs?: number; /** Cap on the per-user `seenDevices` ledger — LRU-evicted beyond it. */
+    maxDevices?: number;
+  };
   forms?: {
     loginCredentials?: TAtscriptAnnotatedType;
     invite?: TAtscriptAnnotatedType;
@@ -1748,6 +1916,11 @@ interface ResolvedAuthWorkflowOpts {
     ttlMs: number;
     bindsTo: "cookie" | "cookie+ip";
   };
+  deviceRecognition: {
+    cookieName: string;
+    ttlMs: number;
+    maxDevices: number;
+  };
   forms: {
     loginCredentials: TAtscriptAnnotatedType;
     invite: TAtscriptAnnotatedType;
@@ -1819,6 +1992,22 @@ type AuthDeliveryPayload = {
   recipient: string;
   deviceLabel?: string;
   loginAt: number;
+}
+/**
+ * Consumer-triggered security notice (e.g. impossible-travel detected by a
+ * `resolveRiskStepUp` override) — routed through the same `deliver()` as
+ * every other notice. `reason` is the machine-readable trigger
+ * (e.g. `"impossible-travel"`); `context` is free-form template data
+ * (distances, cities). NEVER auto-sent by the base class — only a consumer
+ * call to `sendSecurityAlert` emits it.
+ */
+| {
+  kind: "security-alert";
+  channel: "email";
+  recipient: string;
+  reason: string;
+  loginAt: number;
+  context?: Record<string, unknown>;
 };
 /**
  * Top-level `UserCredentials` keys that workflow-collected profile payloads
@@ -1834,6 +2023,22 @@ declare const RESERVED_USER_KEYS: ReadonlySet<string>;
  * Does not mutate the input.
  */
 declare function stripReservedUserKeys(profile: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Best-effort "Browser on OS" label from a raw User-Agent string — feeds the
+ * `name` field of `seenDevices` records so a device list reads "Chrome on
+ * Windows" instead of a token. Deliberately tiny (no UA-parser dependency);
+ * detection order lives in the `UA_BROWSERS` / `UA_OSES` tables above.
+ * Returns just the browser or just the OS when only one side is detected;
+ * `undefined` for empty / fully unrecognized input.
+ */
+declare function humanizeUserAgent(ua: string | undefined): string | undefined;
+declare function haversineKm(a: {
+  lat: number;
+  lon: number;
+}, b: {
+  lat: number;
+  lon: number;
+}): number;
 /** Trim + de-duplicate role identifiers submitted via the admin invite form. */
 declare function parseInviteRoles(input?: string[]): string[];
 /**
@@ -1866,6 +2071,16 @@ declare class AuthWorkflow {
    * sync-friendly: the default `void` preserves the engine's sync fast path.
    */
   protected deliver(_payload: AuthDeliveryPayload): void | Promise<void>;
+  /**
+   * The blessed one-call alert path for risk overrides — emit a
+   * `security-alert` delivery (e.g. from an impossible-travel
+   * `resolveRiskStepUp` override). Recipient comes from `ctx.notice.email`,
+   * the proven-first correspondence chain seeded by `credentials` /
+   * `seedChannelState` and refreshed by `verify/email`. No recipient →
+   * SILENT no-op (a user with no provable inbox simply can't be alerted —
+   * mirrors `notifyNewDevice`'s posture). Never called by the base class.
+   */
+  protected sendSecurityAlert(ctx: AuthWfCtx, reason: string, context?: Record<string, unknown>): Promise<void>;
   /**
    * Return the list of selectable role identifiers for the admin invite form.
    * Mirrors the prior `InviteWorkflow.getAvailableRoles()` consumer hook —
@@ -1897,14 +2112,21 @@ declare class AuthWorkflow {
     email: string;
   }): Promise<string[]> | string[];
   /**
-   * Override the structural duplicate rule for `admin-form`. Default: any
-   * existing row → `'reject'`; nothing → `'allow'`. Multi-tenant apps that
-   * allow re-inviting the same email into a different tenant override.
+   * Override the structural duplicate rule for `admin-form`. Default: a row
+   * still parked on `account.pendingInvitation` → `'reuse'` (re-invite:
+   * `create-user` refreshes the existing record in place and `send-email`
+   * mints a fresh magic link — see `createUser`); any other existing row →
+   * `'reject'`; nothing → `'allow'`.
+   *
+   * Multi-tenant apps that allow re-inviting the same email into a different
+   * tenant override to `'allow'`. Apps that want the strict legacy behavior
+   * ("Invite already pending" error on a duplicate invite of a pending user)
+   * return `'reject'` for pending rows.
    */
   protected duplicateInviteCheck(input: {
     email: string;
     existingUser: UserCredentials | null;
-  }): Promise<"allow" | "reject"> | "allow" | "reject";
+  }): Promise<"allow" | "reject" | "reuse"> | "allow" | "reject" | "reuse";
   /**
    * Implements the "log out other sessions" branch of `sessionPolicy.concurrencyLimit`.
    * Default revokes every existing session via `auth.revokeAllForUser` — which is
@@ -2201,6 +2423,17 @@ declare class AuthWorkflow {
    * matching `resolveOtpDisclosure` / the MFA transport.
    */
   protected resolvePromoteHandleField(_ctx: AuthWfCtx, _channel: "email" | "sms"): string | undefined | Promise<string | undefined>;
+  /**
+   * Decide whether a verified federated profile's email claim counts as inbox
+   * proof for the CORRESPONDENCE address (`users.setVerifiedEmail`). Default
+   * trusts the provider's `email_verified` claim — a provider trusted to
+   * AUTHENTICATE the user is strictly more trusted than its email claim. The
+   * capture is correspondence-only: it never promotes the address to a login
+   * handle and never resolves accounts by it. Override to exclude providers
+   * whose claim should not be taken at face value (e.g. an internal OIDC
+   * issuer that stamps `email_verified` on unverified directory entries).
+   */
+  protected resolveFederatedEmailTrust(_ctx: AuthWfCtx, profile: FederatedProfileSnapshot): boolean | Promise<boolean>;
   /**
    * Route a form alt-action click to a canonical outcome. Defaults match the
    * action ids the bundled `PincodeForm` declares; customers override per
@@ -2496,6 +2729,19 @@ declare class AuthWorkflow {
    * Create the user row from `ctx.admin.userExtras` (plus the admin-supplied
    * `ctx.admin.roles`), then stamp `pendingInvitation = true` via a follow-up
    * deep-merge update so `createUser`-applied account defaults survive.
+   *
+   * Re-invite (`ctx.admin.reuseExisting`, stamped by `admin-form` on a
+   * `'reuse'` verdict): REFRESH the existing row instead of creating — apply
+   * the freshly-picked roles + `prepareUser` extras, re-assert
+   * `pendingInvitation`, and leave password/MFA state untouched (a pending
+   * record never had usable credentials). `send-email` downstream then mints
+   * a fresh durable handle, i.e. a new full-TTL magic link. Guarded by a
+   * FRESH `pendingInvitation` read: a `'reuse'` verdict for an accepted
+   * account 409s as a logic error rather than silently re-pending a live
+   * user; a row that vanished since `admin-form` falls through to the normal
+   * create path. The refresh is a deep-merge update: arrays (`roles`)
+   * replace wholesale, but extras keys the current `prepareUser` no longer
+   * returns linger from the original invite.
    */
   createUser(ctx: AuthWfCtx): Promise<undefined>;
   /**
@@ -2790,6 +3036,29 @@ declare class AuthWorkflow {
    * the MFA-form `hidden` expression on `rememberDevice`).
    */
   deviceTrust(ctx: AuthWfCtx): Promise<undefined>;
+  /**
+   * Always-on device RECOGNITION — verify-or-mint the long-lived recognition
+   * cookie against the `seenDevices` ledger. Recognition is a notification
+   * suppressor ONLY (the notify-new-device gate reads `trust.recognized`); it
+   * never skips MFA — that is `deviceTrust`, which stays opt-in and strict.
+   *
+   * Deliberately a SEPARATE step from `check-trusted-device`: that step is
+   * schema-gated on `deviceTrust.enabled && skipsMfa`, so recognition must
+   * not piggyback on it or recognition dies whenever trust is disabled —
+   * exactly the consumers who get the noisiest notify behaviour today.
+   * Verify-or-mint lives in ONE step so `trust.recognized` captures the
+   * PRE-MINT arrival state the notify gate needs (a freshly minted token
+   * must not mark the current login as recognized).
+   *
+   * A valid arriving cookie is verified with `slideTtlMs` (LRU bump) and
+   * re-stashed on `trust.seenDeviceToken` so `issue` re-sets it with a fresh
+   * maxAge. An unrecognized arrival mints + persists a new record (capped at
+   * `deviceRecognition.maxDevices`) and stashes the new token — `recognized`
+   * stays unset so the notification still fires for this login. Degrades
+   * gracefully to a no-op when no `deviceTrust.secret` is configured,
+   * preserving the legacy notify behaviour for those consumers.
+   */
+  deviceRecognition(ctx: AuthWfCtx): Promise<undefined>;
   /**
    * Standalone terms-bump prompt for returning users whose accepted terms
    * version is stale and no carrier form ran. Delegates to
@@ -2850,7 +3119,16 @@ declare class AuthWorkflow {
   /**
    * Notify the user of a login from a new device via the unified `deliver`
    * hook. Gated upstream by
-   * `!ctx.isFirstLogin && !!ctx.finalize.notifyNewDevice && !!ctx.trust.newDevice`.
+   * `!ctx.isFirstLogin && !!ctx.finalize.notifyNewDevice && !ctx.trust.recognized`
+   * — "not recognized" (no valid recognition cookie on arrival), NOT "no
+   * valid trust cookie": users who decline remember-me, or whose strict trust
+   * cookie expired / failed IP binding, must not get the email on every
+   * login. Recognition is the loose always-on ledger minted by
+   * `device-recognition`; trust stays strict and drives MFA skip only.
+   *
+   * Recipient is `notice.email` — the security-notice slot owned by the
+   * `credentials` / `seedChannelState` seeding and refreshed by
+   * `verify/email`. No recipient seeded → silently skips.
    */
   notifyNewDevice(ctx: AuthWfCtx): Promise<undefined>;
   /**
@@ -3014,14 +3292,31 @@ declare class AuthWorkflow {
    */
   private finishOAuth;
   /**
-   * Seed `ctx.email` / `ctx.channel` from a resolved user's confirmed channels —
+   * Seed `ctx.notice.email` / `ctx.channel` from a resolved user's confirmed channels —
    * shared by `ssoCallback` (linked / created / auto-linked) and `proveControl`
    * (interactively-linked) so the post-success channel shape can't drift between
-   * the two federated entry points. Mirrors `credentials`' post-login seeding.
-   * `fallbackEmail` (the provider / snapshot email) is a DISPLAY fallback only —
-   * never promoted to the unique login handle (a gated, later-phase concern).
+   * the two federated entry points. Mirrors `credentials`' post-login seeding,
+   * including the correspondence fallback (confirmed email-MFA →
+   * `users.getCorrespondenceEmail` → provider display email).
+   *
+   * Also the single federated capture point for `users.setVerifiedEmail`: a
+   * trusted `profile.email` (per `resolveFederatedEmailTrust`) is recorded as
+   * the proven correspondence address on EVERY federated login — first-time
+   * create, returning link, and interactive link alike (the store write is
+   * skipped when the capture is already current). The profile email is
+   * otherwise a DISPLAY fallback only — never promoted to the unique login
+   * handle (a gated, later-phase concern).
    */
   private seedChannelState;
+  /**
+   * Correspondence tail of the `ctx.notice.email` seeding — shared by
+   * `credentials` (post-login) and `seedChannelState` (federated) so the
+   * fallback chain (`users.getCorrespondenceEmail` → optional display email)
+   * can't drift between the two. Does NOT set `channel.emailConfirmed` — that
+   * flag means "confirmed email-MFA channel" and gates enrolment; a
+   * correspondence address is a notice recipient, not a proven OTP channel.
+   */
+  private seedCorrespondenceEmail;
   /**
    * `needs-link` setup (decision A — password, OTP fallback). Decide how the
    * user will prove control of the matched account, stash the pending-link
@@ -3186,4 +3481,4 @@ interface AuditEmitter {
   emit(event: AuditEvent): Promise<void> | void;
 }
 //#endregion
-export { ADD_MFA_WORKFLOW, AUTHZ_BINDING_COOKIE, AUTH_CODE_STORE_TOKEN, type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthDeliveryPayload, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type AuthWfCompletionState, type AuthWfConsentsState, type AuthWfCtx, type AuthWfMfaEnrollState, type AuthWfOAuthState, type AuthWfPasswordUiState, type AuthWfPincodeUiState, AuthWorkflow, type AuthWorkflowOpts, AuthorizeController, AuthorizeRuntime, type BuildMagicLinkUrl, CHANGE_PASSWORD_WORKFLOW, CLIENT_REDIRECT_POLICY_TOKEN, type ConcurrencyLimitOptions, type ConnectedAccount, type ConsentDescriptor, type ConsentDescriptorLike, type ConsentEvent, ConsentStore, DEFAULT_AUTH_WORKFLOWS, type EmailSender, type EnrichedSession, FEDERATED_IDENTITY_STORE_TOKEN, type IssueResult, type LoginRedirect, type MfaSummary, type MfaTransport, OAUTH_CSRF_COOKIE, OAuthController, OAuthRuntime, PENDING_AUTHORIZATION_STORE_TOKEN, Public, RESERVED_USER_KEYS, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedAuthWorkflowOpts, type SessionEnricher, SessionEnricherProvider, type SessionInfo, SessionsController, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, authGuardInterceptor, authzBindingCookieAttrs, buildInviteAlreadyAcceptedEnvelope, createAuthEmailOutlet, deriveWfStateSecret, generateMagicLinkToken, getAuthMate, isSafeRelativeRedirect, oauthCsrfCookieAttrs, parseInviteRoles, resolveOAuthRedirect, stripReservedUserKeys, useAuth };
+export { ADD_MFA_WORKFLOW, AUTHZ_BINDING_COOKIE, AUTH_CODE_STORE_TOKEN, type AuditEmitter, type AuditEvent, type AuthBindings, type AuthContext, AuthController, type AuthDeliveryPayload, type AuthEmailEvent, type AuthEmailKind, type AuthEmailOutletDeps, AuthGuarded, type AuthLoginResponse, type AuthLogoutBody, type AuthOkResponse, type AuthOptions, type AuthRefreshBody, type AuthSmsEvent, type AuthSmsKind, type AuthWfCompletionState, type AuthWfConsentsState, type AuthWfCtx, type AuthWfMfaEnrollState, type AuthWfOAuthState, type AuthWfPasswordUiState, type AuthWfPincodeUiState, AuthWorkflow, type AuthWorkflowOpts, type AuthorizationServerMetadata, AuthorizeController, AuthorizeRuntime, type BuildAuthorizationServerMetadataOptions, type BuildMagicLinkUrl, type BuildProtectedResourceMetadataOptions, CHANGE_PASSWORD_WORKFLOW, CLIENT_REDIRECT_POLICY_TOKEN, type ConcurrencyLimitOptions, type ConnectedAccount, type ConsentDescriptor, type ConsentDescriptorLike, type ConsentEvent, ConsentStore, DEFAULT_AUTH_WORKFLOWS, DYNAMIC_CLIENT_STORE_TOKEN, DynamicClientRegistration, type DynamicClientRegistrationOptions, type EmailSender, type EnrichedSession, FEDERATED_IDENTITY_STORE_TOKEN, type IssueResult, type LoginRedirect, type MfaSummary, type MfaTransport, OAUTH_CSRF_COOKIE, OAuthController, OAuthRuntime, PENDING_AUTHORIZATION_STORE_TOKEN, type ProtectedResourceMetadata, Public, RESERVED_USER_KEYS, type ResolvedAuthCookieConfig, type ResolvedAuthOptions, type ResolvedAuthWorkflowOpts, type SessionEnricher, SessionEnricherProvider, type SessionInfo, SessionsController, type SmsSender, type SsoProvider, type TAuthMeta, UserId, WfTrigger, type WfTriggerOpts, WfTriggerProvider, type WwwAuthenticateBearerChallengeOptions, authGuardInterceptor, authzBindingCookieAttrs, buildAuthorizationServerMetadata, buildInviteAlreadyAcceptedEnvelope, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, createAuthEmailOutlet, deriveWfStateSecret, generateMagicLinkToken, getAuthMate, haversineKm, humanizeUserAgent, isSafeRelativeRedirect, oauthCsrfCookieAttrs, parseInviteRoles, resolveOAuthRedirect, stripReservedUserKeys, useAuth };