@harperfast/integration-testing 0.1.0 → 0.3.0-0

package/dist/security/ocspServer.js

@@ -0,0 +1,132 @@
+/**
+ * Node.js OCSP (Online Certificate Status Protocol) responder
+ *
+ * A pure-Node.js replacement for `openssl ocsp`. Handles OCSP requests using pkijs
+ * for ASN.1 encoding and certGenUtils for Ed25519 signatures.
+ */
+import { createServer } from 'node:http';
+import * as pkijs from 'pkijs';
+import * as asn1js from 'asn1js';
+import { signBasicOCSPResponse } from "./certGenUtils.js";
+const OCSP_BASIC_RESPONSE_OID = '1.3.6.1.5.5.7.48.1.1';
+/**
+ * Build a DER-encoded OCSPResponse for the given DER-encoded OCSPRequest.
+ */
+async function buildOcspResponse(requestBody, certs) {
+    // Parse incoming OCSP request
+    const asn1 = asn1js.fromBER(requestBody);
+    if (asn1.offset === -1) {
+        throw new Error('Failed to parse OCSP request');
+    }
+    const ocspRequest = new pkijs.OCSPRequest({ schema: asn1.result });
+    const now = new Date();
+    const nextUpdate = new Date(now.getTime() + 60 * 60 * 1000); // 1 hour
+    // Build SingleResponse for each requested certificate
+    const singleResponses = ocspRequest.tbsRequest.requestList.map((req) => {
+        // Extract the decimal serial number to look up status
+        const serialDec = req.reqCert.serialNumber.valueBlock.valueDec;
+        const status = certs.statusMap.get(String(serialDec));
+        // certStatus ASN.1 encoding:
+        //   good    [0] IMPLICIT NULL
+        //   revoked [1] IMPLICIT RevokedInfo (SEQUENCE with revocation time)
+        //   unknown [2] IMPLICIT UnknownInfo
+        let certStatus;
+        if (status === 'good') {
+            certStatus = new asn1js.Primitive({
+                idBlock: { tagClass: 3, tagNumber: 0 },
+                valueHex: new ArrayBuffer(0),
+            });
+        }
+        else if (status === 'revoked') {
+            certStatus = new asn1js.Constructed({
+                idBlock: { tagClass: 3, tagNumber: 1 },
+                value: [new asn1js.GeneralizedTime({ valueDate: now })],
+            });
+        }
+        else {
+            // unknown
+            certStatus = new asn1js.Primitive({
+                idBlock: { tagClass: 3, tagNumber: 2 },
+                valueHex: new ArrayBuffer(0),
+            });
+        }
+        return new pkijs.SingleResponse({
+            certID: req.reqCert, // echo back the same certID
+            certStatus,
+            thisUpdate: now,
+            nextUpdate,
+        });
+    });
+    // Use the OCSP responder cert's subject as the responderID (byName, tagNumber=1)
+    const responseData = new pkijs.ResponseData({
+        responderID: certs.ocspCert.subject,
+        producedAt: now,
+        responses: singleResponses,
+    });
+    // Create BasicOCSPResponse and sign it
+    const basicResponse = new pkijs.BasicOCSPResponse({
+        tbsResponseData: responseData,
+        certs: [certs.ocspCert, certs.caCert],
+    });
+    await signBasicOCSPResponse(basicResponse, certs.ocspKeyPair.privateKey);
+    // Encode BasicOCSPResponse to DER, wrap in OCSPResponse
+    const basicDer = basicResponse.toSchema().toBER();
+    const ocspResponse = new pkijs.OCSPResponse({
+        responseStatus: new asn1js.Enumerated({ value: 0 }), // successful
+        responseBytes: new pkijs.ResponseBytes({
+            responseType: OCSP_BASIC_RESPONSE_OID,
+            response: new asn1js.OctetString({ valueHex: basicDer }),
+        }),
+    });
+    return Buffer.from(ocspResponse.toSchema().toBER());
+}
+/**
+ * Start a Node.js HTTP OCSP responder.
+ *
+ * @param port - Port to listen on
+ * @param certs - In-memory certificate and key data for the responder
+ * @returns Promise resolving to the HTTP server (already listening)
+ */
+export async function startOcspServer(port, certs) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            if (req.method !== 'POST' && req.method !== 'GET') {
+                res.writeHead(405);
+                res.end();
+                return;
+            }
+            const chunks = [];
+            req.on('data', (chunk) => chunks.push(chunk));
+            req.on('end', async () => {
+                try {
+                    const body = Buffer.concat(chunks);
+                    const response = await buildOcspResponse(body, certs);
+                    res.writeHead(200, { 'Content-Type': 'application/ocsp-response' });
+                    res.end(response);
+                }
+                catch (err) {
+                    console.error('OCSP server error:', err);
+                    // Return an "internalError" response
+                    const errResponse = new pkijs.OCSPResponse({
+                        responseStatus: new asn1js.Enumerated({ value: 2 }), // internalError
+                    });
+                    const errDer = Buffer.from(errResponse.toSchema().toBER());
+                    res.writeHead(200, { 'Content-Type': 'application/ocsp-response' });
+                    res.end(errDer);
+                }
+            });
+            req.on('error', (err) => {
+                console.error('OCSP request error:', err);
+                res.writeHead(500);
+                res.end();
+            });
+        });
+        server.on('error', reject);
+        server.listen(port, '127.0.0.1', () => resolve(server));
+    });
+}
+/** Stop a running OCSP server */
+export async function stopOcspServer(server) {
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+//# sourceMappingURL=ocspServer.js.map

package/dist/security/ocspServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ocspServer.js","sourceRoot":"","sources":["../../src/security/ocspServer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAG1D,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAEvD;;GAEG;AACH,KAAK,UAAU,iBAAiB,CAAC,WAAmB,EAAE,KAAsB;IAC3E,8BAA8B;IAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACzC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEnE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS;IAEtE,sDAAsD;IACtD,MAAM,eAAe,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtE,sDAAsD;QACtD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC/D,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAEtD,6BAA6B;QAC7B,8BAA8B;QAC9B,qEAAqE;QACrE,qCAAqC;QACrC,IAAI,UAAiD,CAAC;QACtD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACvB,UAAU,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC;gBACjC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBACtC,QAAQ,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC;aACrB,CAAC,CAAC;QACX,CAAC;aAAM,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,UAAU,GAAG,IAAI,MAAM,CAAC,WAAW,CAAC;gBACnC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBACtC,KAAK,EAAE,CAAC,IAAI,MAAM,CAAC,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;aAChD,CAAC,CAAC;QACX,CAAC;aAAM,CAAC;YACP,UAAU;YACV,UAAU,GAAG,IAAI,MAAM,CAAC,SAAS,CAAC;gBACjC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE;gBACtC,QAAQ,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC;aACrB,CAAC,CAAC;QACX,CAAC;QAED,OAAO,IAAI,KAAK,CAAC,cAAc,CAAC;YAC/B,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,4BAA4B;YACjD,UAAU;YACV,UAAU,EAAE,GAAG;YACf,UAAU;SACV,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,iFAAiF;IACjF,MAAM,YAAY,GAAG,IAAI,KAAK,CAAC,YAAY,CAAC;QAC3C,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,OAAO;QACnC,UAAU,EAAE,GAAG;QACf,SAAS,EAAE,eAAe;KAC1B,CAAC,CAAC;IAEH,uCAAuC;IACvC,MAAM,aAAa,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC;QACjD,eAAe,EAAE,YAAY;QAC7B,KAAK,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;KACrC,CAAC,CAAC;IAEH,MAAM,qBAAqB,CAAC,aAAa,EAAE,KAAK,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAEzE,wDAAwD;IACxD,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC;IAElD,MAAM,YAAY,GAAG,IAAI,KAAK,CAAC,YAAY,CAAC;QAC3C,cAAc,EAAE,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,aAAa;QAClE,aAAa,EAAE,IAAI,KAAK,CAAC,aAAa,CAAC;YACtC,YAAY,EAAE,uBAAuB;YACrC,QAAQ,EAAE,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;SACxD,CAAC;KACF,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,KAAsB;IACzE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACxC,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;gBACnD,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBACnB,GAAG,CAAC,GAAG,EAAE,CAAC;gBACV,OAAO;YACR,CAAC;YAED,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YAC9C,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;gBACxB,IAAI,CAAC;oBACJ,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;oBACnC,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;oBACtD,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAC,CAAC;oBACpE,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACnB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACd,OAAO,CAAC,KAAK,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;oBACzC,qCAAqC;oBACrC,MAAM,WAAW,GAAG,IAAI,KAAK,CAAC,YAAY,CAAC;wBAC1C,cAAc,EAAE,IAAI,MAAM,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,gBAAgB;qBACrE,CAAC,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC;oBAC3D,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAC,CAAC;oBACpE,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,CAAC;YACF,CAAC,CAAC,CAAC;YACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBACvB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;gBAC1C,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;gBACnB,GAAG,CAAC,GAAG,EAAE,CAAC;YACX,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,iCAAiC;AACjC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAc;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/securityServices.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Security Services Utilities for Integration Tests
+ *
+ * This module provides utilities for managing OCSP responders, CRL servers,
+ * and certificate generation for security-related integration tests.
+ *
+ * All certificate generation and OCSP responding is done in pure Node.js
+ * using webcrypto + pkijs — no openssl CLI dependency.
+ */
+import { type Server } from 'node:http';
+import type { OcspCertificates } from './security/ocsp/generate-test-certs.ts';
+import type { CrlCertificates } from './security/crl/generate-test-certs.ts';
+export interface OcspResponderContext {
+    server: Server;
+    port: number;
+    certsPath: string;
+    certs: OcspCertificates;
+}
+export interface CrlServerContext {
+    server: Server;
+    port: number;
+    certsPath: string;
+    certs: CrlCertificates;
+}
+/**
+ * Stop an OCSP responder server
+ */
+export declare function stopOcspResponder(ctx: OcspResponderContext): Promise<void>;
+/**
+ * Start a Node.js HTTP server to serve CRL files
+ */
+export declare function startCrlServer(certsPath: string, port: number, certs: CrlCertificates): Promise<CrlServerContext>;
+/**
+ * Stop a CRL server
+ */
+export declare function stopCrlServer(ctx: CrlServerContext): Promise<void>;
+export { generateOcspCertificates, type OcspCertificates } from './security/ocsp/generate-test-certs.ts';
+export { generateCrlCertificates, type CrlCertificates } from './security/crl/generate-test-certs.ts';
+/**
+ * Setup CRL server with automatic port allocation and retry on conflict
+ */
+export declare function setupCrlServerWithCerts(certsPath: string, hostname?: string, maxRetries?: number): Promise<CrlServerContext>;
+/**
+ * Setup OCSP responder with automatic port allocation and retry on conflict
+ *
+ * Generates certificates with OCSP URL embedded, then starts the Node.js
+ * OCSP responder on the same port.
+ */
+export declare function setupOcspResponderWithCerts(certsPath: string, hostname?: string, maxRetries?: number): Promise<OcspResponderContext>;

package/dist/securityServices.js

@@ -0,0 +1,120 @@
+/**
+ * Security Services Utilities for Integration Tests
+ *
+ * This module provides utilities for managing OCSP responders, CRL servers,
+ * and certificate generation for security-related integration tests.
+ *
+ * All certificate generation and OCSP responding is done in pure Node.js
+ * using webcrypto + pkijs — no openssl CLI dependency.
+ */
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { startOcspServer, stopOcspServer } from "./security/ocspServer.js";
+/**
+ * Stop an OCSP responder server
+ */
+export async function stopOcspResponder(ctx) {
+    return stopOcspServer(ctx.server);
+}
+/**
+ * Start a Node.js HTTP server to serve CRL files
+ */
+export async function startCrlServer(certsPath, port, certs) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            if (req.url === '/test.crl') {
+                try {
+                    const crl = readFileSync(join(certsPath, 'test.crl'));
+                    res.writeHead(200, {
+                        'Content-Type': 'application/pkix-crl',
+                        'Cache-Control': 'no-cache',
+                    });
+                    res.end(crl);
+                }
+                catch {
+                    res.writeHead(500);
+                    res.end('Internal Server Error');
+                }
+            }
+            else if (req.url === '/health') {
+                res.writeHead(200, { 'Content-Type': 'text/plain' });
+                res.end('OK');
+            }
+            else {
+                res.writeHead(404);
+                res.end('Not Found');
+            }
+        });
+        server.on('error', reject);
+        server.listen(port, () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('Server did not bind to a network port'));
+                return;
+            }
+            resolve({
+                server,
+                port: address.port,
+                certsPath,
+                certs,
+            });
+        });
+    });
+}
+/**
+ * Stop a CRL server
+ */
+export async function stopCrlServer(ctx) {
+    return new Promise((resolve) => {
+        ctx.server.close(() => resolve());
+    });
+}
+// Re-export certificate generation functions and types
+export { generateOcspCertificates } from "./security/ocsp/generate-test-certs.js";
+export { generateCrlCertificates } from "./security/crl/generate-test-certs.js";
+/**
+ * Setup CRL server with automatic port allocation and retry on conflict
+ */
+export async function setupCrlServerWithCerts(certsPath, hostname = '127.0.0.1', maxRetries = 5) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const port = 50000 + Math.floor(Math.random() * 10000);
+        try {
+            const { generateCrlCertificates } = await import("./security/crl/generate-test-certs.js");
+            const certs = await generateCrlCertificates(certsPath, hostname, port);
+            return startCrlServer(certsPath, port, certs);
+        }
+        catch (error) {
+            if (error.code === 'EADDRINUSE' && attempt < maxRetries - 1) {
+                continue;
+            }
+            throw new Error(`Failed to setup CRL server after ${attempt + 1} attempts: ${error.message}`);
+        }
+    }
+    throw new Error(`Failed to setup CRL server after ${maxRetries} attempts`);
+}
+/**
+ * Setup OCSP responder with automatic port allocation and retry on conflict
+ *
+ * Generates certificates with OCSP URL embedded, then starts the Node.js
+ * OCSP responder on the same port.
+ */
+export async function setupOcspResponderWithCerts(certsPath, hostname = '127.0.0.1', maxRetries = 5) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const port = 50000 + Math.floor(Math.random() * 10000);
+        try {
+            const { generateOcspCertificates } = await import("./security/ocsp/generate-test-certs.js");
+            const { files, serverCerts } = await generateOcspCertificates(certsPath, hostname, port);
+            const server = await startOcspServer(port, serverCerts);
+            return { server, port, certsPath, certs: files };
+        }
+        catch (error) {
+            if (error.code === 'EADDRINUSE' && attempt < maxRetries - 1) {
+                continue;
+            }
+            throw new Error(`Failed to setup OCSP responder after ${attempt + 1} attempts: ${error.message}`);
+        }
+    }
+    throw new Error(`Failed to setup OCSP responder after ${maxRetries} attempts`);
+}
+//# sourceMappingURL=securityServices.js.map

