@fleetless/contracts 5.3.0-next.1 → 6.0.0-next.1

package/dist/routes.js

@@ -1,13 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
-import { appListResponse, appDeletionSummary, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, roleDeleteQuery, rolePermissions, roleRenameRequest, serverKeyListResponse, updateAppRequest, } from './apps.js';
+import { appListResponse, appDeletionSummary, createAppRequest, createServerKeyResponse, app as appSchema, role, roleListResponse, rolePermissions, serverKeyListResponse, updateAppRequest, } from './apps.js';
 import { alertListResponse, orgAlertsQuery, orgFiringAlertsResponse } from './alerts.js';
 import { asset, assetListResponse, assetsClearResponse, assetSyncRequest, assetSyncResponse, assetSyncStatus, missingAssetQuery } from './assets.js';
 import { auditListResponse, auditQuery } from './audit.js';
-import { feedbackRequest, feedbackResponse } from './feedback.js';
-import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
+import { CLIENT_OIDC_CALLBACK_PATH, clientAcceptInvitationRequest, clientIdentity, clientLoginCodeRequest, clientLoginCodeVerifyRequest, clientLoginRequest, clientLogoutRequest, clientMcpInteraction, clientMcpInteractionDecisionResponse, clientOidcCallbackQuery, clientOidcExchangeRequest, clientOidcStartQuery, clientPasswordResetConfirmRequest, clientPasswordResetRequest, clientProviderListQuery, clientProviderListResponse, clientRefreshRequest, clientRegisterRequest, clientResendVerificationRequest, clientSignInResult, clientTwoFactorDisableRequest, clientTwoFactorSetupConfirmRequest, clientTwoFactorSetupConfirmResponse, clientTwoFactorSetupRequest, clientTwoFactorVerifyRequest, clientVerifyEmailRequest, mcpConsentGrantListResponse, } from './client-auth.js';
 import { clientRobotListResponse } from './client-robots.js';
-import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthMcpRequest, putAppAuthRegistrationRequest, putAppAuthUrlsRequest, putAppMailTemplateRequest, } from './app-users.js';
-import { acceptTeamInviteRequest, authMeResponse, createTeamInviteRequest, fleetlessUser, fleetlessUserListResponse, passwordChangeRequest, passwordResetConfirm, passwordResetRequest, patchAuthMeRequest, patchFleetlessUserRequest, patchOrgRequest, patchOrgResponse, pendingTeamInviteListResponse, refreshRequest, sessionTokens, signUpRequest, signUpResponse, teamInvite, tierChangeRequest, waitlistRequest, } from './identity.js';
+import { appAuthConfig, appInvitation, appInvitationListResponse, appMailTemplate, appMailTemplateListResponse, appOidcProvider, appOidcProviderListResponse, appUser, appUserListResponse, createAppInvitationRequest, createAppOidcProviderRequest, createAppUserRequest, mailOutcome, mailTemplatePreviewRequest, mailTemplatePreviewResponse, patchAppOidcProviderRequest, patchAppUserRequest, putAppAuthLookRequest, putAppAuthMcpRequest, putAppAuthRegistrationRequest, putAppAuthSignInRequest, putAppAuthUrlsRequest, putAppMailTemplateRequest, } from './app-users.js';
+import { acceptTeamInviteRequest, authMeResponse, createPasskeyRequest, createPasskeyResponse, createTeamInviteRequest, developerPasskey, developerTwoFactor, fleetlessUser, fleetlessUserListResponse, passwordChangeRequest, patchAuthMeRequest, patchFleetlessUserRequest, patchOrgRequest, patchOrgResponse, pendingTeamInviteListResponse, refreshRequest, sessionTokens, teamInvite, recoveryCodesResponse, renamePasskeyRequest, tierChangeRequest, totpConfirmRequest, totpConfirmResponse, twoFactorSetupResponse, waitlistRequest, webauthnOptionsResponse, } from './identity.js';
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
 import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
 import { authorizationServerMetadata, dynamicClientRegistrationRequest, dynamicClientRegistrationResponse, oauthAuthorizeQuery, oauthRedirectResponse, oauthTokenRequest, oauthTokenResponse, protectedResourceMetadata, } from './oauth.js';
@@ -58,6 +57,11 @@ export const IN_HANDLER_ROUTES = [
     // The one route whose bearer is **optional**: it answers the same document
     // with or without one, and only `already_granted` moves.
     'GET /api/client/mcp/interactions/:id',
+    // Two-factor setup: during sign-in the challenge in the body is the
+    // credential, from the app's account settings the app user's bearer is.
+    // Either one, decided in the handler.
+    'POST /api/client/two-factor/setup',
+    'POST /api/client/two-factor/setup/confirm',
     'GET /api/asset-links/missing',
     'GET /api/asset-links/:token',
 ];
@@ -111,6 +115,161 @@ const DEVELOPER_GUARD = ['unauthorized', 'token_expired', 'token_revoked'];
  * two lists were kept as separate constants while they still read alike.
  */
 const CLIENT_GUARD = ['unauthorized', 'token_expired', 'token_revoked', 'forbidden'];
