@sealant/api-contracts-next 0.39.0-next.712 → 0.39.0-next.714

package/dist/core-api/system.d.ts

@@ -33,6 +33,13 @@ export declare const systemIndexResponseSchema: Schema.Struct<{
         readonly credentialsPiOpencode: Schema.optional<Schema.Boolean>;
         /** `ownerMap` on a capture source: an executor whose restore gives each person their files. */
         readonly captureOwnerMap: Schema.optional<Schema.Boolean>;
+        /**
+         * `sshAsOwner` on a create and `DELETE /v1/workspaces/:id/ssh-user`: the SSH gateway runs a
+         * workspace's SSH sessions as its owner's own Linux user (their `credentialsHome` uid).
+         */
+        readonly workspaceSshUser: Schema.optional<Schema.Boolean>;
+        /** `POST /v1/users/:id/person`: a user's person bound once (what `sshAsOwner` checks). */
+        readonly personBinding: Schema.optional<Schema.Boolean>;
     }>>;
 }>;
 export type SystemIndexResponse = typeof systemIndexResponseSchema.Type;
@@ -93,6 +100,13 @@ export declare const SystemGroup: HttpApiGroup.HttpApiGroup<"system", HttpApiEnd
         readonly credentialsPiOpencode: Schema.optional<Schema.Boolean>;
         /** `ownerMap` on a capture source: an executor whose restore gives each person their files. */
         readonly captureOwnerMap: Schema.optional<Schema.Boolean>;
+        /**
+         * `sshAsOwner` on a create and `DELETE /v1/workspaces/:id/ssh-user`: the SSH gateway runs a
+         * workspace's SSH sessions as its owner's own Linux user (their `credentialsHome` uid).
+         */
+        readonly workspaceSshUser: Schema.optional<Schema.Boolean>;
+        /** `POST /v1/users/:id/person`: a user's person bound once (what `sshAsOwner` checks). */
+        readonly personBinding: Schema.optional<Schema.Boolean>;
     }>>;
 }>>, HttpApiEndpoint.Json<never>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getSetupState", "GET", "/v1/system/setup-state", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly needsSetup: Schema.Boolean;

package/dist/core-api/system.js

