@leaflow/sdk 0.0.0-dev.47.g94a977a → 0.0.0-dev.470.g87d6289

package/dist/fleet/v1/generated/validators/sessionResource.zod.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * Leaflow Fleet API
+ * Machines that run the Leaflow Fleet Agent (`leaflow-fleet-agent`): adding machines, the
+ * accounts and groups that log in to them, running commands, opening and closing sessions, with
+ * or without a desktop, and admitting participants to them.
+ *
+ * ## What this API sees
+ *
+ * This API coordinates. It admits participants to sessions and passes the signaling of their
+ * PeerConnections, but everything a session shows or receives — terminals, files, the screen,
+ * input, the clipboard, printing and privilege approvals on a participant — travels end to end
+ * between the participant and the session, encrypted with keys that never leave them. The
+ * platform sees which machine, which session and who is connected, and nothing of what happens
+ * inside.
+ *
+ * Commands and privilege requests decided on the platform are the exception: the platform passes
+ * a command and its output between the caller and the machine, and keeps the command line of a
+ * privilege request it asks the owner about; it sees both.
+ *
+ * ## Authentication
+ *
+ * Every request carries a scoped token; see the `bearerAuth` security scheme.
+ *
+ * **Neither the path nor the headers carry a `project_id`**: the current project is determined by
+ * the token.
+ *
+ * ## Adding a machine
+ *
+ * 1. Install the Agent and run `leaflow-fleet-agent daemon enroll` on the machine. The command
+ *    carries no secret. The machine shows a pairing code such as `7K2QM-9XWTD`.
+ * 2. Find the request with `GET /api/v1/enrollments:find?pairing_code=…`. Compare its `hostname`
+ *    and `source_address` with the machine in front of you: the pairing code is not a secret,
+ *    and anyone can request enrollment.
+ * 3. Approve it with `POST /api/v1/enrollments/{enrollmentId}:approve`. The machine joins the
+ *    current project within its next polling interval.
+ *
+ * ## Adding a machine without interaction
+ *
+ * A machine that is set up unattended, such as by cloud-init on first boot, joins with a
+ * registration token instead of a pairing code:
+ *
+ * 1. Create a registration with `POST /api/v1/machine-registrations`. It reserves a machine in
+ *    the current project under the given name and returns its `machine_id` and a `token`. The
+ *    token is returned only in this response.
+ * 2. Give the token to the machine in a file that only root can read, and run
+ *    `leaflow-fleet-agent daemon enroll --url <control endpoint> --token-file <path>`. The
+ *    machine joins the current project as `machine_id` at once, and the Agent deletes the file.
+ *
+ * A token enrolls one machine once, and only until the registration expires. Anyone who reads
+ * the token before the machine uses it can enroll a key of their own instead, so pass it only
+ * to the machine, keep its lifetime short, and compare the `public_key` of the used
+ * registration with the key the machine shows when that matters. Revoke a registration that
+ * will not be used with `DELETE /api/v1/machine-registrations/{registrationId}`.
+ *
+ * ## Trusting a machine's key
+ *
+ * Each machine has an Ed25519 key that it generates itself and that never leaves it. Participants
+ * verify that key end to end before they exchange any data with a session, so a client must
+ * decide which key belongs to a machine without relying on any party in between:
+ *
+ * - When approving an enrollment, recompute the pairing code from `public_key` and compare it
+ *   with the code the machine shows. The code is derived as documented for
+ *   `EnrollMachineResponse.pairing_code` in `leaflow/fleet/machine/v1/machine.proto`.
+ *   Approve only when they match, and remember the key for the machine.
+ * - On any other client, remember the key the first time it connects to the machine, and
+ *   refuse to continue whenever the machine later proves a different key. The fingerprint can
+ *   be compared with the one the Agent prints on the machine.
+ *
+ * A machine that is reinstalled enrolls again as a new machine with a new key.
+ *
+ * ## Features
+ *
+ * A machine reports what it offers in `features`, each named after the protocol package that
+ * defines it:
+ *
+ * - `leaflow.fleet.directory.v1`: the accounts of the project's members and the project's groups
+ *   exist on the machine; members log in over SSH with their keys and become root through sudo
+ *   as their permissions allow;
+ * - `leaflow.fleet.command.v1`: running commands;
+ * - `leaflow.fleet.mcp.v1`: the MCP servers each account configures on the machine, local ones
+ *   and remote ones it connects to;
+ * - `leaflow.fleet.host.v1`: terminal sessions, with programs, files, ports, sound, devices,
+ *   printers and privilege approvals;
+ * - `leaflow.fleet.virtualdesktop.host.v1`: sessions with a desktop.
+ *
+ * A machine installed without a desktop does not offer `leaflow.fleet.virtualdesktop.host.v1`. A
+ * request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names the feature.
+ *
+ * ## Directory
+ *
+ * Every user has one account, as with Google Cloud OS Login: a username and a uid that are the
+ * same on every machine of every project. The account is created the first time the user may log
+ * in to a machine or opens a session; its username comes from the email address, such as
+ * `alice_example_com` for `alice@example.com`, and its owner can change it. A project's machines
+ * know the accounts of the project's members and the groups the project defines. A member who
+ * leaves the project can no longer log in, and files keep their owner.
+ *
+ * Who may log in to which machines, and who may become root there through sudo, are permissions
+ * of the project's roles: `fleet:machines.login` and `fleet:machines.admin`, each for all
+ * machines or for chosen ones. Changes reach the machines within about a minute, and every login
+ * and elevation is checked against the current permissions while the machine is connected. To
+ * keep a member out of some machines, deny them `fleet:machines.login` on those machines.
+ * Elevation through sudo is never approved by a password; see "Approving sudo".
+ *
+ * Members log in over SSH with the SSH keys of their own accounts (`/account/v1/me/ssh-keys` on
+ * the account API), while they may log in to the machine.
+ *
+ * Machines resolve directory accounts and groups themselves and never write them into their local
+ * account files. A local account or group that already uses a name or id of the directory keeps
+ * it, and the machine records the conflict among its events.
+ *
+ * ## Running commands
+ *
+ * `POST /api/v1/machines/{machineId}:runCommand` runs one command line on the machine as the
+ * caller's account, as `ssh machine 'command'` would, but without SSH: the machine needs no open
+ * port, no distributed key and no address the caller can reach. Like logging in, it requires
+ * `fleet:machines.login` on the machine. Inside the command, `sudo` works without a prompt for
+ * a caller with `fleet:machines.admin` on the machine: the request approves the elevation.
+ *
+ * ## MCP servers
+ *
+ * A machine that offers `leaflow.fleet.mcp.v1` reaches the MCP servers its accounts configure:
+ * servers it runs itself and remote servers it connects to. Each account configures them in
+ * `~/.local/share/leaflow/agent/mcp.json` in its home directory, in the `mcpServers` format other
+ * MCP clients use, by hand or through this API; the machine picks up every change by itself.
+ * The caller's servers run as the caller's account, and the requests below act on them only.
+ *
+ * The configuration stays on the machine. The values of `env` and `headers` often hold
+ * credentials: this API writes them, and they then pass through the platform, but never returns
+ * them. Arguments, URLs, tool arguments and tool results pass through the platform as they are.
+ *
+ * ## Approving sudo
+ *
+ * An account may become root through sudo on a machine while its user has
+ * `fleet:machines.admin` there. Each elevation is approved, in the first of these ways that
+ * applies:
+ *
+ * - inside a command run through this API, by the request itself;
+ * - by the user's automatic approval for the machine, for a while or until removed
+ *   (`PUT /api/v1/machines/{machineId}/privilege-auto-approval`), in one of two modes:
+ *   - `automatic_review`, the recommended one: a large language model reviews each request and
+ *     approves or denies it with a reason. It stops most dangerous requests, but not all of
+ *     them. Each review is a request to Canopy, the model platform, through the project's
+ *     Canopy service, and may incur Canopy charges; the project needs Canopy enabled. A
+ *     request that cannot be reviewed, such as when the project has not enabled Canopy or the
+ *     review does not complete in time, is denied with a reason saying so;
+ *   - `always_approve`: every request is approved at once. This is dangerous: any program that
+ *     runs as the account, such as a script or an AI agent, becomes root without anyone being
+ *     asked;
+ * - by the user, on any of their devices, for a request listed by `GET /api/v1/privilege-requests`
+ *   (`POST …:approve` or `…:deny`), or on a participant of the session the asking process belongs
+ *   to. A request nobody decides expires, and sudo fails.
+ *
+ * A denied sudo shows whoever ran it the reason, when the denial gave one.
+ *
+ * Requests reach the user's devices as they happen through EventBus: the event
+ * `leaflow.fleet.privilege.requested` when one waits for the user and
+ * `leaflow.fleet.privilege.decided` when it ends, each addressed to the user in the current
+ * project and carrying the request's `id`. Requests decided without asking the user raise
+ * neither. A client that subscribes to them needs no polling; one that does not can list the
+ * pending requests.
+ *
+ * ## Connections that drop
+ *
+ * A machine's Agent and a session's process each keep a connection to the service, and on a poor
+ * network it may drop and come back within seconds. Requests do not fail for that:
+ *
+ * - A request that needs the machine or the session's process waits while it connects again,
+ *   for as long as the request would wait for its answer, and fails with `MACHINE_OFFLINE` or
+ *   `SESSION_UNAVAILABLE` only when it does not come back in that time.
+ * - What the machine or the session's process received before its connection dropped, such as a
+ *   command or a session being opened, goes on, and its result is returned once it has
+ *   connected again within that time.
+ *
+ * A machine stays `online` for up to a minute after its connection was lost, while its Agent
+ * connects again; a machine whose Agent stops is offline at once.
+ *
+ * ## Operations that do not exist
+ *
+ * Some resources lack an operation on purpose:
+ *
+ * - Accounts are created when they are first needed and are never deleted, so that files keep
+ *   their owner.
+ * - Enrollment requests are made only by machines.
+ * - A machine registration cannot be changed; revoke it and create another.
+ * - Machine events are a log: they are listed, never changed, and kept for 30 days.
+ * - A privilege request is decided only by the user whose account asks, or on a participant of
+ *   the session it comes from.
+ *
+ * ## Joining a session
+ *
+ * 1. Have an Ed25519 key, for as long as the client wants: one per participant or one kept by
+ *    the client. The private key must never leave the client; in a browser, use a
+ *    non-extractable WebCrypto key.
+ * 2. Get the ICE servers with `GET /api/v1/sessions/{sessionId}/rtc-configuration`, create a
+ *    PeerConnection with them and its data channels (`leaflow/fleet/transport/v1/transport.proto`)
+ *    and make an offer. Wait briefly for ICE candidates, such as until gathering completes or
+ *    one second has passed, so that the offer carries them.
+ * 3. Join with `POST /api/v1/sessions/{sessionId}/participants`, sending the public key and the
+ *    offer. The answer carries the participant's signed authorization, the keys the service
+ *    signs with, and the first PeerConnection: the session's SDP answer, its ICE candidates and
+ *    the signed PeerAuthorization. Pass candidates gathered later with
+ *    `POST …/participants/{participantId}/peer-connections/{peerConnectionId}/candidates`.
+ * 4. Renew the participant with `POST …/participants/{participantId}:renew` well before
+ *    `lease_expires_at`, every 15 seconds, presenting the PeerAuthorization of each
+ *    PeerConnection; the answer renews them. A participant whose lease runs out ends, and its
+ *    PeerConnections stop within 30 seconds of their last lease.
+ * 5. When a path fails, start another PeerConnection with
+ *    `POST …/participants/{participantId}/peer-connections` and move the connection to it with
+ *    `:prepareMigration` and `:commitMigration`. Abandon a PeerConnection that does not
+ *    connect with `DELETE …/peer-connections/{peerConnectionId}`.
+ * 6. Leave with `DELETE …/participants/{participantId}`.
+ *
+ * Signaling travels only through these requests; a participant holds no other connection to
+ * the service.
+ *
+ * What a participant may do in a session is decided when it is created, from the caller's
+ * permissions and what the request asks for, and does not change afterwards. Participants are not
+ * told apart by kind: a person in a browser and a program that operates the session are both
+ * participants, named by the `client_name` they choose, and either can be disconnected.
+ *
+ * Every participant that ends, including through `DELETE`, is announced through EventBus as
+ * `leaflow.fleet.participant.ended`, addressed to its user in the current project, with its
+ * `session_id`, `participant_id` (a decimal string) and `reason`: `left` when its user ended it,
+ * `removed` when someone else did, `lease_expired` when it was not renewed in time,
+ * `session_ended` when its session ended, `session_process_lost` when the session's process did
+ * not come back in time, `permission_revoked` when a permission it was created with was revoked
+ * from its user, `membership_ended` when its user is no longer a member of the project,
+ * `user_inactive` when its user's account was suspended or banned or its deletion was requested,
+ * `project_deletion_requested` when deletion of the project was requested, `machine_removed` when
+ * its machine was removed, or `key_revoked` when the key that signed its authorization was
+ * revoked. A participant whose creation failed is not announced.
+ * OpenAPI spec version: 1.0.0
+ */
+import * as zod from "zod";
+export declare const SessionResource: zod.ZodObject<{
+    id: zod.ZodString;
+    machine_id: zod.ZodUUID;
+    user: zod.ZodObject<{
+        id: zod.ZodUUID;
+        name: zod.ZodString;
+    }, zod.z.core.$strict>;
+    username: zod.ZodString;
+    state: zod.ZodEnum<{
+        open: "open";
+        closed: "closed";
+        closing: "closing";
+        opening: "opening";
+    }>;
+    desktop: zod.ZodUnion<readonly [zod.ZodObject<{
+        mode: zod.ZodEnum<{
+            desktop: "desktop";
+            seamless: "seamless";
+        }>;
+        display: zod.ZodString;
+    }, zod.z.core.$strict>, zod.ZodNull]>;
+    process_connected: zod.ZodBoolean;
+    last_input_at: zod.ZodNullable<zod.z.ZodISODateTime>;
+    close_reason: zod.ZodUnion<readonly [zod.ZodEnum<{
+        unknown: "unknown";
+        close_requested: "close_requested";
+        terminate_requested: "terminate_requested";
+        logout: "logout";
+        disconnected_timeout: "disconnected_timeout";
+        no_participant_timeout: "no_participant_timeout";
+        max_lifetime: "max_lifetime";
+        display_exit: "display_exit";
+        process_lost: "process_lost";
+        open_failed: "open_failed";
+        access_revoked: "access_revoked";
+        machine_restarted: "machine_restarted";
+    }>, zod.ZodNull]>;
+    created_at: zod.z.ZodISODateTime;
+    closed_at: zod.ZodNullable<zod.z.ZodISODateTime>;
+}, zod.z.core.$strict>;
+export type SessionResource = zod.input<typeof SessionResource>;
+export type SessionResourceOutput = zod.output<typeof SessionResource>;

