@groundnuty/macf-core 0.2.0-rc.0

package/dist/certs/agent-cert.d.ts

@@ -0,0 +1,91 @@
+import { MacfError } from '../errors.js';
+export declare class AgentCertError extends MacfError {
+    constructor(message: string);
+}
+export interface AgentCertResult {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/**
+ * Import a PEM private key into a WebCrypto CryptoKey for signing.
+ *
+ * Return type was `Promise<unknown>` historically — DOM CryptoKey types
+ * weren't exposed via @types/node < v25. Since @types/node v25 (#17 /
+ * PR #130) CryptoKey is resolvable from `globalThis`, so we return
+ * the precise type instead of laundering through `unknown` at each
+ * call site.
+ *
+ * Rejects input that contains zero or multiple BEGIN/END marker pairs
+ * (e.g. two keys accidentally concatenated) — ultrareview finding H4.
+ * Without this shape check, `webcrypto.subtle.importKey` would be
+ * handed a concatenated base64 blob and throw a generic DataError,
+ * which propagates upstream with no hint that the input file itself
+ * was malformed.
+ */
+export declare function importPrivateKey(keyPem: string): Promise<CryptoKey>;
+/**
+ * Generate agent certificate signed by the CA.
+ * Used when the CA key is available locally.
+ *
+ * `advertiseHost`, when supplied, is added to the cert's SAN list on
+ * top of the default [127.0.0.1, localhost] pair. This is how an agent
+ * reachable at a Tailscale IP / DNS name passes server-hostname
+ * verification when the routing Action (or a sibling agent) connects
+ * over the network. Classification is IPv4-shape vs DNS via
+ * `hostToSan()`. See macf#178 Gap 3.
+ */
+export declare function generateAgentCert(config: {
+    readonly agentName: string;
+    readonly caCertPem: string;
+    readonly caKeyPem: string;
+    readonly advertiseHost?: string;
+    readonly certPath?: string;
+    readonly keyPath?: string;
+}): Promise<AgentCertResult>;
+/**
+ * Generate a CA-signed client cert with a given CN and validity window.
+ * Used for non-peer clients (e.g. the routing Action's mTLS cert, per
+ * macf-actions#8 / #119). Unlike generateAgentCert, validity is
+ * parameterized in days so operator can pick the policy.
+ *
+ * Does NOT add SubjectAlternativeName — the routing Action is an
+ * mTLS CLIENT, so the server-hostname SAN pattern doesn't apply. Key
+ * usage is digital signature only (no key encipherment — we're not
+ * doing static-key TLS variants).
+ */
+export declare function generateClientCert(config: {
+    readonly commonName: string;
+    readonly validityDays: number;
+    readonly caCertPem: string;
+    readonly caKeyPem: string;
+}): Promise<AgentCertResult>;
+/**
+ * Generate a CSR (Certificate Signing Request) for an agent.
+ * Used when requesting remote signing via /sign endpoint.
+ */
+export declare function generateCSR(agentName: string): Promise<{
+    readonly csrPem: string;
+    readonly keyPem: string;
+}>;
+/**
+ * Extract the CN from a subject string like "CN=code-agent" or
+ * "O=foo,CN=code-agent,OU=bar".
+ *
+ * Returns undefined if the subject contains ZERO or MULTIPLE CN fields.
+ * A multi-CN subject ("CN=attacker,CN=victim") is explicitly rejected
+ * — signCSR surfaces a specific error so the confused-deputy attack
+ * can't slip through the agent-name equality check. See #89.
+ *
+ * Exported for unit tests.
+ */
+export declare function extractCN(subject: string): string | undefined;
+/**
+ * Sign a CSR using the CA key. Validates CN match and CSR signature (proof-of-possession).
+ */
+export declare function signCSR(config: {
+    readonly csrPem: string;
+    readonly agentName: string;
+    readonly caCertPem: string;
+    readonly caKeyPem: string;
+}): Promise<string>;
+//# sourceMappingURL=agent-cert.d.ts.map

package/dist/certs/agent-cert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cert.d.ts","sourceRoot":"","sources":["../../src/certs/agent-cert.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAQD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CA2BzE;AAsGD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAuB3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,eAAe,CAAC,CAgD3B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC,CAmBD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7D;AAED;;GAEG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC,MAAM,CAAC,CAiClB"}

package/dist/certs/agent-cert.js

@@ -0,0 +1,263 @@
+import { randomBytes } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { x509, webcrypto, RSA_ALGORITHM, AGENT_CERT_VALIDITY_YEARS, } from './crypto-provider.js';
+import { MacfError } from '../errors.js';
+export class AgentCertError extends MacfError {
+    constructor(message) {
+        super('AGENT_CERT_ERROR', message);
+        this.name = 'AgentCertError';
+    }
+}
+function exportKeyToPem(exported) {
+    const b64 = Buffer.from(exported).toString('base64');
+    const lines = b64.match(/.{1,64}/g) ?? [];
+    return `-----BEGIN PRIVATE KEY-----\n${lines.join('\n')}\n-----END PRIVATE KEY-----\n`;
+}
+/**
+ * Import a PEM private key into a WebCrypto CryptoKey for signing.
+ *
+ * Return type was `Promise<unknown>` historically — DOM CryptoKey types
+ * weren't exposed via @types/node < v25. Since @types/node v25 (#17 /
+ * PR #130) CryptoKey is resolvable from `globalThis`, so we return
+ * the precise type instead of laundering through `unknown` at each
+ * call site.
+ *
+ * Rejects input that contains zero or multiple BEGIN/END marker pairs
+ * (e.g. two keys accidentally concatenated) — ultrareview finding H4.
+ * Without this shape check, `webcrypto.subtle.importKey` would be
+ * handed a concatenated base64 blob and throw a generic DataError,
+ * which propagates upstream with no hint that the input file itself
+ * was malformed.
+ */
+export async function importPrivateKey(keyPem) {
+    const beginMatches = keyPem.match(/-----BEGIN PRIVATE KEY-----/g);
+    const endMatches = keyPem.match(/-----END PRIVATE KEY-----/g);
+    if (!beginMatches || beginMatches.length !== 1) {
+        throw new AgentCertError(`Malformed private key PEM: expected exactly one BEGIN marker, got ${beginMatches?.length ?? 0}`);
+    }
+    if (!endMatches || endMatches.length !== 1) {
+        throw new AgentCertError(`Malformed private key PEM: expected exactly one END marker, got ${endMatches?.length ?? 0}`);
+    }
+    const stripped = keyPem
+        .replace(/-----BEGIN PRIVATE KEY-----/g, '')
+        .replace(/-----END PRIVATE KEY-----/g, '')
+        .replace(/\s/g, '');
+    const der = Buffer.from(stripped, 'base64');
+    return webcrypto.subtle.importKey('pkcs8', der, RSA_ALGORITHM, false, ['sign']);
+}
+/**
+ * Classify a host string as an IP or DNS name for SubjectAlternativeName
+ * entries. Shape-only check (matches `999.999.999.999` too — cert
+ * generation doesn't validate octet ranges, and we'd rather keep the
+ * classifier forgiving than have it silently misclassify a typo'd IP
+ * as DNS). IPv6 not handled here; add `:` detection + `[]` URL-wrapping
+ * when there's an actual ask.
+ */
+function hostToSan(host) {
+    const ipv4Shape = /^(\d{1,3}\.){3}\d{1,3}$/;
+    return ipv4Shape.test(host)
+        ? { type: 'ip', value: host }
+        : { type: 'dns', value: host };
+}
+/**
+ * Shared peer-cert builder used by both generateAgentCert (new peer
+ * certs via `macf certs init`) and signCSR (CSR-signed peer certs
+ * via `/sign`). Produces the DR-004-compliant extension set:
+ *
+ *   - KeyUsage: digitalSignature | keyEncipherment (mTLS client+server use)
+ *   - SubjectAlternativeName: 127.0.0.1 / localhost (always, for local-debug
+ *       flows — curl-to-localhost for /health etc.) plus any caller-
+ *       supplied extraSans (typically the agent's advertised host per
+ *       macf#178 Gap 3)
+ *   - ExtendedKeyUsage: serverAuth + clientAuth. Agents are dual-role
+ *       peers — they act as TLS SERVERS when receiving /notify, /health,
+ *       /sign POSTs, and as TLS CLIENTS when originating POSTs to other
+ *       peers. Without serverAuth, OpenSSL/curl server-role validation
+ *       rejects the presented cert with "unsuitable certificate purpose"
+ *       (curl error 60). See macf#180. #121 still enforces clientAuth
+ *       server-side at /health + /notify + /sign; serverAuth is purely
+ *       additive for the client-side TLS validation of agents-as-servers.
+ *       `generateClientCert` (routing-action) stays client-only — it's
+ *       a pure client with no server role.
+ *
+ * Extracted per ultrareview finding A10 — both callers previously
+ * duplicated this ~25-line extension list. When DR-004 extensions
+ * evolve, a single edit here affects both paths instead of two in
+ * lockstep.
+ */
+async function buildPeerCert(opts) {
+    const caCert = new x509.X509Certificate(opts.caCertPem);
+    const caKey = await importPrivateKey(opts.caKeyPem);
+    const notBefore = new Date();
+    const notAfter = new Date();
+    notAfter.setFullYear(notAfter.getFullYear() + AGENT_CERT_VALIDITY_YEARS);
+    const sans = [
+        { type: 'ip', value: '127.0.0.1' },
+        { type: 'dns', value: 'localhost' },
+        ...(opts.extraSans ?? []),
+    ];
+    const cert = await x509.X509CertificateGenerator.create({
+        serialNumber: randomBytes(8).toString('hex'),
+        subject: opts.subject,
+        issuer: caCert.subject,
+        notBefore,
+        notAfter,
+        signingAlgorithm: RSA_ALGORITHM,
+        publicKey: opts.publicKey,
+        signingKey: caKey,
+        extensions: [
+            new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature | x509.KeyUsageFlags.keyEncipherment, true),
+            new x509.SubjectAlternativeNameExtension(sans),
+            new x509.ExtendedKeyUsageExtension([
+                // serverAuth OID — agents are TLS servers on /notify, /health,
+                // /sign. Without this, OpenSSL/curl server-role validation
+                // rejects with "unsuitable certificate purpose" (curl error
+                // 60). See macf#180.
+                '1.3.6.1.5.5.7.3.1',
+                // clientAuth OID (#125) — agents are also TLS clients when
+                // originating POSTs to peers. Enforced server-side at /health
+                // + /notify + /sign per #121.
+                '1.3.6.1.5.5.7.3.2',
+            ]),
+        ],
+    });
+    return cert.toString('pem');
+}
+/**
+ * Generate agent certificate signed by the CA.
+ * Used when the CA key is available locally.
+ *
+ * `advertiseHost`, when supplied, is added to the cert's SAN list on
+ * top of the default [127.0.0.1, localhost] pair. This is how an agent
+ * reachable at a Tailscale IP / DNS name passes server-hostname
+ * verification when the routing Action (or a sibling agent) connects
+ * over the network. Classification is IPv4-shape vs DNS via
+ * `hostToSan()`. See macf#178 Gap 3.
+ */
+export async function generateAgentCert(config) {
+    const { agentName, caCertPem, caKeyPem, advertiseHost, certPath, keyPath } = config;
+    const agentKeys = await webcrypto.subtle.generateKey(RSA_ALGORITHM, true, ['sign', 'verify']);
+    const certPem = await buildPeerCert({
+        subject: `CN=${agentName}`,
+        caCertPem,
+        caKeyPem,
+        publicKey: agentKeys.publicKey,
+        extraSans: advertiseHost ? [hostToSan(advertiseHost)] : undefined,
+    });
+    const exported = await webcrypto.subtle.exportKey('pkcs8', agentKeys.privateKey);
+    const agentKeyPem = exportKeyToPem(exported);
+    if (certPath)
+        writeFileSync(certPath, certPem, { mode: 0o644 });
+    if (keyPath)
+        writeFileSync(keyPath, agentKeyPem, { mode: 0o600 });
+    return { certPem, keyPem: agentKeyPem };
+}
+/**
+ * Generate a CA-signed client cert with a given CN and validity window.
+ * Used for non-peer clients (e.g. the routing Action's mTLS cert, per
+ * macf-actions#8 / #119). Unlike generateAgentCert, validity is
+ * parameterized in days so operator can pick the policy.
+ *
+ * Does NOT add SubjectAlternativeName — the routing Action is an
+ * mTLS CLIENT, so the server-hostname SAN pattern doesn't apply. Key
+ * usage is digital signature only (no key encipherment — we're not
+ * doing static-key TLS variants).
+ */
+export async function generateClientCert(config) {
+    const { commonName, validityDays, caCertPem, caKeyPem } = config;
+    if (!Number.isInteger(validityDays) || validityDays < 1) {
+        throw new AgentCertError(`validityDays must be a positive integer (got ${validityDays})`);
+    }
+    const caCert = new x509.X509Certificate(caCertPem);
+    const caKey = await importPrivateKey(caKeyPem);
+    const clientKeys = await webcrypto.subtle.generateKey(RSA_ALGORITHM, true, ['sign', 'verify']);
+    const notBefore = new Date();
+    const notAfter = new Date();
+    notAfter.setDate(notAfter.getDate() + validityDays);
+    const cert = await x509.X509CertificateGenerator.create({
+        serialNumber: randomBytes(8).toString('hex'),
+        subject: `CN=${commonName}`,
+        issuer: caCert.subject,
+        notBefore,
+        notAfter,
+        signingAlgorithm: RSA_ALGORITHM,
+        publicKey: clientKeys.publicKey,
+        signingKey: caKey,
+        extensions: [
+            new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature, true),
+            new x509.ExtendedKeyUsageExtension([
+                // clientAuth OID — explicit "this cert is for TLS client auth"
+                '1.3.6.1.5.5.7.3.2',
+            ]),
+        ],
+    });
+    const certPem = cert.toString('pem');
+    const exported = await webcrypto.subtle.exportKey('pkcs8', clientKeys.privateKey);
+    const keyPem = exportKeyToPem(exported);
+    return { certPem, keyPem };
+}
+/**
+ * Generate a CSR (Certificate Signing Request) for an agent.
+ * Used when requesting remote signing via /sign endpoint.
+ */
+export async function generateCSR(agentName) {
+    const keys = await webcrypto.subtle.generateKey(RSA_ALGORITHM, true, ['sign', 'verify']);
+    const csr = await x509.Pkcs10CertificateRequestGenerator.create({
+        name: `CN=${agentName}`,
+        keys,
+        signingAlgorithm: RSA_ALGORITHM,
+    });
+    const exported = await webcrypto.subtle.exportKey('pkcs8', keys.privateKey);
+    return {
+        csrPem: csr.toString('pem'),
+        keyPem: exportKeyToPem(exported),
+    };
+}
+/**
+ * Extract the CN from a subject string like "CN=code-agent" or
+ * "O=foo,CN=code-agent,OU=bar".
+ *
+ * Returns undefined if the subject contains ZERO or MULTIPLE CN fields.
+ * A multi-CN subject ("CN=attacker,CN=victim") is explicitly rejected
+ * — signCSR surfaces a specific error so the confused-deputy attack
+ * can't slip through the agent-name equality check. See #89.
+ *
+ * Exported for unit tests.
+ */
+export function extractCN(subject) {
+    const matches = subject.match(/(?:^|,\s*)CN=([^,]+)/gi);
+    if (!matches || matches.length !== 1)
+        return undefined;
+    const inner = /CN=([^,]+)/i.exec(matches[0]);
+    return inner?.[1]?.trim();
+}
+/**
+ * Sign a CSR using the CA key. Validates CN match and CSR signature (proof-of-possession).
+ */
+export async function signCSR(config) {
+    const { csrPem, agentName, caCertPem, caKeyPem } = config;
+    const csr = new x509.Pkcs10CertificateRequest(csrPem);
+    // Verify CSR signature (proof-of-possession — requester controls the private key)
+    const csrValid = await csr.verify();
+    if (!csrValid) {
+        throw new AgentCertError('CSR signature verification failed');
+    }
+    // Verify CN matches agent name. extractCN returns undefined when the
+    // subject has zero OR multiple CN fields — surface that specifically
+    // so operators see "subject malformed" rather than "CN undefined does
+    // not match ..." (see #89).
+    const cn = extractCN(csr.subject);
+    if (cn === undefined) {
+        throw new AgentCertError(`CSR subject must contain exactly one CN field (got: "${csr.subject}")`);
+    }
+    if (cn !== agentName) {
+        throw new AgentCertError(`CSR CN "${cn}" does not match agent name "${agentName}"`);
+    }
+    return buildPeerCert({
+        subject: csr.subject,
+        caCertPem,
+        caKeyPem,
+        publicKey: csr.publicKey,
+    });
+}
+//# sourceMappingURL=agent-cert.js.map