@@ -34,6 +34,13 @@ export const systemIndexResponseSchema = Schema.Struct({
         credentialsPiOpencode: Schema.optional(Schema.Boolean),
         /** `ownerMap` on a capture source: an executor whose restore gives each person their files. */
         captureOwnerMap: Schema.optional(Schema.Boolean),
+        /**
+         * `sshAsOwner` on a create and `DELETE /v1/workspaces/:id/ssh-user`: the SSH gateway runs a
+         * workspace's SSH sessions as its owner's own Linux user (their `credentialsHome` uid).
+         */
+        workspaceSshUser: Schema.optional(Schema.Boolean),
+        /** `POST /v1/users/:id/person`: a user's person bound once (what `sshAsOwner` checks). */
+        personBinding: Schema.optional(Schema.Boolean),
     })),
 });
 export const systemHealthResponseSchema = Schema.Struct({

package/dist/core-api/users.d.ts

@@ -32,6 +32,39 @@ export declare const ensureUserResponseSchema: Schema.Struct<{
     readonly created: Schema.Boolean;
 }>;
 export type EnsureUserResponse = typeof ensureUserResponseSchema.Type;
+/**
+ * The person a user is (Mend ADR 0016: a person's Linux identity, the same in every workspace):
+ * their id in a capture owner map, their uid (40001–49999) and their home, an absolute normalised
+ * path under the deployment's homes root (`SEALANT_PERSON_HOMES_ROOT`, default `/home`).
+ */
+export declare const personBindingSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly uid: Schema.Int;
+    readonly home: Schema.String;
+}>;
+export type PersonBindingWire = typeof personBindingSchema.Type;
+export declare const bindUserPersonResponseSchema: Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly person: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly uid: Schema.Int;
+        readonly home: Schema.String;
+    }>;
+    /** True when this call made the binding; false when it was already exactly this. */
+    readonly created: Schema.Boolean;
+}>;
+export type BindUserPersonResponse = typeof bindUserPersonResponseSchema.Type;
+declare const UserPersonConflictError_base: Schema.Class<UserPersonConflictError, Schema.TaggedStruct<"UserPersonConflictError", {
+    readonly message: Schema.String;
+    readonly code: Schema.Literals<readonly ["person-binding-differs", "person-taken"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A binding that would change one already made: the user is bound to another person
+ * (`person-binding-differs`), or the person id or uid is another user's (`person-taken`). A
+ * binding is never changed through the API; the answer names no other user's values.
+ */
+export declare class UserPersonConflictError extends UserPersonConflictError_base {
+}
 declare const UserBadRequestError_base: Schema.Class<UserBadRequestError, Schema.TaggedStruct<"UserBadRequestError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -47,7 +80,22 @@ declare const UserInternalServerError_base: Schema.Class<UserInternalServerError
 }>, import("effect/Cause").YieldableError>;
 export declare class UserInternalServerError extends UserInternalServerError_base {
 }
-export declare const UsersGroup: HttpApiGroup.HttpApiGroup<"users", HttpApiEndpoint.HttpApiEndpoint<"ensureUser", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+export declare const UsersGroup: HttpApiGroup.HttpApiGroup<"users", HttpApiEndpoint.HttpApiEndpoint<"bindUserPerson", "POST", "/:userId/person", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly userId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly uid: Schema.Int;
+    readonly home: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly person: Schema.Struct<{
+        readonly id: Schema.String;
+        readonly uid: Schema.Int;
+        readonly home: Schema.String;
+    }>;
+    /** True when this call made the binding; false when it was already exactly this. */
+    readonly created: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof UserPersonConflictError | typeof UserBadRequestError | typeof UserNotFoundError | typeof UserInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"ensureUser", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     /** Matched case-insensitively; the stored form is lower-cased. */
     readonly email: Schema.String;
     readonly name: Schema.String;

package/dist/core-api/users.js

@@ -27,6 +27,32 @@ export const ensureUserResponseSchema = Schema.Struct({
     /** True when this call created the user. */
     created: Schema.Boolean,
 });
+/**
+ * The person a user is (Mend ADR 0016: a person's Linux identity, the same in every workspace):
+ * their id in a capture owner map, their uid (40001–49999) and their home, an absolute normalised
+ * path under the deployment's homes root (`SEALANT_PERSON_HOMES_ROOT`, default `/home`).
+ */
+export const personBindingSchema = Schema.Struct({
+    id: NonEmptyString,
+    uid: Schema.Int,
+    home: NonEmptyString,
+});
+export const bindUserPersonResponseSchema = Schema.Struct({
+    userId: NonEmptyString,
+    person: personBindingSchema,
+    /** True when this call made the binding; false when it was already exactly this. */
+    created: Schema.Boolean,
+});
+/**
+ * A binding that would change one already made: the user is bound to another person
+ * (`person-binding-differs`), or the person id or uid is another user's (`person-taken`). A
+ * binding is never changed through the API; the answer names no other user's values.
+ */
+export class UserPersonConflictError extends Schema.TaggedErrorClass()("UserPersonConflictError", {
+    message: Schema.String,
+    code: Schema.Literals(["person-binding-differs", "person-taken"]),
+}, { httpApiStatus: 409 }) {
+}
 export class UserBadRequestError extends Schema.TaggedErrorClass()("UserBadRequestError", { message: Schema.String }, { httpApiStatus: 400 }) {
 }
 export class UserNotFoundError extends Schema.TaggedErrorClass()("UserNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
@@ -39,6 +65,17 @@ export const UsersGroup = HttpApiGroup.make("users")
     payload: ensureUserRequestSchema,
     success: ensureUserResponseSchema,
     error: [UserBadRequestError, UserInternalServerError],
+}))
+    .add(HttpApiEndpoint.post("bindUserPerson", "/:userId/person", {
+    params: userIdParams,
+    payload: personBindingSchema,
+    success: bindUserPersonResponseSchema,
+    error: [
+        UserBadRequestError,
+        UserNotFoundError,
+        UserPersonConflictError,
+        UserInternalServerError,
+    ],
 }))
     .add(HttpApiEndpoint.get("getUser", "/:userId", {
     params: userIdParams,

package/dist/core-api/workspaces.d.ts

@@ -45,6 +45,14 @@ export declare const workspaceSshTargetSchema: Schema.Struct<{
         readonly status: Schema.Literals<readonly ["pending", "running", "ready", "failed", "stopped"]>;
         readonly endpoint: Schema.String;
     }>;
+    /**
+     * Who the gateway runs this workspace's SSH sessions as, always stated: the workspace owner's
+     * Linux user (a decimal uid, from the owner's `credentialsHome`), or `null` for root. A gateway
+     * refuses a target that does not state it (an older API, which knows no SSH user), never reads
+     * the silence as root. Sent only to a gateway that says it runs sessions as a user
+     * (`x-sealant-gateway-ssh-user: 1`); a workspace with a user refuses any other gateway.
+     */
+    readonly sessionUser: Schema.NullOr<Schema.String>;
 }>;
 export type WorkspaceSshTarget = typeof workspaceSshTargetSchema.Type;
 /**
@@ -160,6 +168,15 @@ export declare const createWorkspaceRequestSchema: Schema.Struct<{
      * completion attestation that names a launch must name this one.
      */
     readonly launchId: Schema.optional<Schema.String>;
+    /**
+     * The SSH gateway runs this workspace's SSH sessions as its owner's own Linux user: the person
+     * the owner is bound to (`POST /v1/users/:id/person`). The create must carry a capture owner map
+     * giving that person their bound uid, and `runtime.credentialsHome` must be their bound uid and
+     * home; otherwise 403 (`WorkspaceSshOwnerRefusedError`). The caller names no user. The user need not exist
+     * yet: until it does, an SSH session is refused, never run as root. Absent or false: root. A
+     * control plane reports it takes this with `features.workspaceSshUser`; an older one ignores it.
+     */
+    readonly sshAsOwner: Schema.optional<Schema.Boolean>;
 }>;
 export type CreateWorkspaceRequest = typeof createWorkspaceRequestSchema.Type;
 export declare const createWorkspaceHeadersSchema: Schema.Struct<{
@@ -579,6 +596,15 @@ export declare const renameWorkspaceRequestSchema: Schema.Struct<{
     readonly ownerUserId: Schema.optional<Schema.String>;
 }>;
 export type RenameWorkspaceRequest = typeof renameWorkspaceRequestSchema.Type;
+/**
+ * `DELETE /v1/workspaces/:id/ssh-user`: the gateway runs the workspace's SSH sessions as root from
+ * the next session channel on. The only change after create: no caller ever names a user.
+ */
+export declare const clearWorkspaceSshUserQuerySchema: Schema.Struct<{
+    /** The workspace's owner. Required by the control plane: a request that names none finds nothing. */
+    readonly ownerUserId: Schema.optional<Schema.String>;
+}>;
+export type ClearWorkspaceSshUserQuery = typeof clearWorkspaceSshUserQuerySchema.Type;
 export declare const stopWorkspaceRequestSchema: Schema.Struct<{
     readonly ownerUserId: Schema.String;
     /**
@@ -1007,6 +1033,12 @@ export declare const renameWorkspaceResponseSchema: Schema.Struct<{
     readonly updatedAt: Schema.String;
 }>;
 export type RenameWorkspaceResponse = typeof renameWorkspaceResponseSchema.Type;
+export declare const clearWorkspaceSshUserResponseSchema: Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    /** Always `null` (root) after the call. */
+    readonly sshUser: Schema.Null;
+}>;
+export type ClearWorkspaceSshUserResponse = typeof clearWorkspaceSshUserResponseSchema.Type;
 export declare const createWorkspaceResponseSchema: Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly name: Schema.String;
@@ -1676,6 +1708,7 @@ export type ListWorkspaceEventsResponse = typeof listWorkspaceEventsResponseSche
 export declare const workspaceGatewayHeadersSchema: Schema.Struct<{
     readonly "x-sealant-gateway-token": Schema.optional<Schema.String>;
     readonly "x-sealant-principal-id": Schema.optional<Schema.String>;
+    readonly "x-sealant-gateway-ssh-user": Schema.optional<Schema.String>;
 }>;
 export type WorkspaceGatewayHeaders = typeof workspaceGatewayHeadersSchema.Type;
 declare const WorkspaceBadRequestError_base: Schema.Class<WorkspaceBadRequestError, Schema.TaggedStruct<"WorkspaceBadRequestError", {
@@ -1714,6 +1747,17 @@ declare const WorkspaceUnauthorizedError_base: Schema.Class<WorkspaceUnauthorize
 }>, import("effect/Cause").YieldableError>;
 export declare class WorkspaceUnauthorizedError extends WorkspaceUnauthorizedError_base {
 }
+declare const WorkspaceSshOwnerRefusedError_base: Schema.Class<WorkspaceSshOwnerRefusedError, Schema.TaggedStruct<"WorkspaceSshOwnerRefusedError", {
+    readonly message: Schema.String;
+    readonly code: Schema.Literals<readonly ["ssh-owner-unbound", "ssh-owner-needs-owner-map", "ssh-owner-mismatch"]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * `sshAsOwner` refused: the owner is bound to no person (`ssh-owner-unbound`), the create carries no
+ * capture owner map (`ssh-owner-needs-owner-map`), or the owner map or `credentialsHome` does not
+ * give the owner's bound person their own uid and home (`ssh-owner-mismatch`). Names no path.
+ */
+export declare class WorkspaceSshOwnerRefusedError extends WorkspaceSshOwnerRefusedError_base {
+}
 declare const WorkspaceForbiddenError_base: Schema.Class<WorkspaceForbiddenError, Schema.TaggedStruct<"WorkspaceForbiddenError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -1830,7 +1874,16 @@ export declare const WorkspacesGroup: HttpApiGroup.HttpApiGroup<"workspaces", Ht
     readonly workspaceId: Schema.optional<Schema.String>;
     readonly runId: Schema.optional<Schema.String>;
     readonly launchId: Schema.optional<Schema.String>;
-}>>, HttpApiEndpoint.Json<typeof WorkspaceBadRequestError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createWorkspace", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+}>>, HttpApiEndpoint.Json<typeof WorkspaceBadRequestError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"clearWorkspaceSshUser", "DELETE", "/:workspaceId/ssh-user", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly workspaceId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    /** The workspace's owner. Required by the control plane: a request that names none finds nothing. */
+    readonly ownerUserId: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    /** Always `null` (root) after the call. */
+    readonly sshUser: Schema.Null;
+}>>, HttpApiEndpoint.Json<typeof WorkspaceNotFoundError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createWorkspace", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly ownerUserId: Schema.String;
     readonly registryId: Schema.String;
     readonly repository: Schema.String;
@@ -1873,6 +1926,15 @@ export declare const WorkspacesGroup: HttpApiGroup.HttpApiGroup<"workspaces", Ht
      * completion attestation that names a launch must name this one.
      */
     readonly launchId: Schema.optional<Schema.String>;
+    /**
+     * The SSH gateway runs this workspace's SSH sessions as its owner's own Linux user: the person
+     * the owner is bound to (`POST /v1/users/:id/person`). The create must carry a capture owner map
+     * giving that person their bound uid, and `runtime.credentialsHome` must be their bound uid and
+     * home; otherwise 403 (`WorkspaceSshOwnerRefusedError`). The caller names no user. The user need not exist
+     * yet: until it does, an SSH session is refused, never run as root. Absent or false: root. A
+     * control plane reports it takes this with `features.workspaceSshUser`; an older one ignores it.
+     */
+    readonly sshAsOwner: Schema.optional<Schema.Boolean>;
 }>>, HttpApiEndpoint.StringTree<Schema.Struct<{
     readonly "idempotency-key": Schema.optional<Schema.String>;
 }>>, HttpApiEndpoint.Json<Schema.Struct<{
@@ -1915,7 +1977,7 @@ export declare const WorkspacesGroup: HttpApiGroup.HttpApiGroup<"workspaces", Ht
     readonly replayed: Schema.optional<Schema.Boolean>;
     /** The launch identity the create named (`launchId`), recorded on its attempt. */
     readonly launchId: Schema.optional<Schema.String>;
-}>>, HttpApiEndpoint.Json<typeof BudgetExceededError | typeof WorkspaceBadRequestError | typeof WorkspaceRuntimeEnvReferencesUnsupportedError | typeof WorkspaceDockerServiceUnsupportedError | typeof WorkspaceForbiddenError | typeof WorkspaceNotFoundError | typeof WorkspaceConflictError | typeof WorkspaceBadGatewayError | typeof WorkspaceServiceUnavailableError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"execWorkspace", "POST", "/:workspaceId/exec", HttpApiEndpoint.StringTree<Schema.Struct<{
+}>>, HttpApiEndpoint.Json<typeof BudgetExceededError | typeof WorkspaceBadRequestError | typeof WorkspaceRuntimeEnvReferencesUnsupportedError | typeof WorkspaceDockerServiceUnsupportedError | typeof WorkspaceSshOwnerRefusedError | typeof WorkspaceForbiddenError | typeof WorkspaceNotFoundError | typeof WorkspaceConflictError | typeof WorkspaceBadGatewayError | typeof WorkspaceServiceUnavailableError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"execWorkspace", "POST", "/:workspaceId/exec", HttpApiEndpoint.StringTree<Schema.Struct<{
     readonly workspaceId: Schema.String;
 }>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly ownerUserId: Schema.String;
