@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/project/schema.js

@@ -17,147 +17,20 @@
  * project the first time an older build saves. "Additive is safe" is true of
  * formats that round-trip unknown keys; this one deliberately does not. See
  * ADR-0003.
+ *
+ * This file holds the core documents only: the manifest, an environment, the keystore registry, the
+ * WS-Security configurations, the webhook collection and the definition-cache manifests. A
+ * protocol's container and request files are in its own folder (`soap/files.ts`, `rest/files.ts`,
+ * `grpc/files.ts`, `ws/files.ts`), and the pieces they share in `schema-parts.ts`.
  */
 import { z } from 'zod';
-import { assertionsSchema } from '../assert/schema.js';
-import { ProjectError } from '../errors.js';
 import { FORMAT_VERSION } from './model.js';
 import { DEFAULT_WSS_ENCRYPTION_PARTS, DEFAULT_WSS_SIGNATURE_PARTS } from '../wss/model.js';
-const nonEmpty = z.string().min(1);
+import { authConfigSchema, envName, nonEmpty, restFolderFileSchema, webhookSigningSchema } from './schema-parts.js';
+// The pieces the protocols' file schemas share are declared in `schema-parts.ts` and keep their
+// old names here. A protocol's own file schemas are exported from its folder.
+export { assertSupportedKind, attachmentSourceSchema, authConfigSchema, definitionAuthSchema, endpointAuthSchema, hookLinkSchema, keyValueEntrySchema, parseFile, restFolderFileSchema, scriptsSchema, soapOwnerAuthSchema, webhookSigningSchema, } from './schema-parts.js';
 const propertyMapSchema = z.record(z.string(), z.string());
