@fleetless/contracts 1.0.0 → 1.0.3

package/dist/app-users.js

@@ -2,8 +2,7 @@
 import { z } from 'zod';
 import { idpIssuer, mailStatus, password } from './identity.js';
 /**
- * **App users: the per-app identity space** (spec `2026-09-05-app-user-auth`,
- * D1–D7).
+ * **App users: the per-app identity space.**
  *
  * The 2026-08-29 model put developers and end users into one pool per org,
  * tied apps to groups, and let an org admin enter an app only by
@@ -22,7 +21,7 @@ import { idpIssuer, mailStatus, password } from './identity.js';
  *   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** (D2). The developer's own UI owns
+ * **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
@@ -52,12 +51,12 @@ export const providerSlug = z
 /**
  * **The three states an app user can be in, and the order is the lifecycle.**
  *
- * - `pending_verification` — self-registered, mail sent, cannot log in yet
- *   (D6). Without this state the domain whitelist would prove nothing: anybody
- *   could claim any address at an allowed domain.
+ * - `pending_verification` — self-registered, mail sent, cannot log in yet.
+ *   Without this state a domain allow-list would prove nothing: anybody could
+ *   claim any address at an allowed domain.
  * - `active` — may log in.
  * - `blocked` — may not, and every refusal is the same `invalid_credentials`
- *   a wrong password gets (§4). A block that announced itself would be an
+ *   a wrong password gets. A block that announced itself would be an
  *   account-enumeration oracle with an extra step.
  *
  * `pending_verification` is reached exactly once and left only by spending the
@@ -68,7 +67,7 @@ export const appUserStatus = z.enum(['pending_verification', 'active', 'blocked'
  * **A user of one app.** Not a user of the org: `app_id` is the whole scope,
  * and the uniqueness constraint the cloud enforces is `(app_id, lower(email))`
  * rather than a global one. The same person at two apps of one org is two
- * unrelated rows, by design (D1).
+ * unrelated rows, by design.
  */
 export const appUser = z.object({
     id: z.uuid().meta({
@@ -148,8 +147,8 @@ export const createAppUserRequest = z
  * offering it is a refusal rather than a silently dropped field.
  *
  * **`status` admits only `active` and `blocked`.** `pending_verification` is
- * reached once, by self-registration, and left by spending the mailed token
- * (D6). A developer able to set it back could void a verified address without
+ * reached once, by self-registration, and left by spending the mailed token.
+ * A developer able to set it back could void a verified address without
  * the user ever seeing a mail, and there is no route out of that state that
  * does not require a token nobody re-sent. So the narrower enum is the rule,
  * stated in the schema rather than left to a handler to remember.
@@ -196,7 +195,7 @@ export const createAppInvitationRequest = z
  * 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 (D2).
+ * Fleetless-hosted URL would name a page this product does not serve.
  */
 export const appInvitation = z.object({
     id: z.uuid().meta({ description: 'The invitation, as listed and revoked by the developer.' }),
@@ -231,7 +230,7 @@ export const appInvitationListResponse = z.object({
     }),
 });
 /**
- * **An app's OIDC provider, as read back** (D4). Any number per app, unlike
+ * **An app's OIDC provider, as read back**. Any number per app, unlike
  * the group provider this replaces — a developer serving two customers needs
  * two, and the old at-most-one rule was a property of groups rather than of
  * identity.
@@ -305,7 +304,7 @@ export const createAppOidcProviderRequest = z
         description: 'The client secret, **write-only**: it is stored encrypted and comes back through nothing — not the read, not this route\'s own answer, not an audit detail. Required on create, since a provider with no secret cannot exchange a code; the minimum length refuses a value that is a misconfiguration rather than a secret.',
     }),
     scopes: z.array(z.string().min(1).max(60)).min(1).max(20).default(['openid', 'email', 'profile']).meta({
-        description: 'The scopes to request. Defaults to `openid email profile`, which is what the linking rules in this design actually read: the subject, the address and its verified flag, and a name.',
+        description: 'The scopes to request. Defaults to `openid email profile`, which is what account linking actually reads: the subject, the address and its verified flag, and a name.',
     }),
     link_verified_emails: z.boolean().default(false).meta({
         description: 'Whether a federated login may join an existing app user by verified address. **Defaults to off**, because relaxing later is additive and admitting duplicates now and tightening afterwards is not.',
@@ -438,16 +437,15 @@ export const emailDomain = z
     .max(253)
     .regex(/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/, 'must be a lowercase domain name with at least two labels');
 /**
- * **The app's auth settings: one row per app, configured by a Fleetless user**
- * (D3).
+ * **The app's auth settings: one row per app, configured by a Fleetless user.**
  *
  * `self_registration` and `allowed_domains` are **one policy for one
  * decision** — they govern registration by password and registration through
- * an identity provider alike (D4). An invitation always bypasses both, because
+ * an identity provider alike. An invitation always bypasses both, because
  * a developer inviting somebody by hand has already made the decision the
  * whitelist automates.
  *
- * The four URLs are what makes D2 work: Fleetless mails a link, and the link
+ * 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
@@ -494,7 +492,7 @@ export const putAppAuthConfigRequest = appAuthConfig
     .omit({ oidc_callback_url: true, updated_at: true })
     .strict();
 /**
- * The three mails a developer may replace with their own template (D5).
+ * 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.
@@ -519,7 +517,7 @@ export const MAIL_TEMPLATE_VARIABLES = [
     'expires_in_hours',
 ];
 /**
- * **The Fleetless default text for the three app mails** (spec D5, §6).
+ * **The Fleetless default text for the three 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
@@ -553,7 +551,7 @@ export const MAIL_TEMPLATE_VARIABLES = [
  * that one is written by an authenticated developer about somebody they
  * invited.
  *
- * **`expires_in_hours` is the only lifetime variable the spec offers**, and
+ * **`expires_in_hours` is the only lifetime variable a template gets**, 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

package/dist/apps.d.ts

@@ -1,6 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
 /**
- * Apps, roles and rights (spec §3.2, §3.3, §12.2).
+ * Apps, roles and rights.
  *
  * The rule that shapes all of this: **roles are the only filter**. A robot
  * assigned to an app exposes every one of its services to that app; what a
@@ -42,12 +43,11 @@ export declare const appListResponse: z.ZodObject<{
 }, z.core.$strip>;
 export type AppListResponse = z.infer<typeof appListResponse>;
 /**
- * **`robot_ids` is accepted here, and `.strict()` catches everything else
- * (W7a).** Through W7 this shape carried `name` and `identifier` only, robots
- * attached through `updateAppRequest`, and zod stripped the extra key — so a
- * caller creating an app *with* robots got a `201` and an app with none.
- * **Two people fell into it independently on the same day**, which is the
- * definition of a shape that reads as though it does something it does not.
+ * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
+ * A create shape carrying `name` and `identifier` only would let zod strip an
+ * offered `robot_ids`, so a caller creating an app *with* robots gets a `201`
+ * and an app with none — a shape that reads as though it does something it does
+ * not.
  *
  * Both halves matter and neither alone is enough. Accepting `robot_ids` is
  * right because attaching robots at creation is the obvious operation and the
@@ -69,21 +69,17 @@ export type CreateAppRequest = z.infer<typeof createAppRequest>;
 /**
  * **`.strict()` is what makes an absent field mean something here.**
  *
- * This shape was not strict until 2026-08-29, which meant an offered field the
- * route does not implement was *dropped* — the caller got a `200`, nothing
- * changed, and nothing anywhere said so. That is the exact silence
- * `createAppRequest` above already learned about in W7a (*"a create shape that
- * silently drops a field cost two people a day each"*), and the lesson had not
- * been carried one shape over. A caller who sends a field this route does not
- * do is asking for something, and the honest answer is `400`, not a success
- * that means less than it looks.
+ * Without it, an offered field the route does not implement is *dropped* — the
+ * caller gets a `200`, nothing changes, and nothing anywhere says so. It is the
+ * same silence `createAppRequest` above describes. A caller who sends a field
+ * this route does not do is asking for something, and the honest answer is
+ * `400`, not a success that means less than it looks.
  *
- * Two fields left with the two-space cut and are worth naming, because both
- * were on this shape and neither has a successor here.
+ * Two fields are absent and worth naming, because neither has a successor here.
  * `accepts_dynamic_clients` gated app-level OAuth dynamic client registration,
- * which is deleted: apps use the JSON client-auth API and OAuth 2.1 remains
- * only for MCP. `group_id` named the group that owned the app, and groups are
- * gone; who may log into an app is now the app's own user list.
+ * which no longer exists: apps use the JSON client-auth API, and OAuth 2.1
+ * remains only for MCP. `group_id` named a group that owned the app; who may
+ * log into an app is the app's own user list.
  *
  * The route keeps its own check as belt-and-braces; a schema and a handler
  * agreeing is not two policies, it is one policy stated where each half can
@@ -96,9 +92,9 @@ export declare const updateAppRequest: z.ZodObject<{
 }, z.core.$strict>;
 export type UpdateAppRequest = z.infer<typeof updateAppRequest>;
 /**
- * A server key carries full app rights for server-side code (spec §3.4) —
- * never for clients. Same handling as the robot token from W1: the value is
- * returned exactly once and only its hash is stored.
+ * A server key carries full app rights for server-side code — never for
+ * clients. Same handling as the robot token: the value is returned exactly once
+ * and only its hash is stored.
  */
 export declare const serverKeyToken: z.ZodString;
 export declare const serverKey: z.ZodObject<{
@@ -133,7 +129,7 @@ export declare const createServerKeyResponse: z.ZodObject<{
 export type CreateServerKeyResponse = z.infer<typeof createServerKeyResponse>;
 /**
  * Every app starts with `observe` and `operate`; custom roles are allowed
- * from v1 (§3.3). `builtin` marks the two starting roles — they may be
+ * too. `builtin` marks the two starting roles — they may be
  * edited like any other, the flag exists so the console can explain where
  * they came from.
  */
@@ -156,7 +152,7 @@ export declare const roleListResponse: z.ZodObject<{
 export type RoleListResponse = z.infer<typeof roleListResponse>;
 /**
  * The rights matrix of one role: which slugs of which robot it may use, plus
- * the capabilities roles also govern (§3.3). `capabilities`' own doc comment
+ * the capabilities roles also govern. `capabilities`' own doc comment
  * below says which of them are enforced today and which is still a switch
  * that changes nothing.
  */

package/dist/apps.js

@@ -2,7 +2,7 @@
 import { z } from 'zod';
 import { slug } from './common.js';
 /**
- * Apps, roles and rights (spec §3.2, §3.3, §12.2).
+ * Apps, roles and rights.
  *
  * The rule that shapes all of this: **roles are the only filter**. A robot
  * assigned to an app exposes every one of its services to that app; what a
@@ -33,7 +33,7 @@ export const app = z.object({
     identifier: appIdentifier.meta({
         description: 'The stable handle a client sends at login, lowercase and underscore-separated. **Globally unique, not per organisation** — `clientLoginRequest` carries no org context to disambiguate with, so a collision is refused with `identifier_taken`.',
     }),
-    /** Robots are referenced individually; tags never grant rights (§12.2). */
+    /** Robots are referenced individually; tags never grant rights. */
     robot_ids: z.array(z.uuid()).meta({
         description: 'The robots this app may reach, each referenced individually. Tags never grant rights, and a robot absent from this list is invisible to the app whatever a role grants.',
     }),
@@ -79,12 +79,11 @@ export const appListResponse = z.object({
     }),
 });
 /**
- * **`robot_ids` is accepted here, and `.strict()` catches everything else
- * (W7a).** Through W7 this shape carried `name` and `identifier` only, robots
- * attached through `updateAppRequest`, and zod stripped the extra key — so a
- * caller creating an app *with* robots got a `201` and an app with none.
- * **Two people fell into it independently on the same day**, which is the
- * definition of a shape that reads as though it does something it does not.
+ * **`robot_ids` is accepted here, and `.strict()` catches everything else.**
+ * A create shape carrying `name` and `identifier` only would let zod strip an
+ * offered `robot_ids`, so a caller creating an app *with* robots gets a `201`
+ * and an app with none — a shape that reads as though it does something it does
+ * not.
  *
  * Both halves matter and neither alone is enough. Accepting `robot_ids` is
  * right because attaching robots at creation is the obvious operation and the
@@ -105,21 +104,17 @@ export const createAppRequest = z.object({
 /**
  * **`.strict()` is what makes an absent field mean something here.**
  *
- * This shape was not strict until 2026-08-29, which meant an offered field the
- * route does not implement was *dropped* — the caller got a `200`, nothing
- * changed, and nothing anywhere said so. That is the exact silence
- * `createAppRequest` above already learned about in W7a (*"a create shape that
- * silently drops a field cost two people a day each"*), and the lesson had not
- * been carried one shape over. A caller who sends a field this route does not
- * do is asking for something, and the honest answer is `400`, not a success
- * that means less than it looks.
+ * Without it, an offered field the route does not implement is *dropped* — the
+ * caller gets a `200`, nothing changes, and nothing anywhere says so. It is the
+ * same silence `createAppRequest` above describes. A caller who sends a field
+ * this route does not do is asking for something, and the honest answer is
+ * `400`, not a success that means less than it looks.
  *
- * Two fields left with the two-space cut and are worth naming, because both
- * were on this shape and neither has a successor here.
+ * Two fields are absent and worth naming, because neither has a successor here.
  * `accepts_dynamic_clients` gated app-level OAuth dynamic client registration,
- * which is deleted: apps use the JSON client-auth API and OAuth 2.1 remains
- * only for MCP. `group_id` named the group that owned the app, and groups are
- * gone; who may log into an app is now the app's own user list.
+ * which no longer exists: apps use the JSON client-auth API, and OAuth 2.1
+ * remains only for MCP. `group_id` named a group that owned the app; who may
+ * log into an app is the app's own user list.
  *
  * The route keeps its own check as belt-and-braces; a schema and a handler
  * agreeing is not two policies, it is one policy stated where each half can
@@ -129,7 +124,8 @@ export const updateAppRequest = z.object({
     name: z.string().min(1).max(120).optional(),
     robot_ids: z.array(z.uuid()).optional(),
     /**
-     * `app.default_role_id`'s write half — an app *setting*, which is where D1
+     * `app.default_role_id`'s write half — an app *setting*, which is where the
+   * two-identity-space model
      * put the default role, so it belongs on the app's own PATCH and not on a
      * route of its own.
      *
@@ -142,9 +138,9 @@ export const updateAppRequest = z.object({
     default_role_id: z.uuid().nullable().optional(),
 }).strict();
 /**
- * A server key carries full app rights for server-side code (spec §3.4) —
- * never for clients. Same handling as the robot token from W1: the value is
- * returned exactly once and only its hash is stored.
+ * A server key carries full app rights for server-side code — never for
+ * clients. Same handling as the robot token: the value is returned exactly once
+ * and only its hash is stored.
  */
 export const serverKeyToken = z.string().regex(/^flk_[0-9a-f]{32}$/);
 export const serverKey = z.object({
@@ -177,7 +173,7 @@ export const createServerKeyResponse = z.object({
 });
 /**
  * Every app starts with `observe` and `operate`; custom roles are allowed
- * from v1 (§3.3). `builtin` marks the two starting roles — they may be
+ * too. `builtin` marks the two starting roles — they may be
  * edited like any other, the flag exists so the console can explain where
  * they came from.
  */
@@ -203,23 +199,20 @@ export const roleListResponse = z.object({
 });
 /**
  * The rights matrix of one role: which slugs of which robot it may use, plus
- * the capabilities roles also govern (§3.3). `capabilities`' own doc comment
+ * the capabilities roles also govern. `capabilities`' own doc comment
  * below says which of them are enforced today and which is still a switch
  * that changes nothing.
  */
 export const rolePermissions = z.object({
     role_id: z.uuid(),
     /**
-     * **A slug is unique per robot across ALL service kinds** (spec §4.1:
-     * "Jeder Dienst erhält einen Slug" — one namespace, not one per kind), and
-     * the cloud's config validation enforces that with a kind-agnostic
-     * collection pass. That is why this list carries slugs and not
-     * (kind, slug) pairs: when W4 adds actions, services and publishers, a
-     * grant keeps meaning exactly what it means today, and this shape does not
-     * change. What W4 does need is an endpoint that lists every *grantable*
-     * slug of a robot with its kind, so the console's matrix can offer them —
-     * today it enumerates datapoints only, which is the seam that would
-     * otherwise force a rebuild.
+     * **A slug is unique per robot across ALL exposure kinds** — one namespace,
+     * not one per kind — and the cloud's configuration validation enforces that
+     * with a kind-agnostic collection pass. That is why this list carries slugs
+     * and not (kind, slug) pairs: a grant means the same thing whichever kind the
+     * slug turns out to name. `GET /api/robots/:id/exposures` is the companion
+     * read that lists every grantable slug of a robot **with** its kind, so a
+     * rights matrix can offer them.
      */
     grants: z.array(z.object({
         robot_id: z.uuid(),
@@ -228,25 +221,22 @@ export const rolePermissions = z.object({
     /**
      * App-wide abilities a role grants, as opposed to per-slug grants above.
      *
-     * **A capability here is a promise, and one of them is still not kept.**
-     * `action_history` and `presence` were both gated by this object from W4
-     * and implemented nowhere — no route, no SDK method, no realtime frame
-     * (register row 8). A console could therefore switch them on and nothing
-     * changed, which is worse than their absence: the developer believes they
-     * granted something. **This paragraph stays** whatever the current tally
-     * is: it is the only place that says a switch in the console may change
-     * nothing, and it is how the next unkept capability gets caught.
+     * **A capability here is a promise, and one of them is still not kept.** A
+     * capability with no route, no SDK method and no realtime frame behind it can
+     * be switched on while nothing changes, which is worse than its absence: the
+     * developer believes they granted something. **This paragraph stays**
+     * whatever the current tally is: it is the only place that says a switch may
+     * change nothing, and it is how the next unkept capability gets caught.
      *
-     * `assets` (W7) was the first one redeemed. It gates §4.6's asset store,
-     * which is not covered by `grants` because **assets are not slugs** — and it
-     * is its own decision rather than a side effect of reaching the robot,
-     * because a mesh set gives away the machine's build.
+     * `assets` gates the asset store, which is not covered by `grants` because
+     * **assets are not slugs** — and it is its own decision rather than a side
+     * effect of reaching the robot, because a mesh set gives away the machine's
+     * build.
      *
-     * **`action_history` is kept as of the run-history delta.** It gates
+     * **`action_history` is kept.** It gates
      * `GET /api/robots/:id/jobs/history` — an end user whose role lacks it is
      * refused `403 capability_required`, naming the capability so the developer
-     * knows which switch is off. It was unkeepable while nothing durable
-     * recorded what had run; `jobRun` and `job_runs` are that record.
+     * knows which switch is off.
      *
      * **What granting it discloses.** A `jobRun` names the actor who invoked
      * it, and `jobActor.label` is an email — so an end user holding this