@@ -2429,6 +2491,7 @@ export declare const WorkspacesGroup: HttpApiGroup.HttpApiGroup<"workspaces", Ht
 }>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
     readonly "x-sealant-gateway-token": Schema.optional<Schema.String>;
     readonly "x-sealant-principal-id": Schema.optional<Schema.String>;
+    readonly "x-sealant-gateway-ssh-user": Schema.optional<Schema.String>;
 }>>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly attemptId: Schema.String;
@@ -2439,6 +2502,14 @@ export declare const WorkspacesGroup: HttpApiGroup.HttpApiGroup<"workspaces", Ht
         readonly status: Schema.Literals<readonly ["pending", "running", "ready", "failed", "stopped"]>;
         readonly endpoint: Schema.String;
     }>;
+    /**
+     * Who the gateway runs this workspace's SSH sessions as, always stated: the workspace owner's
+     * Linux user (a decimal uid, from the owner's `credentialsHome`), or `null` for root. A gateway
+     * refuses a target that does not state it (an older API, which knows no SSH user), never reads
+     * the silence as root. Sent only to a gateway that says it runs sessions as a user
+     * (`x-sealant-gateway-ssh-user: 1`); a workspace with a user refuses any other gateway.
+     */
+    readonly sessionUser: Schema.NullOr<Schema.String>;
 }>>, HttpApiEndpoint.Json<typeof WorkspaceUnauthorizedError | typeof WorkspaceNotFoundError | typeof WorkspaceConflictError | typeof WorkspaceServiceUnavailableError | typeof WorkspaceInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"inspectWorkspaceImage", "POST", "/image", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly ownerUserId: Schema.String;
     readonly registryId: Schema.String;

