@andrewheberle/serverless-ssh-ca 0.22.0 → 0.24.0

package/src/api/v4/index.ts

@@ -0,0 +1,266 @@
+import { group, Logger } from "@andrewheberle/ts-slog"
+import {
+	ForbiddenException,
+	fromHono,
+	InputValidationException,
+	OpenAPIRoute,
+	UnauthorizedException,
+} from "chanfana"
+import { Hono } from "hono"
+import type { PublicKey } from "../../ssh/keys.js"
+import { AppContext } from "../../router.js"
+import {
+	CreateCertificateOptions,
+	CreateHostCertificateOptions,
+	createSignedCertificate,
+	createSignedHostCertificate,
+} from "../../certificate.js"
+import { split } from "../../utils.js"
+import { CertificateType } from "../../db/types.js"
+import type { ProofOfPossession } from "../../proof.js"
+import { caPublicKey, issueCertificate, revocationList, revoke } from "../operations.js"
+import { certificateTypeName } from "../schema.js"
+import {
+	createCaPublicKeyEndpointSchema,
+	createGetRevocationListEndpointSchema,
+	createIssueHostCertificateEndpointSchema,
+	createIssueUserCertificateEndpointSchema,
+	createRenewHostCertificateEndpointSchema,
+	createRevokeCertificateEndpointSchema,
+	ProofHeader,
+} from "./schema.js"
+import { logger } from "../../logger.js"
+import type { SshCaBindings } from "../../types.js"
+
+/**
+ * The path the v4 API is served under, which is part of the request a proof
+ * of possession is made for
+ */
+export const BasePath = "/api/v4"
+
+/**
+ * Ensures a proof of possession was made with the private key for a public key
+ * and for this request, so it cannot be replayed against another endpoint or
+ * for another certificate.
+ *
+ * @param l The logger for the request
+ * @param proof The proof of possession from the request
+ * @param key The public key the proof must be made with
+ * @param method The HTTP method of the request
+ * @param path The path of the request below {@link BasePath}, with any parameters filled in
+ * @throws {@link InputValidationException} when the proof is not valid for the key and request
+ */
+const verifyProof = async (l: Logger, proof: ProofOfPossession, key: PublicKey, method: string, path: string): Promise<void> => {
+	if (!proof.matches(key)) {
+		l.warn("proof of possession fingerprint did not match public key")
+		throw new InputValidationException("proof of possession fingerprint did not match public key", ["headers", ProofHeader])
+	}
+
+	if (!await proof.verifyRequest(method, `${BasePath}${path}`)) {
+		l.warn("proof of possession signature validation failed")
+		throw new InputValidationException("proof of possession signature validation failed", ["headers", ProofHeader])
+	}
+}
+
+const CaPublicKeyEndpoint = (env: SshCaBindings) => {
+	return class extends OpenAPIRoute {
+		override schema = createCaPublicKeyEndpointSchema()
+
+		override async handle(c: AppContext) {
+			const l = logger(env).with(
+				...group("request", "action", "ca"),
+			)
+
+			return await caPublicKey(c, l)
+		}
+	}
+}
+
+const IssueUserCertificateEndpoint = (env: SshCaBindings) => {
+	return class extends OpenAPIRoute {
+		override schema = createIssueUserCertificateEndpointSchema(env)
+
+		override async handle(c: AppContext) {
+			const data = await this.getValidatedData<typeof this.schema>()
+
+			const l = logger(env).with(
+				...group("request",
+					"type", "user",
+					"action", "request",
+				),
+				...group("auth_token",
+					"email", data.headers.Authorization.email,
+					"sub", data.headers.Authorization.sub,
+				),
+				...group("id_token",
+					"sub", data.body.identity.sub,
+				),
+			)
+
+			await verifyProof(l, data.headers[ProofHeader], data.body.public_key, "POST", "/user/certificates")
+
+			if (data.body.identity.sub !== data.headers.Authorization.sub) {
+				l.error("token subjects did not match")
+				throw new ForbiddenException("Possible token substitution as subjects for authentication and identity tokens did not match")
+			}
+
+			const opts: CreateCertificateOptions = {
+				lifetime: data.body.lifetime,
+				principals: data.body.identity.principals,
+				extensions: data.body.extensions,
+			}
+
+			return await issueCertificate(c, l,
+				() => createSignedCertificate(c.env, data.headers.Authorization.email, data.body.public_key, opts),
+				CertificateType.User,
+			)
+		}
+	}
+}
+
+const RevocationListEndpoint = (env: SshCaBindings, certificateType: CertificateType) => {
+	return class extends OpenAPIRoute {
+		override schema = createGetRevocationListEndpointSchema(certificateType)
+
+		override async handle(c: AppContext) {
+			const l = logger(env).with(
+				...group("request",
+					"type", certificateTypeName(certificateType),
+					"action", "krl",
+				),
+			)
+
+			return await revocationList(c, l, certificateType)
+		}
+	}
+}
+
+const IssueHostCertificateEndpoint = (env: SshCaBindings) => {
+	return class extends OpenAPIRoute {
+		override schema = createIssueHostCertificateEndpointSchema(env)
+
+		override async handle(c: AppContext) {
+			const data = await this.getValidatedData<typeof this.schema>()
+
+			const l = logger(env).with(
+				...group("request",
+					"type", "host",
+					"action", "request",
+				),
+				...group("auth_token",
+					"email", data.headers.Authorization.email,
+					"sub", data.headers.Authorization.sub,
+				),
+				...group("id_token",
+					"sub", data.body.identity.sub,
+				),
+			)
+
+			await verifyProof(l, data.headers[ProofHeader], data.body.public_key, "POST", "/host/certificates")
+
+			// check id and access token are for the same user
+			if (data.body.identity.sub !== data.headers.Authorization.sub) {
+				l.error("token subjects did not match")
+				throw new ForbiddenException("possible token substitution as subjects for authentication and identity tokens did not match")
+			}
+
+			// check user can issue host certificates
+			if (!split(c.env.SSH_HOST_CERTIFICATE_ALLOWED_EMAILS).includes(data.headers.Authorization.email) && !data.body.identity.principals.some((p: string) => split(c.env.SSH_HOST_CERTIFICATE_ALLOWED_ROLES).includes(p))) {
+				l.error("unauthorized host certificate request")
+				throw new UnauthorizedException("User not allowed to issue host certificates")
+			}
+
+			const opts: CreateHostCertificateOptions = {
+				lifetime: data.body.lifetime,
+				principals: data.body.principals,
+			}
+
+			return await issueCertificate(c, l,
+				() => createSignedHostCertificate(c.env, data.body.public_key, opts),
+				CertificateType.Host,
+			)
+		}
+	}
+}
+
+const RenewHostCertificateEndpoint = (env: SshCaBindings) => {
+	return class extends OpenAPIRoute {
+		override schema = createRenewHostCertificateEndpointSchema(env)
+
+		override async handle(c: AppContext) {
+			const data = await this.getValidatedData<typeof this.schema>()
+			const serial = data.params.serial
+
+			const l = logger(env).with(
+				...group("request",
+					"type", "host",
+					"action", "renewal",
+					"serial", serial,
+				),
+			)
+
+			// the serial in the path is what the proof was made for, so it
+			// must be the certificate being renewed
+			if (data.body.certificate.serial !== serial) {
+				l.warn("certificate serial did not match the serial in the path")
+				throw new InputValidationException("certificate serial did not match the serial in the path", ["body", "certificate"])
+			}
+
+			await verifyProof(l, data.headers[ProofHeader], data.body.certificate.publicKey, "POST", `/host/certificates/${serial}/renew`)
+
+			// use smaller of the current certificate lifetime and the requested lifetime
+			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,
+				principals: data.body.certificate.principals,
+			}
+
+			return await issueCertificate(c, l,
+				() => createSignedHostCertificate(c.env, data.body.certificate.publicKey, opts),
+				CertificateType.Host,
+				data.body.certificate,
+			)
+		}
+	}
+}
+
+const RevokeCertificateEndpoint = (env: SshCaBindings, certificateType: CertificateType) => {
+	return class extends OpenAPIRoute {
+		override schema = createRevokeCertificateEndpointSchema(env, certificateType)
+
+		override async handle(c: AppContext) {
+			const data = await this.getValidatedData<typeof this.schema>()
+			const serial = data.params.serial
+			const proof = data.headers[ProofHeader]
+
+			const l = logger(env).with(
+				...group("request", "type", certificateTypeName(certificateType), "action", "revoke", "serial", serial),
+			)
+
+			// the key the proof was made with is the key the certificate must
+			// have been issued for
+			await verifyProof(l, proof, proof.signaturePubkey, "DELETE", `/${certificateTypeName(certificateType)}/certificates/${serial}`)
+
+			return await revoke(c, l, serial, proof.signaturePubkey, certificateType)
+		}
+	}
+}
+
+export const createApi = (env: SshCaBindings) => {
+	const api = fromHono(new Hono())
+
+	api.get("/ca", CaPublicKeyEndpoint(env))
+	api.post("/user/certificates", IssueUserCertificateEndpoint(env))
+	api.delete("/user/certificates/:serial", RevokeCertificateEndpoint(env, CertificateType.User))
+	api.get("/user/krl", RevocationListEndpoint(env, CertificateType.User))
+	api.post("/host/certificates", IssueHostCertificateEndpoint(env))
+	api.post("/host/certificates/:serial/renew", RenewHostCertificateEndpoint(env))
+	api.delete("/host/certificates/:serial", RevokeCertificateEndpoint(env, CertificateType.Host))
+	api.get("/host/krl", RevocationListEndpoint(env, CertificateType.Host))
+
+	return api
+}

