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

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,10 @@ 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 — so there is always a link, and
+ * `accept_url` is never `null`.
  */
 export declare const appInvitation: z.ZodObject<{
     id: z.ZodUUID;
@@ -175,7 +186,7 @@ export declare const appInvitation: z.ZodObject<{
     email: z.ZodEmail;
     role_id: z.ZodUUID;
     expires_at: z.ZodISODateTime;
-    accept_url: z.ZodNullable<z.ZodURL>;
+    accept_url: z.ZodURL;
     mail: z.ZodEnum<{
         sent: "sent";
         not_requested: "not_requested";
@@ -371,6 +382,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 +450,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 +465,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 +491,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 +506,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 +570,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 +606,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 +637,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 +652,7 @@ export declare const appMailTemplateListResponse: z.ZodObject<{
             invite: "invite";
             verify: "verify";
             reset: "reset";
+            login_code: "login_code";
         }>;
         subject: z.ZodString;
         text: z.ZodString;