@wirebench/engine 2.1.1

package/dist/rest/model.d.ts

@@ -0,0 +1,247 @@
+/**
+ * The REST half of the project model: an *API* and the folders and requests inside it.
+ *
+ * An API is the REST counterpart of a SOAP interface and lives beside one in the same project
+ * (`apis/<slug>/`, see `project/paths.ts`), so one workspace, one project and one set of
+ * environments serve both protocols. Everything here follows the same rules as the SOAP model:
+ * every field is `readonly`, ids are ULIDs so an entity survives a rename, `slug` is the
+ * file-system name derived from `name`, and nothing ever holds a secret — credentials are
+ * `secretRef`s resolved from the OS keychain at send time (ADR-0004).
+ *
+ * `kind` is the discriminator the project format has carried since v1. It is `'rest'` here and
+ * `'soap'` on an interface; `'grpc'` is reserved and refused by the loader (see `project/schema.ts`).
+ */
+import type { Assertion } from '../assert/model.js';
+import type { AttachmentSource, AuthConfig, CreateOptions, IdGenerator } from '../project/model.js';
+/**
+ * An HTTP method. The seven a REST client needs are spelled out so the common case is
+ * autocompleted and checked; a service that wants `PURGE`, `LOCK` or `REPORT` is not told it is
+ * wrong, because HTTP does not say it is (RFC 9110 §9).
+ */
+export type RestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | (string & {});
+/** The methods the editor offers by name, in the order it offers them. */
+export declare const COMMON_METHODS: readonly RestMethod[];
+/**
+ * One row of a params, query, headers or form table: a name, a value, and whether it takes part
+ * in the next send. Rows keep author order and may repeat a name — two `X-Trace` headers and two
+ * `tag=` parameters are both legal on the wire, so neither is deduplicated here.
+ *
+ * `enabled` is always present in memory and written to disk only when `false`, so a file stays
+ * quiet about the common case (see `project/serialize.ts`).
+ */
+export interface KeyValueEntry {
+    readonly name: string;
+    readonly value: string;
+    readonly enabled: boolean;
+    /** Free-form note, carried over from an imported definition's parameter description. */
+    readonly description?: string;
+}
+/** Creates an enabled {@link KeyValueEntry}. */
+export declare function entry(name: string, value: string, options?: {
+    readonly enabled?: boolean;
+    readonly description?: string;
+}): KeyValueEntry;
+/** The languages a raw body can be edited and sent as. Picks the editor mode and a default type. */
+export type RawLanguage = 'json' | 'xml' | 'text' | 'html' | 'javascript';
+/** The `Content-Type` each {@link RawLanguage} implies when the request sets no header itself. */
+export declare const RAW_LANGUAGE_CONTENT_TYPES: Readonly<Record<RawLanguage, string>>;
+/** The file extension a raw body of each language is stored under, beside its request file. */
+export declare const RAW_LANGUAGE_EXTENSIONS: Readonly<Record<RawLanguage, string>>;
+/**
+ * One part of a `multipart/form-data` body: either inline text or a file. Distinct from the SOAP
+ * transport's `MultipartPart`, which is a MIME part of an already-built message.
+ */
+export type MultipartFormPart = {
+    readonly kind: 'text';
+    readonly name: string;
+    readonly value: string;
+    readonly enabled: boolean;
+    readonly contentType?: string;
+} | {
+    readonly kind: 'file';
+    readonly name: string;
+    /** Where the bytes live; content-addressed in the project, or a path under the resource root. */
+    readonly source: AttachmentSource;
+    readonly enabled: boolean;
+    /** The `filename` the part advertises. Defaults to the source file's own name. */
+    readonly fileName?: string;
+    readonly contentType?: string;
+};
+/**
+ * What a request sends as its body.
+ *
+ * A raw body's text lives in a sibling file rather than inside the YAML (`project/paths.ts`), so
+ * a JSON payload diffs, highlights and merges as JSON; every other kind is small enough to stay
+ * in the request document.
+ */
+export type RestBody = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'raw';
+    readonly language: RawLanguage;
+    /** Overrides the language's default `Content-Type`; a typed header still wins over both. */
+    readonly contentType?: string;
+    /** The body exactly as edited. Stored verbatim in the sibling file. */
+    readonly text: string;
+} | {
+    readonly kind: 'form';
+    readonly fields: readonly KeyValueEntry[];
+} | {
+    readonly kind: 'multipart';
+    readonly parts: readonly MultipartFormPart[];
+} | {
+    readonly kind: 'binary';
+    readonly source: AttachmentSource;
+    readonly contentType: string;
+};
+/** The body a freshly created request starts with. */
+export declare const NO_BODY: RestBody;
+/**
+ * Per-request transport settings. Every field is optional and an absent one means *inherit*, not
+ * *off*: the send resolves request → API → project → preference, exactly as a SOAP request's
+ * properties do (`send-options.ts`).
+ */
+export interface RestRequestSettings {
+    readonly timeoutMs?: number;
+    /** Unlike SOAP, REST follows redirects by default; see `rest/send.ts` for the per-status rules. */
+    readonly followRedirects?: boolean;
+    readonly maxRedirects?: number;
+    /** Keep method and body across a 301/302 that would otherwise become a GET (RFC 9110 §15.4). */
+    readonly keepBodyOnRedirect?: boolean;
+    /** Percent-encode path and query values on send. On by default; off sends them verbatim. */
+    readonly encodeUrl?: boolean;
+    /**
+     * Send even when the server's certificate does not verify. Per request, as `trustInvalid` is
+     * per endpoint for SOAP, and badged in red wherever the request appears.
+     */
+    readonly trustInvalid?: boolean;
+    /** Id of a `wss/keystores.yaml` entry: the client identity this request's TLS handshake presents. */
+    readonly sslKeystoreRef?: string;
+    readonly bindAddress?: string;
+    readonly maxSizeBytes?: number;
+    /** Send back the cookies this request's own last response set. Off by default. */
+    readonly sendCookies?: boolean;
+    /** JSON- or XML-escape every property value substituted into the body. Off by default. */
+    readonly escapeProperties?: boolean;
+}
+/** A saved REST request: everything but a raw body lives in `<slug>.request.yaml`. */
+export interface RestRequestDef {
+    readonly kind: 'rest';
+    readonly id: string;
+    readonly name: string;
+    /** File-system name (without the `.request.yaml` suffix). */
+    readonly slug: string;
+    readonly order: number;
+    /** Markdown, shown in the Details inspector; imported from an operation's description. */
+    readonly description?: string;
+    readonly method: RestMethod;
+    /** Absolute, or relative to the API's effective base URL. May contain `{param}` and `${…}`. */
+    readonly url: string;
+    /** One row per `{param}` in {@link url}; an unfilled one is a preflight problem, never a send. */
+    readonly pathParams: readonly KeyValueEntry[];
+    readonly query: readonly KeyValueEntry[];
+    readonly headers: readonly KeyValueEntry[];
+    readonly body: RestBody;
+    /** `inherit` by default: the folder chain, then the API, decides. */
+    readonly auth: AuthConfig;
+    readonly settings: RestRequestSettings;
+    /** Declarative checks a runner evaluates against this request's response. Empty when none. */
+    readonly assertions: readonly Assertion[];
+    /**
+     * True when the operation this request was imported from is no longer in the API's definition,
+     * the same flag a SOAP request carries after an Update Definition. Nothing is ever deleted on
+     * a re-import; the request survives badged.
+     */
+    readonly orphaned?: boolean;
+}
+/** A named node in an API's tree, holding folders and requests. */
+export interface RestFolder {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    /** Default credentials for everything inside, unless a child says otherwise. */
+    readonly auth?: AuthConfig;
+    readonly folders: readonly RestFolder[];
+    readonly requests: readonly RestRequestDef[];
+}
+/** One server an imported definition declared, offered as a choice for the base URL. */
+export interface RestServer {
+    readonly url: string;
+    readonly description?: string;
+}
+/** The definition an imported API came from, cached under `apis/<slug>/definition/`. */
+export interface RestDefinitionRef {
+    /** Where the document was fetched from: a URL, or a path as the user gave it. */
+    readonly source: string;
+    readonly cache: boolean;
+    /** The OpenAPI version of the document, as it declared itself (e.g. `3.1.0`). */
+    readonly version: string;
+}
+/** A REST API: a base URL, default credentials, and a tree of folders and requests. */
+export interface RestApi {
+    readonly kind: 'rest';
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    /**
+     * Position among the project's interfaces *and* APIs, which share one ordering space so the
+     * explorer can interleave them however the user arranged them.
+     */
+    readonly order: number;
+    readonly description?: string;
+    /** May contain `${…}` properties; a workspace environment can override it per environment. */
+    readonly baseUrl: string;
+    readonly servers: readonly RestServer[];
+    readonly auth?: AuthConfig;
+    readonly definition?: RestDefinitionRef;
+    readonly folders: readonly RestFolder[];
+    readonly requests: readonly RestRequestDef[];
+}
+/** Input to {@link createApi} beyond the name. */
+export interface CreateApiInput extends CreateOptions {
+    readonly baseUrl?: string;
+    readonly slug?: string;
+    readonly description?: string;
+    readonly servers?: readonly RestServer[];
+    readonly auth?: AuthConfig;
+    readonly definition?: RestDefinitionRef;
+    readonly folders?: readonly RestFolder[];
+    readonly requests?: readonly RestRequestDef[];
+}
+/** Creates an empty API with no credentials of its own (so its requests authenticate as `none`). */
+export declare function createApi(name: string, input?: CreateApiInput): RestApi;
+/** Input to {@link createFolder} beyond the name. */
+export interface CreateFolderInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly auth?: AuthConfig;
+    readonly folders?: readonly RestFolder[];
+    readonly requests?: readonly RestRequestDef[];
+}
+/** Creates an empty folder. */
+export declare function createFolder(name: string, input?: CreateFolderInput): RestFolder;
+/** Input to {@link createRestRequest} beyond the name. */
+export interface CreateRestRequestInput extends CreateOptions {
+    readonly method?: RestMethod;
+    readonly url?: string;
+    readonly slug?: string;
+    readonly description?: string;
+    readonly pathParams?: readonly KeyValueEntry[];
+    readonly query?: readonly KeyValueEntry[];
+    readonly headers?: readonly KeyValueEntry[];
+    readonly body?: RestBody;
+    readonly auth?: AuthConfig;
+    readonly settings?: RestRequestSettings;
+}
+/** Creates a `GET` request with an empty URL, no body and inherited credentials. */
+export declare function createRestRequest(name: string, input?: CreateRestRequestInput): RestRequestDef;
+/** Generates entity ids; injectable so tests can produce deterministic APIs. */
+export type { IdGenerator };
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export declare function folderRequests(folder: Pick<RestFolder, 'folders' | 'requests'>): RestRequestDef[];
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export declare function apiRequests(api: RestApi): RestRequestDef[];
+/** Every folder in `api`, depth-first. */
+export declare function apiFolders(api: RestApi): RestFolder[];

