@fleetless/contracts 5.2.0 → 6.0.0-next.1

package/artifacts/schema/put-app-auth-sign-in-request.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "sign_in_methods": {
+      "type": "object",
+      "properties": {
+        "password": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a password. Off refuses `POST /api/client/login` with `method_not_allowed`, and registration and invitations then take no password."
+        },
+        "email_code": {
+          "type": "boolean",
+          "description": "Whether app users may sign in with a six-digit code mailed to them, valid ten minutes. A code needs no URL, so it works in local development and in an app with no web UI."
+        }
+      },
+      "required": [
+        "password",
+        "email_code"
+      ],
+      "additionalProperties": false,
+      "description": "Which sign-in methods the app offers: password, emailed code, or both — at least one. Identity providers stay on top of either. The default is password only."
+    },
+    "two_factor": {
+      "type": "string",
+      "enum": [
+        "off",
+        "optional",
+        "required"
+      ],
+      "description": "Whether the app asks for an authenticator code: `off` (the default), `optional` or `required`. A person with a confirmed authenticator is asked at every sign-in whatever the policy; a sign-in through an identity provider is never asked."
+    }
+  },
+  "required": [
+    "sign_in_methods",
+    "two_factor"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-app-auth-urls-request.schema.json

@@ -2,6 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
+    "app_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500,
+          "format": "uri"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The app's own home page, linked as `Open <app>` when a hosted flow is done. `null` makes the hosted done page say `You can close this tab`."
+    },
     "invite_url": {
       "anyOf": [
         {
@@ -12,7 +25,7 @@
           "type": "null"
         }
       ],
-      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` when unconfigured, and then an invitation still issues but `send_mail` is refused with `409 target_state_conflict` — there would be nowhere for the link to point."
+      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
     },
     "verify_url": {
       "anyOf": [
@@ -24,7 +37,7 @@
           "type": "null"
         }
       ],
-      "description": "The page that confirms a new address, with `{token}` where the token goes. Self-registration needs it: without a page to send people to, a registration would leave an account nobody can activate."
+      "description": "The page that confirms a new address, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
     },
     "reset_url": {
       "anyOf": [
@@ -36,13 +49,27 @@
           "type": "null"
         }
       ],
-      "description": "The page that takes a new password, with `{token}` where the token goes."
+      "description": "The page that takes a new password, with `{token}` where the token goes. `null` means the hosted page in `hosted_pages` is used."
+    },
+    "mcp_login_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it. `null` means the hosted MCP sign-in in `hosted_pages` is used."
     }
   },
   "required": [
+    "app_url",
     "invite_url",
     "verify_url",
-    "reset_url"
+    "reset_url",
+    "mcp_login_url"
   ],
   "additionalProperties": false
 }

package/artifacts/schema/recovery-codes-response.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "recovery_codes": {
+      "minItems": 10,
+      "maxItems": 10,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z2-7]{5}-[a-z2-7]{5}$"
+      },
+      "description": "The ten new recovery codes, lowercase, shown once. Every earlier code is void."
+    }
+  },
+  "required": [
+    "recovery_codes"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/rename-passkey-request.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "The new name."
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/totp-confirm-request.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "pattern": "^\\d{6}$",
+      "description": "A code the new authenticator shows now. It proves the secret was copied correctly before anything depends on it."
+    }
+  },
+  "required": [
+    "code"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/totp-confirm-response.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "recovery_codes": {
+      "anyOf": [
+        {
+          "minItems": 10,
+          "maxItems": 10,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z2-7]{5}-[a-z2-7]{5}$"
+          }
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The ten recovery codes, shown once, when this is the account's first second factor; `null` otherwise."
+    }
+  },
+  "required": [
+    "recovery_codes"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/two-factor-challenge.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": [
+        "two_factor_required",
+        "two_factor_setup_required"
+      ],
+      "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": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The handle the next step spends. Valid five minutes; afterwards it answers `410 token_spent` and the sign-in starts over."
+    }
+  },
+  "required": [
+    "status",
+    "challenge"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/two-factor-setup-response.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "secret": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The shared secret, base32, for an authenticator app that cannot scan a QR code. Shown once; the cloud stores it encrypted."
+    },
+    "otpauth_url": {
+      "type": "string",
+      "pattern": "^otpauth:\\/\\/totp\\/.*",
+      "description": "The same secret as an `otpauth://totp/` URL, to render as a QR code. It carries the secret: never log it."
+    }
+  },
+  "required": [
+    "secret",
+    "otpauth_url"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/webauthn-options-response.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "options": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {},
+      "description": "The `PublicKeyCredentialCreationOptionsJSON` or `PublicKeyCredentialRequestOptionsJSON` to pass to the browser. Its challenge is single-use and short-lived."
+    }
+  },
+  "required": [
+    "options"
+  ],
+  "additionalProperties": false
+}

