@wirebench/engine 2.2.1 → 3.1.0

package/dist/{types.d.ts → soap/types.d.ts}

@@ -3,24 +3,25 @@
  * and sending a SOAP request. These are the shapes the desktop app (Task 13)
  * consumes directly.
  */
-import type { FetchDocument } from './wsdl/resolver.js';
-import type { QName } from './wsdl/qname.js';
-import type { DefinitionBundle } from './wsdl/resolver.js';
-import type { MimePartInfo, WsdlDefinition } from './wsdl/model.js';
-import type { SchemaSet } from './xsd/schema-set.js';
-import type { HttpExchange, ProxyOptions, TlsOptions } from './http/types.js';
-import type { SoapEnvelopeVersion } from './soap/envelope.js';
-import type { SoapFault } from './soap/fault.js';
-import type { UnresolvedRef } from './project/properties.js';
-import type { Attachment } from './project/model.js';
-import type { AttachmentResolver, ResponseAttachment } from './soap/mime/types.js';
-import type { WssContext, WssIncomingConfig, WssOutgoingConfig } from './wss/model.js';
-import type { WssResult } from './wss/incoming/index.js';
-import type { WssRequestProperties } from './wss/apply.js';
-import type { WsaConfig } from './wsa/model.js';
-import type { WsaSummary } from './wsa/policy-detect.js';
+import type { FetchDocument } from '../wsdl/resolver.js';
+import type { QName } from '../wsdl/qname.js';
+import type { DefinitionBundle } from '../wsdl/resolver.js';
+import type { MimePartInfo, WsdlDefinition } from '../wsdl/model.js';
+import type { SchemaSet } from '../xsd/schema-set.js';
+import type { AuthSummary, SendAuth } from '../http/auth/send-auth.js';
+import type { HttpExchange, ProxyOptions, TlsOptions } from '../http/types.js';
+import type { SoapEnvelopeVersion } from './envelope.js';
+import type { SoapFault } from './fault.js';
+import type { UnresolvedRef } from '../project/properties.js';
+import type { Attachment } from '../project/model.js';
+import type { AttachmentResolver, ResponseAttachment } from './mime/types.js';
+import type { WssContext, WssIncomingConfig, WssOutgoingConfig } from '../wss/model.js';
+import type { WssResult } from '../wss/incoming/index.js';
+import type { WssRequestProperties } from '../wss/apply.js';
+import type { WsaConfig } from '../wsa/model.js';
+import type { WsaSummary } from '../wsa/policy-detect.js';
 /** Where a WSDL definition comes from. */