package/dist/fleet/v1/generated/validators/sessionResource.zod.js

@@ -0,0 +1,266 @@
+/**
+ * Generated by orval 🍺
+ * Do not edit manually.
+ * Leaflow Fleet API
+ * Machines that run the Leaflow Fleet Agent (`leaflow-fleet-agent`): adding machines, the
+ * accounts and groups that log in to them, running commands, opening and closing sessions, with
+ * or without a desktop, and admitting participants to them.
+ *
+ * ## What this API sees
+ *
+ * This API coordinates. It admits participants to sessions and passes the signaling of their
+ * PeerConnections, but everything a session shows or receives — terminals, files, the screen,
+ * input, the clipboard, printing and privilege approvals on a participant — travels end to end
+ * between the participant and the session, encrypted with keys that never leave them. The
+ * platform sees which machine, which session and who is connected, and nothing of what happens
+ * inside.
+ *
+ * Commands and privilege requests decided on the platform are the exception: the platform passes
+ * a command and its output between the caller and the machine, and keeps the command line of a
+ * privilege request it asks the owner about; it sees both.
+ *
+ * ## Authentication
+ *
+ * Every request carries a scoped token; see the `bearerAuth` security scheme.
+ *
+ * **Neither the path nor the headers carry a `project_id`**: the current project is determined by
+ * the token.
+ *
+ * ## Adding a machine
+ *
+ * 1. Install the Agent and run `leaflow-fleet-agent daemon enroll` on the machine. The command
+ *    carries no secret. The machine shows a pairing code such as `7K2QM-9XWTD`.
+ * 2. Find the request with `GET /api/v1/enrollments:find?pairing_code=…`. Compare its `hostname`
+ *    and `source_address` with the machine in front of you: the pairing code is not a secret,
+ *    and anyone can request enrollment.
+ * 3. Approve it with `POST /api/v1/enrollments/{enrollmentId}:approve`. The machine joins the
+ *    current project within its next polling interval.
+ *
+ * ## Adding a machine without interaction
+ *
+ * A machine that is set up unattended, such as by cloud-init on first boot, joins with a
+ * registration token instead of a pairing code:
+ *
+ * 1. Create a registration with `POST /api/v1/machine-registrations`. It reserves a machine in
+ *    the current project under the given name and returns its `machine_id` and a `token`. The
+ *    token is returned only in this response.
+ * 2. Give the token to the machine in a file that only root can read, and run
+ *    `leaflow-fleet-agent daemon enroll --url <control endpoint> --token-file <path>`. The
+ *    machine joins the current project as `machine_id` at once, and the Agent deletes the file.
+ *
+ * A token enrolls one machine once, and only until the registration expires. Anyone who reads
+ * the token before the machine uses it can enroll a key of their own instead, so pass it only
+ * to the machine, keep its lifetime short, and compare the `public_key` of the used
+ * registration with the key the machine shows when that matters. Revoke a registration that
+ * will not be used with `DELETE /api/v1/machine-registrations/{registrationId}`.
+ *
+ * ## Trusting a machine's key
+ *
+ * Each machine has an Ed25519 key that it generates itself and that never leaves it. Participants
+ * verify that key end to end before they exchange any data with a session, so a client must
+ * decide which key belongs to a machine without relying on any party in between:
+ *
+ * - When approving an enrollment, recompute the pairing code from `public_key` and compare it
+ *   with the code the machine shows. The code is derived as documented for
+ *   `EnrollMachineResponse.pairing_code` in `leaflow/fleet/machine/v1/machine.proto`.
+ *   Approve only when they match, and remember the key for the machine.
+ * - On any other client, remember the key the first time it connects to the machine, and
+ *   refuse to continue whenever the machine later proves a different key. The fingerprint can
+ *   be compared with the one the Agent prints on the machine.
+ *
+ * A machine that is reinstalled enrolls again as a new machine with a new key.
+ *
+ * ## Features
+ *
+ * A machine reports what it offers in `features`, each named after the protocol package that
+ * defines it:
+ *
+ * - `leaflow.fleet.directory.v1`: the accounts of the project's members and the project's groups
+ *   exist on the machine; members log in over SSH with their keys and become root through sudo
+ *   as their permissions allow;
+ * - `leaflow.fleet.command.v1`: running commands;
+ * - `leaflow.fleet.mcp.v1`: the MCP servers each account configures on the machine, local ones
+ *   and remote ones it connects to;
+ * - `leaflow.fleet.host.v1`: terminal sessions, with programs, files, ports, sound, devices,
+ *   printers and privilege approvals;
+ * - `leaflow.fleet.virtualdesktop.host.v1`: sessions with a desktop.
+ *
+ * A machine installed without a desktop does not offer `leaflow.fleet.virtualdesktop.host.v1`. A
+ * request that needs a feature the machine does not report available fails with
+ * `FEATURE_UNAVAILABLE`, whose `metadata.feature` names the feature.
+ *
+ * ## Directory
+ *
+ * Every user has one account, as with Google Cloud OS Login: a username and a uid that are the
+ * same on every machine of every project. The account is created the first time the user may log
+ * in to a machine or opens a session; its username comes from the email address, such as
+ * `alice_example_com` for `alice@example.com`, and its owner can change it. A project's machines
+ * know the accounts of the project's members and the groups the project defines. A member who
+ * leaves the project can no longer log in, and files keep their owner.
+ *
+ * Who may log in to which machines, and who may become root there through sudo, are permissions
+ * of the project's roles: `fleet:machines.login` and `fleet:machines.admin`, each for all
+ * machines or for chosen ones. Changes reach the machines within about a minute, and every login
+ * and elevation is checked against the current permissions while the machine is connected. To
+ * keep a member out of some machines, deny them `fleet:machines.login` on those machines.
+ * Elevation through sudo is never approved by a password; see "Approving sudo".
+ *
+ * Members log in over SSH with the SSH keys of their own accounts (`/account/v1/me/ssh-keys` on
+ * the account API), while they may log in to the machine.
+ *
+ * Machines resolve directory accounts and groups themselves and never write them into their local
+ * account files. A local account or group that already uses a name or id of the directory keeps
+ * it, and the machine records the conflict among its events.
+ *
+ * ## Running commands
+ *
+ * `POST /api/v1/machines/{machineId}:runCommand` runs one command line on the machine as the
+ * caller's account, as `ssh machine 'command'` would, but without SSH: the machine needs no open
+ * port, no distributed key and no address the caller can reach. Like logging in, it requires
+ * `fleet:machines.login` on the machine. Inside the command, `sudo` works without a prompt for
+ * a caller with `fleet:machines.admin` on the machine: the request approves the elevation.
+ *
+ * ## MCP servers
+ *
+ * A machine that offers `leaflow.fleet.mcp.v1` reaches the MCP servers its accounts configure:
+ * servers it runs itself and remote servers it connects to. Each account configures them in
+ * `~/.local/share/leaflow/agent/mcp.json` in its home directory, in the `mcpServers` format other
+ * MCP clients use, by hand or through this API; the machine picks up every change by itself.
+ * The caller's servers run as the caller's account, and the requests below act on them only.
+ *
+ * The configuration stays on the machine. The values of `env` and `headers` often hold
+ * credentials: this API writes them, and they then pass through the platform, but never returns
+ * them. Arguments, URLs, tool arguments and tool results pass through the platform as they are.
+ *
+ * ## Approving sudo
+ *
+ * An account may become root through sudo on a machine while its user has
+ * `fleet:machines.admin` there. Each elevation is approved, in the first of these ways that
+ * applies:
+ *
+ * - inside a command run through this API, by the request itself;
+ * - by the user's automatic approval for the machine, for a while or until removed
+ *   (`PUT /api/v1/machines/{machineId}/privilege-auto-approval`), in one of two modes:
+ *   - `automatic_review`, the recommended one: a large language model reviews each request and
+ *     approves or denies it with a reason. It stops most dangerous requests, but not all of
+ *     them. Each review is a request to Canopy, the model platform, through the project's
+ *     Canopy service, and may incur Canopy charges; the project needs Canopy enabled. A
+ *     request that cannot be reviewed, such as when the project has not enabled Canopy or the
+ *     review does not complete in time, is denied with a reason saying so;
+ *   - `always_approve`: every request is approved at once. This is dangerous: any program that
+ *     runs as the account, such as a script or an AI agent, becomes root without anyone being
+ *     asked;
+ * - by the user, on any of their devices, for a request listed by `GET /api/v1/privilege-requests`
+ *   (`POST …:approve` or `…:deny`), or on a participant of the session the asking process belongs
+ *   to. A request nobody decides expires, and sudo fails.
+ *
+ * A denied sudo shows whoever ran it the reason, when the denial gave one.
+ *
+ * Requests reach the user's devices as they happen through EventBus: the event
+ * `leaflow.fleet.privilege.requested` when one waits for the user and
+ * `leaflow.fleet.privilege.decided` when it ends, each addressed to the user in the current
+ * project and carrying the request's `id`. Requests decided without asking the user raise
+ * neither. A client that subscribes to them needs no polling; one that does not can list the
+ * pending requests.
+ *
+ * ## Connections that drop
+ *
+ * A machine's Agent and a session's process each keep a connection to the service, and on a poor
+ * network it may drop and come back within seconds. Requests do not fail for that:
+ *
+ * - A request that needs the machine or the session's process waits while it connects again,
+ *   for as long as the request would wait for its answer, and fails with `MACHINE_OFFLINE` or
+ *   `SESSION_UNAVAILABLE` only when it does not come back in that time.
+ * - What the machine or the session's process received before its connection dropped, such as a
+ *   command or a session being opened, goes on, and its result is returned once it has
+ *   connected again within that time.
+ *
+ * A machine stays `online` for up to a minute after its connection was lost, while its Agent
+ * connects again; a machine whose Agent stops is offline at once.
+ *
+ * ## Operations that do not exist
+ *
+ * Some resources lack an operation on purpose:
+ *
+ * - Accounts are created when they are first needed and are never deleted, so that files keep
+ *   their owner.
+ * - Enrollment requests are made only by machines.
+ * - A machine registration cannot be changed; revoke it and create another.
+ * - Machine events are a log: they are listed, never changed, and kept for 30 days.
+ * - A privilege request is decided only by the user whose account asks, or on a participant of
+ *   the session it comes from.
+ *
+ * ## Joining a session
+ *
+ * 1. Have an Ed25519 key, for as long as the client wants: one per participant or one kept by
+ *    the client. The private key must never leave the client; in a browser, use a
+ *    non-extractable WebCrypto key.
+ * 2. Get the ICE servers with `GET /api/v1/sessions/{sessionId}/rtc-configuration`, create a
+ *    PeerConnection with them and its data channels (`leaflow/fleet/transport/v1/transport.proto`)
+ *    and make an offer. Wait briefly for ICE candidates, such as until gathering completes or
+ *    one second has passed, so that the offer carries them.
+ * 3. Join with `POST /api/v1/sessions/{sessionId}/participants`, sending the public key and the
+ *    offer. The answer carries the participant's signed authorization, the keys the service
+ *    signs with, and the first PeerConnection: the session's SDP answer, its ICE candidates and
+ *    the signed PeerAuthorization. Pass candidates gathered later with
+ *    `POST …/participants/{participantId}/peer-connections/{peerConnectionId}/candidates`.
+ * 4. Renew the participant with `POST …/participants/{participantId}:renew` well before
+ *    `lease_expires_at`, every 15 seconds, presenting the PeerAuthorization of each
+ *    PeerConnection; the answer renews them. A participant whose lease runs out ends, and its
+ *    PeerConnections stop within 30 seconds of their last lease.
+ * 5. When a path fails, start another PeerConnection with
+ *    `POST …/participants/{participantId}/peer-connections` and move the connection to it with
+ *    `:prepareMigration` and `:commitMigration`. Abandon a PeerConnection that does not
+ *    connect with `DELETE …/peer-connections/{peerConnectionId}`.
+ * 6. Leave with `DELETE …/participants/{participantId}`.
+ *
+ * Signaling travels only through these requests; a participant holds no other connection to
+ * the service.
+ *
+ * What a participant may do in a session is decided when it is created, from the caller's
+ * permissions and what the request asks for, and does not change afterwards. Participants are not
+ * told apart by kind: a person in a browser and a program that operates the session are both
+ * participants, named by the `client_name` they choose, and either can be disconnected.
+ *
+ * Every participant that ends, including through `DELETE`, is announced through EventBus as
+ * `leaflow.fleet.participant.ended`, addressed to its user in the current project, with its
+ * `session_id`, `participant_id` (a decimal string) and `reason`: `left` when its user ended it,
+ * `removed` when someone else did, `lease_expired` when it was not renewed in time,
+ * `session_ended` when its session ended, `session_process_lost` when the session's process did
+ * not come back in time, `permission_revoked` when a permission it was created with was revoked
+ * from its user, `membership_ended` when its user is no longer a member of the project,
+ * `user_inactive` when its user's account was suspended or banned or its deletion was requested,
+ * `project_deletion_requested` when deletion of the project was requested, `machine_removed` when
+ * its machine was removed, or `key_revoked` when the key that signed its authorization was
+ * revoked. A participant whose creation failed is not announced.
+ * OpenAPI spec version: 1.0.0
+ */
+import * as zod from "zod";
+import { DesktopState } from "./desktopState.zod.js";
+import { NamedIdentity } from "./namedIdentity.zod.js";
+import { SessionCloseReason } from "./sessionCloseReason.zod.js";
+import { SessionState } from "./sessionState.zod.js";
+export const SessionResource = zod.strictObject({
+    id: zod.string(),
+    machine_id: zod.uuid(),
+    user: NamedIdentity,
+    username: zod
+        .string()
+        .describe("The Linux user the session runs as; `user` is the project member who owns the session"),
+    state: SessionState,
+    desktop: zod
+        .union([DesktopState, zod.null()])
+        .describe("The session's desktop; null for a session without one"),
+    process_connected: zod
+        .boolean()
+        .describe("The session's process is connected to the service, so participants can join and start\nPeerConnections. False while it connects again, such as after it restarted; such\nrequests then wait for it and fail with `SESSION_UNAVAILABLE` only if it does not come\nback in time."),
+    last_input_at: zod.iso
+        .datetime({ offset: true })
+        .nullable()
+        .describe("The last input of a person in the session"),
+    close_reason: zod
+        .union([SessionCloseReason, zod.null()])
+        .describe("Null until the session is closed"),
+    created_at: zod.iso.datetime({ offset: true }),
+    closed_at: zod.iso.datetime({ offset: true }).nullable(),
+});