package/dist/core-api/workspaces.js

@@ -55,6 +55,14 @@ export const workspaceSshTargetSchema = Schema.Struct({
         status: Schema.Literals(["pending", "running", "ready", "failed", "stopped"]),
         endpoint: Schema.String,
     }),
+    /**
+     * Who the gateway runs this workspace's SSH sessions as, always stated: the workspace owner's
+     * Linux user (a decimal uid, from the owner's `credentialsHome`), or `null` for root. A gateway
+     * refuses a target that does not state it (an older API, which knows no SSH user), never reads
+     * the silence as root. Sent only to a gateway that says it runs sessions as a user
+     * (`x-sealant-gateway-ssh-user: 1`); a workspace with a user refuses any other gateway.
+     */
+    sessionUser: Schema.NullOr(NonEmptyString),
 });
 /**
  * Whether an image can run Mend's per-person layout on a runtime (Mend ADR 0016): the verdict of
@@ -154,6 +162,15 @@ export const createWorkspaceRequestSchema = Schema.Struct({
      * completion attestation that names a launch must name this one.
      */
     launchId: Schema.optional(NonEmptyString),
+    /**
+     * The SSH gateway runs this workspace's SSH sessions as its owner's own Linux user: the person
+     * the owner is bound to (`POST /v1/users/:id/person`). The create must carry a capture owner map
+     * giving that person their bound uid, and `runtime.credentialsHome` must be their bound uid and
+     * home; otherwise 403 (`WorkspaceSshOwnerRefusedError`). The caller names no user. The user need not exist
+     * yet: until it does, an SSH session is refused, never run as root. Absent or false: root. A
+     * control plane reports it takes this with `features.workspaceSshUser`; an older one ignores it.
+     */
+    sshAsOwner: Schema.optional(Schema.Boolean),
 });
 export const createWorkspaceHeadersSchema = Schema.Struct({
     "idempotency-key": Schema.optional(NonEmptyString),
@@ -507,6 +524,14 @@ export const renameWorkspaceRequestSchema = Schema.Struct({
     /** The workspace's owner. Required by the control plane: a rename that names none finds nothing. */
     ownerUserId: Schema.optional(NonEmptyString),
 });
+/**
+ * `DELETE /v1/workspaces/:id/ssh-user`: the gateway runs the workspace's SSH sessions as root from
+ * the next session channel on. The only change after create: no caller ever names a user.
+ */
+export const clearWorkspaceSshUserQuerySchema = Schema.Struct({
+    /** The workspace's owner. Required by the control plane: a request that names none finds nothing. */
+    ownerUserId: Schema.optional(NonEmptyString),
+});
 // Lifecycle actions are owner-scoped like execWorkspace: ownerUserId rides in the payload and a
 // mismatch yields a uniform 404 (existence is not leaked).
 export const stopWorkspaceRequestSchema = Schema.Struct({
@@ -797,6 +822,11 @@ export const renameWorkspaceResponseSchema = Schema.Struct({
     name: NonEmptyString,
     updatedAt: Schema.String,
 });
+export const clearWorkspaceSshUserResponseSchema = Schema.Struct({
+    workspaceId: NonEmptyString,
+    /** Always `null` (root) after the call. */
+    sshUser: Schema.Null,
+});
 export const createWorkspaceResponseSchema = Schema.Struct({
     workspaceId: NonEmptyString,
     name: NonEmptyString,
@@ -1072,6 +1102,9 @@ export const workspaceGatewayHeadersSchema = Schema.Struct({
     // Identifies the client principal (the SSH key's owner). The API authorizes principal x workspace
     // before returning a control target (gateway-spec §3.4).
     "x-sealant-principal-id": Schema.optional(NonEmptyString),
+    // `1` from a gateway that runs a workspace's SSH sessions as its `sshUser`. A workspace with a
+    // user answers no target to a gateway without it, which would run the session as root.
+    "x-sealant-gateway-ssh-user": Schema.optional(NonEmptyString),
 });
 export class WorkspaceBadRequestError extends Schema.TaggedErrorClass()("WorkspaceBadRequestError", {
     message: Schema.String,
@@ -1105,6 +1138,16 @@ export class WorkspaceUnauthorizedError extends Schema.TaggedErrorClass()("Works
     message: Schema.String,
 }, { httpApiStatus: 401 }) {
 }
+/**
+ * `sshAsOwner` refused: the owner is bound to no person (`ssh-owner-unbound`), the create carries no
+ * capture owner map (`ssh-owner-needs-owner-map`), or the owner map or `credentialsHome` does not
+ * give the owner's bound person their own uid and home (`ssh-owner-mismatch`). Names no path.
+ */
+export class WorkspaceSshOwnerRefusedError extends Schema.TaggedErrorClass()("WorkspaceSshOwnerRefusedError", {
+    message: Schema.String,
+    code: Schema.Literals(["ssh-owner-unbound", "ssh-owner-needs-owner-map", "ssh-owner-mismatch"]),
+}, { httpApiStatus: 403 }) {
+}
 export class WorkspaceForbiddenError extends Schema.TaggedErrorClass()("WorkspaceForbiddenError", {
     message: Schema.String,
 }, { httpApiStatus: 403 }) {
@@ -1150,6 +1193,7 @@ export const WorkspacesGroup = HttpApiGroup.make("workspaces")
         WorkspaceRuntimeEnvReferencesUnsupportedError,
         WorkspaceDockerServiceUnsupportedError,
         WorkspaceForbiddenError,
+        WorkspaceSshOwnerRefusedError,
         WorkspaceNotFoundError,
         // Selected connected account exists but is not usable (status "invalid").
         WorkspaceConflictError,
@@ -1414,6 +1458,12 @@ HttpApiEndpoint.post("expireWorkspace", "/:workspaceId/expire", {
     payload: renameWorkspaceRequestSchema,
     success: renameWorkspaceResponseSchema,
     error: [WorkspaceNotFoundError, WorkspaceInternalServerError],
+}))
+    .add(HttpApiEndpoint.delete("clearWorkspaceSshUser", "/:workspaceId/ssh-user", {
+    params: workspaceIdParams,
+    query: clearWorkspaceSshUserQuerySchema,
+    success: clearWorkspaceSshUserResponseSchema,
+    error: [WorkspaceNotFoundError, WorkspaceInternalServerError],
 }))
     .add(HttpApiEndpoint.get("listWorkspaces", "/", {
     query: listWorkspacesQuerySchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.39.0-next.712",
+  "version": "0.39.0-next.714",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -32,7 +32,7 @@
   "peerDependencies": {
     "effect": ">=4.0.0-beta.85 <5"
   },
-  "gitHead": "43bed8e5b68a8412670ea54770a7d203c6b0a554",
+  "gitHead": "6da21a94e3f8650df5cbdb53626f420981cd1831",
   "publishConfig": {
     "access": "public"
   }