-export type ImportSource = {
+export type WsdlImportSource = {
     readonly kind: 'url';
     readonly url: string;
 } | {
@@ -32,8 +33,8 @@ export type ImportSource = {
     /** Base location for resolving relative imports; defaults to `inline:wsdl`. */
     readonly location?: string;
 };
-/** One phase of an in-progress {@link ImportSource} import. */
-export type ImportProgress = {
+/** One phase of an in-progress {@link WsdlImportSource} import. */
+export type WsdlImportProgress = {
     readonly phase: 'fetch';
     readonly location: string;
 } | {
@@ -44,19 +45,19 @@ export type ImportProgress = {
     readonly phase: 'done';
 };
 /**
- * Definition-cache behaviour for `importDefinition`: `'prefer-cache'` resolves
+ * Definition-cache behaviour for `importWsdl`: `'prefer-cache'` resolves
  * entirely from a valid cache with no network access (falling back to the
  * network, with a problem reported, if the cache is missing or corrupt);
  * `'refresh'` always resolves from the network and then (re)writes the
  * cache; `'none'` ignores the cache entirely.
  */
-export interface ImportCacheOptions {
+export interface WsdlImportCacheOptions {
     /** Absolute path of the interface's `definition/` directory (see `definitionCacheDir`). */
     readonly dir: string;
     readonly mode: 'prefer-cache' | 'refresh' | 'none';
 }
-/** Options accepted by `importDefinition`. */
-export interface ImportOptions {
+/** Options accepted by `importWsdl`. */
+export interface WsdlImportOptions {
     /** Overrides the default `file://`/`http(s)://` fetcher, e.g. for tests. */
     readonly fetchDocument?: FetchDocument;
     /** Basic auth credentials added to every `http(s)://` fetch made while importing. */
@@ -65,12 +66,12 @@ export interface ImportOptions {
         readonly password: string;
     };
     readonly signal?: AbortSignal;
-    readonly onProgress?: (event: ImportProgress) => void;
-    /** Definition-cache behaviour; see {@link ImportCacheOptions}. Omitted/absent means no caching. */
-    readonly cache?: ImportCacheOptions;
+    readonly onProgress?: (event: WsdlImportProgress) => void;
+    /** Definition-cache behaviour; see {@link WsdlImportCacheOptions}. Omitted/absent means no caching. */
+    readonly cache?: WsdlImportCacheOptions;
 }
 /** A non-fatal problem encountered while importing a definition, tagged by the stage that raised it. */
-export interface ImportProblem {
+export interface WsdlImportProblem {
     readonly source: 'resolve' | 'wsdl' | 'schema';
     readonly code: string;
     readonly message: string;
@@ -79,7 +80,7 @@ export interface ImportProblem {
     readonly column?: number;
 }
 /** One binding operation's port bindings, as summarized for a picker UI. */
-export interface OperationSummary {
+export interface SoapOperationSummary {
     readonly bindingName: QName;
     readonly operationName: string;
     readonly soapVersion: '1.1' | '1.2' | 'none';
@@ -98,68 +99,17 @@ export interface OperationSummary {
     readonly inputMimeParts: readonly MimePartInfo[];
 }
 /** The full result of importing a WSDL definition: parsed model, schema set, problems and an operation picker list. */
-export interface ImportResult {
+export interface WsdlImportResult {
     readonly definition: WsdlDefinition;
     readonly bundle: DefinitionBundle;
     readonly schemaSet: SchemaSet;
-    readonly problems: readonly ImportProblem[];
-    readonly operations: readonly OperationSummary[];
+    readonly problems: readonly WsdlImportProblem[];
+    readonly operations: readonly SoapOperationSummary[];
     /** What the definition itself says about WS-Addressing; see `summarizeWsa`. */
     readonly wsa: WsaSummary;
     /** True when this result was resolved entirely from the definition cache, with no network access. */
     readonly fromCache?: boolean;
 }
-/**
- * Credentials for one send, already resolved to plaintext: the desktop app looks a
- * `passwordRef` up in its secret store before calling the engine, so the engine never
- * sees a secret reference (and never persists or logs the password).
- */
-export type SendAuth = {
-    readonly type: 'basic';
-    readonly username: string;
-    readonly password: string;
-    /** Send the `Authorization` header on the first attempt instead of waiting for a 401. */
-    readonly preemptive: boolean;
-} | {
-    readonly type: 'ntlm';
-    readonly username: string;
-    readonly password: string;
-    readonly domain?: string;
-    readonly workstation?: string;
-}
-/** A token in an `Authorization` header. `scheme` defaults to `Bearer`. */
- | {
-    readonly type: 'bearer';
-    readonly token: string;
-    readonly scheme?: string;
-}
-/** A key in one header or one query parameter. */
- | {
-    readonly type: 'api-key';
-    readonly name: string;
-    readonly value: string;
-    readonly in: 'header' | 'query';
-}
-/**
- * An OAuth2 access token the host already obtained. The engine never runs a grant during a send:
- * the token is fetched (and cached, and refreshed) by the host, so a send is one exchange and
- * the browser is never opened behind it. On the wire it is a Bearer token.
- */
- | {
-    readonly type: 'oauth2';
-    readonly accessToken: string;
-};
-/** What authentication actually did during one send, for the UI to explain the exchange. */
-export interface AuthSummary {
-    readonly scheme: SendAuth['type'];
-    /** True when the server answered the first attempt with a 401 challenge. */
-    readonly challenged: boolean;
-    /**
-     * How many HTTP attempts the send made: 1 preemptive/unchallenged, 2 after a Basic
-     * challenge, 3 for a full NTLM handshake (bare, Type 1, Type 3).
-     */
-    readonly attempts: 1 | 2 | 3;
-}
 /** Input to `sendSoapRequest`: an already-built envelope plus transport knobs. */
 export interface SoapSendInput {
     readonly endpoint: string;
@@ -195,7 +145,7 @@ export interface SoapSendInput {
     /** Attachments to send; only acted on when {@link attachmentOptions} says how. */
     readonly attachments?: readonly Attachment[];
     /** MTOM/SwA/inline-file behaviour plus the resolvers that turn references into bytes. */
-    readonly attachmentOptions?: SendAttachmentOptions;
+    readonly attachmentOptions?: SoapAttachmentOptions;
     /**
      * WS-Security applied to the envelope after property expansion and inline-file substitution
      * and before attachment packaging, so the header is part of the envelope that actually goes
@@ -236,7 +186,7 @@ export interface SoapSendWss {
  * referenced part's base64, the second keeps those parts listed as attachments even
  * once they have been expanded into the envelope.
  */
-export interface SendAttachmentOptions {
+export interface SoapAttachmentOptions {
     /** Rewrite `cid:` references as `xop:Include` and send an MTOM package. */
     readonly enableMtom: boolean;
     /** Send an MTOM package even when nothing was optimised. */

package/dist/sync/git-cli.d.ts

@@ -0,0 +1,202 @@
+/**
+ * A small, Electron-free wrapper around the system `git` executable: discovery ({@link findGit}),
+ * a hardened {@link GitCli.run}, error mapping and remote URL validation ({@link assertRemoteUrl}).
+ *
+ * This file must never import `electron` — `SyncService` and Wirebench Server's commit store run it
+ * in plain Node, and `ipc/git.ts` is the only place that bridges it to Electron.
+ *
+ * Git is never bundled: it is found on the machine it runs on, or the user is asked to locate
+ * it (`git.locate`). Every invocation goes through {@link GitCli.run}, which never opens a
+ * shell, never prompts, never runs a hook, and refuses any subcommand outside
+ * {@link GIT_SUBCOMMANDS} before a process is even spawned. A `GitCli` the server builds with
+ * `{ plumbing: true }` also accepts {@link GIT_PLUMBING_SUBCOMMANDS}; the desktop never does.
+ */
+/**
+ * The only git subcommands `GitCli.run` will spawn. A `-`-prefixed first argument, or any
+ * subcommand not on this list, is refused before a process is spawned — see `run`.
+ */
+export declare const GIT_SUBCOMMANDS: readonly ["--version", "init", "clone", "add", "commit", "fetch", "merge", "push", "status", "diff", "show", "rev-list", "rev-parse", "log", "checkout", "remote", "config", "symbolic-ref", "var", "rm"];
+/** One of the subcommands {@link GIT_SUBCOMMANDS} allows. */
+export type GitSubcommand = (typeof GIT_SUBCOMMANDS)[number];
+/**
+ * Git plumbing, for Wirebench Server's commit store only (server-sync spec §3.3, R1): it builds
+ * commits in a bare repository, with no working tree. This is a second list rather than a longer
+ * {@link GIT_SUBCOMMANDS}, so the desktop's allow-list does not grow. Only a `GitCli` constructed
+ * with `{ plumbing: true }`, or returned by {@link GitCli.withPlumbing}, accepts these.
+ */
+export declare const GIT_PLUMBING_SUBCOMMANDS: readonly ["ls-tree", "cat-file", "merge-base", "diff-tree", "read-tree", "hash-object", "update-index", "write-tree", "commit-tree", "update-ref"];
+/** One of the subcommands {@link GIT_PLUMBING_SUBCOMMANDS} allows. */
+export type GitPlumbingSubcommand = (typeof GIT_PLUMBING_SUBCOMMANDS)[number];
+/**
+ * The only variables a caller may set per call ({@link GitRunOptions.env}): the commit store's
+ * private index file, and the author and committer of the commit it writes. Anything else
+ * (`GIT_DIR`, `GIT_CONFIG_*`, `GIT_SSH_COMMAND`, `GIT_EXEC_PATH`, `PATH`) could point git somewhere
+ * else or make it run a program, so it is refused.
+ */
+export declare const GIT_CALL_ENV: readonly ["GIT_INDEX_FILE", "GIT_AUTHOR_NAME", "GIT_AUTHOR_EMAIL", "GIT_AUTHOR_DATE", "GIT_COMMITTER_NAME", "GIT_COMMITTER_EMAIL", "GIT_COMMITTER_DATE"];
+/** One of the variables {@link GIT_CALL_ENV} allows. */
+export type GitCallEnv = (typeof GIT_CALL_ENV)[number];
+/** Per-call options of {@link GitCli.run}. */
+export interface GitRunOptions {
+    /** Kills git after this long; 60 s when absent. */
+    readonly timeoutMs?: number;
+    /** Written to the child's stdin, then stdin is closed. */
+    readonly input?: string | Uint8Array;
+    /** Refused (git-failed, before spawning) when a key is not in GIT_CALL_ENV. */
+    readonly env?: Partial<Record<GitCallEnv, string>>;
+    /** Buffered-output ceiling for this call; defaults to today's 16 MiB. */
+    readonly maxBuffer?: number;
+}
+/**
+ * How a git process is actually spawned. It resolves, never rejects, on a non-zero exit. It rejects
+ * only when git was never run or was killed:
+ * - The executable could not be spawned (`ENOENT`/`EACCES`). {@link findGit} treats that as "this
+ *   candidate is not usable", and {@link GitCli.run} maps it to `git-not-found`.
+ * - The timeout killed git.
+ * - git's output passed `maxBuffer` (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`).
+ *
+ * When `input` is present, it is written to stdin and stdin is closed. `encoding: 'buffer'` asks
+ * for stdout as raw bytes, because a blob need not be UTF-8. stderr is always text, because the
+ * error mapping reads it. A fake runner may answer stdout in either shape; `GitCli.run` converts it.
+ */
+export type Runner = (file: string, args: readonly string[], options: {
+    cwd?: string;
+    env: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    input?: string | Uint8Array;
+    encoding: 'utf8' | 'buffer';
+    maxBuffer: number;
+}) => Promise<{
+    stdout: string | Buffer;
+    stderr: string;
+    exitCode: number;
+}>;
+/** A located, usable git executable. */
+export interface GitLocation {
+    readonly path: string;
+    readonly version: string;
+}
+/** Parses `git version 2.39.2 (Apple Git-143)` (or `... 2.42.0.windows.1`) → the version string. */
+export declare function parseGitVersion(stdout: string): string | undefined;
+/**
+ * Finds a usable system git: the configured path first, then every `PATH` entry, then a
+ * platform default. The first candidate whose `--version` probe exits 0 with a parsable,
+ * sufficiently recent version wins; every other outcome (spawn failure, non-zero exit, unparsable
+ * output, too old) just skips to the next candidate.
+ */
+export declare function findGit(options: {
+    configuredPath?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    exists?: (path: string) => boolean;
+    run?: Runner;
+}): Promise<GitLocation | undefined>;
+/**
+ * Refuses anything that is not a literal `https://`, `ssh://` or `file://` URL (scheme
+ * case-insensitive) or a `user@host:path` remote, trims and returns the accepted value
+ * otherwise. In particular refuses: an empty string; whitespace or control characters anywhere
+ * in the trimmed value; a value starting with `-` (which `git` — or a shell a transport helper
+ * invokes — would parse as a flag); `ext::…` (git's "run an arbitrary command" transport); a
+ * scheme-only form with no `//` (`https:x`, `file:/etc/r`, `ssh:-oProxyCommand=…`); and —
+ * crucially — a *user or host* starting with `-` once fully parsed out of the authority
+ * (`user@host[:port]`, `[bracketed-IPv6-host]`, `%`-decoded) and off the scp-like form's
+ * `user@host:`, closing bypasses a leading-`-` check on the whole string alone would miss:
+ * `ssh://git@-oProxyCommand=x/y`, `ssh://[-oProxyCommand=x]/y`, `ssh://%2doProxyCommand=x/y`
+ * (git percent-decodes the host), `https://user@-host/y`. A malformed `%` sequence in the user
+ * or host is refused outright rather than passed through undecoded.
+ *
+ * The error `details` carry only the scheme (or `'scp-like'`) — never the URL, which may embed
+ * credentials — and the message stays generic for the same reason.
+ */
+export declare function assertRemoteUrl(url: string): string;
+/**
+ * Refuses a branch name that could be read as a flag by `git` (a leading `-`) or that git itself
+ * would refuse as a ref name, and returns it otherwise. In particular refuses: empty; a leading
+ * `-`; whitespace or control characters; `~^:?*[` or a backslash anywhere; `..` or `@{` anywhere
+ * (git's own ref-name restrictions); a leading, trailing, or doubled `/`; a trailing `.lock` or
+ * `.`; any `/`-separated component starting with `.`; and the bare name `@`.
+ *
+ * Every `GitBackend` method that builds a git argument or ref expression from a (renderer-
+ * settable) branch name calls this first — see git-backend.ts.
+ */
+export declare function assertBranchName(name: string): string;
+/**
+ * Runs the system git found by {@link findGit}, with every hardening constraint the plan
+ * requires: no shell, no prompt, no hooks, a fixed subcommand allow-list, and error `details`
+ * that never carry the environment or a credential-bearing URL.
+ */
+export declare class GitCli {
+    readonly version: string;
+    private readonly path;
+    private readonly hooksDir;
+    private readonly runner;
+    private readonly extraEnv;
+    /** Whether {@link GIT_PLUMBING_SUBCOMMANDS} are allowed as well: only for the server's commit store. */
+    private readonly plumbing;
+    /**
+     * Memoised `git config --get core.sshCommand` lookups, one per distinct `cwd` a caller has
+     * `run()` with (the `cwd`-less key included) — a repository-local `core.sshCommand` only
+     * applies inside that repository, and a cwd-less run must never pick up a *different*
+     * repository's local config. `undefined` (the resolved value) covers "unset" too.
+     */
+    private readonly sshCommandConfigByCwd;
+    constructor(location: GitLocation, options: {
+        hooksDir: string;
+        run?: Runner;
+        env?: NodeJS.ProcessEnv;
+        plumbing?: boolean;
+    });
+    /**
+     * A copy with the same location, hooks dir, runner and env that also accepts
+     * {@link GIT_PLUMBING_SUBCOMMANDS}. The server's commit store calls this on `ctx.git`. The desktop
+     * never does, because it never runs git for a server share (server-sync spec §3.3, §6). The copy
+     * shares nothing mutable with the original, only the `core.sshCommand` lookups it repeats.
+     */
+    withPlumbing(): GitCli;
+    /** Whether `subcommand` is on this instance's allow-list(s). */
+    private allows;
+    /**
+     * Reads `core.sshCommand` for `cwd` once (cached per `cwd`, including a cached "unset"), via
+     * the same runner every other invocation uses. Exit code 1 (and any other failure) means
+     * unset.
+     */
+    private queryCoreSshCommand;
+    /**
+     * Runs `git <args>` in `cwd` behind the fixed `-c` prefix (with `core.hooksPath` pointing at an empty
+     * directory, so no hook ever runs) and the hardened environment.
+     *
+     * `options.stdout: 'buffer'` returns stdout as raw bytes. Otherwise it is decoded as UTF-8.
+     *
+     * @throws WirebenchError
+     * - `git-failed`, which covers:
+     *   - an off-list subcommand, or an `env` key outside {@link GIT_CALL_ENV}, both refused before
+     *     anything spawns;
+     *   - a non-zero exit;
+     *   - a timeout (`details.timedOut`);
+     *   - output over `maxBuffer` (`details.outputTooLarge`).
+     * - `git-auth-failed` and `git-offline`, read from stderr.
+     * - `git-not-found`.
+     */
+    run(cwd: string | undefined, args: readonly string[], options: GitRunOptions & {
+        readonly stdout: 'buffer';
+    }): Promise<{
+        stdout: Buffer;
+        stderr: string;
+    }>;
+    run(cwd: string | undefined, args: readonly string[], options?: GitRunOptions & {
+        readonly stdout?: 'utf8';
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** The keys of `names` (git config key names) off the local-config allow-list, compared case-insensitively. */
+export declare function refusedLocalConfigKeys(names: readonly string[]): string[];
+/**
+ * Refuses a repository whose `.git/config` sets any key off the allow-list (see
+ * {@link refusedLocalConfigKeys}), or a `remote.*.url` value {@link assertRemoteUrl} refuses, with
+ * `git-config-refused` and `details.keys` naming the keys (never a URL). A folder that is not a
+ * repository is `git-not-a-repository`. Run before any other git command in a repository the app
+ * did not `clone` or `init` itself.
+ */
+export declare function assertSafeLocalConfig(git: GitCli, cwd: string): Promise<void>;