@andrewheberle/serverless-ssh-ca 0.22.0 → 0.23.0

package/src/api/v3/index.ts

@@ -1,43 +1,21 @@
 import { group } from "@andrewheberle/ts-slog"
 import {
-	ApiException,
-	ConflictException,
 	ForbiddenException,
 	fromHono,
-	InternalServerErrorException,
-	NotFoundException,
 	OpenAPIRoute,
 	UnauthorizedException,
-	UnprocessableEntityException,
 } from "chanfana"
 import { Hono } from "hono"
 import { AppContext } from "../../router.js"
-import { CertificateSignerResponse } from "../../types.js"
 import {
-	BadIssuerError,
 	CreateCertificateOptions,
 	CreateHostCertificateOptions,
 	createSignedCertificate,
 	createSignedHostCertificate,
-
 } from "../../certificate.js"
-import {
-	getPrivateKey,
-	getPublic,
-	split,
-	UnsupportedKeyError,
-} from "../../utils.js"
-import sshpk from "sshpk"
+import { split } from "../../utils.js"
 import { CertificateType } from "../../db/types.js"
-import {
-	getKrlVersion,
-	getRevocationList,
-	recordCertificate,
-	RevocationStatus,
-	revocationStatus,
-	revokeCertificate,
-} from "../../db/index.js"
-import { KRLBuilder } from "../../krl.js"
+import { caPublicKey, issueCertificate, revocationList, revoke } from "../operations.js"
 import {
 	CaPublicKeyEndpointSchema,
 	createUserCertificateRequestEndpointSchema,
@@ -50,9 +28,6 @@ import {
 import { logger } from "../../logger.js"
 import type { SshCaBindings } from "../../types.js"
 
-// sshpk is CommonJS and Node's ESM loader cannot detect most of its named exports, so values are taken from the default import
-const { KeyParseError } = sshpk
-
 const CaPublicKeyEndpoint = (env: SshCaBindings) => {
 	return class extends OpenAPIRoute {
 		override schema = CaPublicKeyEndpointSchema
@@ -61,27 +36,7 @@ const CaPublicKeyEndpoint = (env: SshCaBindings) => {
 			const l = logger(env).with(
 				...group("request", "action", "ca"),
 			)
-			try {
-				const pub = await getPublic(c.env)
-
-				return c.text(`${pub.toString("ssh").trim()}\n`)
-			} catch (err) {
-				switch (true) {
-					case (err instanceof UnsupportedKeyError):
-						l.error(err.message)
-						throw new InternalServerErrorException(err.message)
-					case (err instanceof KeyParseError):
-						l.error("error parsing private key")
-						throw new InternalServerErrorException("error parsing private key")
-					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")
-				}
-			}
+			return await caPublicKey(c, l)
 		}
 	}
 }
@@ -118,42 +73,10 @@ const UserCertificateRequestEndpoint = (env: SshCaBindings) => {
 				extensions: data.body.extensions,
 			}
 
-			try {
-				const certificate = await createSignedCertificate(c.env, data.headers.Authorization.email, data.body.public_key, opts)
-				const response: CertificateSignerResponse = {
-					certificate: btoa(certificate.toString("openssh"))
-				}
-
-				try {
-					await recordCertificate(c.env, certificate, data.headers.Authorization.email)
-				} 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.subjects.map(v => v.toString()).join(","), "serial", certificate.serial.readBigUInt64BE(0),
-					),
-				)
-
-				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
-					default:
-						// otherwise throw as InternalServerErrorException
-						l.error("unhandled error", "error", err)
-						throw new InternalServerErrorException("internal server error")
-				}
-			}
+			return await issueCertificate(c, l,
+				() => createSignedCertificate(c.env, data.headers.Authorization.email, data.body.public_key, opts),
+				CertificateType.User,
+			)
 		}
 	}
 }