package/dist/certs/agent-cert.js.map

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

package/dist/certs/ca.d.ts

@@ -0,0 +1,103 @@
+import type { GitHubVariablesClient } from '../registry/types.js';
+import { MacfError } from '../errors.js';
+export declare class CaError extends MacfError {
+    constructor(message: string);
+}
+export interface CaKeyPair {
+    readonly certPem: string;
+    readonly keyPem: string;
+}
+/**
+ * Create a new CA certificate and key pair.
+ * Saves to disk and optionally uploads cert to registry.
+ */
+export declare function createCA(config: {
+    readonly project: string;
+    readonly certPath: string;
+    readonly keyPath: string;
+    readonly client?: GitHubVariablesClient;
+}): Promise<CaKeyPair>;
+/**
+ * Backup CA key to registry, encrypted with AES-256-CBC + PBKDF2.
+ * Format is interoperable with openssl enc -aes-256-cbc -pbkdf2.
+ */
+export declare function backupCAKey(config: {
+    readonly project: string;
+    readonly keyPem: string;
+    readonly passphrase: string;
+    readonly client: GitHubVariablesClient;
+}): Promise<void>;
+/**
+ * Recover CA key from registry.
+ */
+export declare function recoverCAKey(config: {
+    readonly project: string;
+    readonly passphrase: string;
+    readonly keyPath: string;
+    readonly client: GitHubVariablesClient;
+}): Promise<string>;
+export declare const WIRE_FORMAT_VERSION = 2;
+export declare const V2_PBKDF2_ITERS = 600000;
+export declare const V1_PBKDF2_ITERS = 10000;
+/**
+ * Encrypt CA key using AES-256-CBC + PBKDF2-SHA256 at 600k iters
+ * (DR-011 rev2, OWASP 2023 alignment). Output is a versioned JSON
+ * envelope wrapping the OpenSSL-compatible `Salted__` blob:
+ *
+ *   {"v": 2, "iter": 600000, "payload": "<base64 Salted__ ...>"}
+ *
+ * Manual recovery with openssl CLI (see DR-011-rev2 for full doc):
+ *   gh api ... --jq '.value' | jq -r .payload | base64 -d | \
+ *     openssl enc -aes-256-cbc -pbkdf2 -md sha256 -iter 600000 -d -out ca-key.pem
+ */
+export declare function encryptCAKey(keyPem: string, passphrase: string): string;
+/**
+ * Decrypt a CA key from the on-wire registry value. Dispatches by
+ * wire format:
+ *
+ * - **v2 (JSON envelope, DR-011 rev2+):** parses `{v, iter, payload}`,
+ *   decrypts `payload` at the envelope's iter count.
+ * - **v1 (raw base64 `Salted__` blob, legacy pre-2026-04-16):** treats
+ *   the value as a raw base64 blob and decrypts at iter=10000 (the
+ *   OpenSSL 3.0/3.1 default at the time the blob was written).
+ *
+ * Both paths share the same PEM-shape check (#94) after AES decryption
+ * to catch wrong-passphrase attempts that produce valid PKCS7 padding
+ * by chance (~6% of wrong passphrases).
+ *
+ * Disambiguation is safe by construction — base64 output never starts
+ * with `{`, so only v2 JSON envelopes hit the JSON path. See DR-011
+ * rev2 \"Wire Format\" section for the full spec.
+ *
+ * Throws CaError on:
+ *   - malformed v2 envelope (missing/invalid v/iter/payload fields)
+ *   - missing `Salted__` header inside the payload
+ *   - PKCS7 padding failure (wrong passphrase, ~94% of the time)
+ *   - decrypted content doesn't look like a PEM private key (wrong
+ *     passphrase that happened to produce valid PKCS7 padding)
+ */
+export declare function decryptCAKey(encryptedValue: string, passphrase: string): string;
+/**
+ * Hand-construct a v1-shaped CA key backup (legacy wire format) at
+ * 10000 iters. Exported for `test/certs/wire-format-compat.test.ts`
+ * regression guard and for any future tooling that needs to produce
+ * legacy-shaped backups (none expected). NOT used by `encryptCAKey`
+ * itself — `encryptCAKey` always writes v2. (#115)
+ */
+export declare function encryptCAKeyV1Legacy(keyPem: string, passphrase: string): string;
+/**
+ * Cheap semantic check: does this look like a PEM-encoded private key?
+ * Exported for unit tests. Doesn't validate DER content — only the
+ * PEM envelope.
+ *
+ * Random bytes faking BOTH the 28-char BEGIN and 26-char END markers
+ * simultaneously is ~2^-432 per decrypted buffer — effectively
+ * impossible. No minimum body length is needed; the markers alone are
+ * the distinguisher.
+ */
+export declare function isLikelyPemPrivateKey(text: string): boolean;
+/**
+ * Load CA cert and key from disk.
+ */
+export declare function loadCA(certPath: string, keyPath: string): CaKeyPair;
+//# sourceMappingURL=ca.d.ts.map

package/dist/certs/ca.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ca.d.ts","sourceRoot":"","sources":["../../src/certs/ca.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,qBAAa,OAAQ,SAAQ,SAAS;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAsBD;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CACzC,GAAG,OAAO,CAAC,SAAS,CAAC,CA6CrB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;CACxC,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;CACxC,GAAG,OAAO,CAAC,MAAM,CAAC,CAalB;AAMD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,eAAe,SAAS,CAAC;AACtC,eAAO,MAAM,eAAe,QAAQ,CAAC;AAoFrC;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAyBvE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAiB/E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAiB/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAO3D;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAYnE"}