package/dist/app-users.d.ts

@@ -14,19 +14,22 @@ import { z } from 'zod';
  * So there are now **two identity spaces and nothing joins them**:
  *
  * - *Fleetless users* (`identity.ts`) — the org's team. Email globally unique,
- *   tier `owner | developer`, Fleetless password, console access.
+ *   tier `owner | developer`, sign-in by emailed code or passkey, console
+ *   access.
  * - *app users* (this file) — one app each. Email unique **per app**,
  *   case-insensitively. The same address may exist in several apps of one org
  *   as unrelated accounts, and a Fleetless user who wants to use an app
  *   registers or is invited like anybody else.
  *
- * **Fleetless shows an app user no page**. The developer's own UI owns
- * every screen and calls the JSON client-auth API (`client-auth.ts`). The one
- * Fleetless-rendered surface an app user can reach is the problem page for an
- * OIDC callback whose state no longer resolves to a redirect URI — every other
- * error is redirected to the app to render. That is why the four URLs on
- * `appAuthConfig` exist: Fleetless mails a link, and the link points into the
- * app.
+ * **The developer's own UI owns every screen it wants to own**, and calls the
+ * JSON client-auth API (`client-auth.ts`). Fleetless mails a link, and the
+ * link points into the app — at the four URLs on `appAuthConfig`. **A URL the
+ * app leaves unset falls back to a Fleetless-hosted page** on the auth portal
+ * (`hosted_pages`), carrying the app's name, its optional logo and accent
+ * colour, so an app works from its first minute: with no web UI of its own,
+ * and while its pages point nowhere yet. A set URL always wins. The hosted
+ * pages cover mailed links and MCP sign-in only; they are not a hosted login
+ * for the app's own web UI.
  */
 /** App-user display names share the Fleetless-user bound, so a rename cannot be legal in one space and refused in the other. */
 export declare const APP_USER_DISPLAY_NAME_MAX = 120;
@@ -84,6 +87,11 @@ export declare const appUser: z.ZodObject<{
     has_password: z.ZodBoolean;
     providers: z.ZodArray<z.ZodString>;
     last_login_at: z.ZodNullable<z.ZodISODateTime>;
+    two_factor: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        enabled_at: z.ZodNullable<z.ZodISODateTime>;
+        recovery_codes_left: z.ZodNumber;
+    }, z.core.$strip>;
     created_at: z.ZodISODateTime;
 }, z.core.$strip>;
 export type AppUser = z.infer<typeof appUser>;
