@fleetless/contracts 1.0.0

package/dist/client-auth.d.ts

@@ -0,0 +1,409 @@
+import { z } from 'zod';
+/**
+ * **The client auth API: the whole of what an app user's browser talks to**
+ * (spec `2026-09-05-app-user-auth`, §4).
+ *
+ * Fleetless shows an app user **no page** (D2). The developer's own UI owns
+ * every screen — login, 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.
+ *
+ * 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
+ * the whole family is rate-limited per app, address and IP.
+ *
+ * **Two kinds of caller reach the authenticated half**, and both use
+ * `Authorization: Bearer`:
+ *
+ * - an **app user**, with the JWT access token issued here;
+ * - a **server key** (`flk_…`), for server-side code, carrying full app rights.
+ *
+ * The cloud tells them apart by shape — a `flk_` prefix is a server key,
+ * anything else is parsed as a JWT. That rule is written down once, here, so
+ * the SDK and the cloud cannot drift into disagreeing about it.
+ *
+ * **The enumeration discipline is the design's, not a preference** (§4):
+ * `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.
+ */
+export declare const clientLoginRequest: z.ZodObject<{
+    app_identifier: z.ZodString;
+    email: z.ZodEmail;
+    password: z.ZodString;
+}, z.core.$strip>;
+export type ClientLoginRequest = z.infer<typeof clientLoginRequest>;
+export declare const clientRefreshRequest: z.ZodObject<{
+    refresh_token: z.ZodString;
+}, z.core.$strip>;
+export type ClientRefreshRequest = z.infer<typeof clientRefreshRequest>;
+/**
+ * Logging out revokes the whole token family server-side. Without this, a
+ * refresh token stolen before the user pressed "log out" keeps working —
+ * clearing a client-side store is a UI gesture, not a revocation.
+ *
+ * **The route answers `204` and has no response shape.** It used to answer a
+ * `clientLogoutResponse` reporting what was left of the session at the identity
+ * provider — RP-initiated logout, an `end_session_endpoint` to redirect to,
+ * four ways of saying "we cannot end that session". That whole apparatus
+ * belonged to the hosted login flow, where Fleetless owned the browser. It does
+ * not own it any more: the developer's app does, and an app that wants to end
+ * a provider session redirects there itself, knowing its own provider, which
+ * Fleetless never did better than it. Listed as a breaking change rather than
+ * quietly kept as a field nobody fills.
+ */
+export declare const clientLogoutRequest: z.ZodObject<{
+    refresh_token: z.ZodString;
+}, z.core.$strip>;
+export type ClientLogoutRequest = z.infer<typeof clientLogoutRequest>;
+/**
+ * **Self-registration** (D6) — and the account it creates cannot log in yet.
+ *
+ * `register` writes the user as `pending_verification` and mails the app's
+ * `verify_url`. Without that step the domain whitelist would prove nothing:
+ * anybody could claim any address at an allowed domain and be `active`
+ * immediately.
+ *
+ * **The answer is `202` for every policy-allowed request**, whether the address
+ * was new or already known — a mail goes out only in the first case, and a
+ * `register` that finds the address on an account still waiting to verify
+ * replaces that account's password and mails a fresh link, so the mailbox's own
+ * owner always wins over whoever typed their address first. A `202` that
+ * depended on existence would be the enumeration oracle the whole family is
+ * built to avoid. The refusals it *does* make are honest, because none is about
+ * a person: `403 registration_closed` when the app has self-registration off,
+ * `403 domain_not_allowed` when the address is outside `allowed_domains`, and
+ * `404 not_found` for an app identifier no app carries.
+ */
+export declare const clientRegisterRequest: z.ZodObject<{
+    app_identifier: z.ZodString;
+    email: z.ZodEmail;
+    password: z.ZodString;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ClientRegisterRequest = z.infer<typeof clientRegisterRequest>;
+/** Spending the verification token: the account becomes `active` and the answer is a session, so the person is not asked to log in immediately after proving they can read the mail. */
+export declare const clientVerifyEmailRequest: z.ZodObject<{
+    token: z.ZodString;
+}, z.core.$strict>;
+export type ClientVerifyEmailRequest = z.infer<typeof clientVerifyEmailRequest>;
+/** Asking for the verification mail again. **Always `202`**, for the reason `register` is: an answer that depended on the address existing would be the oracle by another door. */
+export declare const clientResendVerificationRequest: z.ZodObject<{
+    app_identifier: z.ZodString;
+    email: z.ZodEmail;
+}, z.core.$strict>;
+export type ClientResendVerificationRequest = z.infer<typeof clientResendVerificationRequest>;
+/**
+ * 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.
+ *
+ * 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
+ * to be. An **app identifier** no app carries is the one refusal, `404
+ * not_found`, because an identifier is public and an address is not.
+ *
+ * Moved here from `identity.ts`, where it sat because the client surface had no
+ * file of its own for it. It is an app-user shape and belongs with them.
+ */
+export declare const clientPasswordResetRequest: z.ZodObject<{
+    app_identifier: z.ZodString;
+    email: z.ZodEmail;
+}, z.core.$strict>;
+export type ClientPasswordResetRequest = z.infer<typeof clientPasswordResetRequest>;
+/** Spending the reset token. **Every refresh family of that user is revoked**, because a forgotten password is one of the two states where somebody else may be holding a session. */
+export declare const clientPasswordResetConfirmRequest: z.ZodObject<{
+    token: z.ZodString;
+    new_password: z.ZodString;
+}, z.core.$strict>;
+export type ClientPasswordResetConfirmRequest = z.infer<typeof clientPasswordResetConfirmRequest>;
+/**
+ * Accepting an app invitation. Creates the account, or activates one that was
+ * invited before it existed, with the role the invitation fixed at creation.
+ *
+ * An invitation **always bypasses the domain whitelist**: a developer inviting
+ * somebody by hand has already made the decision the whitelist automates.
+ */
+export declare const clientAcceptInvitationRequest: z.ZodObject<{
+    token: z.ZodString;
+    password: z.ZodString;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ClientAcceptInvitationRequest = z.infer<typeof clientAcceptInvitationRequest>;
+/**
+ * **The one OIDC callback path, for every app and every provider**, declared
+ * once so the cloud, the console and the documentation cannot spell it
+ * differently.
+ *
+ * `appAuthConfig.oidc_callback_url` is this path appended to the cloud's own
+ * `PUBLIC_API_BASE_URL`, and that URL is what a developer registers at their
+ * identity provider. So the string is not an implementation detail of one
+ * route: it is copied out of the console into somebody else's IdP
+ * configuration, where a later rename would break every sign-in with no error
+ * anybody here can see.
+ *
+ * **This is the path, not the URL.** The cloud mints the URL from its
+ * canonical public base — the same rule `MCP_ENDPOINT_PATH` states — and a
+ * friendly alias in front of the API is not a substitute, because the
+ * redirect target must match the one string registered at the provider
+ * exactly.
+ *
+ * `OAUTH_PATHS` is the precedent, and the warning: nine paths declared once so
+ * two repositories could not disagree, one of which then named a route the
+ * cloud had deleted. What keeps this one honest is `routes.ts` — the manifest
+ * carries the same path, the cloud's `route-manifest.test.ts` asserts set
+ * equality with it, and the test beside this file asserts the two spellings
+ * are the one string rather than two that currently agree.
+ */
+export declare const CLIENT_OIDC_CALLBACK_PATH: "/api/client/oidc/callback";
+/** The query of `GET /api/client/providers` — which app's sign-in buttons to draw. */
+export declare const clientProviderListQuery: z.ZodObject<{
+    app_identifier: z.ZodString;
+}, z.core.$strip>;
+export type ClientProviderListQuery = z.infer<typeof clientProviderListQuery>;
+/**
+ * What the developer's login page needs to draw its provider buttons, 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.
+ *
+ * Only **enabled** providers appear. A disabled one is not a button that
+ * refuses; it is a button that is not there.
+ */
+export declare const clientProviderListResponse: z.ZodObject<{
+    providers: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ClientProviderListResponse = z.infer<typeof clientProviderListResponse>;
+/**
+ * The query of `GET /api/client/oidc/:slug/start`.
+ *
+ * **The app runs its own PKCE** here, against Fleetless — a second, independent
+ * exchange from the one Fleetless runs against the identity provider. So the
+ * one-time code the callback hands back is bound to a verifier only the app's
+ * page holds, and a code intercepted in the redirect is worth nothing on its
+ * own.
+ *
+ * `redirect_uri` is validated against the app's `allowed_origins` **before
+ * anything else**, and a failure there never redirects: until the target is
+ * known-good, sending a browser to it is the attack.
+ */
+export declare const clientOidcStartQuery: z.ZodObject<{
+    app_identifier: z.ZodString;
+    redirect_uri: z.ZodURL;
+    state: z.ZodString;
+    code_challenge: z.ZodString;
+}, z.core.$strip>;
+export type ClientOidcStartQuery = z.infer<typeof clientOidcStartQuery>;
+/**
+ * **The query of `GET /api/client/oidc/callback` — the identity provider's
+ * wire, not Fleetless's.**
+ *
+ * Every field but `state` is optional and **the object is not `.strict()`**,
+ * which is the whole point of writing it down. A conforming provider sends
+ * `code` and `state` on success and `error` (with an optional
+ * `error_description`) on refusal, and many send more besides — `iss` per RFC
+ * 9207, `session_state`, a vendor field. A strict schema over somebody else's
+ * specification refuses conforming callers, which is the mistake
+ * `POST /mcp/oauth/register` documents having avoided by not parsing its body
+ * at all. Declaring the shape loosely says what arrives without promising it is
+ * the only thing that will.
+ *
+ * `state` is the one required field because it is the one Fleetless minted: it
+ * resolves the `oidc_interactions` row that holds the app's `redirect_uri`,
+ * and without it there is nowhere to send any answer, success or failure. That
+ * is the single case where the cloud renders a page of its own (D2).
+ *
+ * It exists as a schema rather than as four parameters read by hand because
+ * the manifest forbids the second: a documented route whose prose names a
+ * `?parameter=` must declare what it reads, and every phrase that used to
+ * excuse one was removed by writing the schema rather than by rewording.
+ */
+export declare const clientOidcCallbackQuery: z.ZodObject<{
+    state: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    error_description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ClientOidcCallbackQuery = z.infer<typeof clientOidcCallbackQuery>;
+/** Trading the one-time code for a session. The code lives 60 seconds and is bound to the challenge from `start`. */
+export declare const clientOidcExchangeRequest: z.ZodObject<{
+    code: z.ZodString;
+    code_verifier: z.ZodString;
+}, z.core.$strict>;
+export type ClientOidcExchangeRequest = z.infer<typeof clientOidcExchangeRequest>;
+/**
+ * **Why a federated sign-in ended without a session, in a code the app can
+ * branch on** — carried back to the app's own `redirect_uri` as `error`, not
+ * rendered by Fleetless (D2). The only Fleetless-rendered page in this flow is
+ * the one for a state that can no longer be resolved to a redirect URI, because
+ * then there is nowhere to send the answer.
+ *
+ * The five rows of D4's table are the first five values plus `no_access`:
+ *
+ * - `no_access` — the identity is unknown and nothing admits it, or the account
+ *   it names is not `active`. **One code for both**, because to the person the
+ *   remedy is the same — ask somebody to let you in — and a code that split an
+ *   outcome nobody acts on differently would tell a stranger which half applied.
+ * - `email_taken` — the address already belongs to another app user, and the
+ *   provider is not permitted to link (`link_verified_emails`, or the provider
+ *   did not assert `email_verified`). Deliberately not `no_access`: the remedy
+ *   is different — *sign in the way you signed up*.
+ * - `email_unverified` — the provider asserted an address without
+ *   `email_verified`. **An unverified address never produces or links an
+ *   account**, whatever the rest of the policy says.
+ * - `domain_not_allowed`, `registration_closed` — the self-registration policy
+ *   refused. Honest, because neither is about whether a person exists.
+ * - `idp_unavailable`, `exchange_failed`, `claims_incomplete`,
+ *   `provider_misconfigured`, `provider_disabled` — the provider's or the
+ *   developer's to fix, and the app can say so.
+ * - `invalid_request` — the start parameters did not hold up.
+ * - `quota_exceeded` — the org has as many app users as its `max_end_users`
+ *   quota allows, so no account can be created for this identity. Named rather
+ *   than folded into `no_access`, for `domain_not_allowed`'s reason: it is not
+ *   about the person, the app can say what happened, and the remedy belongs to
+ *   the developer rather than to whoever is trying to sign in. It is raised
+ *   **only where an account would be created** — an identity that already has
+ *   one signs in at the quota exactly as it does under it, because refusing a
+ *   sign-in would turn a protection limit into an outage.
+ */
+export declare const clientOidcErrorCode: z.ZodEnum<{
+    no_access: "no_access";
+    email_taken: "email_taken";
+    email_unverified: "email_unverified";
+    domain_not_allowed: "domain_not_allowed";
+    registration_closed: "registration_closed";
+    idp_unavailable: "idp_unavailable";
+    exchange_failed: "exchange_failed";
+    claims_incomplete: "claims_incomplete";
+    provider_misconfigured: "provider_misconfigured";
+    provider_disabled: "provider_disabled";
+    invalid_request: "invalid_request";
+    quota_exceeded: "quota_exceeded";
+}>;
+export type ClientOidcErrorCode = z.infer<typeof clientOidcErrorCode>;
+/**
+ * **A pending MCP authorization, as the app's own consent screen reads it**
+ * (D7). 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.
+ *
+ * `client_name_verified` is `z.literal(false)`, and that is the whole point of
+ * the field. The name comes from an **unauthenticated** dynamic registration —
+ * the client typed it about itself, nobody checked it — so a consent screen
+ * that rendered it as though it were an identity would be teaching people to
+ * trust a string an attacker chooses. A literal rather than a boolean because
+ * there is no verified case to distinguish: an app that reads this field at all
+ * has to handle the untrusted one, and a `true` branch would be dead code
+ * pretending to be a safeguard.
+ */
+export declare const clientMcpInteraction: z.ZodObject<{
+    id: z.ZodString;
+    app_id: z.ZodUUID;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    scopes: z.ZodArray<z.ZodString>;
+    already_granted: z.ZodBoolean;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ClientMcpInteraction = z.infer<typeof clientMcpInteraction>;
+/**
+ * What approve and deny both answer: **where to send the browser**. A denial
+ * carries a redirect too, with `error=access_denied` on it — a client that is
+ * refused must learn so from its own callback rather than from a page nobody
+ * sent it.
+ */
+export declare const clientMcpInteractionDecisionResponse: z.ZodObject<{
+    redirect_to: z.ZodURL;
+}, z.core.$strip>;
+export type ClientMcpInteractionDecisionResponse = z.infer<typeof clientMcpInteractionDecisionResponse>;
+/**
+ * **One standing MCP consent, as both withdrawal doors list it.**
+ *
+ * A grant is what lets a later authorization skip the app's consent screen:
+ * `clientMcpInteraction.already_granted` is a read of exactly this row. It is
+ * written when a person approves and it is removed by neither the client's
+ * registration lapsing nor its access token expiring — so without a door it
+ * was a decision a person could make once and never unmake.
+ *
+ * **Standing only.** A withdrawn grant is stamped rather than deleted, so the
+ * store still holds it; neither listing returns one. The question both doors
+ * ask is *what is connected right now*, and a row that answered "connected,
+ * but no" would be a state every caller has to filter for itself.
+ *
+ * `client_name_verified` is `z.literal(false)` for the reason
+ * `clientMcpInteraction` gives at length: the name comes from an
+ * unauthenticated dynamic registration, the client chose it about itself, and
+ * a list that rendered it as an identity would be teaching people to trust a
+ * string an attacker picked. Here it matters more than on the consent screen,
+ * not less — a "connected apps" list is read long after the moment of
+ * approval, when nobody remembers what they clicked.
+ */
+export declare const mcpConsentGrant: z.ZodObject<{
+    client_id: z.ZodString;
+    client_name: z.ZodNullable<z.ZodString>;
+    client_name_verified: z.ZodLiteral<false>;
+    granted_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type McpConsentGrant = z.infer<typeof mcpConsentGrant>;
+/** What both grant listings answer. Never null: a person who has connected nothing gets an empty array, and an absent key would make "nothing" and "not answered" the same reading. */
+export declare const mcpConsentGrantListResponse: z.ZodObject<{
+    grants: z.ZodArray<z.ZodObject<{
+        client_id: z.ZodString;
+        client_name: z.ZodNullable<z.ZodString>;
+        client_name_verified: z.ZodLiteral<false>;
+        granted_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type McpConsentGrantListResponse = z.infer<typeof mcpConsentGrantListResponse>;
+/**
+ * Who the caller turned out to be. Returned by the "who am I" endpoint and by
+ * the realtime `auth_ok` frame, so a client can render a session without
+ * decoding a token itself — decoding a JWT in the client is how apps end up
+ * trusting claims nobody verified.
+ *
+ * **Three kinds of caller reach the client API.** Besides app users and server
+ * keys, a **developer** does: the console's playground runs over the real
+ * client API and appears in the audit as the developer, and the console's own
+ * live views subscribe on `/realtime` as one. A developer is **org-scoped, not
+ * app-scoped** — they own the configuration of every robot in their org — so
+ * `app_id` and `role_id` are null for them, and roles do not filter what they
+ * see. `kind` states this explicitly rather than leaving it to be inferred from
+ * which id happens to be set.
+ *
+ * **`end_user_id` became `app_user_id`, and that is a rename with a meaning.**
+ * The old subject was a member of the org's one pool, reachable through an
+ * assignment; the new one is a row that belongs to exactly one app. Renaming
+ * rather than keeping the key is deliberate: a consumer reading `.end_user_id`
+ * would have typechecked and meant something subtly different, which is the
+ * quietest way for a cut like this to go wrong.
+ *
+ * **`act` is gone.** It named the org admin behind an impersonation (the RFC
+ * 8693 pattern). Impersonation is deleted with no successor (D1), so a field
+ * that could still arrive would describe a delegation nothing can mint — and a
+ * client rendering "you are acting as …" from it would be showing a state the
+ * platform cannot enter.
+ */
+export declare const clientIdentity: z.ZodObject<{
+    kind: z.ZodEnum<{
+        developer: "developer";
+        server_key: "server_key";
+        app_user: "app_user";
+    }>;
+    developer_id: z.ZodNullable<z.ZodUUID>;
+    app_user_id: z.ZodNullable<z.ZodUUID>;
+    server_key_id: z.ZodNullable<z.ZodUUID>;
+    app_id: z.ZodNullable<z.ZodUUID>;
+    role_id: z.ZodNullable<z.ZodUUID>;
+    email: z.ZodNullable<z.ZodEmail>;
+}, z.core.$strip>;
+export type ClientIdentity = z.infer<typeof clientIdentity>;