@andrewheberle/serverless-ssh-ca 0.21.0 → 0.22.0

package/src/api/v3/schema.ts

@@ -24,6 +24,43 @@ import {
 } from "chanfana"
 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) => {
@@ -80,6 +117,7 @@ const certificate = openapiStringByte
 	.meta({ description: "Issued Certificate" })
 
 export const CaPublicKeyEndpointSchema = {
+	tags: ["CA"],
 	responses: {
 		"200": {
 			content: {
@@ -113,6 +151,7 @@ export const userCertificateRequestEndpointBodySchema = (env: SshCaBindings) =>
 )
 
 export const createUserCertificateRequestEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.User)],
 	security: [{ oidcAuth: [] }],
 	request: {
 		headers: createHeaderSchema(env),
@@ -135,15 +174,12 @@ export const createUserCertificateRequestEndpointSchema = (env: SshCaBindings) =
 	}
 })
 
-export const createRevocationListEndpointSchema = () => ({
-	request: {
-		params: z.object({
-			certificateType: z.enum(["user", "host"])
-		}),
-	},
+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 as BASE64 and an SSHSIG signature for verification",
+			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()
@@ -174,6 +210,7 @@ export const hostCertificateRequestEndpointBodySchema = (env: SshCaBindings) =>
 )
 
 export const createHostCertificateRequestEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.Host)],
 	security: [{ oidcAuth: [] }],
 	request: {
 		headers: createHeaderSchema(env),
@@ -215,6 +252,7 @@ export const hostCertificateRenewEndpointBodySchema = (env: SshCaBindings) => (
 )
 
 export const createHostCertificateRenewEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.Host)],
 	request: {
 		body: contentJson(hostCertificateRenewEndpointBodySchema(env))
 	},
@@ -252,16 +290,15 @@ export const revokeCertificateEndpointBodySchema = (env: SshCaBindings) => (
 			.superRefine((val, ctx) => refineRevokeCertificate(env, val, ctx))
 )
 