package/dist/securityServices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"securityServices.js","sourceRoot":"","sources":["../src/securityServices.ts"],"names":[],"mappings":"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"}

package/dist/src/harperLifecycle.d.ts

@@ -0,0 +1,156 @@
+import { ChildProcess } from 'node:child_process';
+import { type SuiteContext, type TestContext } from 'node:test';
+/**
+ * Minimal context interface required by startHarper/teardownHarper.
+ *
+ * This is intentionally loose so it can be satisfied by:
+ * - node:test SuiteContext/TestContext objects (via ContextWithHarper)
+ * - Plain objects (e.g. Playwright worker fixtures: `createHarperContext()`)
+ */
+export interface HarperTestContext {
+    /** Optional name used for log directory naming (e.g. suite name or Playwright worker index). */
+    name?: string;
+    /** Populated by startHarper(). May be pre-seeded with dataRootDir/hostname to reuse across restarts. */
+    harper?: Partial<HarperContext>;
+}
+/**
+ * A started context — harper is fully populated after startHarper() resolves.
+ */
+export interface StartedHarperTestContext extends HarperTestContext {
+    harper: HarperContext;
+}
+/**
+ * Creates a plain object satisfying HarperTestContext, for use outside node:test
+ * (e.g. as a Playwright worker fixture).
+ *
+ * @param name Optional name for log directory naming (e.g. Playwright worker index).
+ */
+export declare function createHarperContext(name?: string): HarperTestContext;
+export declare const OPERATIONS_API_PORT = 9925;
+export declare const DEFAULT_ADMIN_USERNAME = "admin";
+export declare const DEFAULT_ADMIN_PASSWORD = "Abc1234!";
+export declare const DEFAULT_STARTUP_TIMEOUT_MS: number;
+/**
+ * Options for setting up a Harper instance.
+ */
+export interface StartHarperOptions {
+    /**
+     * Timeout in milliseconds to wait for Harper to start.
+     * @default 30000
+     */
+    startupTimeoutMs?: number;
+    /**
+     * Additional configuration options to pass to the Harper CLI.
+     */
+    config?: any;
+    /**
+     * Environment variables to set when running Harper.
+     */
+    env?: any;
+    /**
+     * Explicit path to the Harper CLI script (dist/bin/harper.js).
+     * If not provided, resolution order is:
+     *   1. This option
+     *   2. HARPER_INTEGRATION_TEST_INSTALL_SCRIPT environment variable
+     *   3. Auto-resolved from 'harper' package in node_modules
+     */
+    harperBinPath?: string;
+}
+export interface HarperContext {
+    /** Absolute path to the Harper installation directory */
+    dataRootDir: string;
+    /** Admin credentials for the Harper instance */
+    admin: {
+        /** Admin username (default: 'admin') */
+        username: string;
+        /** Admin password (default: 'Abc1234!') */
+        password: string;
+    };
+    /** HTTP URL for the Harper instance (e.g., 'http://127.0.0.2:9926') */
+    httpURL: string;
+    /** Operations API URL (e.g., 'http://127.0.0.2:9925') */
+    operationsAPIURL: string;
+    /** Assigned loopback IP address (e.g., '127.0.0.2') */
+    hostname: string;
+    /** Child process for the Harper instance */
+    process: ChildProcess;
+    /** Absolute path to the log directory for this suite (only set when HARPER_INTEGRATION_TEST_LOG_DIR is configured) */
+    logDir?: string;
+}
+/**
+ * Test context interface with Harper instance details, for use with node:test.
+ *
+ * This interface is populated by `startHarper()` and contains
+ * all necessary information to interact with the test Harper instance.
+ *
+ * For use outside node:test (e.g. Playwright), use `createHarperContext()` to
+ * create a plain object satisfying `HarperTestContext` instead.
+ */
+export interface ContextWithHarper extends SuiteContext, TestContext {
+    harper: HarperContext;
+}
+/**
+ * Sets up a Harper instance with a component pre-installed from a local directory.
+ *
+ * Copies `fixturePath` into `{dataRootDir}/components/{name}` before Harper starts,
+ * so the component is available on the first request without a post-startup deploy.
+ * Use this when tests need a known route available at startup (e.g. mTLS cert tests).
+ *
+ * @param ctx - The test context to populate with Harper instance details
+ * @param fixturePath - Absolute path to the component directory to pre-install
+ * @param options - Optional configuration for the setup process
+ */
+export declare function setupHarperWithFixture(ctx: HarperTestContext, fixturePath: string, options?: StartHarperOptions): Promise<StartedHarperTestContext>;
+/**
+ * Sets up and starts a Harper instance for testing.
+ *
+ * @param ctx - The test context to populate with Harper instance details
+ * @param options - Optional configuration for the setup process
+ * @returns The context with the `harper` property populated
+ *
+ * @example
+ * ```ts
+ * suite('My tests', (ctx: ContextWithHarper) => {
+ *   before(async () => {
+ *     await startHarper(ctx);
+ *   });
+ *
+ *   after(async () => {
+ *     await teardownHarper(ctx);
+ *   });
+ *
+ *   test('can connect', async () => {
+ *     const response = await fetch(ctx.harper.httpURL);
+ *     // ...
+ *   });
+ * });
+ * ```
+ */
+export declare function startHarper(ctx: HarperTestContext, options?: StartHarperOptions): Promise<StartedHarperTestContext>;
+/**
+ * Kill harper process (can be used for teardown, or killing it before a restart)
+ * @param ctx
+ */
+export declare function killHarper(ctx: StartedHarperTestContext): Promise<void>;
+/**
+ * Tears down a Harper instance and cleans up all resources.
+ *
+ * This function stops the Harper instance, releases the loopback address,
+ * and removes the installation directory.
+ * @param ctx - The test context with Harper instance details
+ *
+ * @example
+ * ```ts
+ * suite('My tests', (ctx: ContextWithHarper) => {
+ *   before(async () => {
+ *     await startHarper(ctx);
+ *   });
+ *
+ *   after(async () => {
+ *     await teardownHarper(ctx);
+ *   });
+ * });
+ * ```
+ */
+export declare function teardownHarper(ctx: StartedHarperTestContext): Promise<void>;
+export declare function sendOperation(context: HarperContext, operation: any): Promise<any>;