@andrewheberle/serverless-ssh-ca-testing 0.0.0-stage → 0.20.1

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# @andrewheberle/serverless-ssh-ca-testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs the [Serverless SSH CA](../core/README.md) for end-to-end tests of
+clients, such as [ssh-ca-client](https://github.com/andrewheberle/ssh-ca-client).
+
+The CA can be run under:
+
+- `node`: Node.js, using the package's Node.js helpers with an in-memory
+  `node:sqlite` database
+- `workerd`: the Cloudflare Workers runtime, using the Wrangler test harness
+  with a local D1 database and Secrets Store, as `wrangler dev` would
+
+Nothing is persisted between runs.
+
+This package is released with `@andrewheberle/serverless-ssh-ca` and uses
+whichever version of that package is installed alongside it. To test a client
+against an unreleased version of the CA, install a tarball from `npm pack` in
+its place.
+
+## Requirements
+
+Node.js 24 or later.
+
+## Usage
+
+```sh
+npm install --save-dev @andrewheberle/serverless-ssh-ca @andrewheberle/serverless-ssh-ca-testing
+npx serverless-ssh-ca-test-server [--runtime node|workerd] config.json
+```
+
+The runtime defaults to `node`. Clients that start the server from another
+language can run `node node_modules/@andrewheberle/serverless-ssh-ca-testing/dist/cli.js`,
+which avoids the platform-specific shims in `node_modules/.bin`.
+
+The server exits when its standard input is closed, so it does not outlive
+the test that started it. If it cannot start, it writes the reason to
+standard error and exits with status 1.
+
+## Configuration
+
+The configuration file is a JSON object:
+
+| Property      | Description                                                              |
+|---------------|--------------------------------------------------------------------------|
+| `private_key` | The CA private key in OpenSSH format                                     |
+| `bindings`    | The CA configuration, as the Workers vars (environment variables)        |
+| `port_file`   | Path the port is written to once the CA is listening on `127.0.0.1`      |
+| `log_file`    | Path that log output from the CA and harness is appended to as JSON lines |
+
+The bindings are those documented for the CA, with every value as a string.
+Under `workerd`, Wrangler's working files are written to the directory
+containing the configuration file.
+
+## Log file
+
+Each line of the log file is a JSON object with at least `level` and
+`message`. Lines logged by the CA are written as they are, and the harness adds
+lines whose `message` starts with `harness`:
+
+- `{"level":"info","message":"harness request","method":...,"url":...,"status":...}`
+  for every request, where `url` is the path and query. When `status` is 400
+  or more, `body` holds the response body, so a test can check why a request
+  was rejected.
+- `{"level":"error","message":"harness ...",...}` for a fault, meaning the CA
+  or harness failed rather than rejected a request. Some faults, such as a
+  failure to record an issued certificate, are only visible in the log, so
+  tests should fail if any of these lines appear. A CA log line that
+  indicates a fault is followed by a line with the message `harness fault`
+  and the original line in `line`.
+
+Under `workerd`, the CA's output is copied to the log file every 100ms, so a
+request may be logged shortly after its response is received.
+
+## Programmatic use
+
+```ts
+import { startTestServer } from "@andrewheberle/serverless-ssh-ca-testing"
+
+const server = await startTestServer("node", "config.json")
+// make requests to http://127.0.0.1:${server.port}
+await server.close()
+```
+
+Under `node` the CA's `console` output is redirected to the log file until the
+server is closed.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// Runs the Serverless SSH CA for end-to-end tests of clients.
+//
+// Usage: serverless-ssh-ca-test-server [--runtime node|workerd] <config.json>
+//
+// The process exits when its stdin is closed, so it does not outlive the test
+// that started it.
+import { parseArgs } from "node:util";
+import z from "zod";
+import { readConfig, RuntimeSchema } from "./config.js";
+import { startTestServer } from "./index.js";
+import { LogFile } from "./log.js";
+const usage = "usage: serverless-ssh-ca-test-server [--runtime node|workerd] <config.json>";
+const main = async () => {
+    const { values, positionals } = parseArgs({
+        options: {
+            runtime: { type: "string", default: "node" },
+        },
+        allowPositionals: true,
+    });
+    const runtime = RuntimeSchema.safeParse(values.runtime);
+    if (!runtime.success) {
+        throw new Error(`--runtime ${z.prettifyError(runtime.error)}\n${usage}`);
+    }
+    const [configFile, ...extra] = positionals;
+    if (configFile === undefined || extra.length > 0) {
+        throw new Error(usage);
+    }
+    // faults after start up are written to the log file, where the test
+    // reading it will find them
+    const config = await readConfig(configFile);
+    const log = new LogFile(config.log_file);
+    process.on("uncaughtException", (err) => {
+        log.fault("uncaught exception", err);
+        process.exit(1);
+    });
+    const server = await startTestServer(runtime.data, configFile);
+    process.stdin.on("end", () => {
+        server.close().then(() => process.exit(0), (err) => {
+            log.fault("close failed", err);
+            process.exit(1);
+        });
+    });
+    process.stdin.resume();
+};
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,8DAA8D;AAC9D,EAAE;AACF,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,mBAAmB;AACnB,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,CAAC,MAAM,KAAK,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC,MAAM,KAAK,GAAG,6EAA6E,CAAA;AAE3F,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;IACtC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;QACzC,OAAO,EAAE;YACR,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;SAC5C;QACD,gBAAgB,EAAE,IAAI;KACtB,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACvD,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,EAAE,CAAC,CAAA;IACzE,CAAC;IAED,MAAM,CAAC,UAAU,EAAE,GAAG,KAAK,CAAC,GAAG,WAAW,CAAA;IAC1C,IAAI,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,CAAA;IACvB,CAAC;IAED,oEAAoE;IACpE,4BAA4B;IAC5B,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;IAC3C,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IACxC,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACvC,GAAG,CAAC,KAAK,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAA;QACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAChB,CAAC,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAE9D,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,GAAY,EAAE,EAAE;YAC3D,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAA;YAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAChB,CAAC,CAAC,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAA;AACvB,CAAC,CAAA;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC7B,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAChB,CAAC,CAAC,CAAA"}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import z from "zod";
+/**
+ * The runtimes the CA can be run under by {@link startTestServer}: `node` uses
+ * the package's Node.js helpers with an in-memory `node:sqlite` database, and
+ * `workerd` uses the Cloudflare Workers runtime with a local D1 database and
+ * Secrets Store.
+ */
+export declare const RuntimeSchema: z.ZodEnum<{
+    node: "node";
+    workerd: "workerd";
+}>;
+/**
+ * A runtime the CA can be run under, see {@link RuntimeSchema}.
+ */
+export type Runtime = z.infer<typeof RuntimeSchema>;
+/**
+ * The configuration file read by {@link readConfig}.
+ */
+export declare const ConfigSchema: z.ZodObject<{
+    private_key: z.ZodString;
+    bindings: z.ZodRecord<z.ZodString, z.ZodString>;
+    port_file: z.ZodString;
+    log_file: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The configuration of a test server, see {@link ConfigSchema}.
+ */
+export type TestServerConfig = z.infer<typeof ConfigSchema>;
+/**
+ * Read and validate a test server configuration file.
+ *
+ * @param path The path of a JSON file matching {@link ConfigSchema}
+ * @returns The validated configuration
+ * @throws Error if the file cannot be read, is not JSON or is not a valid configuration
+ */
+export declare const readConfig: (path: string) => Promise<TestServerConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,CAAC,MAAM,KAAK,CAAA;AAEnB;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;EAA8B,CAAA;AAExD;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;iBASvB,CAAA;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,SAAgB,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAgBvE,CAAA"}

package/dist/config.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import z from "zod";
+/**
+ * The runtimes the CA can be run under by {@link startTestServer}: `node` uses
+ * the package's Node.js helpers with an in-memory `node:sqlite` database, and
+ * `workerd` uses the Cloudflare Workers runtime with a local D1 database and
+ * Secrets Store.
+ */
+export const RuntimeSchema = z.enum(["node", "workerd"]);
+/**
+ * The configuration file read by {@link readConfig}.
+ */
+export const ConfigSchema = z.object({
+    /** The CA private key in OpenSSH format */
+    private_key: z.string().min(1),
+    /** The CA configuration, as the Workers vars (environment variables) */
+    bindings: z.record(z.string(), z.string()),
+    /** Path the listening port is written to once the CA is ready */
+    port_file: z.string().min(1),
+    /** Path that log output from the CA and harness is appended to */
+    log_file: z.string().min(1),
+});
+/**
+ * Read and validate a test server configuration file.
+ *
+ * @param path The path of a JSON file matching {@link ConfigSchema}
+ * @returns The validated configuration
+ * @throws Error if the file cannot be read, is not JSON or is not a valid configuration
+ */
+export const readConfig = async (path) => {
+    const text = await readFile(path, { encoding: "utf-8" });
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`parsing ${path}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    const result = ConfigSchema.safeParse(json);
+    if (!result.success) {
+        throw new Error(`invalid configuration in ${path}:\n${z.prettifyError(result.error)}`);
+    }
+    return result.data;
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,CAAC,MAAM,KAAK,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;AAOxD;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,2CAA2C;IAC3C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,iEAAiE;IACjE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAA;AAOF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,IAAY,EAA6B,EAAE;IAC3E,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAA;IAExD,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;IACxG,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,MAAM,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACvF,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAA;AACnB,CAAC,CAAA"}

package/dist/format.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Format a value logged by the CA as text, with objects as JSON so log lines
+ * from the CA's logger are written as JSON lines.
+ *
+ * @param value A value passed to a `console` method
+ * @returns The value as a string
+ */
+export declare const formatValue: (value: unknown) => string;
+/**
+ * Format the arguments to a `console` method as a single line.
+ *
+ * @param args The arguments passed to a `console` method
+ * @returns The arguments formatted with {@link formatValue}, separated by spaces
+ */
+export declare const formatArgs: (args: readonly unknown[]) => string;
+/**
+ * Format a request handled by the CA as a log line, including the response
+ * body when the request was rejected.
+ *
+ * @param method The request method
+ * @param url The path and query of the request
+ * @param status The response status code
+ * @param body The response body
+ * @returns A JSON line with the message "harness request"
+ */
+export declare const formatRequest: (method: string, url: string, status: number, body: string) => string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAW,OAAO,KAAG,MAIA,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,SAAU,SAAS,OAAO,EAAE,KAAG,MAAyC,CAAA;AAE/F;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,WAAY,MAAM,OAAO,MAAM,UAAU,MAAM,QAAQ,MAAM,KAAG,MAC0B,CAAA"}

package/dist/format.js

@@ -0,0 +1,31 @@
+/**
+ * Format a value logged by the CA as text, with objects as JSON so log lines
+ * from the CA's logger are written as JSON lines.
+ *
+ * @param value A value passed to a `console` method
+ * @returns The value as a string
+ */
+export const formatValue = (value) => typeof value === "string"
+    ? value
+    : JSON.stringify(value, (_, x) => x instanceof Error
+        ? { name: x.name, message: x.message, stack: x.stack }
+        : typeof x === "bigint" ? x.toString() : x);
+/**
+ * Format the arguments to a `console` method as a single line.
+ *
+ * @param args The arguments passed to a `console` method
+ * @returns The arguments formatted with {@link formatValue}, separated by spaces
+ */
+export const formatArgs = (args) => args.map(formatValue).join(" ");
+/**
+ * Format a request handled by the CA as a log line, including the response
+ * body when the request was rejected.
+ *
+ * @param method The request method
+ * @param url The path and query of the request
+ * @param status The response status code
+ * @param body The response body
+ * @returns A JSON line with the message "harness request"
+ */
+export const formatRequest = (method, url, status, body) => formatValue({ level: "info", message: "harness request", method, url, status, ...(status >= 400 ? { body } : {}) });
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ;IAC/E,CAAC,CAAC,KAAK;IACP,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAU,EAAE,EAAE,CAAC,CAAC,YAAY,KAAK;QAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE;QACtD,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAwB,EAAU,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAE/F;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAc,EAAE,GAAW,EAAE,MAAc,EAAE,IAAY,EAAU,EAAE,CAClG,WAAW,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { type Runtime } from "./config.js";
+import type { TestServer } from "./server.js";
+export { ConfigSchema, readConfig, RuntimeSchema } from "./config.js";
+export type { Runtime, TestServerConfig } from "./config.js";
+export { FAULT_MESSAGE, FAULT_MESSAGES, isFault, LogFile } from "./log.js";
+export type { TestServer } from "./server.js";
+/**
+ * Start the CA under `runtime` using the configuration in `configFile` (see
+ * {@link ConfigSchema}), then write the port it is listening on to the
+ * configuration's `port_file`.
+ *
+ * Output from the CA and harness is appended to the configuration's
+ * `log_file`, see {@link LogFile}. Under workerd, Wrangler's working files are
+ * written to the directory containing `configFile`.
+ *
+ * @param runtime The runtime to run the CA under, see {@link Runtime}
+ * @param configFile The path of the configuration file
+ * @returns The running server, see {@link TestServer}
+ */
+export declare const startTestServer: (runtime: Runtime, configFile: string) => Promise<TestServer>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,aAAa,CAAA;AAGtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AACrE,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC5D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAC1E,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,YAAmB,OAAO,cAAc,MAAM,KAAG,OAAO,CAAC,UAAU,CA6B9F,CAAA"}

package/dist/index.js

@@ -0,0 +1,68 @@
+/**
+ * Runs the Serverless SSH CA for end-to-end tests of clients, under Node.js or
+ * workerd, configured from a file and reporting what it does through a log
+ * file of JSON lines (see {@link LogFile}).
+ *
+ * Most clients run the `serverless-ssh-ca-test-server` command rather than
+ * using this module directly.
+ *
+ * @example
+ * ```ts
+ * import { startTestServer } from "@andrewheberle/serverless-ssh-ca-testing"
+ *
+ * const server = await startTestServer("node", "config.json")
+ * // make requests to http://127.0.0.1:${server.port}
+ * await server.close()
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { readConfig } from "./config.js";
+import { LogFile } from "./log.js";
+import { startNode } from "./node.js";
+export { ConfigSchema, readConfig, RuntimeSchema } from "./config.js";
+export { FAULT_MESSAGE, FAULT_MESSAGES, isFault, LogFile } from "./log.js";
+/**
+ * Start the CA under `runtime` using the configuration in `configFile` (see
+ * {@link ConfigSchema}), then write the port it is listening on to the
+ * configuration's `port_file`.
+ *
+ * Output from the CA and harness is appended to the configuration's
+ * `log_file`, see {@link LogFile}. Under workerd, Wrangler's working files are
+ * written to the directory containing `configFile`.
+ *
+ * @param runtime The runtime to run the CA under, see {@link Runtime}
+ * @param configFile The path of the configuration file
+ * @returns The running server, see {@link TestServer}
+ */
+export const startTestServer = async (runtime, configFile) => {
+    const config = await readConfig(configFile);
+    const log = new LogFile(config.log_file);
+    let server;
+    switch (runtime) {
+        case "node":
+            server = await startNode(config, log);
+            break;
+        case "workerd": {
+            // loaded on demand as importing Wrangler is slow
+            const { startWorkerd } = await import("./workerd.js");
+            server = await startWorkerd(config, log, dirname(resolve(configFile)));
+            break;
+        }
+        default: {
+            const unknown = runtime;
+            throw new Error(`unknown runtime: ${String(unknown)}`);
+        }
+    }
+    try {
+        await writeFile(config.port_file, String(server.port));
+    }
+    catch (err) {
+        await server.close();
+        throw err;
+    }
+    return server;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAErE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAG1E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAAE,OAAgB,EAAE,UAAkB,EAAuB,EAAE;IAClG,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;IAC3C,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAExC,IAAI,MAAkB,CAAA;IACtB,QAAQ,OAAO,EAAE,CAAC;QACjB,KAAK,MAAM;YACV,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;YACrC,MAAK;QACN,KAAK,SAAS,EAAE,CAAC;YAChB,iDAAiD;YACjD,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAA;YACrD,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;YACtE,MAAK;QACN,CAAC;QACD,SAAS,CAAC;YACT,MAAM,OAAO,GAAU,OAAO,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACvD,CAAC;IACF,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IACvD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;QACpB,MAAM,GAAG,CAAA;IACV,CAAC;IAED,OAAO,MAAM,CAAA;AACd,CAAC,CAAA"}

package/dist/log.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Messages the CA logs at error level when it has failed rather than rejected
+ * a request, see {@link isFault}.
+ */
+export declare const FAULT_MESSAGES: readonly string[];
+/**
+ * The message of the line written by {@link LogFile.write} after a CA log line
+ * that indicates a fault.
+ */
+export declare const FAULT_MESSAGE = "harness fault";
+/**
+ * Report whether a line logged by the CA indicates a fault, such as a database
+ * error, rather than an expected rejection of a request. Some faults are only
+ * logged, as the CA still issues a certificate when it cannot record it.
+ *
+ * @param line A line of output from the CA
+ * @returns true if the line is an error logged by the CA for a fault
+ */
+export declare const isFault: (line: string) => boolean;
+/**
+ * The log file of a test server, written as JSON lines.
+ *
+ * Lines from the CA are written as they are logged. The harness adds the
+ * following lines, whose messages all start with "harness":
+ *
+ * - `{"level":"info","message":"harness request",...}` for each request, with
+ *   `method`, `url`, `status` and, when `status` is 400 or more, the response
+ *   `body`.
+ * - `{"level":"error","message":"harness ...",...}` for a fault in the CA or
+ *   harness. A CA log line that indicates a fault (see {@link isFault}) is
+ *   followed by a line with the message {@link FAULT_MESSAGE}.
+ */
+export declare class LogFile {
+    readonly path: string;
+    constructor(path: string);
+    /**
+     * Append a line of output from the CA, followed by a fault line if it
+     * indicates a fault.
+     */
+    write(line: string): void;
+    /**
+     * Append a request handled by the CA.
+     */
+    request(method: string, url: string, status: number, body: string): void;
+    /**
+     * Append a fault in the harness.
+     *
+     * @param message A description of the fault, which is prefixed with "harness"
+     * @param error The error that caused the fault
+     */
+    fault(message: string, error: unknown): void;
+    private append;
+}
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAwD,CAAA;AAEpG;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAQ5C;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,SAAU,MAAM,KAAG,OActC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,OAAO;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,YAAY,IAAI,EAAE,MAAM,EAEvB;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKxB;IAED;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvE;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAE3C;IAED,OAAO,CAAC,MAAM;CAGd"}

package/dist/log.js

@@ -0,0 +1,88 @@
+import { appendFileSync } from "node:fs";
+import z from "zod";
+import { formatRequest, formatValue } from "./format.js";
+/**
+ * Messages the CA logs at error level when it has failed rather than rejected
+ * a request, see {@link isFault}.
+ */
+export const FAULT_MESSAGES = ["unhandled error", "unexpected error from router"];
+/**
+ * The message of the line written by {@link LogFile.write} after a CA log line
+ * that indicates a fault.
+ */
+export const FAULT_MESSAGE = "harness fault";
+// the fields of a CA log line used to detect faults
+const LogLineSchema = z.object({
+    level: z.string(),
+    message: z.string(),
+});
+/**
+ * Report whether a line logged by the CA indicates a fault, such as a database
+ * error, rather than an expected rejection of a request. Some faults are only
+ * logged, as the CA still issues a certificate when it cannot record it.
+ *
+ * @param line A line of output from the CA
+ * @returns true if the line is an error logged by the CA for a fault
+ */
+export const isFault = (line) => {
+    let json;
+    try {
+        json = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    const result = LogLineSchema.safeParse(json);
+    if (!result.success || result.data.level.toLowerCase() !== "error") {
+        return false;
+    }
+    return FAULT_MESSAGES.includes(result.data.message) || result.data.message.includes("database");
+};
+/**
+ * The log file of a test server, written as JSON lines.
+ *
+ * Lines from the CA are written as they are logged. The harness adds the
+ * following lines, whose messages all start with "harness":
+ *
+ * - `{"level":"info","message":"harness request",...}` for each request, with
+ *   `method`, `url`, `status` and, when `status` is 400 or more, the response
+ *   `body`.
+ * - `{"level":"error","message":"harness ...",...}` for a fault in the CA or
+ *   harness. A CA log line that indicates a fault (see {@link isFault}) is
+ *   followed by a line with the message {@link FAULT_MESSAGE}.
+ */
+export class LogFile {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /**
+     * Append a line of output from the CA, followed by a fault line if it
+     * indicates a fault.
+     */
+    write(line) {
+        this.append(line);
+        if (isFault(line)) {
+            this.append(formatValue({ level: "error", message: FAULT_MESSAGE, line }));
+        }
+    }
+    /**
+     * Append a request handled by the CA.
+     */
+    request(method, url, status, body) {
+        this.append(formatRequest(method, url, status, body));
+    }
+    /**
+     * Append a fault in the harness.
+     *
+     * @param message A description of the fault, which is prefixed with "harness"
+     * @param error The error that caused the fault
+     */
+    fault(message, error) {
+        this.append(formatValue({ level: "error", message: `harness ${message}`, error }));
+    }
+    append(line) {
+        appendFileSync(this.path, line + "\n");
+    }
+}
+//# sourceMappingURL=log.js.map

package/dist/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,CAAC,MAAM,KAAK,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB,CAAC,iBAAiB,EAAE,8BAA8B,CAAC,CAAA;AAEpG;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAA;AAE5C,oDAAoD;AACpD,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;CACnB,CAAC,CAAA;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAY,EAAW,EAAE;IAChD,IAAI,IAAa,CAAA;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;IAC5C,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,OAAO,EAAE,CAAC;QACpE,OAAO,KAAK,CAAA;IACb,CAAC;IAED,OAAO,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;AAChG,CAAC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,OAAO;IACV,IAAI,CAAQ;IAErB,YAAY,IAAY;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IACjB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAY;QACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACjB,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACnB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;QAC3E,CAAC;IACF,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,MAAc,EAAE,GAAW,EAAE,MAAc,EAAE,IAAY;QAChE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IACtD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,KAAc;QACpC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;IACnF,CAAC;IAEO,MAAM,CAAC,IAAY;QAC1B,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC,CAAA;IACvC,CAAC;CACD"}

package/dist/node.d.ts

@@ -0,0 +1,17 @@
+import type { TestServerConfig } from "./config.js";
+import type { LogFile } from "./log.js";
+import type { TestServer } from "./server.js";
+/**
+ * Run the CA on Node.js, created with the package's Node.js helpers and an
+ * in-memory `node:sqlite` database, behind an HTTP server on a random port.
+ *
+ * Output the CA writes with `console` is written to `log` until the server is
+ * closed.
+ *
+ * @param config The test server configuration
+ * @param log The log file for the CA and harness
+ * @returns The running server
+ * @throws InvalidConfigurationError if `config.bindings` is not a valid CA configuration
+ */
+export declare const startNode: (config: TestServerConfig, log: LogFile) => Promise<TestServer>;
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AA2B7C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,WAAkB,gBAAgB,OAAO,OAAO,KAAG,OAAO,CAAC,UAAU,CAiE1F,CAAA"}