-export const createRevokeCertificateEndpointSchema = (env: SshCaBindings) => ({
+export const createRevokeCertificateEndpointSchema = (env: SshCaBindings, certificateType: CertificateType) => ({
+	tags: [certificateTypeTag(certificateType)],
+	summary: `Revoke a ${certificateTypeName(certificateType)} certificate`,
 	request: {
-		params: z.object({
-			certificateType: z.enum(["user", "host"])
-		}),
 		body: contentJson(revokeCertificateEndpointBodySchema(env))
 	},
 	responses: {
 		"200": {
-			description: "SSH certificate revoked successfully",
+			description: `SSH ${certificateTypeName(certificateType)} certificate revoked successfully`,
 			...contentJson(z.object({
 				revoked_at: z.iso.datetime(),
 			})

package/src/db/index.ts

@@ -2,30 +2,10 @@ import type { Certificate, Format, Identity } from "sshpk"
 import { logger } from "../logger.js"
 import type { SshCaBindings } from "../types.js"
 import { D1QB } from "workers-qb"
+import { z } from "zod"
 import { migrateOnce } from "./migrate.js"
 import { migrations } from "./migrations/index.js"
-
-export enum CertificateType {
-	User,
-	Host
-}
-
-export type CertificateRecord = {
-	id: number
-	serial: string
-	key_id: string
-	principals: string
-	extensions: string | null
-	valid_after: Date
-	valid_before: Date
-	revoked_at: Date | null
-	certificate_type: CertificateType
-	public_key: string | null
-}
-
-export type DatabaseSchema = {
-	certificates: CertificateRecord
-}
+import { CertificateType, type CertificateRecord, type DatabaseSchema, type KrlRecord } from "./types.js"
 
 const connect = async (env: SshCaBindings): Promise<D1QB<DatabaseSchema>> => {
 	const l = logger(env)
@@ -146,7 +126,9 @@ export const revocationStatus = async (env: SshCaBindings, serial: bigint, publi
 
 export const getRevocationList = async (env: SshCaBindings, certificateType: CertificateType): Promise<string[]> => {
 	const qb = await connect(env)
-	const res = await qb.fetchAll({
+	// fetchAll cannot infer the table from its parameters, so it is given explicitly
+	// as otherwise the result is untyped once the schema has more than one table
+	const res = await qb.fetchAll<"certificates", "serial">({
 		tableName: "certificates",
 		fields: ["serial"],
 		where: {
@@ -192,3 +174,70 @@ export const revokeCertificate = async (env: SshCaBindings, serial: bigint): Pro
 
 	return res.results
 }
+
+const KrlVersionRow = z.object({
+	version: z.number().int().nonnegative(),
+	digest: z.string().nullable(),
+})
+
+// the number of times to retry when another request updates the KRL version concurrently
+const KRL_VERSION_ATTEMPTS = 5
+
+/**
+ * Get the version of the KRL for a certificate type, incrementing it if the
+ * content of the KRL has changed since the version was last returned.
+ *
+ * The version is only ever incremented, so clients can use it to detect a
+ * newer KRL. When several requests see the same change concurrently the
+ * version is incremented once.
+ *
+ * @param env The bindings for the CA, see {@link SshCaBindings}
+ * @param certificateType The type of certificates in the KRL, see {@link CertificateType}
+ * @param digest A digest of the content of the KRL, which changes whenever the content does
+ * @returns The version to use for the KRL
+ */
+export const getKrlVersion = async (env: SshCaBindings, certificateType: CertificateType, digest: string): Promise<bigint> => {
+	const qb = await connect(env)
+
+	for (let attempt = 0; attempt < KRL_VERSION_ATTEMPTS; attempt++) {
+		const res = await qb.fetchOne({
+			tableName: "krl",
+			fields: ["version", "digest"],
+			where: {
+				conditions: "certificate_type = ?",
+				params: certificateType
+			}
+		}).execute()
+
+		const current = KrlVersionRow.parse(res.results)
+		if (current.digest === digest) {
+			return BigInt(current.version)
+		}
+
+		// only update if the version has not been changed by another request
+		const next = current.version + 1
+		const updated = await qb.update<Pick<KrlRecord, "version">>({
+			tableName: "krl",
+			data: {
+				version: next,
+				digest: digest,
+				updated_at: (new Date).toISOString()
+			},
+			where: {
+				conditions: "certificate_type = ? AND version = ?",
+				params: [certificateType, current.version]
+			},
+			returning: ["version"]
+		}).execute()
+
+		if (!updated.success) {
+			throw new Error("error during query")
+		}
+
+		if (updated.results !== undefined && updated.results.length > 0) {
+			return BigInt(next)
+		}
+	}
+
+	throw new Error("unable to update KRL version due to concurrent updates")
+}

package/src/db/migrations/0002_krl_version.ts

@@ -0,0 +1,16 @@
+import type { Migration } from "../migrate.js"
+
+export const migration: Migration = {
+	name: "0002_krl_version",
+	statements: [
+		`CREATE TABLE IF NOT EXISTS krl (
+			certificate_type INTEGER PRIMARY KEY,
+			version INTEGER NOT NULL,
+			digest TEXT,
+			updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
+		)`,
+		// KRLs were previously always version 1 and have no digest, so the
+		// first KRL generated after this migration is version 2
+		"INSERT OR IGNORE INTO krl (certificate_type, version, digest) VALUES (0, 1, NULL), (1, 1, NULL)",
+	]
+}

package/src/db/migrations/index.ts

@@ -1,6 +1,8 @@
 import type { Migration } from "../migrate.js"
 import { migration as initialSchema0001 } from "./0001_initial_schema.js"
+import { migration as krlVersion0002 } from "./0002_krl_version.js"
 
 export const migrations: Migration[] = [
-	initialSchema0001
+	initialSchema0001,
+	krlVersion0002,
 ]

package/src/db/types.ts

@@ -0,0 +1,40 @@
+/**
+ * Database types used by workers-qb to type queries.
+ *
+ * These must match the schema created by the migrations in `./migrations`, so
+ * update them with any change to the database.
+ */
+
+/** The type of certificate, as stored in the `certificate_type` column */
+export enum CertificateType {
+	User,
+	Host
+}
+
+/** A row in the `certificates` table */
+export type CertificateRecord = {
+	id: number
+	serial: string
+	key_id: string
+	principals: string
+	extensions: string | null
+	valid_after: Date
+	valid_before: Date
+	revoked_at: Date | null
+	certificate_type: CertificateType
+	public_key: string | null
+}
+
+/** A row in the `krl` table, holding the current version of the KRL for a {@link CertificateType} */
+export type KrlRecord = {
+	certificate_type: CertificateType
+	version: number
+	digest: string | null
+	updated_at: Date
+}
+
+/** The tables in the database, used to type queries made with workers-qb */
+export type DatabaseSchema = {
+	certificates: CertificateRecord
+	krl: KrlRecord
+}

package/src/krl.ts

@@ -298,6 +298,29 @@ export class KRLBuilder {
         return this
     }
 
+    /**
+     * Return a hex encoded SHA-256 digest of the content of the KRL.
+     *
+     * The digest covers the CA public key and the revoked serials and key IDs,
+     * but not the order they were added in or the header, so it only changes
+     * when the set of revoked certificates or the CA does.
+     */
+    async digest(): Promise<string> {
+        const serials = [...this._serials].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        const keyIds = [...this._keyIds].sort()
+
+        const content = concat(
+            encodeString(caKeyWireBytes(this._caKey)),
+            encodeUint32(serials.length),
+            ...serials.map(encodeUint64),
+            encodeUint32(keyIds.length),
+            ...keyIds.map((id) => encodeString(id)),
+        )
+
+        const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", content))
+        return Array.from(hash, (b) => b.toString(16).padStart(2, "0")).join("")
+    }
+
     /**
      * Generate the binary KRL
      *