@@ -170,53 +93,7 @@ const RevocationListEndpoint = (env: SshCaBindings, certificateType: Certificate
 				),
 			)
 
-			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) {
-				switch (true) {
-					case (err instanceof UnsupportedKeyError):
-						l.error(err.message)
-						throw new InternalServerErrorException(err.message)
-					case (err instanceof KeyParseError):
-						l.error("error parsing private key")
-						throw new InternalServerErrorException("error parsing private key")
-					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")
-				}
-			}
+			return await revocationList(c, l, certificateType)
 		}
 	}
 }
@@ -259,42 +136,10 @@ const HostCertificateRequestEndpoint = (env: SshCaBindings) => {
 				principals: data.body.principals,
 			}
 
-			try {
-				const certificate = await createSignedHostCertificate(c.env, data.body.public_key, opts)
-				const response: CertificateSignerResponse = {
-					certificate: btoa(certificate.toString("openssh"))
-				}
-
-				try {
-					await recordCertificate(c.env, certificate, `host_${certificate.subjects[0]!.hostname}`, CertificateType.Host)
-				} 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.subjects.map(v => v.toString()).join(","), "serial", certificate.serial.readBigUInt64BE(0),
-					),
-				)
-
-				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
-					default:
-						// otherwise throw as InternalServerErrorException
-						l.error("unhandled error", "error", err)
-						throw new InternalServerErrorException("internal server error")
-				}
-			}
+			return await issueCertificate(c, l,
+				() => createSignedHostCertificate(c.env, data.body.public_key, opts),
+				CertificateType.Host,
+			)
 		}
 	}
 }
@@ -305,7 +150,7 @@ const HostCertificateRenewEndpoint = (env: SshCaBindings) => {
 
 		override async handle(c: AppContext) {
 			const data = await this.getValidatedData<typeof this.schema>()
-			const serial = data.body.certificate.serial.readBigUInt64BE(0)
+			const serial = data.body.certificate.serial
 
 			const l = logger(env).with(
 				...group("request",
@@ -316,54 +161,20 @@ const HostCertificateRenewEndpoint = (env: SshCaBindings) => {
 			)
 
 			// use smaller of the current certificate lifetime and the requested lifetime
-			const originalLifetime = (data.body.certificate.validUntil.getTime() - data.body.certificate.validFrom.getTime()) / 1000
+			const originalLifetime = (data.body.certificate.validBefore.getTime() - data.body.certificate.validAfter.getTime()) / 1000
 			const lifetime = originalLifetime > data.body.lifetime
 				? data.body.lifetime
 				: originalLifetime
 
 			const opts: CreateHostCertificateOptions = {
 				lifetime: lifetime,
-				subjects: data.body.certificate.subjects
+				principals: data.body.certificate.principals,
 			}
 
-			try {
-				const certificate = await createSignedHostCertificate(c.env, data.body.public_key, opts)
-				const response: CertificateSignerResponse = {
-					certificate: btoa(certificate.toString("openssh"))
-				}
-
-				try {
-					await recordCertificate(c.env, certificate, `host_${certificate.subjects[0]!.hostname}`, CertificateType.Host)
-				} 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.subjects.map(v => v.toString()).join(","), "serial", certificate.serial.readBigUInt64BE(0),
-					),
-				)
-
-				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")
-				}
-			}
+			return await issueCertificate(c, l,
+				() => createSignedHostCertificate(c.env, data.body.public_key, opts),
+				CertificateType.Host,
+			)
 		}
 	}
 }
@@ -379,46 +190,7 @@ const RevokeCertificateEndpoint = (env: SshCaBindings, certificateType: Certific
 				...group("request", "type", certificateTypeName(certificateType), "action", "revoke", "serial", data.body.serial),
 			)
 