package/dist/rest/model.js

@@ -0,0 +1,118 @@
+/**
+ * The REST half of the project model: an *API* and the folders and requests inside it.
+ *
+ * An API is the REST counterpart of a SOAP interface and lives beside one in the same project
+ * (`apis/<slug>/`, see `project/paths.ts`), so one workspace, one project and one set of
+ * environments serve both protocols. Everything here follows the same rules as the SOAP model:
+ * every field is `readonly`, ids are ULIDs so an entity survives a rename, `slug` is the
+ * file-system name derived from `name`, and nothing ever holds a secret — credentials are
+ * `secretRef`s resolved from the OS keychain at send time (ADR-0004).
+ *
+ * `kind` is the discriminator the project format has carried since v1. It is `'rest'` here and
+ * `'soap'` on an interface; `'grpc'` is reserved and refused by the loader (see `project/schema.ts`).
+ */
+import { generateId } from '../project/model.js';
+import { slugify } from '../project/paths.js';
+/** The methods the editor offers by name, in the order it offers them. */
+export const COMMON_METHODS = Object.freeze([
+    'GET',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'HEAD',
+    'OPTIONS',
+]);
+/** Creates an enabled {@link KeyValueEntry}. */
+export function entry(name, value, options) {
+    return {
+        name,
+        value,
+        enabled: options?.enabled ?? true,
+        ...(options?.description !== undefined ? { description: options.description } : {}),
+    };
+}
+/** The `Content-Type` each {@link RawLanguage} implies when the request sets no header itself. */
+export const RAW_LANGUAGE_CONTENT_TYPES = Object.freeze({
+    json: 'application/json',
+    xml: 'application/xml',
+    text: 'text/plain',
+    html: 'text/html',
+    javascript: 'application/javascript',
+});
+/** The file extension a raw body of each language is stored under, beside its request file. */
+export const RAW_LANGUAGE_EXTENSIONS = Object.freeze({
+    json: 'json',
+    xml: 'xml',
+    text: 'txt',
+    html: 'html',
+    javascript: 'js',
+});
+/** The body a freshly created request starts with. */
+export const NO_BODY = Object.freeze({ kind: 'none' });
+function idOf(options) {
+    return options?.id ?? (options?.newId ?? generateId)();
+}
+/** Creates an empty API with no credentials of its own (so its requests authenticate as `none`). */
+export function createApi(name, input = {}) {
+    return {
+        kind: 'rest',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        baseUrl: input.baseUrl ?? '',
+        servers: input.servers ?? [],
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        ...(input.definition !== undefined ? { definition: input.definition } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates an empty folder. */
+export function createFolder(name, input = {}) {
+    return {
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates a `GET` request with an empty URL, no body and inherited credentials. */
+export function createRestRequest(name, input = {}) {
+    return {
+        kind: 'rest',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        method: input.method ?? 'GET',
+        url: input.url ?? '',
+        pathParams: input.pathParams ?? [],
+        query: input.query ?? [],
+        headers: input.headers ?? [],
+        body: input.body ?? NO_BODY,
+        auth: input.auth ?? { type: 'inherit' },
+        settings: input.settings ?? {},
+        assertions: [],
+    };
+}
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export function folderRequests(folder) {
+    return [...folder.requests, ...folder.folders.flatMap((child) => folderRequests(child))];
+}
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export function apiRequests(api) {
+    return folderRequests(api);
+}
+/** Every folder in `api`, depth-first. */
+export function apiFolders(api) {
+    const walk = (folders) => folders.flatMap((folder) => [folder, ...walk(folder.folders)]);
+    return walk(api.folders);
+}

package/dist/rest/oauth2.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The OAuth2 pieces that are pure: what a token request looks like, what a token response means,
+ * and the PKCE maths (RFC 6749, RFC 7636, RFC 8252).
+ *
+ * Everything stateful stays out of the engine on purpose. Opening a browser, listening on a
+ * loopback port, caching a token for the session, deciding when to refresh — those belong to the
+ * host, which owns windows, ports and the keychain. This module only builds and reads messages, so
+ * both the desktop app and the planned CLI runner authenticate the same way.
+ *
+ * No access token is ever written to a project file or returned to a renderer by this module; it
+ * hands back a {@link TokenSet} and the host decides where it lives (ADR-0004).
+ */
+import type { OAuth2Auth } from '../project/model.js';
+import type { HttpRequest } from '../http/types.js';
+/** The credential values the host resolved for one OAuth2 configuration. */
+export interface OAuth2Secrets {
+    /** The client secret, when the configuration references one. */
+    readonly clientSecret?: string;
+    /** A refresh token, from the session cache or the keychain. */
+    readonly refreshToken?: string;
+}
+/** A token as obtained, with its expiry already turned into an absolute moment. */
+export interface TokenSet {
+    readonly accessToken: string;
+    readonly tokenType: string;
+    /** ISO-8601; absent when the server did not say how long the token lasts. */
+    readonly expiresAt?: string;
+    readonly refreshToken?: string;
+    /** The scopes actually granted, when the server named them. */
+    readonly scopes?: readonly string[];
+}
+/** A PKCE verifier and the challenge derived from it (RFC 7636, S256). */
+export interface PkcePair {
+    readonly verifier: string;
+    readonly challenge: string;
+    readonly method: 'S256';
+}
+/**
+ * A fresh PKCE pair.
+ *
+ * 32 random bytes give a 43-character verifier, the shortest RFC 7636 §4.1 allows and the length
+ * every provider tests against. `plain` is not offered: a challenge equal to its verifier protects
+ * nothing, and every provider worth supporting takes S256.
+ */
+export declare function pkce(random?: (size: number) => Uint8Array): PkcePair;
+/** A random `state` value, which is what makes a callback attributable to this flow. */
+export declare function newState(random?: (size: number) => Uint8Array): string;
+/** Options for {@link authorizationUrl}. */
+export interface AuthorizationUrlInput {
+    readonly config: OAuth2Auth;
+    readonly redirectUri: string;
+    readonly state: string;
+    /** Omit for a configuration with PKCE switched off. */
+    readonly challenge?: string;
+}
+/**
+ * The URL the user's browser is sent to for an authorization-code flow.
+ *
+ * @throws WirebenchError `oauth2-no-authorization-url` when the configuration has no endpoint to
+ * send them to, which is a configuration error rather than something to guess at.
+ */
+export declare function authorizationUrl(input: AuthorizationUrlInput): string;
+/** Which token request to build. */
+export type TokenGrantInput = {
+    readonly grant: 'client-credentials';
+} | {
+    readonly grant: 'authorization-code';
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly verifier?: string;
+} | {
+    readonly grant: 'refresh';
+    readonly refreshToken: string;
+};
+/** Options for {@link buildTokenRequest} beyond the configuration and the grant. */
+export interface TokenRequestOptions {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Builds the `POST` to the token endpoint.
+ *
+ * `clientAuth` decides where the client credentials go: `basic` puts them in an `Authorization`
+ * header (RFC 6749 §2.3.1, which providers overwhelmingly prefer), `body` puts `client_secret` in
+ * the form. A public client — no secret at all — sends `client_id` in the body and no header, which
+ * is what RFC 8252 §8.4 expects of a native app.
+ *
+ * @throws WirebenchError `oauth2-no-token-url` when the configuration has no token endpoint
+ */
+export declare function buildTokenRequest(config: OAuth2Auth, secrets: OAuth2Secrets, grantInput: TokenGrantInput, options?: TokenRequestOptions): HttpRequest;
+/** What the token endpoint answered with, as far as reading it goes. */
+export interface TokenResponseInput {
+    readonly status: number;
+    readonly body: Uint8Array;
+    /** Clock for turning `expires_in` into an absolute moment; injected so tests are deterministic. */
+    readonly now?: () => Date;
+}
+/**
+ * Reads a token response (RFC 6749 §5.1) or raises the error it describes (§5.2).
+ *
+ * A provider that answers 200 with an `error` field, or 400 with a perfectly good token, is not
+ * unheard of, so the body decides and the status only breaks ties. `expires_in` is turned into an
+ * absolute `expiresAt` immediately: a duration is meaningless once it has been cached.
+ *
+ * @throws WirebenchError `oauth2-token-error` with the provider's own `error`/`error_description`,
+ * or `oauth2-token-malformed` when the body is not a token response at all
+ */
+export declare function parseTokenResponse(input: TokenResponseInput): TokenSet;
+/** How close to its expiry a token is refreshed rather than used. */
+export declare const TOKEN_REFRESH_MARGIN_MS = 30000;
+/**
+ * Whether `token` should be replaced before the next send.
+ *
+ * A token with no stated expiry is used until it fails, which is all a client can do; one with an
+ * expiry is refreshed while it still has {@link TOKEN_REFRESH_MARGIN_MS} left, so a slow request
+ * does not arrive just after it lapsed.
+ */
+export declare function needsRefresh(token: TokenSet, now?: Date): boolean;