feat: add create-only root certificate API (#7033)

* feat: add create-only root certificate API [skip ci]

* fix: harden root certificate API handling
This commit is contained in:
Thomas authored and GitHub committed 2026-10-05 09:48:06 +02:00
1 parent 67cff1fbc0
commit a17845aa1c
8 files changed
+542 -2

No files matched your search

+5
View File
@@ -4,6 +4,7 @@ import { API_KEY_HEADER_NAME } from "@homarr/auth/api-key";
import { appRouter } from "./router/app";
import { boardRouter } from "./router/board";
import { ensureRootCertificateProcedure, getCertificateProcedure } from "./router/certificates/certificate-router";
import { integrationRequestProcedure } from "./router/integration/integration-request";
import { integrationTestStoredConnectionProcedure } from "./router/integration/integration-test-stored-connection";
import { infoRouter } from "./router/info";
@@ -21,6 +22,10 @@ export const openApiRouter = createTRPCRouter({
inviteRouter,
serverSettingsRouter,
userRouter,
certificates: createTRPCRouter({
getCertificate: getCertificateProcedure,
ensureRootCertificate: ensureRootCertificateProcedure,
}),
integration: createTRPCRouter({
request: integrationRequestProcedure,
testConnection: integrationTestStoredConnectionProcedure,
@@ -5,18 +5,83 @@ import { z } from "zod/v4";
import {
addCustomRootCertificateAsync,
ensureCustomRootCertificateAsync,
getCustomRootCertificateAsync,
removeCustomRootCertificateAsync,
RootCertificateError,
} from "@homarr/core/infrastructure/certificates";
import { createLogger } from "@homarr/core/infrastructure/logs";
import { and, eq } from "@homarr/db";
import { trustedCertificateHostnames } from "@homarr/db/schema";
import { certificateValidFileNameSchema, checkCertificateFile } from "@homarr/validation/certificates";
import {
certificateValidFileNameSchema,
checkCertificateFile,
rootCertificateFileNameSchema,
rootCertificateMetadataSchema,
} from "@homarr/validation/certificates";
import { createTRPCRouter, permissionRequiredProcedure } from "../../trpc";
const logger = createLogger({ module: "certificateRouter" });
const withCertificateErrorsAsync = async <T>(operation: () => Promise<T>) => {
try {
return await operation();
} catch (error) {
if (error instanceof RootCertificateError) {
throw new TRPCError({ code: error.code, message: error.message });
}
throw error;
}
};
export const getCertificateProcedure = permissionRequiredProcedure
.requiresPermission("admin")
.meta({
openapi: {
method: "GET",
path: "/api/certificates/{fileName}",
tags: ["certificates"],
protect: true,
summary: "Inspect a named custom root CA certificate",
description:
"Return public metadata or null when absent. Requires admin permission. Does not return PEM contents.",
},
})
.input(z.object({ fileName: rootCertificateFileNameSchema }))
.output(rootCertificateMetadataSchema.nullable())
.query(({ input }) => withCertificateErrorsAsync(() => getCustomRootCertificateAsync(input.fileName)));
export const ensureRootCertificateProcedure = permissionRequiredProcedure
.requiresPermission("admin")
.meta({
openapi: {
method: "POST",
path: "/api/certificates/root",
tags: ["certificates"],
protect: true,
summary: "Ensure a named custom root CA certificate without overwriting",
description:
"Accept one currently valid self-signed PEM root CA (64 KiB maximum). Identical bytes are idempotent; different existing bytes return CONFLICT. Requires admin permission.",
},
})
.input(
z.object({
fileName: rootCertificateFileNameSchema,
certificate: z
.string()
.min(1)
.max(64 * 1024),
}),
)
.output(z.object({ created: z.boolean(), certificate: rootCertificateMetadataSchema }))
.mutation(({ input }) =>
withCertificateErrorsAsync(() => ensureCustomRootCertificateAsync(input.fileName, input.certificate)),
);
export const certificateRouter = createTRPCRouter({
getCertificate: getCertificateProcedure,
ensureRootCertificate: ensureRootCertificateProcedure,
addCertificate: permissionRequiredProcedure
.requiresPermission("admin")
.input(
@@ -4,7 +4,7 @@ import fs from "node:fs/promises";
import path from "node:path";
import { rootCertificates } from "node:tls";
const getCertificateFolder = () => {
export const getCertificateFolder = () => {
if (process.env.NODE_ENV !== "production") return process.env.LOCAL_CERTIFICATE_PATH;
return process.env.LOCAL_CERTIFICATE_PATH ?? path.join("/appdata", "trusted-certificates");
};
@@ -0,0 +1,170 @@
import { createHash, randomUUID, X509Certificate } from "node:crypto";
import { constants } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
import { createLogger } from "../../logs";
import { getCertificateFolder } from "./index";
const logger = createLogger({ module: "rootCertificate" });
const maxCertificateBytes = 64 * 1024;
const fileNamePattern = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(crt|pem)$/;
const pemPattern = /^\s*-----BEGIN CERTIFICATE-----\s+([A-Za-z0-9+/=][A-Za-z0-9+/=\s]*)-----END CERTIFICATE-----\s*$/;
export class RootCertificateError extends Error {
constructor(
public readonly code: "BAD_REQUEST" | "CONFLICT",
message: string,
) {
super(message);
}
}
const validateFileName = (fileName: string) => {
if (fileName.length > 128 || !fileNamePattern.test(fileName)) {
throw new RootCertificateError("BAD_REQUEST", "Invalid certificate file name");
}
};
const describeCertificate = (fileName: string, content: Buffer, requireCurrent: boolean) => {
if (content.length > maxCertificateBytes) {
throw new RootCertificateError("BAD_REQUEST", "Expected one PEM root CA certificate, at most 64 KiB");
}
const pem = pemPattern.exec(content.toString("utf8"));
if (!pem?.[1]) {
throw new RootCertificateError("BAD_REQUEST", "Expected one PEM root CA certificate, at most 64 KiB");
}
let certificate: X509Certificate;
try {
certificate = new X509Certificate(content);
// Reject extra DER data as well as PEM chains, keys, leaf certificates and non-root CAs.
const der = Buffer.from(pem[1].replace(/\s/g, ""), "base64");
if (
!certificate.raw.equals(der) ||
!certificate.ca ||
!certificate.checkIssued(certificate) ||
!certificate.verify(certificate.publicKey)
) {
throw new Error("Expected a self-signed root CA certificate");
}
} catch {
throw new RootCertificateError("BAD_REQUEST", "Expected a self-signed root CA certificate");
}
const validFrom = new Date(certificate.validFrom);
const validTo = new Date(certificate.validTo);
const now = Date.now();
if (requireCurrent && (validFrom.getTime() > now || validTo.getTime() <= now)) {
throw new RootCertificateError("BAD_REQUEST", "Root CA certificate is not currently valid");
}
return {
fileName,
sha256: createHash("sha256").update(content).digest("hex"),
fingerprint256: certificate.fingerprint256,
ca: true as const,
validFrom: validFrom.toISOString(),
validTo: validTo.toISOString(),
};
};
const hasCode = (error: unknown, code: string) => {
return error instanceof Error && "code" in error && error.code === code;
};
const readCertificateAsync = async (fullPath: string) => {
let file;
try {
// NONBLOCK prevents opening a FIFO from hanging before the regular-file check.
file = await fs.open(fullPath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
} catch (error) {
if (hasCode(error, "ENOENT")) return null;
if (hasCode(error, "ELOOP") || hasCode(error, "ENXIO")) {
throw new RootCertificateError("CONFLICT", "Certificate path is not a regular file");
}
throw error;
}
try {
const stat = await file.stat();
if (!stat.isFile() || stat.size > maxCertificateBytes) {
throw new RootCertificateError("CONFLICT", "Certificate path is not a bounded regular file");
}
const content = Buffer.alloc(maxCertificateBytes + 1);
let size = 0;
while (size < content.length) {
const { bytesRead } = await file.read(content, size, content.length - size, size);
if (bytesRead === 0) break;
size += bytesRead;
}
if (size > maxCertificateBytes) {
throw new RootCertificateError("CONFLICT", "Certificate file exceeds 64 KiB");
}
return content.subarray(0, size);
} finally {
await file.close();
}
};
export const getCustomRootCertificateAsync = async (fileName: string) => {
validateFileName(fileName);
const folder = getCertificateFolder();
if (!folder) return null;
const content = await readCertificateAsync(path.join(folder, fileName));
if (!content) return null;
return describeCertificate(fileName, content, false);
};
export const ensureCustomRootCertificateAsync = async (fileName: string, pem: string) => {
validateFileName(fileName);
const content = Buffer.from(pem, "utf8");
const certificate = describeCertificate(fileName, content, true);
const folder = getCertificateFolder();
if (!folder) {
throw new Error("Set LOCAL_CERTIFICATE_PATH to an absolute path to manage local certificates");
}
await fs.mkdir(folder, { recursive: true });
const fullPath = path.join(folder, fileName);
const existing = await readCertificateAsync(fullPath);
if (existing) {
if (!existing.equals(content)) {
throw new RootCertificateError("CONFLICT", "A different certificate already exists at this file name");
}
return { created: false, certificate };
}
// Publish a complete file atomically without replacing an existing directory entry.
const temporaryPath = path.join(folder, `.root-certificate-${randomUUID()}.tmp`);
const temporaryFile = await fs.open(
temporaryPath,
constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
0o644,
);
try {
try {
await temporaryFile.writeFile(content);
await temporaryFile.sync();
} finally {
await temporaryFile.close();
}
try {
await fs.link(temporaryPath, fullPath);
} catch (error) {
if (!hasCode(error, "EEXIST")) throw error;
const concurrent = await readCertificateAsync(fullPath);
if (!concurrent?.equals(content)) {
throw new RootCertificateError("CONFLICT", "A different certificate already exists at this file name");
}
return { created: false, certificate };
}
return { created: true, certificate };
} finally {
// Cleanup must not turn a published certificate into a failed operation.
try {
await fs.unlink(temporaryPath);
} catch (error) {
logger.warn("Failed to remove temporary root certificate file", { error });
}
}
};
@@ -1,4 +1,9 @@
export { getTrustedCertificateHostnamesAsync } from "./hostnames";
export {
ensureCustomRootCertificateAsync,
getCustomRootCertificateAsync,
RootCertificateError,
} from "./files/root-certificate";
export {
addCustomRootCertificateAsync,
removeCustomRootCertificateAsync,
+14
View File
@@ -4,6 +4,20 @@ import { createCustomErrorParams } from "./form/i18n";
export const certificateValidFileNameSchema = z.string().regex(/^[\w\-. ]+$/);
export const rootCertificateFileNameSchema = z
.string()
.max(128)
.regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*\.(crt|pem)$/);
export const rootCertificateMetadataSchema = z.object({
fileName: rootCertificateFileNameSchema,
sha256: z.string(),
fingerprint256: z.string(),
ca: z.literal(true),
validFrom: z.string(),
validTo: z.string(),
});
export const checkCertificateFile: z.core.CheckFn<File> = (context) => {
const result = certificateValidFileNameSchema.safeParse(context.value.name);
if (!result.success) {