@@ -103,6 +111,11 @@ export declare const appUserListResponse: z.ZodObject<{
         has_password: z.ZodBoolean;
         providers: z.ZodArray<z.ZodString>;
         last_login_at: z.ZodNullable<z.ZodISODateTime>;
+        two_factor: z.ZodObject<{
+            enabled: z.ZodBoolean;
+            enabled_at: z.ZodNullable<z.ZodISODateTime>;
+            recovery_codes_left: z.ZodNumber;
+        }, z.core.$strip>;
         created_at: z.ZodISODateTime;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -162,12 +175,11 @@ export type CreateAppInvitationRequest = z.infer<typeof createAppInvitationReque
 /**
  * The invitation as issued.
  *
- * **`accept_url` is nullable, and that is a policy rather than a convenience.**
- * The link points into the developer's app, at their configured `invite_url`.
- * An app that has configured none has nowhere for it to point, so there is no
- * link to hand back — `null` says that outright, where an absent key would be
- * indistinguishable from a mapper that dropped the field and a fabricated
- * Fleetless-hosted URL would name a page this product does not serve.
+ * The link points into the developer's app, at their configured `invite_url`,
+ * or at the Fleetless-hosted invitation page (`appAuthConfig.hosted_pages`)
+ * when the app has configured none. **`accept_url` stays nullable** so a
+ * reader written against the earlier shape keeps parsing; the cloud fills it
+ * in every case now that a hosted page always exists.
  */
 export declare const appInvitation: z.ZodObject<{
     id: z.ZodUUID;
@@ -371,6 +383,65 @@ export declare const allowedOrigin: z.ZodString;
  * name limit.
  */
 export declare const emailDomain: z.ZodString;
+/**
+ * **How an app's users sign in: by password, by emailed code, or both.**
+ *
+ * At least one is on — an app with neither would have no door but its
+ * identity providers, and a provider can be disabled. Identity providers are
+ * not part of this choice; they stay on top of whichever methods are on. A
+ * method turned off refuses its routes with `method_not_allowed`; a stored
+ * password stays stored, so turning the method back on restores it.
+ */
+export declare const appSignInMethods: z.ZodObject<{
+    password: z.ZodBoolean;
+    email_code: z.ZodBoolean;
+}, z.core.$strict>;
+export type AppSignInMethods = z.infer<typeof appSignInMethods>;
+/**
+ * **Whether an app asks its users for a second factor**, an authenticator
+ * app (TOTP) with ten single-use recovery codes.
+ *
+ * - `off` — nobody is asked to set one up, and nobody can.
+ * - `optional` — people turn it on in the app's own account settings.
+ * - `required` — a person without one sets it up at their next sign-in,
+ *   before any session exists. Nobody is signed out when it is switched on.
+ *
+ * Whatever the policy, a person who **has** a confirmed authenticator is asked
+ * for a code at every sign-in that yields a session. A sign-in through an
+ * identity provider is never asked: the provider owns that sign-in.
+ */
+export declare const appTwoFactorPolicy: z.ZodEnum<{
+    optional: "optional";
+    required: "required";
+    off: "off";
+}>;
+export type AppTwoFactorPolicy = z.infer<typeof appTwoFactorPolicy>;
+/**
+ * **The app's own home page**: https, or http on `localhost`/`127.0.0.1` —
+ * the host rule `appUrlTemplate` keeps — and no placeholder, because nothing
+ * is substituted into it. The hosted pages link to it as `Open <app>` when a
+ * flow is done.
+ */
+export declare const appHomeUrl: z.ZodURL;
+/** The accent colour of the hosted pages: `#rrggbb`, lowercase, the one spelling the renderer compares against. */
+export declare const hostedAccent: z.ZodString;
+/** The largest logo the hosted pages take, in bytes: 100 KB. */
+export declare const HOSTED_LOGO_MAX_BYTES = 102400;
+/** The logo types the hosted pages take. An SVG is served sandboxed and embedded only as an image. */
+export declare const HOSTED_LOGO_TYPES: readonly ["image/png", "image/svg+xml"];
+/**
+ * **The Fleetless-hosted pages an unset URL falls back to**, one per URL
+ * field, as templates with the same placeholder the field takes. Read-only:
+ * they are minted by the cloud from the auth portal's base URL and the app's
+ * identifier.
+ */
+export declare const appHostedPages: z.ZodObject<{
+    invite_url: z.ZodURL;
+    verify_url: z.ZodURL;
+    reset_url: z.ZodURL;
+    mcp_login_url: z.ZodURL;
+}, z.core.$strip>;
+export type AppHostedPages = z.infer<typeof appHostedPages>;
 /**
  * **The app's auth settings: one row per app, configured by a Fleetless user.**
  *
@@ -380,11 +451,11 @@ export declare const emailDomain: z.ZodString;
  * a developer inviting somebody by hand has already made the decision the
  * whitelist automates.
  *
- * The four URLs are what makes that work: Fleetless mails a link, and the link
- * points into the developer's app. An app that has configured none of them
- * still works for password login — it simply cannot send a mail that leads
- * anywhere, and `send_mail` is refused rather than silently sending a dead
- * link.
+ * The four URLs point Fleetless's mails and the MCP sign-in into the
+ * developer's app. **Each is optional**: an unset one falls back to the
+ * Fleetless-hosted page in `hosted_pages`, so nothing is refused for a
+ * missing URL — self-registration, mailed invitations, resets and MCP sign-in
+ * all work before the app has a page of its own.
  */
 export declare const appAuthConfig: z.ZodObject<{
     self_registration: z.ZodBoolean;
@@ -395,6 +466,24 @@ export declare const appAuthConfig: z.ZodObject<{
     verify_url: z.ZodNullable<z.ZodString>;
     reset_url: z.ZodNullable<z.ZodString>;
     mcp_login_url: z.ZodNullable<z.ZodString>;
+    app_url: z.ZodNullable<z.ZodURL>;
+    sign_in_methods: z.ZodObject<{
+        password: z.ZodBoolean;
+        email_code: z.ZodBoolean;
+    }, z.core.$strict>;
+    two_factor: z.ZodEnum<{
+        optional: "optional";
+        required: "required";
+        off: "off";
+    }>;
+    hosted_logo_url: z.ZodNullable<z.ZodURL>;
+    hosted_accent: z.ZodNullable<z.ZodString>;
+    hosted_pages: z.ZodObject<{
+        invite_url: z.ZodURL;
+        verify_url: z.ZodURL;
+        reset_url: z.ZodURL;
+        mcp_login_url: z.ZodURL;
+    }, z.core.$strip>;
     oidc_callback_url: z.ZodURL;
     updated_at: z.ZodISODateTime;
 }, z.core.$strip>;
@@ -403,8 +492,8 @@ export type AppAuthConfig = z.infer<typeof appAuthConfig>;
  * `PUT /api/apps/:id/auth-config/registration` — who may get in, and from
  * where.
  *
- * Three slices rather than one document, and each still a **replace** with
- * every field of its slice required: three screens carving up one
+ * Several slices rather than one document, and each still a **replace** with
+ * every field of its slice required: several screens carving up one
  * all-required request is how a field nobody's screen shows becomes a field
  * somebody's save clears. The slice states its own ownership, so a new field
  * lands in one schema and one screen.
@@ -418,33 +507,59 @@ export declare const putAppAuthRegistrationRequest: z.ZodObject<{
     allowed_origins: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 export type PutAppAuthRegistrationRequest = z.infer<typeof putAppAuthRegistrationRequest>;
-/** `PUT /api/apps/:id/auth-config/urls` — the three pages Fleetless's mails point at. */
+/** `PUT /api/apps/:id/auth-config/sign-in` — how the app's users sign in, and whether they give a second factor. */
+export declare const putAppAuthSignInRequest: z.ZodObject<{
+    two_factor: z.ZodEnum<{
+        optional: "optional";
+        required: "required";
+        off: "off";
+    }>;
+    sign_in_methods: z.ZodObject<{
+        password: z.ZodBoolean;
+        email_code: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type PutAppAuthSignInRequest = z.infer<typeof putAppAuthSignInRequest>;
+/**
+ * `PUT /api/apps/:id/auth-config/urls` — the app's home page and the four
+ * pages Fleetless's mails and the MCP sign-in point at. One slice, because
+ * the console's Pages section owns all five; each `null` falls back to the
+ * hosted page.
+ */
 export declare const putAppAuthUrlsRequest: z.ZodObject<{
     invite_url: z.ZodNullable<z.ZodString>;
     verify_url: z.ZodNullable<z.ZodString>;
     reset_url: z.ZodNullable<z.ZodString>;
+    mcp_login_url: z.ZodNullable<z.ZodString>;
+    app_url: z.ZodNullable<z.ZodURL>;
 }, z.core.$strict>;
 export type PutAppAuthUrlsRequest = z.infer<typeof putAppAuthUrlsRequest>;
 /**
- * `PUT /api/apps/:id/auth-config/mcp` — the switch and the login URL, which
- * belong together: on without a URL refuses every sign-in, in the MCP
- * client's browser mid-OAuth, where no console screen ever sees it.
+ * `PUT /api/apps/:id/auth-config/mcp` — the switch alone. Its login URL moved
+ * to the `urls` slice: on without a URL no longer refuses anything, because
+ * the hosted MCP sign-in stands in for it.
  */
 export declare const putAppAuthMcpRequest: z.ZodObject<{
     mcp_enabled: z.ZodBoolean;
-    mcp_login_url: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
 export type PutAppAuthMcpRequest = z.infer<typeof putAppAuthMcpRequest>;
+/** `PUT /api/apps/:id/auth-config/look` — the hosted pages' accent colour. The logo is its own write, a raw image body. */
+export declare const putAppAuthLookRequest: z.ZodObject<{
+    hosted_accent: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PutAppAuthLookRequest = z.infer<typeof putAppAuthLookRequest>;
 /**
- * The three mails a developer may replace with their own template.
- * Mails to *Fleetless* users — a team invitation, a console password reset —
- * stay Fleetless default and are deliberately not customisable: they are
- * about this platform, not about the developer's product.
+ * The four mails a developer may replace with their own template: the
+ * invitation, the address confirmation, the password reset and the sign-in
+ * code. Mails to *Fleetless* users — a team invitation, a console sign-in
+ * code — stay Fleetless default and are deliberately not customisable: they
+ * are about this platform, not about the developer's product.
  */
 export declare const mailTemplateKind: z.ZodEnum<{
     invite: "invite";
     verify: "verify";
     reset: "reset";
+    login_code: "login_code";
 }>;
 export type MailTemplateKind = z.infer<typeof mailTemplateKind>;
 /**
@@ -456,9 +571,9 @@ export type MailTemplateKind = z.infer<typeof mailTemplateKind>;
  * where the renderer, the console's completion and the docs all read the same
  * one.
  */
-export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name", "user.email", "user.display_name", "role.name", "link", "expires_in_hours"];
+export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name", "user.email", "user.display_name", "role.name", "link", "expires_in_hours", "code", "expires_in_minutes"];
 /**
- * **The Fleetless default text for the three app mails.**
+ * **The Fleetless default text for the four app mails.**
  *
  * It lives here rather than in the cloud because two products send the same
  * words: the cloud renders these when an app has no template of its own, and
@@ -492,12 +607,15 @@ export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name",
  * that one is written by an authenticated developer about somebody they
  * invited.
  *
- * **`expires_in_hours` is the only lifetime variable a template gets**, and
+ * **`expires_in_hours` is the lifetime variable of the three link mails**, and
  * the three values are 1, 24 and 168. "The next 168 hours" is not how a person
  * says a week, so each default converts: 48 and up reads in days, exactly one
  * reads "1 hour", everything else reads in hours. The conversion is in the
  * template rather than in a new variable because a custom template has the
- * same problem and this is the spelling it can copy.
+ * same problem and this is the spelling it can copy. The sign-in code mail
+ * carries no link: it names the `code` and its lifetime in
+ * `expires_in_minutes` (10), and greets nobody, since whoever asked for it
+ * typed the address unauthenticated.
  *
  * **What contracts does NOT assert about these.** That they compile as Liquid
  * is the cloud's business — contracts has no renderer and adding one to check
@@ -520,6 +638,7 @@ export declare const appMailTemplate: z.ZodObject<{
         invite: "invite";
         verify: "verify";
         reset: "reset";
+        login_code: "login_code";
     }>;
     subject: z.ZodString;
     text: z.ZodString;
@@ -534,6 +653,7 @@ export declare const appMailTemplateListResponse: z.ZodObject<{
             invite: "invite";
             verify: "verify";
             reset: "reset";
+            login_code: "login_code";
         }>;
         subject: z.ZodString;
         text: z.ZodString;