@sealant/api-contracts-next 0.39.0-next.708 → 0.39.0-next.710

package/dist/core-api/control-plane.js

@@ -6,6 +6,7 @@ import { InferenceGroup } from "./inference.js";
 import { PackagesGroup } from "./packages.js";
 import { ProfilesGroup } from "./profiles.js";
 import { RegistriesGroup } from "./registries.js";
+import { RequestRefusal } from "./request-refusal.js";
 import { RunsGroup } from "./runs.js";
 import { SessionsGroup } from "./sessions.js";
 import { SshKeysGroup } from "./ssh-keys.js";
@@ -26,6 +27,8 @@ export const ControlPlaneAPI = HttpApi.make("sealantControlPlaneApi")
     .add(RegistriesGroup.prefix("/v1/registries"))
     .add(GitHubGroup.prefix("/v1/github"))
     .add(UsersGroup.prefix("/v1/users"))
+    // Last, so it reaches every endpoint above (`HttpApi.middleware` skips endpoints added after it).
+    .middleware(RequestRefusal)
     .annotate(OpenApi.Title, "Sealant Control Plane API")
     .annotate(OpenApi.Version, "0.0.0")
     .annotate(OpenApi.Description, "Sealant control-plane HTTP API.");

package/dist/core-api/request-refusal.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Requests the contract cannot decode, on every route of the control plane API.
+ *
+ * Effect answers such a request with an empty `400`, and the failure it reports (to the request
+ * log, every `ErrorReporter` and the request's tracing span) quotes the rejected input: `Expected
+ * array, got "<argv>"`, a whole body that arrived wrapped in an array, `JSON.parse`'s excerpt of a
+ * malformed body. A request body can carry a process's arguments, a script or a credential, so
+ * `RequestRefusal`, applied to the whole API, answers `400` `RequestRefusedError` instead, with a
+ * reason that names where the request is wrong and never what it held. `describeRequestIssue` words
+ * that reason from the decode issue alone: field names the contract declares, array positions, and
+ * what was expected; a key the caller chose (an `env` or `metadata` name) reads `[…]`.
+ */
+import { Schema, SchemaIssue } from "effect";
+import { HttpApiMiddleware } from "effect/unstable/httpapi";
+declare const RequestRefusedError_base: Schema.Class<RequestRefusedError, Schema.TaggedStruct<"RequestRefusedError", {
+    /** Where the request is wrong and what was expected; never a value it held. */
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class RequestRefusedError extends RequestRefusedError_base {
+}
+declare const RequestRefusal_base: HttpApiMiddleware.ServiceClass<RequestRefusal, "@sealant/api-contracts/RequestRefusal", {
+    requires: never;
+    provides: never;
+    error: typeof RequestRefusedError;
+    clientError: never;
+    requiredForClient: false;
+    security: never;
+}, HttpApiMiddleware.HttpApiMiddleware<never, typeof RequestRefusedError, never>>;
+/** Applied to every endpoint of `ControlPlaneAPI`: see the module comment. */
+export declare class RequestRefusal extends RequestRefusal_base {
+}
+/** The reason for a body that is not JSON at all (`JSON.parse` failed). */
+export declare const REQUEST_BODY_NOT_JSON = "the request body is not valid JSON";
+/**
+ * Why a request part (`body`, `query`, `path parameters`, `headers`) cannot be decoded, from its
+ * decode issue: up to three places, each with what was expected. Never a value the request held.
+ */
+export declare const describeRequestIssue: (part: string, issue: SchemaIssue.Issue) => string;
+export {};

package/dist/core-api/request-refusal.js

@@ -0,0 +1,135 @@
+/**
+ * Requests the contract cannot decode, on every route of the control plane API.
+ *
+ * Effect answers such a request with an empty `400`, and the failure it reports (to the request
+ * log, every `ErrorReporter` and the request's tracing span) quotes the rejected input: `Expected
+ * array, got "<argv>"`, a whole body that arrived wrapped in an array, `JSON.parse`'s excerpt of a
+ * malformed body. A request body can carry a process's arguments, a script or a credential, so
+ * `RequestRefusal`, applied to the whole API, answers `400` `RequestRefusedError` instead, with a
+ * reason that names where the request is wrong and never what it held. `describeRequestIssue` words
+ * that reason from the decode issue alone: field names the contract declares, array positions, and
+ * what was expected; a key the caller chose (an `env` or `metadata` name) reads `[…]`.
+ */
+import { Option, Schema, SchemaAST, SchemaIssue } from "effect";
+import { HttpApiMiddleware } from "effect/unstable/httpapi";
+export class RequestRefusedError extends Schema.TaggedErrorClass()("RequestRefusedError", {
+    /** Where the request is wrong and what was expected; never a value it held. */
+    message: Schema.String,
+}, { httpApiStatus: 400 }) {
+}
+/** Applied to every endpoint of `ControlPlaneAPI`: see the module comment. */
+export class RequestRefusal extends HttpApiMiddleware.Service()("@sealant/api-contracts/RequestRefusal", { error: RequestRefusedError }) {
+}
+/** The reason for a body that is not JSON at all (`JSON.parse` failed). */
+export const REQUEST_BODY_NOT_JSON = "the request body is not valid JSON";
+const MAX_REASONS = 3;
+const expectedOf = (ast) => {
+    if (SchemaAST.isString(ast))
+        return "a string";
+    if (SchemaAST.isNumber(ast))
+        return "a number";
+    if (SchemaAST.isBoolean(ast))
+        return "a boolean";
+    if (SchemaAST.isArrays(ast))
+        return "an array";
+    if (SchemaAST.isObjects(ast))
+        return "an object";
+    if (SchemaAST.isNull(ast))
+        return "null";
+    if (SchemaAST.isUndefined(ast))
+        return undefined;
+    if (SchemaAST.isUnion(ast)) {
+        // The JSON codec widens some types into unions (a number also takes "NaN" and "Infinity"):
+        // what the members expect, the fixed values said only when nothing else is.
+        const kinds = [...new Set(ast.types.map(expectedOf))].filter((kind) => kind !== undefined);
+        const open = kinds.filter((kind) => kind !== "one of the allowed values");
+        return (open.length > 0 ? open : kinds).join(" or ") || undefined;
+    }
+    return "one of the allowed values";
+};
+const stringAnnotation = (annotations, key) => {
+    if (typeof annotations !== "object" || annotations === null || !(key in annotations)) {
+        return undefined;
+    }
+    const value = Reflect.get(annotations, key);
+    return typeof value === "string" ? value : undefined;
+};
+/**
+ * A schema author's own words for a failed check, unless they quote the rejected value (a guard
+ * against a future check that interpolates its input; no check in the contract does today).
+ */
+const authoredMessage = (message, actual) => {
+    if (message === undefined)
+        return undefined;
+    if (typeof actual === "string" && actual.length >= 3 && message.includes(actual)) {
+        return undefined;
+    }
+    return message;
+};
+/** A path segment: a declared field by name, a position by index, anything else as `[…]`. */
+const segment = (key, parent) => {
+    if (typeof key === "number")
+        return `[${key}]`;
+    const declared = parent !== undefined &&
+        SchemaAST.isObjects(parent) &&
+        parent.propertySignatures.some((signature) => signature.name === key);
+    return declared && typeof key === "string" ? `.${key}` : "[…]";
+};
+const leaf = (path, message) => [{ path, message }];
+const reasonsOf = (issue, path, parent) => {
+    if (issue instanceof SchemaIssue.Composite) {
+        return issue.issues.flatMap((inner) => reasonsOf(inner, path, issue.ast));
+    }
+    if (issue instanceof SchemaIssue.Pointer) {
+        const at = issue.path.reduce((acc, key) => acc + segment(key, parent), path);
+        return reasonsOf(issue.issue, at, undefined);
+    }
+    if (issue instanceof SchemaIssue.Encoding) {
+        return reasonsOf(issue.issue, path, parent);
+    }
+    if (issue instanceof SchemaIssue.AnyOf) {
+        return issue.issues.length === 0
+            ? leaf(path, `must be ${expectedOf(issue.ast) ?? "one of the allowed values"}`)
+            : issue.issues.flatMap((inner) => reasonsOf(inner, path, parent));
+    }
+    if (issue instanceof SchemaIssue.Filter) {
+        const inner = issue.issue instanceof SchemaIssue.InvalidValue
+            ? stringAnnotation(issue.issue.annotations, "message")
+            : undefined;
+        const message = authoredMessage(inner ?? stringAnnotation(issue.filter.annotations, "message"), issue.actual);
+        if (message !== undefined)
+            return leaf(path, message);
+        const expected = stringAnnotation(issue.filter.annotations, "expected");
+        if (expected !== undefined)
+            return leaf(path, `must be ${expected}`);
+        return issue.issue instanceof SchemaIssue.InvalidValue
+            ? leaf(path, "is invalid")
+            : reasonsOf(issue.issue, path, parent);
+    }
+    if (issue instanceof SchemaIssue.InvalidType) {
+        return leaf(path, `must be ${expectedOf(issue.ast) ?? "present"}`);
+    }
+    if (issue instanceof SchemaIssue.MissingKey)
+        return leaf(path, "is required");
+    if (issue instanceof SchemaIssue.InvalidValue) {
+        const actual = Option.getOrUndefined(issue.actual);
+        return leaf(path, authoredMessage(stringAnnotation(issue.annotations, "message"), actual) ?? "is invalid");
+    }
+    if (issue instanceof SchemaIssue.OneOf)
+        return leaf(path, "matches more than one allowed shape");
+    return leaf(path, "is not allowed");
+};
+/**
+ * Why a request part (`body`, `query`, `path parameters`, `headers`) cannot be decoded, from its
+ * decode issue: up to three places, each with what was expected. Never a value the request held.
+ */
+export const describeRequestIssue = (part, issue) => {
+    const reasons = reasonsOf(issue, "", undefined);
+    const shown = reasons.slice(0, MAX_REASONS).map(({ path, message }) => {
+        const where = path === "" ? `the request ${part}` : path.replace(/^\./, "");
+        // A check that names its own position (`argv[1] contains a NUL byte`) needs no prefix.
+        return message.startsWith(where) ? message : `${where} ${message}`;
+    });
+    const more = reasons.length - shown.length;
+    return more > 0 ? `${shown.join("; ")}; and ${more} more` : shown.join("; ");
+};

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

@@ -51,10 +51,41 @@ export type WorkspaceProcessUser = typeof workspaceProcessUserSchema.Type;
  * group other than `mend`), or no such user exists yet. Nothing is started.
  */
 export declare const PROCESS_USER_UNSUPPORTED_CODE = "user-unsupported";
+/** The most words a session's argv may hold, the program included. */
+export declare const SESSION_ARGV_MAX_WORDS = 64;
+/**
+ * The most UTF-8 bytes one word of a session's argv may hold, its terminating NUL not counted:
+ * Linux's `MAX_ARG_STRLEN` (32 pages, 128 KiB on 4 KiB pages) counts the NUL, so 131,071 bytes of
+ * text is the longest word `execve` takes there; one byte more fails with `E2BIG` whatever the total.
+ */
+export declare const SESSION_ARGV_MAX_WORD_BYTES: number;
+/**
+ * The most UTF-8 bytes a session's argv may hold in all: half of Linux's usual 2 MiB `ARG_MAX`,
+ * which argv shares with the environment, and far below sealantd's 8 MiB control frame.
+ */
+export declare const SESSION_ARGV_MAX_TOTAL_BYTES: number;
+/**
+ * Why `argv` cannot start a session, or `undefined` when it can. `argv[0]`, the program, is
+ * non-empty with no leading or trailing whitespace. Every later word is opaque to Sealant and may be
+ * any string, empty, whitespace-led or multi-line (`bash -lc "\n echo hi"`, `git commit -m ""`),
+ * except one with a NUL byte, which no process argument can carry, or a lone UTF-16 surrogate, which
+ * has no UTF-8 form and would not reach the process as sent. The reason names a word by its position
+ * and size, never its text, which can carry a secret: it reaches the caller in the `400` and the
+ * server's request log.
+ */
+export declare const sessionArgvIssue: (argv: readonly string[]) => string | undefined;
+/**
+ * A session's argv: the program, then its arguments, as `sessionArgvIssue` allows. One check over
+ * the whole array, because Effect's own length and whitespace checks quote the offending value.
+ */
+export declare const sessionArgvSchema: Schema.$Array<Schema.String>;
 export declare const createSessionRequestSchema: Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly ownerUserId: Schema.String;
-    /** argv[0] is the program the session runs; the rest its arguments. */
+    /**
+     * argv[0] is the program the session runs; the rest its arguments, passed to it as an argv array,
+     * never through a shell. See `sessionArgvIssue` for what is refused.
+     */
     readonly argv: Schema.$Array<Schema.String>;
     /** Working directory inside the workspace (defaults to the workspace working directory). */
     readonly cwd: Schema.optional<Schema.String>;
@@ -83,7 +114,10 @@ export type CreateSessionRequest = typeof createSessionRequestSchema.Type;
 export declare const createSessionAsUserRequestSchema: Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly ownerUserId: Schema.String;
-    /** argv[0] is the program the session runs; the rest its arguments. */
+    /**
+     * argv[0] is the program the session runs; the rest its arguments, passed to it as an argv array,
+     * never through a shell. See `sessionArgvIssue` for what is refused.
+     */
     readonly argv: Schema.$Array<Schema.String>;
     /** Working directory inside the workspace (defaults to the workspace working directory). */
     readonly cwd: Schema.optional<Schema.String>;
@@ -309,7 +343,10 @@ export declare const SessionsGroup: HttpApiGroup.HttpApiGroup<"sessions", HttpAp
 }>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createSession", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly ownerUserId: Schema.String;
-    /** argv[0] is the program the session runs; the rest its arguments. */
+    /**
+     * argv[0] is the program the session runs; the rest its arguments, passed to it as an argv array,
+     * never through a shell. See `sessionArgvIssue` for what is refused.
+     */
     readonly argv: Schema.$Array<Schema.String>;
     /** Working directory inside the workspace (defaults to the workspace working directory). */
     readonly cwd: Schema.optional<Schema.String>;
@@ -366,7 +403,10 @@ export declare const SessionsGroup: HttpApiGroup.HttpApiGroup<"sessions", HttpAp
 }>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionConflictError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createSessionAsUser", "POST", "/as-user", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
     readonly workspaceId: Schema.String;
     readonly ownerUserId: Schema.String;
-    /** argv[0] is the program the session runs; the rest its arguments. */
+    /**
+     * argv[0] is the program the session runs; the rest its arguments, passed to it as an argv array,
+     * never through a shell. See `sessionArgvIssue` for what is refused.
+     */
     readonly argv: Schema.$Array<Schema.String>;
     /** Working directory inside the workspace (defaults to the workspace working directory). */
     readonly cwd: Schema.optional<Schema.String>;

package/dist/core-api/sessions.js

@@ -48,11 +48,77 @@ export const workspaceProcessUserSchema = Schema.String.check(Schema.isPattern(/
  * group other than `mend`), or no such user exists yet. Nothing is started.
  */
 export const PROCESS_USER_UNSUPPORTED_CODE = "user-unsupported";
+/** The most words a session's argv may hold, the program included. */
+export const SESSION_ARGV_MAX_WORDS = 64;
+/**
+ * The most UTF-8 bytes one word of a session's argv may hold, its terminating NUL not counted:
+ * Linux's `MAX_ARG_STRLEN` (32 pages, 128 KiB on 4 KiB pages) counts the NUL, so 131,071 bytes of
+ * text is the longest word `execve` takes there; one byte more fails with `E2BIG` whatever the total.
+ */
+export const SESSION_ARGV_MAX_WORD_BYTES = 128 * 1024 - 1;
+/**
+ * The most UTF-8 bytes a session's argv may hold in all: half of Linux's usual 2 MiB `ARG_MAX`,
+ * which argv shares with the environment, and far below sealantd's 8 MiB control frame.
+ */
+export const SESSION_ARGV_MAX_TOTAL_BYTES = 1024 * 1024;
+const utf8Bytes = (value) => new TextEncoder().encode(value).length;
+/**
+ * A UTF-16 surrogate with no partner (with the `u` flag a pair is one code point and never matches):
+ * it has no UTF-8 form, so it would reach the process as U+FFFD.
+ */
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+/**
+ * Why `argv` cannot start a session, or `undefined` when it can. `argv[0]`, the program, is
+ * non-empty with no leading or trailing whitespace. Every later word is opaque to Sealant and may be
+ * any string, empty, whitespace-led or multi-line (`bash -lc "\n echo hi"`, `git commit -m ""`),
+ * except one with a NUL byte, which no process argument can carry, or a lone UTF-16 surrogate, which
+ * has no UTF-8 form and would not reach the process as sent. The reason names a word by its position
+ * and size, never its text, which can carry a secret: it reaches the caller in the `400` and the
+ * server's request log.
+ */
+export const sessionArgvIssue = (argv) => {
+    const program = argv[0];
+    if (program === undefined) {
+        return "argv is empty: argv[0] must name the program";
+    }
+    if (argv.length > SESSION_ARGV_MAX_WORDS) {
+        return `argv has ${argv.length} words; the maximum is ${SESSION_ARGV_MAX_WORDS}`;
+    }
+    if (program.length === 0 || program.trim() !== program) {
+        return "argv[0], the program, must be non-empty with no leading or trailing whitespace";
+    }
+    let totalBytes = 0;
+    for (const [index, word] of argv.entries()) {
+        if (word.includes("\u0000")) {
+            return `argv[${index}] contains a NUL byte, which no process argument can carry`;
+        }
+        if (LONE_SURROGATE.test(word)) {
+            return `argv[${index}] is not well-formed Unicode (a lone surrogate)`;
+        }
+        const bytes = utf8Bytes(word);
+        if (bytes > SESSION_ARGV_MAX_WORD_BYTES) {
+            return `argv[${index}] is ${bytes} bytes; the maximum per word is ${SESSION_ARGV_MAX_WORD_BYTES}`;
+        }
+        totalBytes += bytes;
+    }
+    if (totalBytes > SESSION_ARGV_MAX_TOTAL_BYTES) {
+        return `argv totals ${totalBytes} bytes; the maximum is ${SESSION_ARGV_MAX_TOTAL_BYTES}`;
+    }
+    return undefined;
+};
+/**
+ * A session's argv: the program, then its arguments, as `sessionArgvIssue` allows. One check over
+ * the whole array, because Effect's own length and whitespace checks quote the offending value.
+ */
+export const sessionArgvSchema = Schema.Array(Schema.String).check(Schema.makeFilter(sessionArgvIssue));
 export const createSessionRequestSchema = Schema.Struct({
     workspaceId: NonEmptyString,
     ownerUserId: NonEmptyString,
-    /** argv[0] is the program the session runs; the rest its arguments. */
-    argv: Schema.Array(NonEmptyString).check(Schema.isNonEmpty(), Schema.isMaxLength(64)),
+    /**
+     * argv[0] is the program the session runs; the rest its arguments, passed to it as an argv array,
+     * never through a shell. See `sessionArgvIssue` for what is refused.
+     */
+    argv: sessionArgvSchema,
     /** Working directory inside the workspace (defaults to the workspace working directory). */
     cwd: Schema.optional(NonEmptyString),
     /** Extra environment for the PTY process (values are NOT secrets — use credentials for those). */

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./core-api/budgets.js";
 export * from "./core-api/oci-names.js";
 export * from "./core-api/registries.js";
 export * from "./core-api/runs.js";
+export * from "./core-api/request-refusal.js";
 export * from "./core-api/sessions.js";
 export * from "./core-api/access-tokens.js";
 export * from "./core-api/workspaces.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./core-api/budgets.js";
 export * from "./core-api/oci-names.js";
 export * from "./core-api/registries.js";
 export * from "./core-api/runs.js";
+export * from "./core-api/request-refusal.js";
 export * from "./core-api/sessions.js";
 export * from "./core-api/access-tokens.js";
 export * from "./core-api/workspaces.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.39.0-next.708",
+  "version": "0.39.0-next.710",
   "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": "e8ad7f7a3f1b96333e67c980e93c49a764a3f245",
+  "gitHead": "5e7c33bdaf78dd6aaf0b4b64332e803f3ce8d396",
   "publishConfig": {
     "access": "public"
   }