-/**
- * A committed, human-chosen name for a secret reference — not the secret itself — used to build
- * the environment variable a CI run reads it from (see `secrets/env-names.ts`).
- */
-const envName = z
-    .string()
-    .regex(/^[A-Z][A-Z0-9_]*$/)
-    .optional();
-/**
- * Credentials as persisted: usernames and a `secretRef`, never a password
- * value. Unlike every other schema here, a plaintext `password` key is
- * explicitly rejected rather than merely ignored — secrets must never be
- * written to a project file, in any format.
- */
-export const endpointAuthSchema = z
-    .looseObject({
-    type: z.enum(['none', 'basic', 'ntlm']),
-    username: z.string().optional(),
-    passwordRef: z.string().optional(),
-    passwordEnv: envName,
-    domain: z.string().optional(),
-    workstation: z.string().optional(),
-    preemptive: z.boolean().optional(),
-})
-    .refine((value) => !('password' in value), {
-    message: 'endpoint auth must not contain a plaintext "password" field; use passwordRef',
-    path: ['password'],
-});
-/**
- * Keys that would hold a credential *value* rather than a reference to one. A project file must
- * never carry one, in any authentication scheme, so they are rejected outright rather than
- * ignored — the same rule `endpointAuthSchema` applies to `password`, stated once for the
- * schemes added with the REST client (ADR-0004).
- */
-const PLAINTEXT_SECRET_KEYS = [
-    'password',
-    'token',
-    'secret',
-    'clientSecret',
-    'client_secret',
-    'apiKey',
-    'refreshToken',
-];
-/** Adds the {@link PLAINTEXT_SECRET_KEYS} rejection to one authentication schema. */
-function refuseSecretValues(schema) {
-    return schema.superRefine((value, ctx) => {
-        for (const key of PLAINTEXT_SECRET_KEYS) {
-            if (key in value) {
-                ctx.addIssue({
-                    code: 'custom',
-                    path: [key],
-                    message: `auth must not contain a plaintext "${key}" field; use a secretRef`,
-                });
-            }
-        }
-    });
-}
-const inheritAuthSchema = z.looseObject({ type: z.literal('inherit') });
-const bearerAuthSchema = refuseSecretValues(z.looseObject({
-    type: z.literal('bearer'),
-    tokenRef: z.string().optional(),
-    tokenEnv: envName,
-    scheme: z.string().optional(),
-}));
-const apiKeyAuthSchema = refuseSecretValues(z.looseObject({
-    type: z.literal('api-key'),
-    name: z.string(),
-    valueRef: z.string().optional(),
-    valueEnv: envName,
-    in: z.enum(['header', 'query']),
-}));
-const oauth2AuthSchema = refuseSecretValues(z.looseObject({
-    type: z.literal('oauth2'),
-    grant: z.enum(['client-credentials', 'authorization-code']),
-    tokenUrl: z.string(),
-    authorizationUrl: z.string().optional(),
-    clientId: z.string(),
-    clientSecretRef: z.string().optional(),
-    clientSecretEnv: envName,
-    scopes: z.array(z.string()).default([]),
-    audience: z.string().optional(),
-    clientAuth: z.enum(['basic', 'body']).default('basic'),
-    pkce: z.boolean().default(true),
-    refreshTokenRef: z.string().optional(),
-}));
-/**
- * Authentication as persisted anywhere a project configures it. `endpointAuthSchema` is one arm,
- * so a file written before the REST client — which only ever held `none`/`basic`/`ntlm` — parses
- * unchanged. `inherit` is accepted here and rejected by the SOAP schemas that reuse
- * `endpointAuthSchema` instead, since an interface has nothing to inherit from.
- */
-export const authConfigSchema = z.union([
-    endpointAuthSchema,
-    inheritAuthSchema,
-    bearerAuthSchema,
-    apiKeyAuthSchema,
-    oauth2AuthSchema,
-]);
-const endpointSchema = z.looseObject({
-    id: nonEmpty,
-    name: z.string(),
-    url: z.string(),
-    auth: endpointAuthSchema.optional(),
-    authMode: z.enum(['override', 'complement']),
-    trustInvalid: z.boolean().optional(),
-});
-/**
- * A stored WS-Addressing configuration. Every field beyond `enabled` is optional so a project
- * written before the WS-Addressing task — which only ever held `{ enabled, version? }` — still
- * loads; `normalizeWsa` fills the rest in with the v1 defaults.
- */
-const wsaSchema = z.looseObject({
-    enabled: z.boolean(),
-    version: z.enum(['2005/08', '2004/08']).optional(),
-    mustUnderstand: z.enum(['none', 'true', 'false']).optional(),
-    action: z.string().optional(),
-    to: z.string().optional(),
-    messageId: z.string().optional(),
-    replyTo: z.string().optional(),
-    from: z.string().optional(),
-    faultTo: z.string().optional(),
-    relatesTo: z.string().optional(),
-    relationshipType: z.string().optional(),
-    addDefaultAction: z.boolean().optional(),
-    addDefaultTo: z.boolean().optional(),
-    generateMessageId: z.boolean().optional(),
-});
-const operationEntrySchema = z.looseObject({
-    name: nonEmpty,
-    bindingName: z.string(),
-    slug: nonEmpty,
-    order: z.number().int(),
-});
 /** `wirebench.yaml`. */
 export const manifestSchema = z.looseObject({
     formatVersion: z.literal(FORMAT_VERSION),
@@ -177,322 +50,18 @@ export const manifestSchema = z.looseObject({
     /** Name of the Wirebench build that last wrote this manifest; informational only. */
     writtenBy: z.string().optional(),
 });
-/** `interfaces/<slug>/interface.yaml`. */
-export const interfaceFileSchema = z.looseObject({
-    kind: z.literal('soap'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    definitionUrl: z.string(),
-    cacheDefinition: z.boolean(),
-    targetNamespace: z.string().optional(),
-    endpoints: z.array(endpointSchema),
-    defaultEndpointId: z.string().optional(),
-    wsa: wsaSchema,
-    auth: endpointAuthSchema.optional(),
-    operations: z.array(operationEntrySchema),
-});
-const requestPropertiesSchema = z.looseObject({
-    encoding: z.string(),
-    timeoutMs: z.number().int().nonnegative().optional(),
-    bindAddress: z.string().optional(),
-    followRedirects: z.boolean(),
-    skipSoapAction: z.boolean(),
-    enableMtom: z.boolean(),
-    forceMtom: z.boolean(),
-    inlineResponseAttachments: z.boolean(),
-    expandMtomAttachments: z.boolean(),
-    disableMultiparts: z.boolean(),
-    encodeAttachments: z.boolean(),
-    enableInlineFiles: z.boolean(),
-    removeEmptyContent: z.boolean(),
-    entitizeProperties: z.boolean(),
-    prettyPrint: z.boolean(),
-    stripWhitespaces: z.boolean(),
-    dumpFile: z.string().optional(),
-    maxSizeBytes: z.number().int().nonnegative().optional(),
-    wssPasswordType: z.enum(['text', 'digest']).optional(),
-    wssTimeToLive: z.number().int().nonnegative().optional(),
-    sslKeystoreRef: z.string().optional(),
-});
-/** Where a file's bytes live: the project's content-addressed cache, or a path on disk. */
-export const attachmentSourceSchema = z.union([
-    z.looseObject({ kind: z.literal('cache'), sha256: nonEmpty }),
-    z.looseObject({ kind: z.literal('path'), path: nonEmpty }),
-]);
-const attachmentSchema = z.looseObject({
-    id: nonEmpty,
-    name: z.string(),
-    contentType: z.string(),
-    size: z.number().int().nonnegative(),
-    part: z.string().optional(),
-    type: z.enum(['XOP', 'MIME', 'SWAREF', 'CONTENT', 'UNKNOWN']),
-    contentId: z.string(),
-    cached: z.boolean(),
-    source: attachmentSourceSchema,
-});
-/** `interfaces/<slug>/operations/<slug>/<name>.request.yaml` (the envelope lives in the sibling `.xml`). */
-export const requestFileSchema = z.looseObject({
-    kind: z.literal('soap'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    endpointId: z.string().optional(),
-    endpointUrl: z.string().optional(),
-    soapVersion: z.enum(['1.1', '1.2']),
-    soapAction: z.string().optional(),
-    headers: z.array(z.looseObject({ name: z.string(), value: z.string() })),
-    attachments: z.array(attachmentSchema),
-    auth: endpointAuthSchema.optional(),
-    wsa: wsaSchema.optional(),
-    wssOutgoingRef: z.string().optional(),
-    wssIncomingRef: z.string().optional(),
-    properties: requestPropertiesSchema,
-    assertions: assertionsSchema.default([]),
-    orphaned: z.boolean().optional(),
-});
-/**
- * One table row as persisted. `enabled` is written only when `false`, so a missing key means
- * enabled; names may repeat and their order is the wire order.
- */
-export const keyValueEntrySchema = z.looseObject({
-    name: z.string(),
-    value: z.string(),
-    enabled: z.boolean().default(true),
-    description: z.string().optional(),
-});
-/**
- * An HTTP method: any RFC 9110 token, not just the seven the editor names. A service that speaks
- * `PURGE` or `REPORT` is not a malformed project.
- */
-const methodSchema = z
-    .string()
-    .min(1)
-    .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, 'a method must be an HTTP token');
-const multipartPartSchema = z.union([
-    z.looseObject({
-        kind: z.literal('text'),
-        name: z.string(),
-        value: z.string(),
-        enabled: z.boolean().default(true),
-        contentType: z.string().optional(),
-    }),
-    z.looseObject({
-        kind: z.literal('file'),
-        name: z.string(),
-        source: attachmentSourceSchema,
-        enabled: z.boolean().default(true),
-        fileName: z.string().optional(),
-        contentType: z.string().optional(),
-    }),
-]);
-/**
- * A request body as persisted. A raw body names its sibling file rather than carrying its text:
- * `file` is a bare file name in the request's own directory, validated as a path segment before
- * anything is read or written (ADR-0005).
- */
-export const restBodySchema = z.union([
-    z.looseObject({ kind: z.literal('none') }),
-    z.looseObject({
-        kind: z.literal('raw'),
-        language: z.enum(['json', 'xml', 'text', 'html', 'javascript']),
-        contentType: z.string().optional(),
-        file: nonEmpty,
-    }),
-    z.looseObject({ kind: z.literal('form'), fields: z.array(keyValueEntrySchema).default([]) }),
-    z.looseObject({ kind: z.literal('multipart'), parts: z.array(multipartPartSchema).default([]) }),
-    z.looseObject({ kind: z.literal('binary'), source: attachmentSourceSchema, contentType: z.string() }),
-]);
-const restSettingsSchema = z.looseObject({
-    timeoutMs: z.number().int().nonnegative().optional(),
-    followRedirects: z.boolean().optional(),
-    maxRedirects: z.number().int().nonnegative().optional(),
-    keepBodyOnRedirect: z.boolean().optional(),
-    encodeUrl: z.boolean().optional(),
-    trustInvalid: z.boolean().optional(),
-    sslKeystoreRef: z.string().optional(),
-    bindAddress: z.string().optional(),
-    maxSizeBytes: z.number().int().nonnegative().optional(),
-    sendCookies: z.boolean().optional(),
-    escapeProperties: z.boolean().optional(),
-});
-/** `apis/<slug>/requests/[<folder>/…]<name>.request.yaml`. */
-export const restRequestFileSchema = z.looseObject({
-    kind: z.literal('rest'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    method: methodSchema,
-    url: z.string(),
-    pathParams: z.array(keyValueEntrySchema).default([]),
-    query: z.array(keyValueEntrySchema).default([]),
-    headers: z.array(keyValueEntrySchema).default([]),
-    body: restBodySchema.default({ kind: 'none' }),
-    auth: authConfigSchema.default({ type: 'inherit' }),
-    settings: restSettingsSchema.default({}),
-    assertions: assertionsSchema.default([]),
-    orphaned: z.boolean().optional(),
-});
-/** `apis/<slug>/requests/[<folder>/…]folder.yaml`. */
-export const restFolderFileSchema = z.looseObject({
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    auth: authConfigSchema.optional(),
-});
-/** `apis/<slug>/api.yaml`. */
-export const apiFileSchema = z.looseObject({
-    kind: z.literal('rest'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    baseUrl: z.string(),
-    servers: z.array(z.looseObject({ url: z.string(), description: z.string().optional() })).default([]),
-    auth: authConfigSchema.optional(),
-    definition: z
-        .looseObject({ source: nonEmpty, cache: z.boolean().default(true), version: z.string().default('') })
-        .optional(),
-});
-const grpcSettingsSchema = z.looseObject({
-    timeoutMs: z.number().int().nonnegative().optional(),
-    trustInvalid: z.boolean().optional(),
-    sslKeystoreRef: z.string().optional(),
-    bindAddress: z.string().optional(),
-    maxSizeBytes: z.number().int().nonnegative().optional(),
-    escapeProperties: z.boolean().optional(),
-});
-/** The four shapes a gRPC method can take. */
-export const grpcMethodKindSchema = z.enum(['unary', 'server-streaming', 'client-streaming', 'bidi-streaming']);
-/**
- * `apis/<slug>/requests/[<folder>/…]<name>.request.yaml` for a gRPC request. The message text lives
- * in the sibling file `message` names, validated as a path segment before it is read (ADR-0005),
- * so a JSON message is a JSON file in git like a REST raw body.
- */
-export const grpcRequestFileSchema = z.looseObject({
-    kind: z.literal('grpc'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    service: z.string(),
-    method: z.string(),
-    methodKind: grpcMethodKindSchema.default('unary'),
-    metadata: z.array(keyValueEntrySchema).default([]),
-    message: nonEmpty.optional(),
-    auth: authConfigSchema.default({ type: 'inherit' }),
-    settings: grpcSettingsSchema.default({}),
-    orphaned: z.boolean().optional(),
-});
-/** `apis/<slug>/api.yaml` for a gRPC API. */
-export const grpcApiFileSchema = z.looseObject({
-    kind: z.literal('grpc'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
+/** `webhooks/webhooks.yaml`. */
+export const webhooksFileSchema = z.looseObject({
     target: z.string(),
-    tls: z.boolean().default(false),
-    metadata: z.array(keyValueEntrySchema).default([]),
     auth: authConfigSchema.optional(),
-    definition: z
-        .looseObject({
-        // Absent in every project written before server reflection, which is an imported set.
-        kind: z.enum(['proto', 'reflection']).default('proto'),
-        source: nonEmpty,
-        cache: z.boolean().default(true),
-        roots: z.array(nonEmpty).default([]),
-        reflectionVersion: z.enum(['auto', 'v1', 'v1alpha']).optional(),
-        trustInvalid: z.boolean().optional(),
-    })
-        .optional(),
-});
-const wsSettingsSchema = z.looseObject({
-    handshakeTimeoutMs: z.number().int().nonnegative().optional(),
-    trustInvalid: z.boolean().optional(),
-    sslKeystoreRef: z.string().optional(),
-    bindAddress: z.string().optional(),
-    maxMessageBytes: z.number().int().nonnegative().optional(),
-    escapeProperties: z.boolean().optional(),
+    signing: webhookSigningSchema.optional(),
 });
-/**
- * One saved message as persisted: its text (or, for `binary`, base64) lives in the sibling file
- * `file` names, validated as a path segment before it is read (ADR-0005) — the same convention a
- * gRPC message or a REST raw body follows.
- */
-const wsSavedMessageSchema = z.looseObject({
-    id: nonEmpty,
-    name: z.string(),
-    format: z.enum(['text', 'binary']).default('text'),
-    file: nonEmpty,
+/** `webhooks/requests/[<folder>/…]folder.yaml`: a REST folder plus a target override and its source API. */
+export const webhookFolderFileSchema = restFolderFileSchema.extend({
+    target: z.string().optional(),
+    source: z.looseObject({ apiId: nonEmpty }).optional(),
+    signing: webhookSigningSchema.optional(),
 });
-/**
- * `apis/<slug>/requests/[<folder>/…]<name>.request.yaml` for a WebSocket request. Each saved
- * message's own text lives in its own sibling file, so a JSON message is a JSON file in git.
- */
-export const wsRequestFileSchema = z.looseObject({
-    kind: z.literal('websocket'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    url: z.string(),
-    query: z.array(keyValueEntrySchema).default([]),
-    headers: z.array(keyValueEntrySchema).default([]),
-    subprotocols: z.array(z.string()).default([]),
-    auth: authConfigSchema.default({ type: 'inherit' }),
-    settings: wsSettingsSchema.default({}),
-    messages: z.array(wsSavedMessageSchema).default([]),
-});
-/** `apis/<slug>/api.yaml` for a WebSocket API. */
-export const wsApiFileSchema = z.looseObject({
-    kind: z.literal('websocket'),
-    id: nonEmpty,
-    name: z.string(),
-    order: z.number().int(),
-    description: z.string().optional(),
-    url: z.string(),
-    headers: z.array(keyValueEntrySchema).default([]),
-    auth: authConfigSchema.optional(),
-    definition: z
-        .looseObject({ kind: z.literal('asyncapi'), source: nonEmpty, cache: z.boolean().default(true) })
-        .optional(),
-});
-/** Every protocol this build can load. A `kind` outside this list is refused by name, never guessed at. */
-const SUPPORTED_KINDS = ['soap', 'rest', 'grpc', 'websocket'];
-/**
- * Refuses a document whose `kind` this build does not know how to honour — a protocol a later
- * release adds, or a typo — before schema validation, so the error says what is actually wrong
- * ("this build cannot open a graphql document") instead of "expected 'rest', received 'graphql'",
- * and so a project written by a future build fails loudly rather than losing its requests to a
- * dropped unknown key. `grpc` was the reserved name this guard existed for until the gRPC client
- * arrived; it stays for whatever comes next.
- *
- * @throws ProjectError `project-kind-not-supported`
- */
-export function assertSupportedKind(document, file) {
-    if (typeof document !== 'object' || document === null || Array.isArray(document)) {
-        return;
-    }
-    const kind = document['kind'];
-    if (typeof kind !== 'string' || SUPPORTED_KINDS.includes(kind)) {
-        return;
-    }
-    throw new ProjectError('project-kind-not-supported', `${file} is a "${kind}" document, which this build cannot open`, {
-        details: { file, kind, supported: SUPPORTED_KINDS },
-    });
-}
-/** The `kind` of an `api.yaml`, read ahead of full validation so the loader knows which schema applies. */
-export function apiKindOf(document) {
-    const kind = typeof document === 'object' && document !== null ? document['kind'] : undefined;
-    if (kind === 'grpc' || kind === 'websocket') {
-        return kind;
-    }
-    return 'rest';
-}
 /** `environments/<slug>.yaml`. */
 export const environmentFileSchema = z.looseObject({
     id: nonEmpty,
@@ -717,21 +286,3 @@ export const descriptorDefinitionCacheManifestSchema = z.looseObject({
     /** The descriptor set itself: its path under `definition/`, its SHA-256 and its size. */
     file: protoDefinitionCacheFileSchema,
 });
-/**
- * Validates `value` against `schema`, raising
- * `ProjectError('project-file-invalid')` carrying the file path and the
- * individual zod issues when it does not match.
- */
-export function parseFile(schema, value, file) {
-    const result = schema.safeParse(value);
-    if (result.success) {
-        return result.data;
-    }
-    const issues = result.error.issues.map((issue) => ({
-        path: issue.path.join('.'),
-        message: issue.message,
-    }));
-    throw new ProjectError('project-file-invalid', `Invalid project file ${file}`, {
-        details: { file, issues },
-    });
-}

package/dist/project/sequence-guards.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The checks ADR-0015 puts on `${#Sequence#…}` values wherever a request is expanded: text a server
+ * chose may be escaped into a body, but it may never pick where the request goes, and it may never
+ * carry a line break or NUL into a URL, a header or metadata. Each per-protocol expander calls these
+ * only when the scopes hold Sequence values, so a send outside a sequence pays nothing.
+ */
+import type { ExpandResult, PropertyScopes } from './properties.js';
+/** True when `scopes` carry at least one Sequence value, which is when the guards apply. */
+export declare function hasSequenceValues(scopes: PropertyScopes): boolean;
+/** Full XML escaping, quotes included, so a value is safe in element text and in an attribute alike. */
+export declare function escapeXmlValue(value: string): string;
+/**
+ * Expands with every Sequence value escaped by `escape` exactly once, wherever it lands and however it
+ * is reached, directly or through a chained property.
+ *
+ * Escaping the Sequence map up front is not enough: a request that escapes its own values would escape
+ * a Sequence value a second time. So each value is first replaced by a placeholder no user text can
+ * contain (a fresh random nonce per call) and made only of letters and digits, which no escaping
+ * touches. `expandText` runs with the request's own escaping, and then each placeholder is swapped
+ * for its escaped value.
+ */
+export declare function expandWithSequenceEscaped(expandText: (scopes: PropertyScopes) => string, scopes: PropertyScopes, escape: (value: string) => string): string;
+/** The origin of an absolute URL (`scheme://host:port`), or `undefined` when `text` is not one. */
+export declare function urlOrigin(text: string): string | undefined;
+/**
+ * Refuses a send whose destination depends on a Sequence value: `resolve` is expanded once with the
+ * real values and once with every Sequence value replaced by a fixed marker, and the two results must
+ * have the same origin under `originOf`. A value in the path, query or fragment changes neither;
+ * one in the scheme, host or port changes it.
+ *
+ * @param place what is being sent to, for the message ("The request URL")
+ * @param resolve builds the destination text from a set of scopes
+ * @param originOf reduces that text to what must not change
+ * @throws SequenceError `sequence-origin-from-response`
+ */
+export declare function assertOriginIndependent(place: string, resolve: (scopes: PropertyScopes) => string, scopes: PropertyScopes, originOf?: (text: string) => string | undefined): void;
+/**
+ * Refuses a Sequence value holding CR, LF or NUL wherever `result` put one: a URL, a header name or
+ * value, gRPC metadata, a SOAP action. A body may carry them; a line-oriented place may not.
+ *
+ * @throws SequenceError `sequence-value-invalid`
+ */
+export declare function assertNoControlCharacters(place: string, result: ExpandResult, scopes: PropertyScopes): void;

package/dist/project/sequence-guards.js

@@ -0,0 +1,109 @@
+/**
+ * The checks ADR-0015 puts on `${#Sequence#…}` values wherever a request is expanded: text a server
+ * chose may be escaped into a body, but it may never pick where the request goes, and it may never
+ * carry a line break or NUL into a URL, a header or metadata. Each per-protocol expander calls these
+ * only when the scopes hold Sequence values, so a send outside a sequence pays nothing.
+ */
+import { randomUUID } from 'node:crypto';
+import { SequenceError } from '../errors.js';
+/** What every Sequence value becomes in the comparison expansion: plain, host-safe, unlikely to be real. */
+const MARKER = 'wbseq';
+/** CR, LF and NUL: what splits a header or a request line. */
+const CONTROL_CHARACTERS = /[\r\n\0]/;
+/** True when `scopes` carry at least one Sequence value, which is when the guards apply. */
+export function hasSequenceValues(scopes) {
+    return scopes.sequence !== undefined && Object.keys(scopes.sequence).length > 0;
+}
+function mapValues(map, transform) {
+    const out = {};
+    for (const [name, value] of Object.entries(map)) {
+        out[name] = transform(value);
+    }
+    return out;
+}
+/** Full XML escaping, quotes included, so a value is safe in element text and in an attribute alike. */
+export function escapeXmlValue(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Expands with every Sequence value escaped by `escape` exactly once, wherever it lands and however it
+ * is reached, directly or through a chained property.
+ *
+ * Escaping the Sequence map up front is not enough: a request that escapes its own values would escape
+ * a Sequence value a second time. So each value is first replaced by a placeholder no user text can
+ * contain (a fresh random nonce per call) and made only of letters and digits, which no escaping
+ * touches. `expandText` runs with the request's own escaping, and then each placeholder is swapped
+ * for its escaped value.
+ */
+export function expandWithSequenceEscaped(expandText, scopes, escape) {
+    if (!hasSequenceValues(scopes) || scopes.sequence === undefined) {
+        return expandText(scopes);
+    }
+    const prefix = `wbseq${randomUUID().replace(/-/g, '')}x`;
+    const escaped = new Map();
+    const placeholders = {};
+    let index = 0;
+    for (const [name, value] of Object.entries(scopes.sequence)) {
+        // The trailing `z` ends the index, so placeholder 1 followed by a digit is never read as 15.
+        const placeholder = `${prefix}${index++}z`;
+        placeholders[name] = placeholder;
+        escaped.set(placeholder, escape(value));
+    }
+    const text = expandText({ ...scopes, sequence: placeholders });
+    return text.replace(new RegExp(`${prefix}\\d+z`, 'g'), (placeholder) => escaped.get(placeholder) ?? placeholder);
+}
+/** The origin of an absolute URL (`scheme://host:port`), or `undefined` when `text` is not one. */
+export function urlOrigin(text) {
+    try {
+        const url = new URL(text);
+        // A non-special scheme (`grpc:`, `ws+unix:`) has an opaque `origin` of "null"; host and port
+        // still say where the request goes.
+        return url.origin !== 'null' ? url.origin : `${url.protocol}//${url.host}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Refuses a send whose destination depends on a Sequence value: `resolve` is expanded once with the
+ * real values and once with every Sequence value replaced by a fixed marker, and the two results must
+ * have the same origin under `originOf`. A value in the path, query or fragment changes neither;
+ * one in the scheme, host or port changes it.
+ *
+ * @param place what is being sent to, for the message ("The request URL")
+ * @param resolve builds the destination text from a set of scopes
+ * @param originOf reduces that text to what must not change
+ * @throws SequenceError `sequence-origin-from-response`
+ */
+export function assertOriginIndependent(place, resolve, scopes, originOf = urlOrigin) {
+    if (!hasSequenceValues(scopes) || scopes.sequence === undefined) {
+        return;
+    }
+    const marked = { ...scopes, sequence: mapValues(scopes.sequence, () => MARKER) };
+    if (originOf(resolve(scopes)) !== originOf(resolve(marked))) {
+        throw new SequenceError('sequence-origin-from-response', `${place} would take its scheme, host or port from a value a response supplied; ` +
+            'use ${#Sequence#…} only in the path, query or fragment', { details: { place } });
+    }
+}
+/**
+ * Refuses a Sequence value holding CR, LF or NUL wherever `result` put one: a URL, a header name or
+ * value, gRPC metadata, a SOAP action. A body may carry them; a line-oriented place may not.
+ *
+ * @throws SequenceError `sequence-value-invalid`
+ */
+export function assertNoControlCharacters(place, result, scopes) {
+    if (scopes.sequence === undefined) {
+        return;
+    }
+    for (const { scope, name } of result.used) {
+        const value = scope === 'Sequence' && Object.hasOwn(scopes.sequence, name) ? scopes.sequence[name] : undefined;
+        if (value !== undefined && CONTROL_CHARACTERS.test(value)) {
+            throw new SequenceError('sequence-value-invalid', `${place} would carry a line break or NUL from \${#Sequence#${name}}`, { details: { place, name } });
+        }
+    }
+}