package/src/api/v4/schema.ts

@@ -0,0 +1,241 @@
+import z from "zod"
+import type { SshCaBindings } from "../../types.js"
+import {
+	refineHostPrincipal,
+	refineRenewableCertificate,
+	split,
+	transformCertificate,
+	transformProofOfPossession,
+} from "../../utils.js"
+import {
+	ConflictException,
+	contentJson,
+	InputValidationException,
+	InternalServerErrorException,
+	TooManyRequestsException,
+	NotFoundException,
+	UnauthorizedException,
+	ForbiddenException,
+	UnprocessableEntityException,
+} from "chanfana"
+import { seconds } from "itty-time"
+import { isRevoked } from "../../db/index.js"
+import { CertificateType } from "../../db/types.js"
+import {
+	CaPublicKeyEndpointSchema,
+	certificate,
+	certificateTypeName,
+	certificateTypeTag,
+	createAccessTokenSchema,
+	createIdentityTokenSchema,
+	createRevocationListEndpointSchema,
+	openapiStringByte,
+	subjectPublicKey,
+} from "../schema.js"
+
+/**
+ * The name of the header carrying the proof of possession of the private key
+ */
+export const ProofHeader = "Proof-Of-Possession"
+
+export const createProofSchema = (env: SshCaBindings) => (
+	z.string()
+		.meta({
+			description: "Proof of possession of the private key comprising of `${timestamp}.${fingerprint}.${signature}`. The signature is a BASE64 encoded armored SSHSIG signature, made with the `request-proof-of-possession@com.github.serverless-ssh-ca.andrewheberle` namespace, of `${timestamp}.${fingerprint}.${METHOD} ${path}` where `${METHOD} ${path}` is the request the proof is for, for example `DELETE /api/v4/user/certificates/12345678901234567890`. The timestamp is in milliseconds since the Unix epoch.",
+			example: "1765696780805.SHA256:79mq0wtpQMTvS4+Of8VzLN0qmYWNUyTXYmqKwhEgSLs.LS0tLS1CRUdJTiBTU0ggU0lHTkFUVVJFLS0tLS0K...",
+		})
+		.transform((val, ctx) => transformProofOfPossession(env, val, ctx))
+)
+
+/**
+ * Headers for a request authorised by a proof of possession alone
+ */
+export const createProofHeaderSchema = (env: SshCaBindings) => (
+	z.object({
+		[ProofHeader]: createProofSchema(env),
+	})
+)
+
+/**
+ * Headers for a request authenticated with an access token and authorised by
+ * a proof of possession
+ */
+export const createAuthenticatedHeaderSchema = (env: SshCaBindings) => (
+	z.object({
+		"Authorization": createAccessTokenSchema(env),
+		[ProofHeader]: createProofSchema(env),
+	})
+)
+
+export const serialParamSchema = z.object({
+	// a string as JSON cannot carry a bigint and numbers lose precision
+	// above 2^53, and without leading zeros so the path a proof is made for
+	// has only one form
+	serial: z.string()
+		.regex(/^(0|[1-9]\d*)$/)
+		.transform(BigInt)
+		.refine((v) => v <= 0xFFFFFFFFFFFFFFFFn, { message: "serial must fit in an unsigned 64-bit integer" })
+		.meta({ description: "Serial number of the certificate", example: "12345678901234567890" }),
+})
+
+const certificateResponse = {
+	...contentJson(z.object({
+		certificate: certificate,
+	})
+		.openapi("Certificate Response")
+	)
+}
+
+export const createCaPublicKeyEndpointSchema = () => ({
+	...CaPublicKeyEndpointSchema,
+	operationId: "get_ca_public_key",
+})
+
+export const createGetRevocationListEndpointSchema = (certificateType: CertificateType) => ({
+	...createRevocationListEndpointSchema(certificateType),
+	operationId: `get_${certificateTypeName(certificateType)}_revocation_list`,
+})
+
+export const issueUserCertificateEndpointBodySchema = (env: SshCaBindings) => (
+	z.object({
+		public_key: subjectPublicKey,
+		identity: createIdentityTokenSchema(env),
+		extensions: z.array(z.string())
+			.default(split(env.SSH_CERTIFICATE_EXTENSIONS))
+			.meta({ description: "Extensions to include in the issued SSH certificate" }),
+		lifetime: z.int()
+			.min(seconds("5 minutes"))
+			.max(seconds(env.SSH_CERTIFICATE_LIFETIME))
+			.default(seconds(env.SSH_CERTIFICATE_LIFETIME))
+			.meta({ description: "Lifetime of issued SSH certificate" }),
+	})
+		.openapi("User Certificate Issue Request")
+)
+
+export const createIssueUserCertificateEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.User)],
+	operationId: "issue_user_certificate",
+	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 for \`public_key\` in the \`${ProofHeader}\` header made for this request. Principals on the issued certificate are derived from the identity token.`,
+	security: [{ oidcAuth: [] }],
+	request: {
+		headers: createAuthenticatedHeaderSchema(env),
+		body: contentJson(issueUserCertificateEndpointBodySchema(env)),
+	},
+	responses: {
+		"200": {
+			description: "SSH User Certificate issued successfully",
+			...certificateResponse,
+		},
+		...UnauthorizedException.schema(),
+		...ForbiddenException.schema(),
+		...InputValidationException.schema(),
+		...UnprocessableEntityException.schema(),
+		...InternalServerErrorException.schema(),
+		...TooManyRequestsException.schema(),
+	}
+})
+
+export const issueHostCertificateEndpointBodySchema = (env: SshCaBindings) => (
+	z.object({
+		public_key: subjectPublicKey,
+		identity: createIdentityTokenSchema(env),
+		principals: z.array(z.string().superRefine(refineHostPrincipal)).min(1)
+			.meta({ description: "List of principals to include on the issued certificate" }),
+		lifetime: z.int()
+			.min(seconds("24 hours"))
+			.max(seconds(env.SSH_HOST_CERTIFICATE_LIFETIME))
+			.default(seconds(env.SSH_HOST_CERTIFICATE_LIFETIME))
+			.meta({ description: "Lifetime of issued Host SSH certificate" }),
+	})
+		.openapi("Host Certificate Issue Request")
+)
+
+export const createIssueHostCertificateEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.Host)],
+	operationId: "issue_host_certificate",
+	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 for \`public_key\` in the \`${ProofHeader}\` header made for this request. The user must be permitted to request host certificates by email address or role.`,
+	security: [{ oidcAuth: [] }],
+	request: {
+		headers: createAuthenticatedHeaderSchema(env),
+		body: contentJson(issueHostCertificateEndpointBodySchema(env)),
+	},
+	responses: {
+		"200": {
+			description: "SSH Host Certificate issued successfully",
+			...certificateResponse,
+		},
+		...UnauthorizedException.schema(),
+		...ForbiddenException.schema(),
+		...InputValidationException.schema(),
+		...UnprocessableEntityException.schema(),
+		...InternalServerErrorException.schema(),
+		...TooManyRequestsException.schema(),
+	}
+})
+
+export const renewHostCertificateEndpointBodySchema = (env: SshCaBindings) => (
+	z.object({
+		certificate: openapiStringByte
+			.transform(transformCertificate)
+			.meta({ description: "SSH certificate to renew, which must have the serial number in the path" }),
+		lifetime: z.int()
+			.min(seconds("24 hours"))
+			.max(seconds(env.SSH_HOST_CERTIFICATE_LIFETIME))
+			.default(seconds(env.SSH_HOST_CERTIFICATE_LIFETIME))
+			.meta({ description: "Lifetime of renewed Host SSH certificate" }),
+	})
+		.superRefine((val, ctx) => refineRenewableCertificate(env, isRevoked, val, ctx))
+		.openapi("Host Certificate Renewal Request")
+)
+
+export const createRenewHostCertificateEndpointSchema = (env: SshCaBindings) => ({
+	tags: [certificateTypeTag(CertificateType.Host)],
+	operationId: "renew_host_certificate",
+	summary: "Renew a host certificate",
+	description: `Issues a new SSH host certificate for the same public key and principals as an existing, unexpired and unrevoked host certificate issued by this CA. No OIDC authentication is required; instead the \`${ProofHeader}\` header must contain a proof of possession of the private key for the existing certificate made for this request. The lifetime of the renewed certificate is no longer than that of the existing certificate. The existing certificate is revoked, so it cannot be used or renewed again once the renewed certificate is installed.`,
+	request: {
+		params: serialParamSchema,
+		headers: createProofHeaderSchema(env),
+		body: contentJson(renewHostCertificateEndpointBodySchema(env)),
+	},
+	responses: {
+		"200": {
+			description: "SSH Host Certificate renewed successfully",
+			...certificateResponse,
+		},
+		...UnauthorizedException.schema(),
+		...ForbiddenException.schema(),
+		...InputValidationException.schema(),
+		...UnprocessableEntityException.schema(),
+		...InternalServerErrorException.schema(),
+		...TooManyRequestsException.schema(),
+	}
+})
+
+export const createRevokeCertificateEndpointSchema = (env: SshCaBindings, certificateType: CertificateType) => ({
+	tags: [certificateTypeTag(certificateType)],
+	operationId: `revoke_${certificateTypeName(certificateType)}_certificate`,
+	summary: `Revoke a ${certificateTypeName(certificateType)} certificate`,
+	description: `Revokes a ${certificateTypeName(certificateType)} certificate issued by this CA and adds it to the ${certificateTypeName(certificateType)} Key Revocation List. The \`${ProofHeader}\` header must contain a proof of possession of the private key for the public key that the certificate was issued for, made for this request. A certificate issued for a different public key is reported as not found.`,
+	request: {
+		params: serialParamSchema,
+		headers: createProofHeaderSchema(env),
+	},
+	responses: {
+		"200": {
+			description: `SSH ${certificateTypeName(certificateType)} certificate revoked successfully`,
+			...contentJson(z.object({
+				revoked_at: z.iso.datetime(),
+			})
+				.openapi("Revocation Response")
+			),
+		},
+		...InputValidationException.schema(),
+		...NotFoundException.schema(),
+		...ConflictException.schema(),
+		...InternalServerErrorException.schema(),
+		...TooManyRequestsException.schema(),
+	}
+})