@fleetless/contracts 5.2.0 → 6.0.0-next.1

package/dist/client-auth.js

@@ -1,16 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 import { appIdentifier } from './apps.js';
-import { APP_USER_DISPLAY_NAME_MAX, providerSlug } from './app-users.js';
-import { password } from './identity.js';
+import { APP_USER_DISPLAY_NAME_MAX, appSignInMethods, providerSlug } from './app-users.js';
+import { loginCode, password, recoveryCode, recoveryCodesList, sessionTokens, totpCode } from './identity.js';
 /**
  * **The client auth API: the whole of what an app user's browser talks to.**
  *
- * Fleetless shows an app user **no page**. The developer's own UI owns
- * every screen — login, registration, verification, invitation acceptance,
+ * The developer's own UI owns every screen it wants to — login, emailed
+ * code, second factor, registration, verification, invitation acceptance,
  * password reset, the provider buttons, the MCP consent — and calls these
- * routes as JSON. The hosted, app-branded login and consent pages this file
- * used to describe are deleted.
+ * routes as JSON. **Where the app sets no URL, a Fleetless-hosted page on the
+ * auth portal stands in** (`appAuthConfig.hosted_pages`) and calls the same
+ * policy: one set of rules, whichever page drives it.
  *
  * Everything here is public: `app_identifier` travels in the body (in the
  * query for a GET), CORS is answered only for the app's `allowed_origins`, and
@@ -27,12 +28,19 @@ import { password } from './identity.js';
  * the SDK and the cloud cannot drift into disagreeing about it.
  *
  * **The enumeration discipline is deliberate, not a preference:**
- * `register`, `resend-verification` and `password/reset` answer `202` for every
- * policy-allowed request whether or not the address exists, and `login` answers
- * the identical `invalid_credentials` for a wrong password, a `blocked` account
- * and a `pending_verification` one. Policy refusals are honest —
- * `registration_closed` and `domain_not_allowed` say what they are, because
- * neither reveals whether a *person* exists.
+ * `register`, `resend-verification`, `password/reset` and `login/code` answer
+ * `202` for every policy-allowed request whether or not the address exists,
+ * and `login` answers the identical `invalid_credentials` for a wrong
+ * password, a `blocked` account and a `pending_verification` one. Policy
+ * refusals are honest — `registration_closed`, `domain_not_allowed` and
+ * `method_not_allowed` say what they are, because none reveals whether a
+ * *person* exists.
+ *
+ * **Every step that signs somebody in answers a `clientSignInResult`**:
+ * session tokens, or a two-factor challenge when the person has a confirmed
+ * authenticator or the app requires one. No path yields a session without the
+ * second factor then — except a sign-in through an identity provider, which
+ * owns that sign-in and answers tokens as before.
  */
 /* ------------------------------------------------------ password login -- */
 export const clientLoginRequest = z.object({
@@ -70,6 +78,102 @@ export const clientLogoutRequest = z.object({
         description: 'Any refresh token of the session to end. The whole token family is revoked server-side, so a token stolen before this call stops working too — clearing a client-side store is a gesture, not a revocation. The answer is `204`: a token the server does not recognise gets it too, since that is the end state being asked for.',
     }),
 });
