@andrewheberle/serverless-ssh-ca 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@andrewheberle/serverless-ssh-ca",
-	"version": "0.22.0",
+	"version": "0.23.0",
 	"description": "A serverless SSH CA built for Cloudflare Workers that can also run on Node.js",
 	"type": "module",
 	"types": "./dist/index.d.ts",
@@ -31,18 +31,19 @@
 	},
 	"dependencies": {
 		"@andrewheberle/ts-slog": "^1.3.0",
+		"@noble/hashes": "^2.4.0",
+		"@scure/base": "^2.4.0",
 		"chanfana": "^3.0.0",
 		"hono": "^4.10.6",
 		"itty-time": "^2.0.2",
 		"jose": "^6.0.12",
-		"sshpk": "^1.18.0",
+		"micro-packed": "^0.11.1",
 		"workers-qb": "^1.14.0",
 		"zod": "^4.0.0"
 	},
 	"devDependencies": {
 		"@eslint/js": "^10.0.1",
 		"@types/node": "^24.19.1",
-		"@types/sshpk": "^1.17.4",
 		"@vitest/coverage-v8": "^4.1.7",
 		"eslint": "^10.4.1",
 		"tsx": "^4.21.0",

package/src/api/operations.ts

@@ -0,0 +1,211 @@
+import { group, Logger } from "@andrewheberle/ts-slog"
+import {
+	ApiException,
+	ConflictException,
+	InternalServerErrorException,
+	NotFoundException,
+	UnprocessableEntityException,
+} from "chanfana"
+import type { AppContext } from "../router.js"
+import type { CertificateSignerResponse } from "../types.js"
+import { BadIssuerError } from "../certificate.js"
+import type { SshCertificate } from "../ssh/certificate.js"
+import { KeyParseError, type PublicKey } from "../ssh/keys.js"
+import { getPrivateKey, getPublic, UnsupportedKeyError } from "../utils.js"
+import { CertificateType } from "../db/types.js"
+import { KRLBuilder } from "../krl.js"
+import {
+	getKrlVersion,
+	getRevocationList,
+	recordCertificate,
+	RevocationStatus,
+	revocationStatus,
+	revokeCertificate,
+} from "../db/index.js"
+
+/**
+ * Maps an error from an operation that uses the CA key to an API error.
+ */
+const caKeyError = (l: Logger, err: unknown): ApiException => {
+	switch (true) {
+		case (err instanceof UnsupportedKeyError):
+			l.error(err.message)
+			return new InternalServerErrorException(err.message)
+		case (err instanceof KeyParseError):
+			l.error("error parsing private key")
+			return new InternalServerErrorException("error parsing private key")
+		case (err instanceof ApiException):
+			// re-throw any exisiting chanfana error
+			return err
+		default:
+			// otherwise throw as InternalServerErrorException
+			l.error("unhandled error", "error", err)
+			return new InternalServerErrorException("internal server error")
+	}
+}
+
+/**
+ * Returns the public key of the CA in OpenSSH format.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @returns The response containing the CA public key
+ */
+export const caPublicKey = async (c: AppContext, l: Logger): Promise<Response> => {
+	try {
+		const pub = await getPublic(c.env)
+
+		return c.text(`${pub.toString()}\n`)
+	} catch (err) {
+		throw caKeyError(l, err)
+	}
+}
+
+/**
+ * Returns the signed Key Revocation List for a type of certificate.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param certificateType The type of certificate to return the KRL for
+ * @returns The response containing the KRL and its signature
+ */
+export const revocationList = async (c: AppContext, l: Logger, certificateType: CertificateType): Promise<Response> => {
+	try {
+		// get revoked serials
+		const serials = (await getRevocationList(c.env, certificateType)).map(v => BigInt(v))
+
+		// grab private key from secret store
+		const key = await getPrivateKey(c.env)
+
+		// generate KRL
+		const krl = new KRLBuilder(key)
+			.addSerials(serials)
+
+		// the version only changes when the content of the KRL does
+		const version = await getKrlVersion(c.env, certificateType, await krl.digest())
+
+		const krlBytes = krl.generate(version)
+
+		// convert to base64
+		const bytes = new Uint8Array(krlBytes)
+		let binary = ""
+		for (const byte of bytes) {
+			binary += String.fromCharCode(byte)
+		}
+		const base64Krl = btoa(binary)
+
+		const signature = await krl.signature()
+
+		return c.json({
+			krl: base64Krl,
+			signature: signature,
+		})
+	} catch (err) {
+		throw caKeyError(l, err)
+	}
+}
+
+/**
+ * Signs a certificate, records it so it can later be revoked and returns it
+ * as the response to a certificate request or renewal.
+ *
+ * These are the steps shared by every API version once a request has been
+ * validated and authorised.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param sign Signs and returns the certificate
+ * @param certificateType The type of certificate being issued
+ * @returns The response containing the issued certificate
+ */
+export const issueCertificate = async (c: AppContext, l: Logger, sign: () => Promise<SshCertificate>, certificateType: CertificateType): Promise<Response> => {
+	try {
+		const certificate = await sign()
+		const response: CertificateSignerResponse = {
+			certificate: btoa(certificate.toString())
+		}
+
+		try {
+			await recordCertificate(c.env, certificate, certificate.keyId, certificateType)
+		} catch (err) {
+			// a certificate that is not recorded cannot be revoked, so do not issue it
+			l.error("there was a problem adding issued certificate to database", "error", err)
+			throw new InternalServerErrorException("there was a problem recording the issued certificate")
+		}
+
+		l.info("completed issuing certificate",
+			...group(
+				"certificate", "principals",
+				certificate.principals.join(","), "serial", certificate.serial,
+			),
+		)
+
+		return c.json(response)
+	} catch (err) {
+		switch (true) {
+			case (err instanceof UnsupportedKeyError):
+				l.error(err.message)
+				throw new InternalServerErrorException(err.message)
+			case (err instanceof ApiException):
+				// re-throw any exisiting chanfana error
+				throw err
+			case (err instanceof BadIssuerError):
+				throw new UnprocessableEntityException(err.message)
+			default:
+				// otherwise throw as InternalServerErrorException
+				l.error("unhandled error", "error", err)
+				throw new InternalServerErrorException("internal server error")
+		}
+	}
+}
+
+/**
+ * Revokes a certificate once the requester has proven possession of the
+ * private key for the public key it was issued for.
+ *
+ * @param c The request context
+ * @param l The logger for the request
+ * @param serial The serial of the certificate to revoke
+ * @param publicKey The public key the requester has proven possession of
+ * @param certificateType The type of certificate being revoked
+ * @returns The response containing the time of revocation
+ */
+export const revoke = async (c: AppContext, l: Logger, serial: bigint, publicKey: PublicKey, certificateType: CertificateType): Promise<Response> => {
+	// ensure certificate can be revoked
+	const status = await revocationStatus(c.env, serial, publicKey, certificateType)
+	switch (status) {
+		case RevocationStatus.Revoked:
+			l.warn("certificate is already revoked")
+			throw new ConflictException("certificate is already revoked")
+		case RevocationStatus.NotFound:
+			l.warn("certificate not found")
+			throw new NotFoundException("certificate not found")
+	}
+
+	try {
+		const res = await revokeCertificate(c.env, serial)
+
+		if (res.length === 0) {
+			throw new InternalServerErrorException("no results were returned for revocation")
+		}
+
+		if (res.length > 1) {
+			l.warn("more than one revocation result was returned", "count", res.length)
+		}
+
+		l.info("completed revocation")
+		return c.json({
+			revoked_at: res[0]!.revoked_at
+		})
+	} catch (err) {
+		switch (true) {
+			case (err instanceof ApiException):
+				// re-throw any exisiting chanfana error
+				throw err
+			default:
+				// otherwise throw as InternalServerErrorException
+				l.error("unhandled error", "error", err)
+				throw new InternalServerErrorException("internal server error")
+		}
+	}
+}

package/src/api/schema.ts

@@ -0,0 +1,137 @@
+import z from "zod"
+import type { SshCaBindings } from "../types.js"
+import {
+	transformAuthorizationHeader,
+	transformPublicKey,
+	transformIdentityToken,
+} from "../utils.js"
+import {
+	contentJson,
+	InternalServerErrorException,
+} from "chanfana"
+import { CertificateType } from "../db/types.js"
+
+/**
+ * Returns the name of a {@link CertificateType} as used in API paths and logs
+ * @param certificateType The type of certificate
+ * @returns "user" or "host"
+ */
+export const certificateTypeName = (certificateType: CertificateType): "user" | "host" => {
+	switch (certificateType) {
+		case CertificateType.User:
+			return "user"
+		case CertificateType.Host:
+			return "host"
+		default: {
+			const unknownType: never = certificateType
+			throw new Error(`unknown certificate type: ${String(unknownType)}`)
+		}
+	}
+}
+
+/**
+ * Returns the OpenAPI tag that groups the endpoints for a {@link CertificateType}
+ * @param certificateType The type of certificate
+ * @returns "User" or "Host"
+ */
+export const certificateTypeTag = (certificateType: CertificateType): "User" | "Host" => {
+	switch (certificateType) {
+		case CertificateType.User:
+			return "User"
+		case CertificateType.Host:
+			return "Host"
+		default: {
+			const unknownType: never = certificateType
+			throw new Error(`unknown certificate type: ${String(unknownType)}`)
+		}
+	}
+}
+
+export const openapiStringByte = z.base64()
+	.transform((v) => {
+		const a = z.util.base64ToUint8Array(v)
+		return Buffer.from(
+			a.buffer,
+			a.byteOffset,
+			a.length
+		)
+	})
+	.openapi({ format: "byte" })
+
+export const proofOfPossession = z.string()
+	.meta({
+		description: "Proof of possession comprising of ${timestamp}.${fingerprint}.${signature}",
+		example: "1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.LS0tLS1CRUdJTiBTU0ggU0lHTkFUVVJFLS0tLS0KVTFOSVUwbEhBQUFBQVFBQUFHZ0FBQUFUWldOa2MyRXRjMmhoTWkxdWFYTjBjREkxTmdBQUFBaHVhWE4wY0RJMQpOZ0FBQUVFRUR6Ymk4OE10alBYSDFCb1JURU9HaS96aEc4QnhQNVZUUW5OQkFNMGZtMExtekErUUZkUlNVYVRFCkdNN2l0QjhINmZNZFAydlAxcElQcGUyOWVLQkJZd0FBQUFSbWFXeGxBQUFBQUFBQUFBWnphR0UxTVRJQUFBQmsKQUFBQUUyVmpaSE5oTFhOb1lUSXRibWx6ZEhBeU5UWUFBQUJKQUFBQUlHdmZVZGNDQkRXa3ZwL0ZHS3NkakgrRQpKZzZXN0EvWUJVZng2Z0srQ01raEFBQUFJUUQxOFd5cDNZejZ0eXNvdllXbEJHTXprRnlYbFRrSHM5blVVRXJqCkczNWVPQT09Ci0tLS0tRU5EIFNTSCBTSUdOQVRVUkUtLS0tLQo="
+	})
+
+export const publicKey = openapiStringByte
+	.transform(transformPublicKey)
+	.meta({
+		description: "SSH public key to sign",
+		example: "ZWNkc2Etc2hhMi1uaXN0cDI1NiBBQUFBRTJWalpITmhMWE5vWVRJdGJtbHpkSEF5TlRZQUFBQUlibWx6ZEhBeU5UWUFBQUJCQkdNcFNKdHRmMEl0dE5DVmMyOFR6WEZSMUQweHZPM25wNjdWemVBUXNiZFpza3JEY1lqU2x3SjZIUERtVHBYYVUwbEVhWDlMNFloYy9jQ2YxTWU5RlRrPQo="
+	})
+
+export const createIdentityTokenSchema = (env: SshCaBindings) => (
+	z.string()
+		.meta({
+			description: "Identity Token JWT from OIDC IdP",
+			example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZW1haWwiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaWF0IjoxNzc1NzAzMDk1fQ.ri_neAWnhMNK3LzlsrBcQYymSM4yRjmNSZZSeZiXhrEqtEz6c3cXk0Esq765umGjpUsWcosL-OFrDJlyAjTDnhrd9oV08uc_CW0rQRsJIGEuRo3ryxkLdVu9mGoZWEUb9KwjGJrwxvr-0cPWx5jaDyKwJcqMvtV_bEITUD51sDB1Vm89QfYRO_pGJo2vrRzSvMjpUenRpwPay4lYIBxl41_4YpR9Rc6VrIZuYsjV2iqEZ4eBrygMA7zPR_hN7l7s95FddLOzj5NsK57VT4uLHwYohx2oqMzw3M-B9HsZIQin_9q61pZFQXepzJth0woXiZheU27llnfHX967PhNQyg"
+		})
+		.transform((val, ctx) => transformIdentityToken(env, val, ctx))
+)
+
+export const createAccessTokenSchema = (env: SshCaBindings) => (
+	z.string()
+		.meta({
+			description: "Access Token JWT from OIDC IdP",
+			example: "Bearer eyJ..."
+		})
+		.transform((val, ctx) => transformAuthorizationHeader(env, val, ctx))
+)
+
+export const krl = openapiStringByte
+	.meta({ description: "Key Revocation List" })
+
+export const createHeaderSchema = (env: SshCaBindings) => (
+	z.object({
+		"Authorization": createAccessTokenSchema(env)
+	})
+)
+
+export const certificate = openapiStringByte
+	.meta({ description: "Issued Certificate" })
+
+export const CaPublicKeyEndpointSchema = {
+	tags: ["CA"],
+	summary: "Get the CA public key",
+	description: "Returns the public key of the SSH Certificate Authority in OpenSSH format, for use in `TrustedUserCAKeys` on SSH servers or `@cert-authority` entries in `known_hosts` on SSH clients.",
+	responses: {
+		"200": {
+			content: {
+				"text/plain": {
+					schema: z.string()
+				}
+			},
+			description: "Returns SSH Certificate Authority Public Key",
+		},
+		...InternalServerErrorException.schema(),
+	}
+}
+
+export const createRevocationListEndpointSchema = (certificateType: CertificateType) => ({
+	tags: [certificateTypeTag(certificateType)],
+	summary: `Get the Key Revocation List for ${certificateTypeName(certificateType)} certificates`,
+	description: `Returns the OpenSSH Key Revocation List (KRL) of revoked ${certificateTypeName(certificateType)} certificates issued by this CA, along with an SSHSIG signature made by the CA key so the KRL can be verified before use.`,
+	responses: {
+		"200": {
+			description: `Returns an Open SSH Key Revocation List of revoked ${certificateTypeName(certificateType)} certificates as BASE64 and an SSHSIG signature for verification`,
+			...contentJson(z.object({
+				krl: krl,
+				signature: z.string()
+			})
+				.openapi("Key Revocation List Response")
+			)
+		},
+		...InternalServerErrorException.schema(),
+	}
+})