+/**
+ * **The steps of a developer sign-in, written once for both portal flows.**
+ *
+ * The console's own OAuth flow (`/console/oauth`) and the central MCP
+ * endpoint's (`/mcp/oauth`) sign the same people in the same way: an emailed
+ * code or a passkey, then the second factor where the person has one or the
+ * organisation requires one. Two hand-written copies of thirteen rows would
+ * drift; this returns them for a prefix, and `ROUTES` spreads both.
+ *
+ * Every step is a page the auth portal serves to itself: `audience:
+ * 'internal'`, no request schema — the handlers read form fields by hand — and
+ * HTML for a browser form post, JSON for a JSON caller. Every step after
+ * `identify` needs the browser-proof cookie set there, so a step posted from
+ * another browser renders the `wrong_browser` page. The interaction's ten
+ * minutes cover every step; only when the last one is done is anything
+ * minted. **For `/mcp/oauth`, "done" means the consent step**, as the
+ * password did before.
+ */
+export function developerSignInRoutes(prefix) {
+    const section = prefix === '/console/oauth' ? 'developer-auth' : 'mcp';
+    const done = prefix === '/console/oauth'
+        ? 'the console callback with the authorization code'
+        : 'the consent screen for a self-registered client, or straight to the callback for the central one';
+    const page = (path, summary, notes) => ({
+        method: 'GET', path: `${prefix}${path}`, section, summary,
+        audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The interaction id of this sign-in; the step before redirects the browser here.' }],
+        query: null, request: null, response: null, errors: [], transport: 'http', notes,
+    });
+    const step = (path, summary, response, errors, notes) => ({
+        method: 'POST', path: `${prefix}${path}`, section, summary,
+        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response, errors: ['rate_limited', ...errors], transport: 'http', notes,
+    });
+    return [
+        step('/identify', 'Takes the email address, mails a sign-in code and hands back the code step.', null, ['validation_error', 'token_spent'], 'The page answers `Check your email` **for every address**: a known one gets `Your Fleetless sign-in code`, six digits valid ten ' +
+            'minutes; an unknown one gets a mail saying no Fleetless account uses it, with a link to sign up (or the waiting list while sign-up ' +
+            'is closed). So the page never reveals who has an account, and the address is trimmed and compared case-insensitively. A request ' +
+            'within sixty seconds of the last one for the same address renders the same page without a second mail. The browser-proof cookie is ' +
+            `set here. A browser form post gets the code card; a JSON caller gets \`{ "next": "${prefix}/code" }\`, which has no schema. A dead ` +
+            'interaction is `410 token_spent`.'),
+        step('/code', 'Checks the emailed code and finishes the sign-in, or hands back the second step.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_code'], 'A wrong code renders the code card again with the attempts left (`400 invalid_code`, `details.attempts_left`); a code spent, past ' +
+            'its ten minutes or out of its five attempts is `410 token_spent` and a new one has to be asked for. Spaces inside a typed code are ' +
+            `removed before it is checked. With no second factor to give, a browser gets a \`303\` to ${done}, and a JSON caller that URL as ` +
+            '`redirect_to`. Otherwise the next step: a JSON caller gets `{ "next" }` naming `' + prefix + '/two-factor` — the person has a ' +
+            'passkey or an authenticator — or `' + prefix + '/two-factor/setup` — the organisation requires one and the person has none — and a ' +
+            'browser the page itself. Audited as `developer.login` with `details.method` `email_code` once the sign-in completes.'),
+        page('/two-factor/:id', 'Serves the second step: the authenticator code, or the passkey prompt.', 'HTML. Six boxes for the authenticator code, `Use a passkey`, and `Use a recovery code`; a developer with passkeys only sees the ' +
+            'passkey prompt directly. The browser-proof cookie is checked on this GET too. A dead interaction renders the `410` page.'),
+        page('/two-factor/:id/recovery', 'Serves the recovery-code page of the second step.', 'HTML. One field for a recovery code, and the way out when none is left: an owner of the organisation can reset the member\'s ' +
+            'two-factor in Settings › Team.'),
+        step('/two-factor', 'Checks an authenticator code or a recovery code and finishes the sign-in.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_code'], 'The form carries either `code` or `recovery_code`. **An authenticator code is accepted at most once**, so the same code sent twice ' +
+            'finishes one sign-in. A recovery code is spent by its use. Five wrong codes end the interaction (`410 token_spent`). A browser gets ' +
+            `a \`303\` to ${done}; a JSON caller that URL as \`redirect_to\`.`),
+        step('/passkey/options', 'Answers the WebAuthn request options for a passkey sign-in or second step.', webauthnOptionsResponse, ['token_spent', 'wrong_browser'], 'Before an address is known the options name no credential, so the browser offers every discoverable passkey for `fleetless.dev` ' +
+            '(`Sign in with a passkey`); after the code step they name the account\'s own passkeys. User verification is required. The challenge ' +
+            'is bound to the interaction and single-use.'),
+        step('/passkey', 'Checks a passkey assertion; a passkey completes the sign-in on its own.', oauthRedirectResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_credentials'], '**A passkey is a full sign-in**: it proves possession and user verification, two factors, so it skips the emailed code and the ' +
+            'second step — used as the second step, it finishes it. An assertion that does not verify, or names no passkey of an account, is ' +
+            '`401 invalid_credentials`, the same answer for both. When the organisation requires two-factor, a passkey satisfies it. A browser ' +
+            `gets a \`303\` to ${done}; a JSON caller that URL as \`redirect_to\`. Audited as \`developer.login\` with \`details.method\` \`passkey\`.`),
+        page('/two-factor/setup/:id', 'Serves the "your organisation requires two-factor" choice between a passkey and an authenticator.', 'HTML. Reached when the organisation requires two-factor and the person has none; no session exists until the setup is done. Two ' +
+            'options, the passkey recommended because it also signs the person in without an emailed code. `Signed in as <email> · Sign out` ' +
+            'under it.'),
+        step('/two-factor/setup/totp', 'Starts an authenticator setup inside the sign-in and hands back its QR code and key.', twoFactorSetupResponse, ['token_spent', 'wrong_browser'], 'A browser gets the page with the QR code, the key and the confirm field; a JSON caller the secret and `otpauth_url`. Nothing is ' +
+            'stored as confirmed yet.'),
+        step('/two-factor/setup/totp/confirm', 'Confirms the new authenticator and hands back the ten recovery codes.', recoveryCodesResponse, ['validation_error', 'token_spent', 'wrong_browser', 'invalid_code'], 'A code that does not match is `400 invalid_code`. On success the authenticator is on and ten recovery codes are shown once; ' +
+            '`I saved my recovery codes` then finishes the sign-in. Audited as `developer.two_factor_added` with `details.kind` `authenticator`.'),
+        step('/two-factor/setup/passkey/options', 'Answers the WebAuthn creation options for a passkey set up inside the sign-in.', webauthnOptionsResponse, ['token_spent', 'wrong_browser'], 'The same options `POST /api/auth/passkeys/options` answers a signed-in developer: relying party `fleetless.dev`, user verification ' +
+            'required, a discoverable credential.'),
+        step('/two-factor/setup/passkey', 'Registers the passkey and hands back the ten recovery codes.', recoveryCodesResponse, ['validation_error', 'token_spent', 'wrong_browser'], 'A ceremony that does not verify is `400 validation_error`. On success the passkey is stored, named after the browser\'s device ' +
+            'where it says so, and ten recovery codes are shown once. Audited as `developer.two_factor_added` with `details.kind` `passkey`.'),
+        step('/two-factor/setup/done', 'Finishes the sign-in once the recovery codes are saved.', oauthRedirectResponse, ['token_spent', 'wrong_browser'], '`I saved my recovery codes` gates the button on the page; the step itself only checks that a second factor now exists. A browser ' +
+            `gets a \`303\` to ${done}; a JSON caller that URL as \`redirect_to\`.`),
+    ];
+}
+/**
+ * **The Fleetless-hosted pages an app falls back to**, under
+ * `/app/:appIdentifier` on the auth portal.
+ *
+ * An app that leaves one of its URLs unset gets these instead: the invitation,
+ * email-confirmation and new-password pages its mails link to, a forgot-password
+ * and a sign-up page, and the MCP sign-in. They are pages the portal serves to
+ * itself — `audience: 'internal'`, HTML only, forms with no request schema —
+ * on a neutral shell carrying the app's name, its optional logo and accent,
+ * and `Secured by Fleetless`. They call the same sign-in policy as the
+ * `/api/client/*` routes, so there is one set of rules, not two; the portal
+ * origin is always allowed for them, whatever the app's `allowed_origins`.
+ * They are not a hosted login for the app's own web UI: nothing hands a
+ * session to the app's origin.
+ *
+ * **A mailed link never spends its token on `GET`**: the `GET` renders a form,
+ * and only its `POST` spends the token — a mail scanner opening the link
+ * changes nothing. Every MCP step after the sign-in needs the browser-proof
+ * cookie set there. A done page offers `Open <app>` when the app's `app_url`
+ * is set, and `You can close this tab` otherwise; a spent or expired link
+ * renders one `410` page with the next step for its kind.
+ */
+const HOSTED_TOKEN = {
+    name: 'token',
+    description: 'The opaque token from the mailed link; it is never sent as a query parameter.',
+};
+const HOSTED_INTERACTION = {
+    name: 'interaction',
+    description: 'The interaction id `GET /mcp/:appIdentifier/oauth/authorize` put into the hosted MCP sign-in URL.',
+};
+function hostedPage(method, path, summary, notes, params = []) {
+    return {
+        method, path: `/app/:appIdentifier${path}`, section: 'client-auth', summary,
+        audience: 'internal', auth: 'none', rateLimited: method === 'POST', ownerTier: false, status: 200,
+        params: [APP_IDENTIFIER, ...params], query: null, request: null, response: null,
+        errors: method === 'POST' ? ['rate_limited'] : [], transport: 'http', notes,
+    };
+}
+const HOSTED_FORM = 'Renders a form; only its `POST` spends the token, so a mail scanner opening the link changes nothing. ';
+const HOSTED_DEAD = 'A spent, expired or unknown token renders the `410` page with the next step for its kind.';
+const HOSTED_POST = 'HTML: the next page on success, the same page with the problem named on a refusal. ';
+const HOSTED_APP_ROUTES = [
+    hostedPage('GET', '/logo', "Serves the app's logo for its hosted pages.", 'The stored PNG or SVG, as written through `PUT /api/apps/:id/auth-config/logo`; `404` when the app has none. **Served sandboxed**: ' +
+        '`X-Content-Type-Options: nosniff` and `Content-Security-Policy: default-src \'none\'; style-src \'unsafe-inline\'; sandbox`, so a ' +
+        'script inside an SVG never runs, even opened directly. The hosted pages embed it as an image only.'),
+    hostedPage('GET', '/mcp/:interaction', 'Serves the hosted MCP sign-in, the page an unset `mcp_login_url` falls back to.', 'HTML: the app\'s identity providers, then the sign-in the app offers — email and password with `Email me a sign-in code instead`, ' +
+        'or email and `Email me a code` for a code-only app — and `Create one` when self-registration is on. A dead interaction renders the ' +
+        '`410` page. The browser-proof cookie is set here.', [HOSTED_INTERACTION]),
+    hostedPage('POST', '/mcp/:interaction/password', 'Checks the email and password of the hosted MCP sign-in.', HOSTED_POST + 'One refusal for every miss, as `POST /api/client/login` answers. With a second factor to give, the two-factor page ' +
+        'follows; otherwise the consent page.', [HOSTED_INTERACTION]),
+    hostedPage('POST', '/mcp/:interaction/code', 'Mails a sign-in code for the hosted MCP sign-in and renders the code page.', HOSTED_POST + 'The same page for a known and an unknown address, as `POST /api/client/login/code` answers; six boxes, `Resend code ' +
+        'in 0:42`, and `Use password instead` where the app has passwords on.', [HOSTED_INTERACTION]),
+    hostedPage('POST', '/mcp/:interaction/code/verify', 'Checks the emailed code of the hosted MCP sign-in.', HOSTED_POST + 'A wrong code renders the code page with the attempts left; a spent one asks for a new code. With a second factor to ' +
+        'give, the two-factor page follows; otherwise the consent page.', [HOSTED_INTERACTION]),
+    hostedPage('POST', '/mcp/:interaction/consent', 'Records the allow-or-deny of the hosted MCP sign-in and sends the browser back to the client.', 'Answers a `303` to the MCP client\'s callback, carrying the code or `error=access_denied`, as `POST ' +
+        '/api/client/mcp/interactions/:id/approve` and `…/deny` do. Fail-closed: anything but the Allow value denies. The browser-proof cookie ' +
+        'set at the sign-in must match, or the `wrong_browser` page renders.', [HOSTED_INTERACTION]),
+    hostedPage('POST', '/two-factor', 'Checks an authenticator or recovery code on a hosted page and finishes the sign-in it interrupted.', HOSTED_POST + 'The form carries the challenge the step before answered and either `code` or `recovery_code`, checked as `POST ' +
+        '/api/client/two-factor/verify` checks them. Success continues where the sign-in was going: the MCP consent, or the done page.'),
+    hostedPage('POST', '/two-factor/setup', 'Starts an authenticator setup on a hosted page, when the app requires two-factor.', HOSTED_POST + 'Renders the QR code, the key with `Copy key`, and the confirm field, for the challenge the step before answered.'),
+    hostedPage('POST', '/two-factor/setup/confirm', 'Confirms the new authenticator on a hosted page and shows the ten recovery codes.', HOSTED_POST + 'A wrong code renders the setup page again. On success the ten recovery codes are shown once, with `Copy` and `Download ' +
+        '.txt`; `I saved my recovery codes` gates `Continue`.'),
+    hostedPage('GET', '/invite/:token', 'Serves the hosted invitation page, the one an unset `invite_url` falls back to.', 'HTML. ' + HOSTED_FORM + 'Asks for a name, and a password only while the app has passwords on; announces the two-factor setup when ' +
+        'the app requires it. ' + HOSTED_DEAD, [HOSTED_TOKEN]),
+    hostedPage('POST', '/invite', 'Accepts an invitation from the hosted invitation page.', HOSTED_POST + 'Spends the token as `POST /api/client/invitations/accept` does; the two-factor setup follows when the app requires it, ' +
+        'then the done page.'),
+    hostedPage('GET', '/reset/:token', 'Serves the hosted new-password page, the one an unset `reset_url` falls back to.', 'HTML. ' + HOSTED_FORM + 'Says that two-factor stays on. ' + HOSTED_DEAD, [HOSTED_TOKEN]),
+    hostedPage('POST', '/reset', 'Sets the new password from the hosted new-password page.', HOSTED_POST + 'Spends the token as `POST /api/client/password/reset/confirm` does; a person with an authenticator gives a code ' +
+        'before the done page.'),
+    hostedPage('GET', '/forgot', 'Serves the hosted "forgot your password" page.', 'HTML: the address field. Reached from the hosted sign-in and the dead-link page.'),
+    hostedPage('POST', '/forgot', 'Mails a reset link from the hosted "forgot your password" page.', HOSTED_POST + 'The same "check your mail" page for a known and an unknown address, as `POST /api/client/password/reset` answers.'),
+    hostedPage('GET', '/sign-up', 'Serves the hosted sign-up page, when the app has self-registration on.', 'HTML: the address, a password while the app has passwords on, and an optional name. With self-registration off it renders the ' +
+        '"registration closed" page.'),
+    hostedPage('POST', '/sign-up', 'Creates an account from the hosted sign-up page and mails the confirmation link.', HOSTED_POST + 'Registers as `POST /api/client/register` does, and renders the same "check your mail" page for a new and a known ' +
+        'address.'),
+    hostedPage('GET', '/verify/:token', 'Serves the hosted email-confirmation page, the one an unset `verify_url` falls back to.', 'HTML. ' + HOSTED_FORM + HOSTED_DEAD, [HOSTED_TOKEN]),
+    hostedPage('POST', '/verify', 'Confirms the address from the hosted email-confirmation page.', HOSTED_POST + 'Spends the token as `POST /api/client/verify-email` does; the two-factor setup follows when the app requires it, then ' +
+        'the done page.'),
+];
 export const ROUTES = [
     /* ------------------------------------------------------------- health */
     {
@@ -123,16 +282,6 @@ export const ROUTES = [
             '`/healthz` must never itself be a reason the process looks down. Read `ok`, not the status code.',
     },
     /* ----------------------------------------------------- developer auth */
-    {
-        method: 'POST', path: '/api/auth/signup', section: 'developer-auth',
-        summary: 'Creates an org and its founding Owner, and answers a developer session.',
-        audience: 'developer', auth: 'none', rateLimited: true, ownerTier: false, status: 201,
-        params: [], query: null, request: signUpRequest, response: signUpResponse,
-        errors: ['rate_limited', 'signup_closed', 'validation_error', 'email_taken'], transport: 'http',
-        notes: 'While the deployment runs in closed beta this answers `403 signup_closed` before it looks at the body — there is nothing for a ' +
-            'validation message, or an `email_taken` answer, to be right about when nothing will be created. Email is globally unique, so an ' +
-            'address already registered in any org is refused.',
-    },
     {
         method: 'POST', path: '/api/auth/refresh', section: 'developer-auth',
         summary: 'Rotates a developer refresh token and mints a fresh access token.',
@@ -140,7 +289,7 @@ export const ROUTES = [
         params: [], query: null, request: refreshRequest, response: sessionTokens,
         errors: ['rate_limited', 'validation_error', 'token_expired', 'token_revoked'], transport: 'http',
         notes: 'The whole family is re-checked here, not just the token: an account that has been removed from the org, or whose `token_version` was ' +
-            'bumped by a password change, cannot mint a fresh console token and answers `token_revoked`. Refusing that only on the other routes ' +
+            'bumped by an owner\'s two-factor reset, cannot mint a fresh console token and answers `token_revoked`. Refusing that only on the other routes ' +
             'would leave a session that is dead everywhere but here.',
     },
     {
@@ -170,46 +319,94 @@ export const ROUTES = [
             'held writes nothing and records no audit event — the org activity stream reaches every developer with the console open, and an event ' +
             'for a no-op would misreport that something changed.',
     },
+    /* ------------------------------------ a developer's own second factors */
     {
-        method: 'POST', path: '/api/auth/password/change', section: 'developer-auth',
-        summary: 'Verifies the current password, sets a new one and answers a fresh session.',
+        method: 'GET', path: '/api/auth/two-factor', section: 'developer-auth',
+        summary: "Answers the calling developer's passkeys, authenticator, recovery codes left and the org's policy.",
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [], query: null, request: passwordChangeRequest, response: sessionTokens,
-        errors: [...DEVELOPER_GUARD, 'validation_error', 'invalid_credentials'], transport: 'http',
-        notes: 'Every session of this account ends, including the caller\'s — the request carries nothing identifying its own refresh family, so there ' +
-            'is none to spare. The answer is a working replacement pair, which is what the promise has to mean when nothing distinguishes one ' +
-            'session from another.',
+        params: [], query: null, request: null, response: developerTwoFactor,
+        errors: [...DEVELOPER_GUARD], transport: 'http',
+        notes: 'What Settings › Profile › Security draws. No key material, secret or code travels here — the passkeys are names and dates, the ' +
+            'authenticator is a date, the recovery codes are a count.',
     },
     {
-        method: 'POST', path: '/api/auth/password/reset', section: 'developer-auth',
-        summary: 'Mails a password-reset link to the address, and answers the same either way.',
-        audience: 'developer', auth: 'none', rateLimited: true, ownerTier: false, status: 202,
-        params: [], query: null, request: passwordResetRequest, response: null,
-        errors: ['rate_limited', 'validation_error'], transport: 'http',
-        notes: 'Status, body and timing are identical for a known and an unknown address — any difference is an account-enumeration oracle, which is ' +
-            'why the unknown branch still pays a real SMTP round trip to a discard address. An account provisioned through OIDC has no Fleetless ' +
-            'password and is mailed nothing. A browser form post gets a `303` to the "check your mail" card instead of this `202`.',
+        method: 'POST', path: '/api/auth/passkeys/options', section: 'developer-auth',
+        summary: 'Answers the WebAuthn creation options for registering a passkey.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: webauthnOptionsResponse,
+        errors: [...DEVELOPER_GUARD], transport: 'http',
+        notes: 'Hand `options` to the browser\'s WebAuthn API as it is. The relying party is `fleetless.dev`, so the passkey works on the auth ' +
+            'portal and in the console alike; user verification is required and the credential is discoverable, so it can sign the person in ' +
+            'without an address. The passkeys the caller already has are excluded. The challenge is single-use and expires with the ceremony.',
     },
-    /* ------------------------------------------- client auth (portal pages) */
     {
-        method: 'GET', path: '/reset-password', section: 'client-auth',
-        summary: 'Serves the auth portal\'s "forgot your password" card as an HTML page.',
-        audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
-        params: [], query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML, not JSON: this is a page a person opens, served by the cloud from the auth portal origin. `?sent=1` draws the "check your mail" ' +
-            'state instead — one path, because that second card has no inputs and a second path would exist only to be redirected to. The value is ' +
-            'caller-settable and discloses nothing, since the page it draws is a constant.',
+        method: 'POST', path: '/api/auth/passkeys', section: 'developer-auth',
+        summary: 'Registers a passkey from the browser\'s answer to the creation options.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 201,
+        params: [], query: null, request: createPasskeyRequest, response: createPasskeyResponse,
+        errors: [...DEVELOPER_GUARD, 'validation_error'], transport: 'http',
+        notes: 'A ceremony that does not verify — a wrong challenge, origin or relying party, no user verification — is `400 validation_error` ' +
+            'naming `credential`. When this is the account\'s first second factor, ten recovery codes are issued and answered once; otherwise ' +
+            '`recovery_codes` is `null` and the existing ones stay valid. Audited as `developer.two_factor_added` with `details.kind` `passkey`.',
     },
     {
-        method: 'GET', path: '/reset-password/:token', section: 'client-auth',
-        summary: 'Serves the "pick a new password" page for a mailed reset link.',
-        audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'token', description: 'The opaque reset token from the mailed link; it is never sent as a query parameter.' }],
-        query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML. An unknown, spent or expired token renders one "link no longer valid" page at `410` — they are one refusal on the wire already, ' +
-            'and splitting them here would tell a stranger which tokens ever existed. No rate limiter: the GET changes nothing, and the POST it ' +
-            'leads to is limited per IP.',
+        method: 'PATCH', path: '/api/auth/passkeys/:id', section: 'developer-auth',
+        summary: "Renames one of the caller's passkeys.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The passkey\'s uuid, as listed by `GET /api/auth/two-factor`; another person\'s passkey answers `404`.' }],
+        query: null, request: renamePasskeyRequest, response: developerPasskey,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
+    },
+    {
+        method: 'DELETE', path: '/api/auth/passkeys/:id', section: 'developer-auth',
+        summary: "Removes one of the caller's passkeys.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
+        params: [{ name: 'id', description: 'The passkey\'s uuid, as listed by `GET /api/auth/two-factor`; another person\'s passkey answers `404`.' }],
+        query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'target_state_conflict'], transport: 'http',
+        notes: '`409 target_state_conflict` names `two_factor` with rule `required_by_org` when this is the caller\'s last second factor and the ' +
+            'organisation requires one. Removing the last one otherwise also voids the recovery codes. Audited as `developer.two_factor_removed` ' +
+            'with `details.kind` `passkey`.',
     },
+    {
+        method: 'POST', path: '/api/auth/totp', section: 'developer-auth',
+        summary: 'Starts an authenticator setup and answers its secret and otpauth URL.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: twoFactorSetupResponse,
+        errors: [...DEVELOPER_GUARD], transport: 'http',
+        notes: 'The secret is pending until `POST /api/auth/totp/confirm` accepts a code from it; a second call replaces a pending secret. A ' +
+            'developer who already has an authenticator keeps it until the new one is confirmed, which is how `Replace…` works.',
+    },
+    {
+        method: 'POST', path: '/api/auth/totp/confirm', section: 'developer-auth',
+        summary: 'Confirms the pending authenticator with a code it shows now.',
+        audience: 'developer', auth: 'developer', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: totpConfirmRequest, response: totpConfirmResponse,
+        errors: [...DEVELOPER_GUARD, 'rate_limited', 'validation_error', 'invalid_code', 'token_spent'], transport: 'http',
+        notes: 'A code that does not match the pending secret is `400 invalid_code`; no pending setup is `410 token_spent`. On success the new ' +
+            'authenticator replaces any earlier one. Ten recovery codes are answered when it is the account\'s first second factor, otherwise ' +
+            '`null`. Audited as `developer.two_factor_added` with `details.kind` `authenticator`.',
+    },
+    {
+        method: 'DELETE', path: '/api/auth/totp', section: 'developer-auth',
+        summary: "Removes the caller's authenticator app.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
+        params: [], query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'not_found', 'target_state_conflict'], transport: 'http',
+        notes: '`404 not_found` when there is no authenticator. `409 target_state_conflict` names `two_factor` with rule `required_by_org` when it ' +
+            'is the caller\'s last second factor and the organisation requires one. Audited as `developer.two_factor_removed` with ' +
+            '`details.kind` `authenticator`.',
+    },
+    {
+        method: 'POST', path: '/api/auth/recovery-codes', section: 'developer-auth',
+        summary: 'Issues ten new recovery codes and voids the old ones.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: recoveryCodesResponse,
+        errors: [...DEVELOPER_GUARD, 'target_state_conflict'], transport: 'http',
+        notes: 'The codes are shown this once. `409 target_state_conflict` names `two_factor` with rule `off` when the caller has no second factor: ' +
+            'recovery codes only stand in for one. Audited as `developer.recovery_codes_generated`.',
+    },
+    /* ------------------------------------------- client auth (portal pages) */
     {
         method: 'GET', path: '/favicon.svg', section: 'client-auth',
         summary: 'Serves the Fleetless icon for the auth portal\'s and the MCP welcome page\'s browser tab.',
@@ -218,16 +415,6 @@ export const ROUTES = [
         notes: 'An SVG, not JSON. Those pages carry a Content-Security-Policy that admits no `data:` image, so the icon is a file on their own ' +
             'origin — the one source `img-src \'self\'` names. Cached for a day: the bytes change when the brand does, not per deploy.',
     },
-    {
-        method: 'POST', path: '/api/auth/password/reset/confirm', section: 'developer-auth',
-        summary: 'Spends a reset token, sets the new password and ends every session of the account.',
-        audience: 'developer', auth: 'none', rateLimited: true, ownerTier: false, status: 204,
-        params: [], query: null, request: passwordResetConfirm, response: null,
-        errors: ['rate_limited', 'validation_error', 'token_spent'], transport: 'http',
-        notes: 'Unknown, spent and expired tokens all answer `410 token_spent`. Sessions are revoked under the account\'s actual kind — a console admin ' +
-            'holds developer sessions, an app user holds end-user ones — so an app user\'s open `/realtime` socket does not outlive the reset. ' +
-            'A browser form post gets the rendered "done" page instead of this `204`.',
-    },
     {
         method: 'POST', path: '/api/waitlist', section: 'developer-auth',
         summary: 'Adds an address to the closed-beta waiting list.',
@@ -329,7 +516,7 @@ export const ROUTES = [
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: null, response: role,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error'], transport: 'http',
-        notes: 'The body is `{ "name": string }` — non-empty, trimmed, at most 60 characters as on `role.name` — and is deliberately not a contract shape: contracts ' +
+        notes: 'The body is `{ "name": string }` — non-empty, trimmed, at most 120 characters — and is deliberately not a contract shape: contracts ' +
             'define the `role` this answers with, not this one trivial request. **The answer is a bare `role`, not an envelope**, unlike the ' +
             'listing beside it.',
     },
@@ -382,33 +569,6 @@ export const ROUTES = [
             'offered and consults nothing about any user\'s actual MCP entitlement. A robot the role grants nothing on still appears, with an empty ' +
             '`exposures` — dropping it would read as "not attached", which is a different fact.',
     },
-    {
-        method: 'PATCH', path: '/api/apps/:id/roles/:roleId', section: 'apps',
-        summary: 'Renames a role; its users keep it.',
-        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
-        params: [
-            { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
-            { name: 'roleId', description: 'The role\'s uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.' },
-        ],
-        query: null, request: roleRenameRequest, response: role,
-        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'role_name_taken'], transport: 'http',
-        notes: 'Names are unique per app, compared exactly as stored after trimming. Built-in roles can be renamed.',
-    },
-    {
-        method: 'DELETE', path: '/api/apps/:id/roles/:roleId', section: 'apps',
-        summary: 'Deletes a role, moving its users, pending invitations and default-role status to another role.',
-        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
-        params: [
-            { name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' },
-            { name: 'roleId', description: 'The role\'s uuid, from `GET /api/apps/:id/roles`; a role of another app answers `404`.' },
-        ],
-        query: roleDeleteQuery, request: null, response: null,
-        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found', 'validation_error', 'role_in_use', 'last_role'], transport: 'http',
-        notes: 'Without `move_to`, a role that app users or pending invitations hold, or that is the app\'s default, answers ' +
-            '`409 role_in_use` with `{ users, invitations, is_default }`. With `move_to` — another role of the same app, else ' +
-            '`400 validation_error` — one transaction moves `app_users.role_id`, pending invitations and `default_role_id`, then deletes ' +
-            'the role and its permissions. The app\'s only role answers `409 last_role`. Built-in roles can be deleted like any other.',
-    },
     {
         method: 'POST', path: '/api/apps/:id/server-keys', section: 'apps',
         summary: 'Mints a server key for the app and returns the raw secret once.',
@@ -540,13 +700,25 @@ export const ROUTES = [
         notes: 'The support door beside `POST /api/client/password/reset`: the same one-hour token and the same link, triggered by a developer for a ' +
             'user who asked them rather than the form. **No enumeration discipline applies** — the caller is authenticated into the app and can read ' +
             'the user list — so this one answers what actually happened: `{ "mail": mailStatus }`, where `not_configured` is a deployment without a ' +
-            'mailer and `failed` is the state worth somebody\'s attention. `409 target_state_conflict` names `reset_url` when the app has configured ' +
-            'none: the token would be minted and the link would point nowhere, so nothing is minted. The same `409` names `password` with rule ' +
+            'mailer and `failed` is the state worth somebody\'s attention. The link points at the app\'s `reset_url`, or at the hosted reset page ' +
+            'when the app has configured none. `409 target_state_conflict` names `password` with rule ' +
             '`not_set` for an account that has none — an OIDC-only app user, whom a reset link would hand a second, quieter door — and `status` ' +
             'with rule `blocked` for a blocked one, since `POST /api/client/password/reset` mails a blocked account nothing and the two doors may ' +
             'not disagree. Setting the password directly is deliberately not offered; a developer who could would hold their customers\' ' +
             'credentials.',
     },
+    {
+        method: 'DELETE', path: '/api/apps/:id/users/:userId/two-factor', section: 'apps',
+        summary: "Removes an app user's authenticator and recovery codes and ends every session they hold.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 204,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }, { name: 'userId', description: 'The app user\'s uuid, from `GET /api/apps/:id/users`; a user of another app answers `404`.' }],
+        query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: 'The support door for a person who lost their authenticator and their recovery codes. The authenticator and every recovery code go, ' +
+            'and so does every session of the account — whoever held one may be the reason for the reset. **A user with no second factor answers ' +
+            '`204` too**: that is the end state being asked for. When the app requires two-factor, the person sets it up again at their next ' +
+            'sign-in, before any session exists. Audited as `app_user.two_factor_reset`.',
+    },
     /* ---------------------------- the MCP clients one app user has connected */
     {
         method: 'GET', path: '/api/apps/:id/users/:userId/mcp-grants', section: 'apps',
@@ -613,11 +785,9 @@ export const ROUTES = [
         transport: 'http',
         notes: '**An app user, not a team member.** `POST /api/org/invitations` is the other space and leads to the console; this link leads into the ' +
             'developer\'s own app. The role is resolved and stored now, so a later change to `default_role_id` does not re-aim a link already sent. ' +
-            'An invitation **always bypasses `allowed_domains`**. \n\nThe answer carries `accept_url`, which is `null` when the app has configured no ' +
-            '`invite_url` — there is nowhere for the link to point, and Fleetless serves an app user no page of its own. That is a `201` with a ' +
-            'null link, not a refusal: the invitation exists and a developer may hand the token over by another route. Asking to **mail** it in that ' +
-            'state is `409 target_state_conflict` naming `invite_url`, because a mail carrying a dead link is worse than no mail. The same `409` ' +
-            'names `default_role_id` when `role_id` is absent and the app has no default role, or its default no longer resolves: an invitation ' +
+            'An invitation **always bypasses `allowed_domains`**. \n\nThe answer carries `accept_url`: the app\'s `invite_url` with the token in it, ' +
+            'or the Fleetless-hosted invitation page when the app has configured none — so mailing it is never refused for a missing URL. ' +
+            '`409 target_state_conflict` names `default_role_id` when `role_id` is absent and the app has no default role, or its default no longer resolves: an invitation ' +
             'that names no role has nothing to hand its acceptor, so it is refused here rather than at the acceptance a week later. `409 ' +
             'email_taken` is an address the app already has as a user; `404 not_found` is the app or a `role_id` that is not one of its roles. ' +
             '\n\nCreating shares the reissue route\'s ceiling of **five invitation mails a minute per app**, answering `429 rate_limited` with ' +
@@ -728,7 +898,7 @@ export const ROUTES = [
     /* ------------------------------- the app's auth configuration and mails */
     {
         method: 'GET', path: '/api/apps/:id/auth-config', section: 'apps',
-        summary: "Reads the app's auth settings: self-registration, domains, origins, URLs and the MCP switch.",
+        summary: "Reads the app's auth settings: sign-in methods, two-factor, registration, pages, the hosted look and the MCP switch.",
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: null, response: appAuthConfig,
@@ -738,7 +908,8 @@ export const ROUTES = [
             'for every app and every provider, and is the value a developer registers at their identity provider. It stays read-only on every slice ' +
             'write below for a second reason: a writable callback URL would let a caller point the return leg of an OIDC sign-in, which carries an ' +
             'authorization code, at a host they own. `updated_at` is read-only for a duller one: the server stamps it on every write, and a ' +
-            'client-supplied value would be a lie about when the row last changed.',
+            'client-supplied value would be a lie about when the row last changed. `hosted_pages` and `hosted_logo_url` are read-only as well: ' +
+            'the cloud mints both from the auth portal\'s base URL and the app\'s identifier.',
     },
     {
         method: 'PUT', path: '/api/apps/:id/auth-config/registration', section: 'apps',
@@ -753,37 +924,83 @@ export const ROUTES = [
             '\n\n`400 validation_error` is where the two field rules land: an entry in `allowed_domains` must be lowercase, since a capitalised one ' +
             'can never match a lowercased address, and an entry in `allowed_origins` must be a bare scheme-host-port with no path, since a browser ' +
             'sends nothing longer in its `Origin` header. Each refuses at configuration time rather than failing silently later. ' +
-            '\n\nThe merge is server-side against the stored row, so this write never disturbs the urls or mcp slice.',
+            '\n\nThe merge is server-side against the stored row, so this write never disturbs another slice.',
+    },
+    {
+        method: 'PUT', path: '/api/apps/:id/auth-config/sign-in', section: 'apps',
+        summary: 'Replaces how the app\'s users sign in and whether they give a second factor.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
+        query: null, request: putAppAuthSignInRequest, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
+        notes: '**A replace, not a merge, and `.strict()`**: `sign_in_methods` and `two_factor` both arrive or the write is refused. Both methods off ' +
+            'is `400 validation_error` naming `sign_in_methods.password` — an app needs at least one door besides its identity providers. ' +
+            '\n\nTurning a method off refuses its routes with `method_not_allowed` from the next request on; a stored password stays stored. ' +
+            'Setting `two_factor` to `required` signs nobody out: each person without an authenticator sets one up at their next sign-in, before ' +
+            'any session exists. Audited with both old and new values. The merge is server-side against the stored row, so this write never ' +
+            'disturbs another slice.',
     },
     {
         method: 'PUT', path: '/api/apps/:id/auth-config/urls', section: 'apps',
-        summary: "Replaces the three pages Fleetless's mails point at.",
+        summary: "Replaces the app's home page and the four pages Fleetless's mails and MCP sign-in point at.",
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: putAppAuthUrlsRequest, response: appAuthConfig,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
-        notes: '**A replace, not a merge, and `.strict()`**: `invite_url`, `verify_url` and `reset_url` all arrive or the write is refused, so a ' +
-            'client built against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are ' +
-            'the server\'s, refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
-            '\n\n`400 validation_error` is where the field rule lands: a URL template must be https (or `http` on `localhost`) and carry its ' +
+        notes: '**A replace, not a merge, and `.strict()`**: `app_url`, `invite_url`, `verify_url`, `reset_url` and `mcp_login_url` all arrive or ' +
+            'the write is refused, so a client built against an older shape cannot silently clear a setting it does not know about. ' +
+            '`oidc_callback_url` and `updated_at` are the server\'s, refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
+            '\n\nEach may be `null`, and then the Fleetless-hosted page in `hosted_pages` stands in for it: nothing is refused for a missing URL. ' +
+            '`400 validation_error` is where the field rules land: a URL template must be https (or `http` on `localhost`) and carry its ' +
             'placeholder exactly once — a second occurrence leaves one literal in a mailed link, refused here rather than failing silently once ' +
-            'the mail is sent. ' +
-            '\n\nThe merge is server-side against the stored row, so this write never disturbs the registration or mcp slice.',
+            'the mail is sent — and `app_url` takes the same host rule with no placeholder. `mcp_login_url` moved here from the `mcp` slice, ' +
+            'because one screen owns all four pages. ' +
+            '\n\nThe merge is server-side against the stored row, so this write never disturbs another slice.',
     },
     {
         method: 'PUT', path: '/api/apps/:id/auth-config/mcp', section: 'apps',
-        summary: 'Replaces the MCP switch and its login URL together.',
+        summary: 'Turns the app\'s MCP endpoint on or off.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: putAppAuthMcpRequest, response: appAuthConfig,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
-        notes: '**A replace, not a merge, and `.strict()`**: `mcp_enabled` and `mcp_login_url` both arrive or the write is refused, so a client built ' +
-            'against an older shape cannot silently clear a setting it does not know about. `oidc_callback_url` and `updated_at` are the server\'s, ' +
-            'refused in this body as in every slice\'s — see `GET`\'s notes for why. ' +
-            '\n\n`mcp_login_url` answers to the same rule as the `urls` slice\'s three templates — https (or `http` on `localhost`), its placeholder ' +
-            'exactly once — refused as `400 validation_error` rather than left to fail mid-OAuth, in a client\'s browser where no console screen ' +
-            'is watching. ' +
-            '\n\nThe merge is server-side against the stored row, so this write never disturbs the registration or urls slice.',
+        notes: '**A replace, not a merge, and `.strict()`**: `mcp_enabled` arrives or the write is refused. It used to take `mcp_login_url` as ' +
+            'well, because on without a URL refused every sign-in; the hosted MCP sign-in now stands in for an unset URL, and the URL moved to ' +
+            'the `urls` slice. A body still carrying it is `400 validation_error`. `oidc_callback_url` and `updated_at` are the server\'s, ' +
+            'refused in this body as in every slice\'s. The merge is server-side against the stored row, so this write never disturbs another slice.',
+    },
+    {
+        method: 'PUT', path: '/api/apps/:id/auth-config/look', section: 'apps',
+        summary: "Replaces the hosted pages' accent colour.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
+        query: null, request: putAppAuthLookRequest, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found'], transport: 'http',
+        notes: '**A replace, and `.strict()`**: `hosted_accent` arrives, `#rrggbb` in lowercase, or `null` for the neutral shell\'s own accent. ' +
+            'The logo is its own write, `PUT /api/apps/:id/auth-config/logo`, because it is an image rather than a field. The merge is ' +
+            'server-side against the stored row, so this write never disturbs another slice.',
+    },
+    {
+        method: 'PUT', path: '/api/apps/:id/auth-config/logo', section: 'apps',
+        summary: "Stores the logo the hosted pages show above the app's name.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
+        query: null, request: null, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'validation_error', 'not_found', 'unsupported_media_type'], transport: 'http',
+        notes: 'The body is the **raw image**, not JSON, so it has no request schema: `Content-Type` is one of `HOSTED_LOGO_TYPES` (`image/png`, ' +
+            '`image/svg+xml`) and anything else is `415 unsupported_media_type`. At most `HOSTED_LOGO_MAX_BYTES` (100 KB); a larger body, or one ' +
+            'that is not the image its type names, is `400 validation_error`. A new logo replaces the stored one. The hosted pages load it from ' +
+            '`hosted_logo_url` as an image only, and the cloud serves an SVG sandboxed, so a script inside one never runs.',
+    },
+    {
+        method: 'DELETE', path: '/api/apps/:id/auth-config/logo', section: 'apps',
+        summary: 'Removes the logo from the hosted pages.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
+        query: null, request: null, response: appAuthConfig,
+        errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
+        notes: 'Answers the whole configuration, with `hosted_logo_url` now `null`; the hosted pages show the app\'s name alone. An app with no ' +
+            'logo answers the same: that is the end state being asked for.',
     },
     {
         method: 'GET', path: '/api/apps/:id/mail-templates', section: 'apps',
@@ -792,9 +1009,9 @@ export const ROUTES = [
         params: [{ name: 'id', description: 'The app\'s uuid, as returned by `POST /api/apps` or listed by `GET /api/apps`.' }],
         query: null, request: null, response: appMailTemplateListResponse,
         errors: [...DEVELOPER_GUARD, 'invalid_uuid', 'not_found'], transport: 'http',
-        notes: 'Answers `{ "templates": [appMailTemplate, …] }` with **only the kinds that have a custom template** — at most three. A kind that does ' +
+        notes: 'Answers `{ "templates": [appMailTemplate, …] }` with **only the kinds that have a custom template** — at most four. A kind that does ' +
             'not appear is one using the Fleetless default text, which is an ordinary state and not a missing row. Mails to *Fleetless* users, a ' +
-            'team invitation or a console password reset, are not in this list and are deliberately not customisable: they are about this platform, ' +
+            'team invitation or a console sign-in code, are not in this list and are deliberately not customisable: they are about this platform, ' +
             'not about the developer\'s product.',
     },
     {
@@ -936,13 +1153,15 @@ export const ROUTES = [
     },
     {
         method: 'POST', path: '/api/org/invitations/accept', section: 'users',
-        summary: 'Spends an invitation token and creates the login it was addressed to.',
+        summary: 'Spends an invitation token and creates the account it was addressed to.',
         audience: 'developer', auth: 'none', rateLimited: true, ownerTier: false, status: 204,
         params: [], query: null, request: acceptTeamInviteRequest, response: null,
         errors: ['rate_limited', 'validation_error', 'token_spent', 'email_taken'], transport: 'http',
         notes: '**`204`, not a session.** The console signs in through its own OAuth portal, so a session minted here would be a second credential door ' +
-            'for one account — and every security property would then have to be right in two places. Unknown, expired and already-accepted tokens ' +
-            'collapse into `410 token_spent`. A browser form post gets the rendered "you\'re in" page instead.',
+            'for one account — and every security property would then have to be right in two places. **No password**: the mailed link proves the ' +
+            'address, so accepting needs no code either, and the new member signs in by emailed code from then on. When the organisation requires ' +
+            'two-factor, the member sets one up at their first sign-in. Unknown, expired and already-accepted tokens collapse into `410 token_spent`. ' +
+            'A browser form post gets the rendered "you\'re in" page instead.',
     },
     {
         method: 'GET', path: '/accept-invite/:token', section: 'users',
@@ -950,9 +1169,10 @@ export const ROUTES = [
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'token', description: 'The opaque invitation token from the mailed link; it is never sent as a query parameter.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML, served by the cloud from the auth portal origin; the form on it posts to `POST /api/org/invitations/accept`. An unknown, ' +
-            'spent or expired token renders the "link no longer valid" page at `410`, which offers the password-reset page — the only self-service ' +
-            'door the portal has, since an invitation cannot be re-issued by the person holding it.',
+        notes: 'HTML, served by the cloud from the auth portal origin; the form on it posts to `POST /api/org/invitations/accept`. **The GET spends ' +
+            'nothing** — a mail scanner opening the link must not accept the invitation — only the form\'s POST does. An unknown, spent or ' +
+            'expired token renders the "link no longer valid" page at `410`, which says to ask the organisation for a new invitation: the person ' +
+            'holding a dead link cannot re-issue it.',
     },
     {
         method: 'PATCH', path: '/api/org/users/:id', section: 'users',
@@ -992,15 +1212,30 @@ export const ROUTES = [
             'transaction rather than by a read beforehand. Setting the tier already held changes nothing and writes no audit event. No session is ' +
             'revoked: a tier is re-read from the row on every request, so no issued token carries a stale copy of it.',
     },
+    {
+        method: 'DELETE', path: '/api/org/users/:id/two-factor', section: 'users',
+        summary: "Removes a team member's passkeys, authenticator and recovery codes and ends their sessions.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 204,
+        params: [{ name: 'id', description: 'The Fleetless user\'s uuid, as listed by `GET /api/org/users`.' }],
+        query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'tier_required', 'invalid_uuid', 'not_found', 'target_state_conflict'], transport: 'http',
+        notes: 'Owner tier: the door for a member who lost every second factor and every recovery code. Every session of the member ends, and when ' +
+            'the organisation requires two-factor they set one up again at their next sign-in. **An owner cannot reset their own** — `409 ' +
+            'target_state_conflict` naming `user_id` with rule `self`; Settings › Profile is where they change it. A member with no second factor ' +
+            'answers `204` too. Audited as `developer.two_factor_reset`, naming the owner who did it.',
+    },
     {
         method: 'PATCH', path: '/api/org', section: 'org',
-        summary: 'Renames the org.',
+        summary: 'Renames the org, requires two-factor for its members, or both.',
         audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 200,
         params: [], query: null, request: patchOrgRequest, response: patchOrgResponse,
         errors: [...DEVELOPER_GUARD, 'tier_required', 'validation_error'], transport: 'http',
         notes: 'Answers `{ "org": org }`. Owner tier, and the gate runs ' +
-            'before the body is looked at, so a malformed rename and a forbidden one answer the same way. Renaming to the name already held writes ' +
-            'nothing and records no audit event.',
+            'before the body is looked at, so a malformed patch and a forbidden one answer the same way — `403 tier_required` for a developer, ' +
+            'whichever field they sent. An empty body is `400 validation_error`. Writing the values already held writes ' +
+            'nothing and records no audit event. \n\n`require_two_factor` on signs nobody out: each member without a passkey or authenticator ' +
+            'sets one up at their next sign-in, before any session exists, on the console and the central MCP endpoint alike. Server keys and ' +
+            'robot bridges are not people and are not affected. Audited as `org.two_factor_required_changed`.',
     },
     /* --------------------------------------------------------------- mcp */
     {
@@ -1050,8 +1285,8 @@ export const ROUTES = [
             'applies; those refusals are `oauthError`. Exact `redirect_uri` matching for both client kinds — the loopback-port wildcard of RFC 8252 ' +
             '§7.3 belongs to the one central client alone, whose URIs are configured ahead of time and cannot name an ephemeral port. A client that ' +
             'registered itself seconds ago can name the port it bound, and widening the wildcard there would only widen where a stolen `client_id` ' +
-            'may send a browser. Nothing about the person is decided here — the next card asks for an email address and the password step after ' +
-            'it resolves the account; this route knows only the client.',
+            'may send a browser. Nothing about the person is decided here — the next card asks for an email address, or a passkey, and the steps ' +
+            'after it resolve the account; this route knows only the client.',
     },
     {
         method: 'GET', path: '/mcp/oauth/interaction/:id', section: 'mcp',
@@ -1063,33 +1298,12 @@ export const ROUTES = [
             'the inline page it replaced was not. An expired, consumed, unknown or hand-edited interaction renders one page at `410`, and so does a ' +
             'client whose dynamic registration lapsed in between.',
     },
-    {
-        method: 'POST', path: '/mcp/oauth/identify', section: 'mcp',
-        summary: 'Takes the email address and hands back the password step.',
-        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: null, response: null,
-        errors: ['rate_limited', 'validation_error', 'token_spent'], transport: 'http',
-        notes: 'The identifier-first step, with nothing left to identify: Fleetless users are password-only, so **this step does not ' +
-            'read the address at all** — it renders the password card for a known address, an unknown one and an empty one alike, and the login ' +
-            'step below answers the same `401` for all three. That is a property of the shape rather than of two branches agreeing: there is no ' +
-            'lookup here whose result could differ. A browser form post gets the password card; a JSON caller gets `{ "next" }`, which has no ' +
-            'schema. Still rate limited per (route, ip, email), because it is an unauthenticated endpoint that renders a page.',
-    },
-    {
-        method: 'POST', path: '/mcp/oauth/login', section: 'mcp',
-        summary: 'Checks the password and hands back where the MCP sign-in continues.',
-        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: null, response: oauthRedirectResponse,
-        errors: ['rate_limited', 'validation_error', 'token_spent', 'invalid_credentials'], transport: 'http',
-        notes: 'The body is `{ "interaction_id", "email", "password" }`, read field by field rather than through a contract shape. A browser gets a ' +
-            '`303` — to the consent screen for a self-registered client, or straight to the callback for the central one — where a JSON caller gets ' +
-            'this `200` and `redirect_to`.',
-    },
+    ...developerSignInRoutes('/mcp/oauth'),
     {
         method: 'GET', path: '/mcp/oauth/consent/:id', section: 'mcp',
         summary: 'Serves the consent screen for an MCP client that registered itself.',
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
-        params: [{ name: 'id', description: 'The interaction id from the sign-in; the login step redirects the browser here.' }],
+        params: [{ name: 'id', description: 'The interaction id from the sign-in; the last sign-in step redirects the browser here.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
         notes: 'HTML. The browser-proof cookie is checked on this GET, not only on the POST. The **central** client never reaches this screen and ' +
             'renders the `410` page instead: it is configured by the operator, so there is no self-registered stranger for a person to weigh up.',
@@ -1133,51 +1347,41 @@ export const ROUTES = [
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The interaction id minted by `GET /console/oauth/authorize`, which redirects the browser here.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML. An expired, consumed, unknown or hand-edited interaction renders one page at `410`: which of the four it was is not a fact a ' +
-            'stranger may learn, and to the person it is one fact anyway. The page resolves nothing about the address typed into it, so there is no ' +
-            'enumeration oracle here at all.',
-    },
-    {
-        method: 'POST', path: '/console/oauth/identify', section: 'developer-auth',
-        summary: 'Takes the email address and hands back the password step.',
-        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: null, response: null,
-        errors: ['rate_limited', 'token_spent'], transport: 'http',
-        notes: 'A browser form post gets the password card as HTML; a JSON caller gets `{ "next": "/console/oauth/login" }`, which has no schema — the ' +
-            'step made no decision, and it says so rather than inventing a redirect. A dead interaction is `410 token_spent`. Rate limited despite ' +
-            'spending no credential: it is an unauthenticated endpoint that renders a page.',
-    },
-    {
-        method: 'POST', path: '/console/oauth/login', section: 'developer-auth',
-        summary: 'Checks the password and mints the authorization code the console exchanges.',
-        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: null, response: oauthRedirectResponse,
-        errors: ['rate_limited', 'token_spent', 'invalid_credentials'], transport: 'http',
-        notes: 'This is the only place a Fleetless developer password may be typed; `POST /api/auth/login` is gone, because a second credential door ' +
-            'means every security property has to be right in two places. A browser form post gets a `303` to the callback URL; a JSON caller gets ' +
-            'that same URL as `redirect_to` at `200`. An argon2 verify runs whether or not the address exists, and the Org Admins check runs after ' +
-            'it — filtering first would hand back a faster "no" for a non-admin account, which is a timing oracle. Wrong password, unknown address ' +
-            'and "not an org admin" render identical bytes under one `401`.',
+        notes: 'HTML: the email field, `Email me a code`, and `Sign in with a passkey`. An expired, consumed, unknown or hand-edited interaction ' +
+            'renders one page at `410`: which of the four it was is not a fact a stranger may learn, and to the person it is one fact anyway. The ' +
+            'page resolves nothing about the address typed into it, so there is no enumeration oracle here at all.',
     },
+    ...developerSignInRoutes('/console/oauth'),
     {
         method: 'GET', path: '/console/oauth/signup/:id', section: 'developer-auth',
-        summary: 'Serves step one of console sign-up, the account card.',
+        summary: 'Serves step one of console sign-up, the email card.',
         audience: 'internal', auth: 'none', rateLimited: false, ownerTier: false, status: 200,
         params: [{ name: 'id', description: 'The interaction id minted by `GET /console/oauth/authorize` with `?prompt=create`.' }],
         query: null, request: null, response: null, errors: [], transport: 'http',
-        notes: 'HTML. While the deployment runs in closed beta this renders the "sign-up is closed" card at `403` instead, keeping the interaction alive ' +
-            'and pointing back at sign-in — the person may well already have an account.',
+        notes: 'HTML: the email field and `Email me a code`, the first of three steps — email, code, organization. While the deployment runs in ' +
+            'closed beta this renders the "sign-up is closed" card at `403` instead, keeping the interaction alive and pointing back at sign-in and ' +
+            'the waiting list — the person may well already have an account.',
     },
     {
         method: 'POST', path: '/console/oauth/signup', section: 'developer-auth',
-        summary: 'Takes the sign-up email and password and hands back the organization step.',
+        summary: 'Takes the sign-up email, mails a code and hands back the code step.',
         audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
         params: [], query: null, request: null, response: null,
         errors: ['rate_limited', 'token_spent', 'signup_closed', 'validation_error', 'email_taken'], transport: 'http',
-        notes: 'A browser form post gets the organization card; a JSON caller gets `{ "next", "email" }`, which has no schema. The plaintext password ' +
-            'exists for this one request: what is stored is its argon2 hash, on the interaction row, which expires with it. A per-interaction proof ' +
-            'cookie is set here — it is what stops a third party from finishing a sign-up somebody else started. Sign-up is the one surface whose job ' +
-            'is to say an address is taken, so `409 email_taken` is not a leak here.',
+        notes: 'A browser form post gets the code card; a JSON caller gets `{ "next", "email" }`, which has no schema. **No password**: the code ' +
+            'mailed here, six digits valid ten minutes, proves the address. A per-interaction proof cookie is set here — it is what stops a third ' +
+            'party from finishing a sign-up somebody else started. Sign-up is the one surface whose job is to say an address is taken, so `409 ' +
+            'email_taken` is not a leak here.',
+    },
+    {
+        method: 'POST', path: '/console/oauth/signup/code', section: 'developer-auth',
+        summary: 'Checks the sign-up code and hands back the organization step.',
+        audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: null,
+        errors: ['rate_limited', 'token_spent', 'signup_closed', 'wrong_browser', 'validation_error', 'invalid_code'], transport: 'http',
+        notes: 'A wrong code renders the code card again with the attempts left (`400 invalid_code`); a spent, expired or exhausted one is `410 ' +
+            'token_spent`. The step before must have run in **this** browser (`401 wrong_browser`). A browser form post gets the organization card, ' +
+            'the address shown `confirmed`; a JSON caller gets `{ "next" }`, which has no schema.',
     },
     {
         method: 'POST', path: '/console/oauth/signup/organization', section: 'developer-auth',
@@ -1185,9 +1389,11 @@ export const ROUTES = [
         audience: 'internal', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
         params: [], query: null, request: null, response: oauthRedirectResponse,
         errors: ['rate_limited', 'token_spent', 'signup_closed', 'wrong_browser', 'validation_error', 'email_taken'], transport: 'http',
-        notes: 'The same single transaction `POST /api/auth/signup` runs. Step one must have run in **this** browser: a missing or mismatched proof ' +
-            'cookie is `401 wrong_browser` and the person is sent back to step one. A browser form post gets a `303` to the console callback; a JSON ' +
-            'caller gets `redirect_to` at `200`.',
+        notes: 'The form carries `org_name` only. The org and its founding Owner are created in one transaction, and only after the code step ' +
+            'confirmed the address. Both steps before must have run in **this** browser: a missing or mismatched proof cookie is `401 ' +
+            'wrong_browser` and the person is sent back to step one. `409 email_taken` when the address was taken meanwhile. A browser form post ' +
+            'gets a `303` to the console callback; a JSON caller gets `redirect_to` at `200`. This is the only way an organisation is created: ' +
+            '`POST /api/auth/signup` is gone, because without a password it would hand a session to anybody who names an address.',
     },
     {
         method: 'POST', path: '/console/oauth/token', section: 'developer-auth',
@@ -1199,6 +1405,8 @@ export const ROUTES = [
             'the replay check, and the single-use consume is atomic, so exactly one caller ever mints. The Org Admins membership is re-read here: the ' +
             'code was minted earlier, and a user moved out in between must not get a console session.',
     },
+    /* --------------------------------- the Fleetless-hosted app pages */
+    ...HOSTED_APP_ROUTES,
     /* ---------------------------------------------------- mcp (the endpoint) */
     {
         method: 'GET', path: '/mcp/welcome', section: 'mcp',
@@ -1322,8 +1530,8 @@ export const ROUTES = [
             'itself and never asks a person for a `client_id`. \n\n**`issuer`, `token_endpoint` and the resource identifier are minted from the ' +
             'canonical public base, never from the friendly `mcp.fleetless.dev` alias or the request\'s `Host`**, because a client checks a minted ' +
             'token\'s `iss` and `aud` against these exact strings. \n\n**Unlike the central document, `authorization_endpoint` does not move to an ' +
-            'auth-portal origin**, and there is nothing here for one to serve: this authorization step renders no Fleetless page at all. It ' +
-            'redirects to the app\'s own `mcp_login_url`, which is on the developer\'s origin already.',
+            'auth-portal origin**: the authorization step renders no page itself. It redirects to the app\'s own `mcp_login_url`, or to the ' +
+            'hosted MCP sign-in on the auth portal when the app has configured none.',
     },
     {
         method: 'POST', path: MCP_APP.register, section: 'mcp',
@@ -1346,29 +1554,27 @@ export const ROUTES = [
     },
     {
         method: 'GET', path: MCP_APP.authorize, section: 'mcp',
-        summary: "Starts an MCP sign-in and redirects the browser to the app's own login page.",
+        summary: "Starts an MCP sign-in and redirects the browser to the app's own login page, or to the hosted one.",
         audience: 'client', auth: 'none', rateLimited: false, ownerTier: false, status: 302,
         params: [APP_IDENTIFIER], query: oauthAuthorizeQuery, request: null, response: null,
-        errors: ['not_found', 'target_state_conflict'], transport: 'http',
+        errors: ['not_found'], transport: 'http',
         notes: 'The same query as `GET /mcp/oauth/authorize`, read the same way — parameter by parameter, because the answers differ and one parse ' +
-            'would collapse them. \n\n**Fleetless renders no page here**, and that is the whole of it. The route writes an interaction — ten minutes, as the OIDC ones live ' +
+            'would collapse them. \n\n**This route renders no page.** It writes an interaction — ten minutes, as the OIDC ones live ' +
             '— and redirects to `appAuthConfig.mcp_login_url` with `{interaction}` filled in. The app then authenticates the person with its own ' +
             'UI, reads `GET /api/client/mcp/interactions/:id` to show the client\'s claimed name and the scopes it asked for, and calls approve or ' +
-            'deny. \n\nClient and `redirect_uri` are validated first and a failure there never redirects — the open-redirect discipline `GET ' +
+            'deny. **An app with no `mcp_login_url` is redirected to the hosted MCP sign-in** (`GET /app/:appIdentifier/mcp/:interaction`), ' +
+            'which runs the same steps on the auth portal; nothing is refused for a missing URL. \n\nClient and `redirect_uri` are validated first and a failure there never redirects — the open-redirect discipline `GET ' +
             '/mcp/oauth/authorize` and `GET /api/client/oidc/:slug/start` both keep — and those refusals are RFC 6749\'s flat `oauthError`, which ' +
             'is why none of them appear above. `redirect_uri` is matched **exactly** against the registration, with no loopback-port wildcard: ' +
             'every client here registered itself minutes ago and can name the port it bound, so a wildcard would only widen where a stolen ' +
-            '`client_id` may send a browser. \n\nThe two codes above are the `apiError` envelope because they are refusals about the **app**, ' +
+            '`client_id` may send a browser. \n\nThe code above is the `apiError` envelope because it is a refusal about the **app**, ' +
             'decided before an OAuth parameter is looked at. **`404 not_found` covers an identifier no app carries AND an app with MCP switched ' +
             'off** — the same single answer the two metadata documents, `register` and the transport give. An earlier draft answered `403 ' +
             'mcp_disabled` here, on the argument that a client which registered while the switch was on is owed the difference between "turned ' +
             'off" and "mistyped"; that argument does not survive the caller being anonymous. This route takes no credential, so the extra code ' +
             'was readable by anyone who could type an identifier, and it handed back precisely the existence distinction every neighbouring ' +
             'route collapses. `mcp_disabled` survives only where the caller has already proved they belong to the app — the two decision routes ' +
-            'under `/api/client/mcp/interactions/:id`. `409 ' +
-            'target_state_conflict` names `mcp_login_url` with rule `not_set`: MCP is enabled and no page is configured to send the person to. It ' +
-            'is the same code and the same shape `send_mail` answers for an unconfigured `invite_url`, and the refusal is the honest one — ' +
-            'Fleetless has nowhere to redirect, and rendering a page of its own would contradict the rule that Fleetless shows an app user no page.',
+            'under `/api/client/mcp/interactions/:id`.',
     },
     {
         method: 'POST', path: MCP_APP.token, section: 'mcp',
@@ -1390,11 +1596,40 @@ export const ROUTES = [
         method: 'POST', path: '/api/client/login', section: 'client-auth',
         summary: 'Signs an app user in with an app identifier, an email address and a password.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientLoginRequest, response: sessionTokens,
-        errors: ['rate_limited', 'validation_error', 'invalid_credentials'], transport: 'http',
+        params: [], query: null, request: clientLoginRequest, response: clientSignInResult,
+        errors: ['rate_limited', 'validation_error', 'invalid_credentials', 'method_not_allowed'], transport: 'http',
         notes: 'One refusal for every miss — unknown app, unknown address, wrong password, a `blocked` account and one still `pending_verification` — ' +
             'because the caller supplies the `app_identifier` unauthenticated, so "this app knows this user" is not a fact the answer may carry. ' +
-            'The argon2 verify is paid unconditionally, including for an unknown app identifier, so response time is not an oracle either.',
+            'The argon2 verify is paid unconditionally, including for an unknown app identifier, so response time is not an oracle either. ' +
+            '\n\n**The answer is a `clientSignInResult`**: session tokens, or a `twoFactorChallenge` when the person has a confirmed authenticator ' +
+            'or the app requires one — then no session exists until `POST /api/client/two-factor/verify` or the setup is done. `403 ' +
+            'method_not_allowed` when the app has the password method off; it names the app\'s policy, not a person.',
+    },
+    {
+        method: 'POST', path: '/api/client/login/code', section: 'client-auth',
+        summary: 'Mails a six-digit sign-in code, and answers the same whether or not the address exists.',
+        audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 202,
+        params: [], query: null, request: clientLoginCodeRequest, response: null,
+        errors: ['rate_limited', 'validation_error', 'not_found', 'method_not_allowed'], transport: 'http',
+        notes: '**`202` and an empty body for every request the policy allows**, in status, body and timing, whether or not the address names an ' +
+            'active account of this app — a decoy like `POST /api/client/resend-verification`, so this is no enumeration oracle. A mail goes out ' +
+            'only for an account that may sign in. The code is six digits, valid ten minutes, takes five wrong attempts, and a new request expires ' +
+            'the previous one for the same address; a request within sixty seconds of the last sends no second mail. The address is trimmed and ' +
+            'compared case-insensitively. `404 not_found` is the **app identifier**, never the address; `403 method_not_allowed` when the app has ' +
+            'the email-code method off. Limited per app, address and IP, so it cannot be used to mail somebody repeatedly.',
+    },
+    {
+        method: 'POST', path: '/api/client/login/code/verify', section: 'client-auth',
+        summary: 'Spends a mailed sign-in code and answers a session or a two-factor challenge.',
+        audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: clientLoginCodeVerifyRequest, response: clientSignInResult,
+        errors: ['rate_limited', 'validation_error', 'invalid_code', 'token_spent', 'method_not_allowed'], transport: 'http',
+        notes: 'A wrong code is `400 invalid_code` with `details.attempts_left` (`invalidCodeDetails`). A code that is spent, past its ten minutes, ' +
+            'out of attempts, or was never mailed is `410 token_spent` — one answer, because telling them apart would say whether a code was ever ' +
+            'sent to that address; the recovery is the same, ask for a new code. The address is trimmed and compared case-insensitively, so the ' +
+            'address typed at the request and here need not match in case. \n\n**The answer is a `clientSignInResult`**, like the password ' +
+            'login: tokens, or a `twoFactorChallenge` when the person has an authenticator or the app requires one. A pending-verification account ' +
+            'that spends a code is activated — reading a mail at that address is the proof verification asks for.',
     },
     {
         method: 'POST', path: '/api/client/register', section: 'client-auth',
@@ -1415,11 +1650,12 @@ export const ROUTES = [
             'app has self-registration off and `403 domain_not_allowed` when the address is outside `allowed_domains`: both are the developer\'s own ' +
             'configuration, and a stranger learns the app\'s policy rather than who is in it. **A password under twelve characters is part of that ' +
             '`400 validation_error`** and not a code of its own — the minimum is the `password` field\'s schema rule, and the error names the field, ' +
-            'which is what a form needs to mark it. `404 not_found` names an ' +
+            'which is what a form needs to mark it. The same `400` names `password` when one is missing while the app\'s password method is on, ' +
+            'or sent while it is off: an email-code-only app registers people without one. `404 not_found` names an ' +
             '**app identifier no app carries**, and never an address: an app identifier is already public (it is in the MCP metadata path and in the ' +
             'developer\'s own URLs), while collapsing it into `registration_closed` sent a developer who mistyped their own identifier hunting a ' +
-            'configuration bug that was not there. `409 target_state_conflict` when the app has configured no `verify_url` or has no default role — ' +
-            'there would be nowhere to send the person and no role to give them, and mailing a link that leads nowhere is worse than refusing. ' +
+            'configuration bug that was not there. `409 target_state_conflict` when the app has no default role — there would be no role to give ' +
+            'the person. An app with no `verify_url` is not refused: the mailed link points at the hosted confirmation page instead. ' +
             '\n\n**`409 quota_exceeded` when the org is at its `max_end_users` limit**, counted across every app of the org. It is the one refusal ' +
             'here that is answered **before the address is looked at** — and that ordering is the point rather than an implementation detail: a ' +
             'quota checked after the existence branch would answer `202` for an address the app already knows and `409` for one it does not, which ' +
@@ -1430,9 +1666,10 @@ export const ROUTES = [
         method: 'POST', path: '/api/client/verify-email', section: 'client-auth',
         summary: 'Spends a verification token, activates the account and answers a session.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientVerifyEmailRequest, response: sessionTokens,
+        params: [], query: null, request: clientVerifyEmailRequest, response: clientSignInResult,
         errors: ['rate_limited', 'validation_error', 'token_spent'], transport: 'http',
-        notes: '**The answer is a session, not a `204`.** Somebody who has just proved they can read the mail should not be asked to type their ' +
+        notes: '**The answer is a session, not a `204`** — or, as on every sign-in step, a `twoFactorChallenge` when the app requires two-factor ' +
+            '(`clientSignInResult`). Somebody who has just proved they can read the mail should not be asked to type their ' +
             'password again on the next screen, and the app has an access token to carry them into it. The token is spent first and the account is ' +
             'activated second, as **two writes**: the spend is the atomic one, so a link opened twice cannot mint two sessions, but a process that ' +
             'died between them would leave a spent token on an account still `pending_verification`, whose recovery is ' +
@@ -1461,20 +1698,20 @@ export const ROUTES = [
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 202,
         params: [], query: null, request: clientPasswordResetRequest, response: null,
         errors: ['rate_limited', 'validation_error', 'not_found'], transport: 'http',
-        notes: '**The app-user twin of `POST /api/auth/password/reset`, and a different shape** because the two surfaces name a person differently: a ' +
-            'Fleetless address is globally unique and resolves alone, an app user\'s is unique only within their app, so the pair is the identifier. ' +
-            'Status, body and timing are identical for a known and an unknown address. An account with no Fleetless password — one created through an ' +
+        notes: 'The pair of app identifier and address is the identifier: an app user\'s address is unique only within their app. ' +
+            'Status, body and timing are identical for a known and an unknown address. An account with no password — one created through an ' +
             'identity provider — is mailed nothing and still answers `202`. `404 not_found` is the **app identifier**, never the address. The link ' +
-            'points at the app\'s `reset_url`; an app that has configured none can send no mail, which the `202` does not distinguish, because saying ' +
-            'so would answer for the address as well.',
+            'points at the app\'s `reset_url`, or at the hosted reset page when the app has configured none.',
     },
     {
         method: 'POST', path: '/api/client/password/reset/confirm', section: 'client-auth',
         summary: 'Spends a reset token, sets the new password and answers a fresh session.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientPasswordResetConfirmRequest, response: sessionTokens,
-        errors: ['rate_limited', 'validation_error', 'token_spent'], transport: 'http',
-        notes: '**Every refresh family of that account is revoked**, then a fresh pair is minted for the caller — a forgotten password is one of the two ' +
+        params: [], query: null, request: clientPasswordResetConfirmRequest, response: clientSignInResult,
+        errors: ['rate_limited', 'validation_error', 'token_spent', 'method_not_allowed'], transport: 'http',
+        notes: '**A new password does not bypass the second factor**: a person with an authenticator, or in an app that requires one, gets a ' +
+            '`twoFactorChallenge` instead of tokens (`clientSignInResult`), and the authenticator stays on. `403 method_not_allowed` when the app ' +
+            'has the password method off. \n\n**Every refresh family of that account is revoked**, then a fresh pair is minted for the caller — a forgotten password is one of the two ' +
             'states where somebody else may be holding a live session, and the person completing the reset is the one who should keep theirs. The ' +
             'account is activated if it was still `pending_verification`: reading a mail at that address is the same proof verification asks for. ' +
             '\n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, past its hour, or already used. There is one code ' +
@@ -1486,13 +1723,15 @@ export const ROUTES = [
         method: 'POST', path: '/api/client/invitations/accept', section: 'client-auth',
         summary: 'Spends an invitation token, creates or activates the app user and answers a session.',
         audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
-        params: [], query: null, request: clientAcceptInvitationRequest, response: sessionTokens,
+        params: [], query: null, request: clientAcceptInvitationRequest, response: clientSignInResult,
         errors: ['rate_limited', 'validation_error', 'token_spent', 'email_taken', 'target_state_conflict', 'quota_exceeded'], transport: 'http',
         notes: '**An app invitation, not a team one.** `POST /api/org/invitations/accept` is the other space and answers `204`; this one answers a ' +
             'session, because the person is landing in the developer\'s app and there is no second door for them to sign in through. The role is the ' +
             'one the invitation fixed at creation, so a later change to the app\'s default role does not re-aim a link already in somebody\'s inbox, ' +
             'and the invitation **bypasses `allowed_domains`** — a developer inviting somebody by hand has already made the decision the whitelist ' +
-            'automates. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, expired past the seven days, revoked by ' +
+            'automates. The answer is a `clientSignInResult`: a `twoFactorChallenge` instead of tokens when the app requires two-factor. ' +
+            '`password` is required while the app\'s password method is on and refused while it is off, both as `400 validation_error` naming ' +
+            'the field. \n\n**One refusal for every token that does not work: `410 token_spent`** — unknown, expired past the seven days, revoked by ' +
             'the developer, or already accepted. There is one code because telling them apart would say whether a token ever existed, and because ' +
             'the one thing the holder of a dead link can do is ask the developer for a new one, whichever of the four it was. A chosen password ' +
             'under twelve characters is part of the `400 validation_error`, naming the `password` field. `409 email_taken` is an address this app ' +
@@ -1551,6 +1790,53 @@ export const ROUTES = [
         notes: 'The one route that answers for all three caller kinds — a developer bearer, an app-user bearer and a server key — which is why the ' +
             'shape names each of `developer_id`, `app_user_id` and `server_key_id` and fills exactly one.',
     },
+    /* ------------------------------------------------ app-user two-factor */
+    {
+        method: 'POST', path: '/api/client/two-factor/verify', section: 'client-auth',
+        summary: 'Answers a two-factor challenge with an authenticator or recovery code, and answers the session.',
+        audience: 'client', auth: 'none', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: clientTwoFactorVerifyRequest, response: sessionTokens,
+        errors: ['rate_limited', 'validation_error', 'invalid_code', 'token_spent'], transport: 'http',
+        notes: 'The challenge is the one a sign-in step answered with `two_factor_required`; it lives five minutes and takes five wrong codes, after ' +
+            'which it is `410 token_spent` and the sign-in starts over. A wrong code is `400 invalid_code` with `details.attempts_left`. **A code ' +
+            'is accepted at most once**: the same authenticator code sent twice, even at the same moment, signs in exactly once. A recovery code is ' +
+            'spent by its use and audited as `app_user.recovery_code_used`. Exactly one of `code` and `recovery_code`, or `400 validation_error`.',
+    },
+    {
+        method: 'POST', path: '/api/client/two-factor/setup', section: 'client-auth',
+        summary: 'Starts an authenticator setup and answers its secret and otpauth URL.',
+        audience: 'client', auth: 'in_handler', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: clientTwoFactorSetupRequest, response: twoFactorSetupResponse,
+        errors: ['rate_limited', 'validation_error', 'token_spent', 'unauthorized', 'target_state_conflict'], transport: 'http',
+        notes: '**Two ways in, decided in the handler.** During sign-in the body carries the `two_factor_setup_required` challenge, and that is the ' +
+            'credential; from the app\'s own account settings the app user\'s bearer is, with no challenge. Neither is `401 unauthorized`, and a ' +
+            'dead challenge is `410 token_spent`. `409 target_state_conflict` names `two_factor` with rule `off` when the app\'s policy is `off`. ' +
+            'The secret is not in use until `POST /api/client/two-factor/setup/confirm` accepts a code from it; a second call replaces a pending ' +
+            'secret, and an account that already has an authenticator keeps it until the new one is confirmed.',
+    },
+    {
+        method: 'POST', path: '/api/client/two-factor/setup/confirm', section: 'client-auth',
+        summary: 'Confirms the new authenticator with a code and answers the recovery codes and a session.',
+        audience: 'client', auth: 'in_handler', rateLimited: true, ownerTier: false, status: 200,
+        params: [], query: null, request: clientTwoFactorSetupConfirmRequest, response: clientTwoFactorSetupConfirmResponse,
+        errors: ['rate_limited', 'validation_error', 'invalid_code', 'token_spent', 'unauthorized'], transport: 'http',
+        notes: 'The same two ways in as `setup`. A code that does not match the pending secret is `400 invalid_code`; no pending setup, or a dead ' +
+            'challenge, is `410 token_spent`. On success the authenticator is on, ten recovery codes are issued — shown this once, any earlier set ' +
+            'void — and the answer carries a session: the one the sign-in was waiting for, or, from account settings, a fresh one while every other ' +
+            'session of the account ends. Audited as `app_user.two_factor_enabled`.',
+    },
+    {
+        method: 'DELETE', path: '/api/client/two-factor', section: 'client-auth',
+        summary: "Turns the signed-in app user's authenticator off.",
+        audience: 'client', auth: 'developer_or_client', rateLimited: true, ownerTier: false, status: 204,
+        params: [], query: null, request: clientTwoFactorDisableRequest, response: null,
+        errors: [...CLIENT_GUARD, 'rate_limited', 'validation_error', 'invalid_code', 'target_state_conflict'], transport: 'http',
+        notes: 'The app user\'s own door; a developer bearer or a server key is `401 unauthorized`, because the factor is the person\'s. A current ' +
+            'code proves they still hold the authenticator: a stolen session alone cannot remove it. The authenticator and every recovery code go. ' +
+            '`409 target_state_conflict` names `two_factor` with rule `required` while the app requires two-factor, and with rule `off` when there ' +
+            'is none to remove. Audited as `app_user.two_factor_disabled`. The developer\'s support door is `DELETE ' +
+            '/api/apps/:id/users/:userId/two-factor`.',
+    },
     /* ---------------------------------------- app-user sign-in through an IdP */
     {
         method: 'GET', path: '/api/client/providers', section: 'client-auth',
@@ -1610,10 +1896,10 @@ export const ROUTES = [
             '\n\n**It lists `rate_limited` and no other code, because every sign-in outcome it has is a redirect.** Success and failure alike are ' +
             'a `302` to the app\'s own ' +
             '`redirect_uri`: `?code=…&state=…` when a session was resolved, `?error=<clientOidcErrorCode>&state=…` when it was not, so the app ' +
-            'renders its own message and can bind either answer to the request it started. Fleetless shows an app user no page. \n\n**The one ' +
+            'renders its own message and can bind either answer to the request it started. This route renders no page for an outcome. \n\n**The one ' +
             'exception is a `state` that resolves to no interaction** — unknown, hand-edited, or past its ten minutes. Then there is no confirmed ' +
             'redirect target to carry the answer to, and bouncing a browser to an unvalidated one is the hole the whole flow is arranged to avoid, ' +
-            'so the cloud renders an HTML problem page at `400`. That is the only Fleetless-rendered surface an app user can reach. It is HTML ' +
+            'so the cloud renders an HTML problem page at `400`. It is HTML ' +
             'rather than an `apiError`, which is why no code is listed: a code here would document an envelope no caller receives, and this ' +
             'manifest\'s other HTML pages (`GET /mcp/oauth/interaction/:id`, `GET /console/oauth/interaction/:id`) say their status in prose for ' +
             'the same reason.',
@@ -2445,16 +2731,6 @@ export const ROUTES = [
             'platform will answer is owed a refusal, not a shorter answer they will mistake for the whole picture. `from_day <= to_day` is a ' +
             'cross-field rule no JSON Schema can express and is enforced here. The window is echoed back.',
     },
-    {
-        method: 'POST', path: '/api/feedback', section: 'org',
-        summary: 'Sends a message from a developer to the people who build Fleetless.',
-        audience: 'developer', auth: 'developer', rateLimited: true, ownerTier: false, status: 202,
-        params: [], query: null, request: feedbackRequest, response: feedbackResponse,
-        errors: [...DEVELOPER_GUARD, 'validation_error', 'rate_limited'], transport: 'http',
-        notes: 'The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or ' +
-            '`not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers ' +
-            '`429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender\'s address.',
-    },
     /* ------------------------------------------------- assets (robot upload) */
     {
         method: 'POST', path: '/api/bridge/assets', section: 'assets',