+/* -------------------------------------------------- emailed sign-in code -- */
+/**
+ * **Asking for a sign-in code.** A six-digit code, mailed, valid ten minutes;
+ * a new request expires the previous code for the same address. The answer is
+ * `202` whether or not the address names an account — a decoy, like
+ * `resend-verification` — so this is no enumeration oracle.
+ */
+export const clientLoginCodeRequest = z
+    .object({
+    app_identifier: appIdentifier.meta({ description: 'The app to sign in to. An identifier no app carries is `404 not_found`; the address is never the subject of a refusal.' }),
+    email: z.email().meta({
+        description: 'The address to mail the code to, trimmed and compared case-insensitively. `202` whether or not it names an account of this app.',
+    }),
+})
+    .strict();
+/** **Spending the code.** Five wrong attempts spend it; so does its tenth minute. */
+export const clientLoginCodeVerifyRequest = z
+    .object({
+    app_identifier: appIdentifier.meta({ description: 'The app the code was requested for.' }),
+    email: z.email().meta({ description: 'The address the code was mailed to, as typed when it was requested; trimmed and compared case-insensitively.' }),
+    code: loginCode.meta({ description: 'The six digits from the mail, exactly — leading zeros included, no spaces.' }),
+})
+    .strict();
+/* ---------------------------------------------------------- two-factor -- */
+/**
+ * **A sign-in that needs its second factor first.** No session exists yet:
+ * the `challenge` is a short-lived handle, five minutes, that the next call
+ * spends.
+ *
+ * - `two_factor_required` — the person has an authenticator; send a code or
+ *   a recovery code to `POST /api/client/two-factor/verify`.
+ * - `two_factor_setup_required` — the app requires two-factor and the person
+ *   has none; set one up with `POST /api/client/two-factor/setup` and
+ *   `…/setup/confirm`, which answers the session.
+ */
+export const twoFactorChallenge = z.object({
+    status: z.enum(['two_factor_required', 'two_factor_setup_required']).meta({
+        description: '`two_factor_required`: ask for the authenticator code. `two_factor_setup_required`: the app requires two-factor and the person has none yet, so set one up before any session exists.',
+    }),
+    challenge: z.string().min(1).meta({
+        description: 'The handle the next step spends. Valid five minutes; afterwards it answers `410 token_spent` and the sign-in starts over.',
+    }),
+});
+/**
+ * **What every session-minting sign-in step answers**: password login, code
+ * verify, and spending an invitation, verification or reset token. Session
+ * tokens when the sign-in is complete; a `twoFactorChallenge` when a second
+ * factor comes first. Tell them apart by `status`, which only the challenge
+ * carries.
+ */
+export const clientSignInResult = z.union([sessionTokens, twoFactorChallenge]);
+/** **Answering a `two_factor_required` challenge**, with the authenticator's code or one recovery code — exactly one of the two. */
+export const clientTwoFactorVerifyRequest = z
+    .object({
+    challenge: z.string().min(1).meta({ description: 'The challenge the sign-in step answered.' }),
+    code: totpCode.optional().meta({ description: 'The six-digit code the authenticator shows now. A code already accepted once is refused, so a replay of a seen code does not sign anybody in.' }),
+    recovery_code: recoveryCode.optional().meta({ description: 'One of the ten recovery codes, `xxxxx-xxxxx`, in either case. Spent by its use.' }),
+})
+    .strict()
+    .refine((b) => (b.code === undefined) !== (b.recovery_code === undefined), { message: 'Send exactly one of code and recovery_code.' });
+/**
+ * **Starting an authenticator setup.** Either during sign-in, with the
+ * `two_factor_setup_required` challenge in the body, or from the app's own
+ * account settings, with the app user's bearer and no challenge.
+ */
+export const clientTwoFactorSetupRequest = z
+    .object({
+    challenge: z.string().min(1).optional().meta({
+        description: 'The `two_factor_setup_required` challenge, during sign-in. Absent when the call carries the app user\'s bearer instead.',
+    }),
+})
+    .strict();
+/** **Confirming the setup** with a code from the new authenticator. Only then is it on. */
+export const clientTwoFactorSetupConfirmRequest = z
+    .object({
+    challenge: z.string().min(1).optional().meta({ description: 'The same challenge as at `setup`, during sign-in; absent with a bearer.' }),
+    code: totpCode.meta({ description: 'A code the new authenticator shows now. It proves the secret was copied correctly before anything depends on it.' }),
+})
+    .strict();
+/**
+ * **The confirmed setup**: the ten recovery codes, shown this once, and a
+ * session — during sign-in the first one, from account settings a fresh one,
+ * since every other session of the account ends.
+ */
+export const clientTwoFactorSetupConfirmResponse = z.object({
+    recovery_codes: recoveryCodesList.meta({
+        description: 'The ten single-use recovery codes, lowercase, shown once. Any earlier set is void.',
+    }),
+    session: sessionTokens.meta({ description: 'The session the sign-in was waiting for, or a fresh one for the account settings.' }),
+});
+/** **Turning the authenticator off**, from the app's own account settings. A current code proves the person still holds it. */
+export const clientTwoFactorDisableRequest = z
+    .object({
+    code: totpCode.meta({ description: 'A code the authenticator shows now.' }),
+})
+    .strict();
 /* ---------------------------------------------- registration and mails -- */
 /**
  * **Self-registration** — and the account it creates cannot log in yet.
@@ -98,8 +202,8 @@ export const clientRegisterRequest = z
     email: z.email().meta({
         description: 'The address to register. Unique per app, case-insensitively. An address this app already knows still answers `202`, without a mail — the answer may not say whether an account exists.',
     }),
-    password: password.meta({
-        description: 'The password for the new account. At least 12 characters; length only, because a rule a user cannot predict is a rule they work around.',
+    password: password.optional().meta({
+        description: 'The password for the new account, at least 12 characters. **Required while the app\'s password method is on, refused while it is off** — both as `400 validation_error` naming `password`. An email-code-only app registers people without one.',
     }),
     display_name: z.string().min(1).max(APP_USER_DISPLAY_NAME_MAX).nullable().optional().meta({
         description: 'An optional human name for the account. The developer\'s own UI decides whether to ask for it.',
@@ -124,12 +228,10 @@ export const clientResendVerificationRequest = z
 })
     .strict();
 /**
- * Asking for a reset link **as an app user**.
- *
- * Same act as `passwordResetRequest`, different shape, because the two surfaces
- * identify a person differently. A Fleetless user's address is globally unique
- * and resolves alone; an app user's is unique only within their app, so the
- * pair is what names them.
+ * Asking for a reset link **as an app user** — the only password reset
+ * there is: Fleetless users hold no password. An app user's address is
+ * unique only within their app, so the pair of app and address is what names
+ * them.
  *
  * The response is identical for a known and an unknown pair — otherwise this
  * becomes the enumeration oracle the rest of the family is carefully built not
@@ -170,7 +272,9 @@ export const clientAcceptInvitationRequest = z
     token: z.string().min(1).meta({
         description: 'The opaque token from the invitation link, valid seven days. Unknown, expired, revoked and already-accepted all answer `410 token_spent`.',
     }),
-    password: password.meta({ description: 'The password the new account will use.' }),
+    password: password.optional().meta({
+        description: 'The password the new account will use, at least 12 characters. **Required while the app\'s password method is on, refused while it is off** — both as `400 validation_error` naming `password`. An email-code-only app accepts invitations without one.',
+    }),
     display_name: z.string().min(1).max(APP_USER_DISPLAY_NAME_MAX).nullable().optional().meta({
         description: 'An optional name, overriding whatever the invitation pre-filled.',
     }),
@@ -210,8 +314,8 @@ export const clientProviderListQuery = z
 })
     .meta({ description: 'The one parameter of the public provider listing.' });
 /**
- * What the developer's login page needs to draw its provider buttons, and
- * **nothing more**. This route is public and unauthenticated: the issuer, the
+ * What the developer's login page needs to draw its provider buttons and its
+ * password or code fields, and **nothing more**. This route is public and unauthenticated: the issuer, the
  * client id, the scopes and the linking policy are all management-side facts
  * that would tell a stranger how the app's federation is configured.
  *
@@ -225,7 +329,10 @@ export const clientProviderListResponse = z.object({
         name: z.string().meta({ description: 'What to write on the button, as the developer configured it.' }),
     }))
         .meta({
-        description: 'The app\'s **enabled** providers, slug and display name only. An app with none answers an empty array, which is the state of an app that offers password login alone.',
+        description: 'The app\'s **enabled** providers, slug and display name only. An app with none answers an empty array, which is the state of an app that offers password or code sign-in alone.',
+    }),
+    sign_in_methods: appSignInMethods.meta({
+        description: 'Which of password and emailed code the app accepts, so its sign-in page draws the right fields without guessing. The same value the developer set; public, like the provider buttons.',
     }),
 });
 /**
@@ -353,10 +460,11 @@ export const clientOidcErrorCode = z.enum([
 ]);
 /* ------------------------------------------------ MCP, delegated login -- */
 /**
- * **A pending MCP authorization, as the app's own consent screen reads it**
- * Fleetless renders no page here either: `authorize` redirects to the
- * app's `mcp_login_url` with an interaction id, the app authenticates the user
- * with its normal UI, shows this, and approves or denies through the API.
+ * **A pending MCP authorization, as the app's own consent screen reads it.**
+ * `authorize` redirects to the app's `mcp_login_url` with an interaction id,
+ * the app authenticates the user with its normal UI, shows this, and approves
+ * or denies through the API. An app with no `mcp_login_url` gets the hosted
+ * MCP sign-in instead, which reads and decides the same interaction.
  *
  * `client_name_verified` is `z.literal(false)`, and that is the whole point of
  * the field. The name comes from an **unauthenticated** dynamic registration —
@@ -482,4 +590,7 @@ export const clientIdentity = z.object({
     email: z.email().nullable().meta({
         description: 'The address of the Fleetless user or app user behind this session, and `null` for a server key, which is not a person.',
     }),
+    two_factor_enabled: z.boolean().nullable().meta({
+        description: 'Whether the app user has a confirmed authenticator, so the app\'s account settings can offer to turn it on or off. `null` unless `kind` is `app_user`.',
+    }),
 });

package/dist/config.d.ts

@@ -648,9 +648,9 @@ export declare const LOW_BANDWIDTH_DEFAULTS: {
  */
 export declare const lowBandwidthSection: z.ZodObject<{
     mode: z.ZodOptional<z.ZodEnum<{
+        off: "off";
         auto: "auto";
         on: "on";
-        off: "off";
     }>>;
     enter_lag_ms: z.ZodOptional<z.ZodNumber>;
     enter_after_s: z.ZodOptional<z.ZodNumber>;
@@ -858,9 +858,9 @@ export declare const robotConfigDoc: z.ZodObject<{
     }, z.core.$strict>>>;
     low_bandwidth: z.ZodOptional<z.ZodObject<{
         mode: z.ZodOptional<z.ZodEnum<{
+            off: "off";
             auto: "auto";
             on: "on";
-            off: "off";
         }>>;
         enter_lag_ms: z.ZodOptional<z.ZodNumber>;
         enter_after_s: z.ZodOptional<z.ZodNumber>;

package/dist/errors.d.ts

@@ -63,10 +63,19 @@ export declare const cancelRejectedDetails: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type CancelRejectedDetails = z.infer<typeof cancelRejectedDetails>;
+/**
+ * The `details` of an `invalid_code` refusal: how many wrong codes are left
+ * before the code is spent. Pinned for the reason `parameterInvalidDetails`
+ * is — a sign-in page parses it instead of reading the shape from prose.
+ */
+export declare const invalidCodeDetails: z.ZodObject<{
+    attempts_left: z.ZodNumber;
+}, z.core.$strip>;
+export type InvalidCodeDetails = z.infer<typeof invalidCodeDetails>;
 /**
  * The codes in use today. The wire deliberately allows any string — this
  * list is the shared vocabulary, not a closed set, so a new refusal never
  * needs a contracts release before it can be reported honestly.
  */
-export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "bridge_too_old", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "cancel_rejected", "job_lost", "job_unknown_to_bridge", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired"];
+export declare const ERROR_CODES: readonly ["not_found", "validation_error", "bad_request", "unknown_datapoint", "invalid_token", "protocol_mismatch", "bridge_too_old", "invalid_frame", "duplicate_slug", "reserved_slug", "unknown_slug", "unknown_field_path", "unknown_type", "unknown_topic", "invalid_rate", "invalid_range", "config_conflict", "no_data", "robot_offline", "bridge_timeout", "unauthorized", "forbidden", "invalid_credentials", "token_expired", "token_revoked", "email_taken", "identifier_taken", "weak_password", "account_blocked", "busy", "parameter_invalid", "cancel_rejected", "job_lost", "job_unknown_to_bridge", "action_server_lost", "action_failed", "goal_rejected", "goal_send_failed", "result_failed", "goal_uncontrollable", "bridge_disconnected", "config_changed", "publisher_busy", "unknown_command", "not_subscribable", "camera_offline", "no_snapshot_yet", "live_unavailable", "wrong_kind", "not_recorded", "not_aggregatable", "quota_exceeded", "credential_in_use", "goal_timeout", "robot_in_use", "robot_deletion_partial", "job_queue_full", "invalid_uuid", "rate_limited", "tier_required", "token_spent", "service_timeout", "asset_missing", "dynamic_registration_disabled", "client_limit_reached", "idp_unavailable", "mcp_disabled", "tool_not_available", "capability_required", "last_owner", "target_state_conflict", "signup_closed", "draft_not_a_document", "internal_error", "not_cancellable", "unsupported_media_type", "wrong_browser", "invalid_yaml", "unstorable_yaml", "registration_closed", "domain_not_allowed", "email_unverified", "origin_not_allowed", "template_invalid", "provider_disabled", "provider_misconfigured", "invalid_redirect_uri", "interaction_expired", "invalid_code", "method_not_allowed"];
 export type ErrorCode = (typeof ERROR_CODES)[number];

package/dist/errors.js

@@ -53,6 +53,16 @@ export const parameterInvalidDetails = z.object({
 export const cancelRejectedDetails = z.object({
     goals: z.array(bridgeCancelResultEntry).min(1),
 });
+/**
+ * The `details` of an `invalid_code` refusal: how many wrong codes are left
+ * before the code is spent. Pinned for the reason `parameterInvalidDetails`
+ * is — a sign-in page parses it instead of reading the shape from prose.
+ */
+export const invalidCodeDetails = z.object({
+    attempts_left: z.number().int().min(0).meta({
+        description: 'How many more wrong codes this code or challenge takes before it is spent. `0` means the next attempt answers `410 token_spent`.',
+    }),
+});
 /**
  * The codes in use today. The wire deliberately allows any string — this
  * list is the shared vocabulary, not a closed set, so a new refusal never
@@ -390,6 +400,10 @@ export const ERROR_CODES = [
      * Deliberately one code for both: distinguishing them tells a stranger
      * whether a token ever existed, and the recovery is identical either way —
      * ask for a new link.
+     *
+     * The same code answers an emailed sign-in code that is spent, expired or
+     * out of attempts, and a two-factor challenge past its five minutes: the
+     * recovery is the same — ask for a new code, or start the sign-in again.
      */
     'token_spent',
     // The command path, continued.
@@ -597,11 +611,9 @@ export const ERROR_CODES = [
     'target_state_conflict',
     // 2026-09-04 — the public site (closed beta).
     /**
-     * `403` from `POST /api/auth/signup` and the portal's sign-up pages while
-     * `SIGNUP_MODE=closed`. Not `forbidden`: nothing about the caller is
-     * refused, the door is closed for everyone. The message names the
-     * waiting list. Produced by cloud `routes/auth.ts` and
-     * `routes/console-oauth.ts` in the same release.
+     * `403` from the portal's sign-up pages while `SIGNUP_MODE=closed`. Not
+     * `forbidden`: nothing about the caller is refused, the door is closed for
+     * everyone. The message names the waiting list.
      */
     'signup_closed',
     // Emitted by the cloud, catalogued late.
@@ -834,4 +846,21 @@ export const ERROR_CODES = [
      * advice for the state a person is actually in.
      */
     'interaction_expired',
+    // 2026-09-30 — email codes and two-factor.
+    /**
+     * `400`: a six-digit code, an authenticator code or a recovery code that
+     * does not match. `details` is `invalidCodeDetails`: how many attempts the
+     * emailed code has left, so the page can say so. At zero the code is spent
+     * and the next answer is `410 token_spent`. Distinct from
+     * `invalid_credentials`, which is about a password and says nothing about
+     * attempts.
+     */
+    'invalid_code',
+    /**
+     * `403`: the app does not offer this sign-in method — a password login on a
+     * code-only app, a code request on a password-only one, or a password where
+     * the app takes none. It names the app's policy, never a person, so it is
+     * no enumeration oracle.
+     */
+    'method_not_allowed',
 ];