-			// ensure certificate can be revoked
-			const status = await revocationStatus(c.env, data.body.serial, data.body.public_key.toString("ssh"), certificateType)
-			switch (status) {
-				case RevocationStatus.Revoked:
-					l.warn("certificate is already revoked")
-					throw new ConflictException("certificate is already revoked")
-				case RevocationStatus.Unrevokable:
-					l.warn("cannot revoke this certificate")
-					throw new ForbiddenException("cannot revoke this certificate")
-				case RevocationStatus.NotFound:
-					l.warn("certificate not found")
-					throw new NotFoundException("certificate not found")
-			}
-
-			try {
-				const res = await revokeCertificate(c.env, data.body.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")
-				}
-			}
+			return await revoke(c, l, data.body.serial, data.body.public_key, certificateType)
 		}
 	}
 }

package/src/api/v3/schema.ts

@@ -3,15 +3,12 @@ import type { SshCaBindings } from "../../types.js"
 import {
 	split,
 	refineCertificateRequest,
-	transformAuthorizationHeader,
 	transformProofOfPossession,
-	transformPublicKey,
 	transformRenewalProofOfPossession,
 	refineHostCertificateRequest,
 	transformCertificate,
 	refineHostCertificateRenewal,
 	refineRevokeCertificate,
-	transformIdentityToken,
 } from "../../utils.js"
 import {
 	ConflictException,
@@ -25,111 +22,25 @@ import {
 import { seconds } from "itty-time"
 import { isRevoked } from "../../db/index.js"
 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"
- */
-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)}`)
-		}
-	}
-}
-
-const openapiStringByte = z.base64()
-	.transform((v) => {
-		const a = z.util.base64ToUint8Array(v)
-		return Buffer.from(
-			a.buffer,
-			a.byteOffset,
-			a.length
-		)
-	})
-	.openapi({ format: "byte" })
-
-const proofOfPossession = z.string()
-	.meta({
-		description: "Proof of possession comprising of ${timestamp}.${fingerprint}.${signature}",
-		example: "1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.LS0tLS1CRUdJTiBTU0ggU0lHTkFUVVJFLS0tLS0KVTFOSVUwbEhBQUFBQVFBQUFHZ0FBQUFUWldOa2MyRXRjMmhoTWkxdWFYTjBjREkxTmdBQUFBaHVhWE4wY0RJMQpOZ0FBQUVFRUR6Ymk4OE10alBYSDFCb1JURU9HaS96aEc4QnhQNVZUUW5OQkFNMGZtMExtekErUUZkUlNVYVRFCkdNN2l0QjhINmZNZFAydlAxcElQcGUyOWVLQkJZd0FBQUFSbWFXeGxBQUFBQUFBQUFBWnphR0UxTVRJQUFBQmsKQUFBQUUyVmpaSE5oTFhOb1lUSXRibWx6ZEhBeU5UWUFBQUJKQUFBQUlHdmZVZGNDQkRXa3ZwL0ZHS3NkakgrRQpKZzZXN0EvWUJVZng2Z0srQ01raEFBQUFJUUQxOFd5cDNZejZ0eXNvdllXbEJHTXprRnlYbFRrSHM5blVVRXJqCkczNWVPQT09Ci0tLS0tRU5EIFNTSCBTSUdOQVRVUkUtLS0tLQo="
-	})
-
-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))
-)
-
-const krl = openapiStringByte
-	.meta({ description: "Key Revocation List" })
-
-export const createHeaderSchema = (env: SshCaBindings) => (
-	z.object({
-		"Authorization": createAccessTokenSchema(env)
-	})
-)
-
-const certificate = openapiStringByte
-	.meta({ description: "Issued Certificate" })
-
-export const CaPublicKeyEndpointSchema = {
-	tags: ["CA"],
-	responses: {
-		"200": {
-			content: {
-				"text/plain": {
-					schema: z.string()
-				}
-			},
-			description: "Returns SSH Certificate Authority Public Key",
-		},
-		...InternalServerErrorException.schema(),
-	}
-}
+import {
+	certificate,
+	certificateTypeName,
+	certificateTypeTag,
+	createHeaderSchema,
+	createIdentityTokenSchema,
+	openapiStringByte,
+	proofOfPossession,
+	publicKey,
+} from "../schema.js"
+
+export {
+	CaPublicKeyEndpointSchema,
+	certificateTypeName,
+	createAccessTokenSchema,
+	createHeaderSchema,
+	createIdentityTokenSchema,
+	createRevocationListEndpointSchema,
+} from "../schema.js"
 
 export const userCertificateRequestEndpointBodySchema = (env: SshCaBindings) => (
 	z.object({
@@ -152,6 +63,8 @@ export const userCertificateRequestEndpointBodySchema = (env: SshCaBindings) =>
 
 export const createUserCertificateRequestEndpointSchema = (env: SshCaBindings) => ({
 	tags: [certificateTypeTag(CertificateType.User)],
+	summary: "Request a user certificate",
+	description: "Issues a signed SSH user certificate for the provided public key. The request must be authenticated with an access token and include an identity token from the OIDC IdP for the same subject, along with a proof of possession of the private key. Principals on the issued certificate are derived from the identity token.",
 	security: [{ oidcAuth: [] }],
 	request: {
 		headers: createHeaderSchema(env),
@@ -174,23 +87,6 @@ export const createUserCertificateRequestEndpointSchema = (env: SshCaBindings) =
 	}
 })
 
-export const createRevocationListEndpointSchema = (certificateType: CertificateType) => ({
-	tags: [certificateTypeTag(certificateType)],
-	summary: `Get the Key Revocation List for ${certificateTypeName(certificateType)} certificates`,
-	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(),
-	}
-})
-
 export const hostCertificateRequestEndpointBodySchema = (env: SshCaBindings) => (
 	z.object({
 				public_key: publicKey,
@@ -211,6 +107,8 @@ export const hostCertificateRequestEndpointBodySchema = (env: SshCaBindings) =>
 
 export const createHostCertificateRequestEndpointSchema = (env: SshCaBindings) => ({
 	tags: [certificateTypeTag(CertificateType.Host)],
+	summary: "Request a host certificate",
+	description: "Issues a signed SSH host certificate for the provided public key and principals. The request must be authenticated with an access token and include an identity token from the OIDC IdP for the same subject, along with a proof of possession of the private key. The user must be permitted to request host certificates by email address or role.",
 	security: [{ oidcAuth: [] }],
 	request: {
 		headers: createHeaderSchema(env),
@@ -253,6 +151,8 @@ export const hostCertificateRenewEndpointBodySchema = (env: SshCaBindings) => (
 
 export const createHostCertificateRenewEndpointSchema = (env: SshCaBindings) => ({
 	tags: [certificateTypeTag(CertificateType.Host)],
+	summary: "Renew a host certificate",
+	description: "Issues a new SSH host certificate with the same principals as an existing, unexpired and unrevoked host certificate issued by this CA. No OIDC authentication is required; instead the public key must match the existing certificate and the proof of possession must be made with its private key. The lifetime of the renewed certificate is no longer than that of the existing certificate.",
 	request: {
 		body: contentJson(hostCertificateRenewEndpointBodySchema(env))
 	},
@@ -293,6 +193,7 @@ export const revokeCertificateEndpointBodySchema = (env: SshCaBindings) => (
 export const createRevokeCertificateEndpointSchema = (env: SshCaBindings, certificateType: CertificateType) => ({
 	tags: [certificateTypeTag(certificateType)],
 	summary: `Revoke a ${certificateTypeName(certificateType)} certificate`,
+	description: `Revokes a ${certificateTypeName(certificateType)} certificate issued by this CA, identified by its serial number, and adds it to the ${certificateTypeName(certificateType)} Key Revocation List. The request must include a proof of possession of the private key for the public key that the certificate was issued for.`,
 	request: {
 		body: contentJson(revokeCertificateEndpointBodySchema(env))
 	},