@andrewheberle/serverless-ssh-ca 0.19.0 → 0.20.0

package/package.json

@@ -1,24 +1,30 @@
 {
 	"name": "@andrewheberle/serverless-ssh-ca",
-	"version": "0.19.0",
-	"description": "A serverless SSH CA built on Cloudflare Workers",
+	"version": "0.20.0",
+	"description": "A serverless SSH CA built for Cloudflare Workers that can also run on Node.js",
 	"type": "module",
 	"types": "./dist/index.d.ts",
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"openapi.json"
 	],
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
-		}
+		},
+		"./node": {
+			"types": "./dist/node/index.d.ts",
+			"default": "./dist/node/index.js"
+		},
+		"./openapi.json": "./openapi.json"
 	},
 	"scripts": {
 		"build": "tsc",
 		"coverage": "vitest run --coverage",
 		"lint": "eslint",
-		"prepublishOnly": "npm run build",
+		"prepublishOnly": "npm run build && npm run schema",
 		"release": "release-it",
 		"release:ci": "npm run release:patch",
 		"release:ci:major": "release-it major --ci",

package/src/index.ts

@@ -2,7 +2,7 @@ import type { ExecutionContext } from "hono"
 import { dbCleanup } from "./db/index.js"
 import { createApp } from "./router.js"
 import type { SshCaBindings } from "./types.js"
-export type { CaDatabase, CaSecret, SshCaBindings } from "./types.js"
+export type { CaDatabase, CaDatabaseQueryResult, CaDatabaseResult, CaPreparedStatement, CaSecret, SshCaBindings } from "./types.js"
 
 // the handlers the CA exposes, compatible with a Cloudflare Workers ExportedHandler
 type SshCaHandler = {
@@ -10,6 +10,42 @@ type SshCaHandler = {
     scheduled(controller: unknown, env: SshCaBindings, ctx: ExecutionContext): Promise<void>
 }
 
+/**
+ * A runtime neutral instance of the CA, returned by {@link createSshCa}.
+ */
+export interface SshCa {
+    /**
+     * Handle a request to the CA's API, suitable for any server that speaks
+     * the Fetch API `Request` and `Response` types.
+     */
+    fetch(req: Request): Promise<Response>
+    /**
+     * Remove expired certificates from the database according to
+     * `DB_CERTIFICATE_RETENTION`. This should be run periodically (for example
+     * once a day), as the `scheduled` handler does on Cloudflare Workers.
+     */
+    cleanup(): Promise<void>
+}
+
+/**
+ * Create an instance of the CA bound to a fixed set of bindings, for use on
+ * runtimes other than Cloudflare Workers.
+ *
+ * On Workers use the default export instead, which receives its bindings from
+ * the runtime on each request.
+ *
+ * @param env The bindings (configuration, database and private key) for the CA, see {@link SshCaBindings}
+ * @returns The CA's request handler and database cleanup task, see {@link SshCa}
+ */
+export const createSshCa = (env: SshCaBindings): SshCa => {
+    const app = createApp(env)
+
+    return {
+        fetch: async (req: Request): Promise<Response> => await app.fetch(req, env),
+        cleanup: async (): Promise<void> => await dbCleanup(env),
+    }
+}
+
 let app: ReturnType<typeof createApp> | undefined
 
 export default {

package/src/node/env.ts

@@ -0,0 +1,90 @@
+import { seconds } from "itty-time"
+import z from "zod"
+import type { CaDatabase, CaSecret, SshCaBindings } from "../types.js"
+
+const required = z.string().trim().min(1, { message: "must be set" })
+
+// a duration in the format accepted by itty-time, such as "24 hours"
+const duration = (opts: { allowZero: boolean }) => required.refine(v => {
+	const s = seconds(v)
+	return Number.isFinite(s) && (opts.allowZero ? s >= 0 : s > 0)
+}, { message: opts.allowZero ? "must be a duration such as \"90 seconds\"" : "must be a positive duration such as \"24 hours\"" })
+
+const boolean = z.enum(["true", "false"], { message: "must be \"true\" or \"false\"" })
+
+/**
+ * The environment variables read by {@link bindingsFromEnv}, which match the
+ * Workers vars documented for the CA.
+ */
+export const EnvSchema = z.object({
+	DB_CERTIFICATE_RETENTION: z.union([
+		z.literal("infinite"),
+		// an SQLite date modifier such as "1 year" or "90 days"
+		z.string().regex(/^[+-]?\d+(\.\d+)? (second|minute|hour|day|month|year)s?$/),
+	], { message: "must be \"infinite\" or a period such as \"1 year\"" }),
+	SSH_CERTIFICATE_EXTENSIONS: z.string(),
+	SSH_CERTIFICATE_LIFETIME: duration({ allowZero: false }),
+	SSH_CERTIFICATE_INCLUDE_SELF: boolean.optional(),
+	SSH_CERTIFICATE_INCLUDE_SELF_EMAIL: boolean.optional(),
+	SSH_CERTIFICATE_PRINCIPALS: z.string().optional(),
+	SSH_HOST_CERTIFICATE_LIFETIME: duration({ allowZero: false }),
+	SSH_HOST_CERTIFICATE_ALLOWED_EMAILS: z.string().optional(),
+	SSH_HOST_CERTIFICATE_ALLOWED_ROLES: z.string().optional(),
+	ISSUER_DN: required,
+	JWT_JWKS_URL: z.url({ protocol: /^https?$/, message: "must be an http or https URL" }),
+	JWT_AUD: z.string().optional(),
+	JWT_ISSUER: required,
+	JWT_ALGORITHMS: required,
+	JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM: required,
+	CERTIFICATE_REQUEST_TIME_SKEW_MAX: duration({ allowZero: true }),
+	LOG_LEVEL: z.enum(["none", "error", "warning", "info", "debug"]).optional(),
+})
+
+/**
+ * The CA's configuration as read from environment variables, see {@link EnvSchema}.
+ */
+export type CaEnv = z.infer<typeof EnvSchema>
+
+/**
+ * Thrown by {@link bindingsFromEnv} when the environment is not a valid configuration.
+ */
+export class InvalidConfigurationError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "InvalidConfigurationError"
+
+		Object.setPrototypeOf(this, InvalidConfigurationError.prototype)
+	}
+}
+
+/**
+ * Build the CA's bindings from environment variables, for runtimes where
+ * configuration is not supplied as Workers bindings.
+ *
+ * The variables have the same names and formats as the Workers vars, and are
+ * validated before use so that misconfiguration is reported at start up.
+ *
+ * @example
+ * ```ts
+ * const env = bindingsFromEnv({
+ *     DB: fromNodeSqlite(new DatabaseSync("ssh-ca.sqlite")),
+ *     PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
+ * })
+ * ```
+ *
+ * @param bindings The database and private key, see {@link CaDatabase} and {@link CaSecret}
+ * @param source The environment variables to read, `process.env` by default
+ * @returns The bindings to pass to `createSshCa`
+ * @throws {@link InvalidConfigurationError} if a variable is missing or invalid
+ */
+export const bindingsFromEnv = (
+	bindings: { DB: CaDatabase, PRIVATE_KEY: CaSecret },
+	source: Record<string, string | undefined> = process.env,
+): SshCaBindings => {
+	const result = EnvSchema.safeParse(source)
+	if (!result.success) {
+		throw new InvalidConfigurationError(`invalid configuration:\n${z.prettifyError(result.error)}`)
+	}
+
+	return { ...result.data, DB: bindings.DB, PRIVATE_KEY: bindings.PRIVATE_KEY }
+}

package/src/node/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Helpers for running the CA on Node.js, imported from
+ * `@andrewheberle/serverless-ssh-ca/node`.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseSync } from "node:sqlite"
+ * import { createSshCa } from "@andrewheberle/serverless-ssh-ca"
+ * import { bindingsFromEnv, fromNodeSqlite, secretFromFile } from "@andrewheberle/serverless-ssh-ca/node"
+ *
+ * const ca = createSshCa(bindingsFromEnv({
+ *     DB: fromNodeSqlite(new DatabaseSync("ssh-ca.sqlite")),
+ *     PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
+ * }))
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { bindingsFromEnv, EnvSchema, InvalidConfigurationError } from "./env.js"
+export type { CaEnv } from "./env.js"
+export { secretFromFile, secretFromString } from "./secret.js"
+export { fromNodeSqlite } from "./sqlite.js"

package/src/node/secret.ts

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises"
+import type { CaSecret } from "../types.js"
+
+/**
+ * Use a string as the CA's private key secret.
+ *
+ * @example
+ * ```ts
+ * const PRIVATE_KEY = secretFromString(process.env.SSH_CA_PRIVATE_KEY ?? "")
+ * ```
+ *
+ * @param value The CA private key in OpenSSH format
+ * @returns A secret for the `PRIVATE_KEY` binding, see {@link CaSecret}
+ */
+export const secretFromString = (value: string): CaSecret => ({
+	get: async (): Promise<string> => value,
+})
+
+/**
+ * Use the contents of a file as the CA's private key secret.
+ *
+ * The file is read each time the key is needed, so replacing the file takes
+ * effect without a restart.
+ *
+ * @param path The path of a file containing the CA private key in OpenSSH format
+ * @returns A secret for the `PRIVATE_KEY` binding, see {@link CaSecret}
+ */
+export const secretFromFile = (path: string): CaSecret => ({
+	get: async (): Promise<string> => await readFile(path, { encoding: "utf-8" }),
+})

package/src/node/sqlite.ts

@@ -0,0 +1,315 @@
+import type { DatabaseSync, SQLInputValue } from "node:sqlite"
+import type { CaDatabase, CaDatabaseQueryResult, CaDatabaseResult, CaPreparedStatement } from "../types.js"
+
+/**
+ * A single SQL statement split from a larger query by {@link splitStatements}.
+ */
+export type SqlStatement = {
+	/** The SQL of the statement, without its trailing `;` */
+	sql: string
+	/** The number of anonymous (`?`) parameters in the statement */
+	parameters: number
+	/** Whether the statement uses numbered or named parameters (`?1`, `:name`, `@name` or `$name`) */
+	named: boolean
+}
+
+const isWordChar = (ch: string | undefined): boolean => ch !== undefined && /[A-Za-z0-9_$]/.test(ch)
+
+/**
+ * Split SQL that may contain several statements into individual statements.
+ *
+ * `node:sqlite` only compiles the first statement passed to `prepare()`,
+ * whereas Cloudflare D1 runs them all, so queries are split here first. Quoted
+ * strings and identifiers, comments and `CREATE TRIGGER ... BEGIN ... END`
+ * bodies are not split. Statements containing nothing but whitespace or
+ * comments are dropped.
+ *
+ * @param sql The SQL to split
+ * @returns The statements found in `sql`, see {@link SqlStatement}
+ */
+export const splitStatements = (sql: string): SqlStatement[] => {
+	const statements: SqlStatement[] = []
+
+	let start = 0
+	let parameters = 0
+	let named = false
+	let hasTokens = false
+	let words: string[] = []
+	let depth = 0
+
+	const push = (end: number): void => {
+		if (hasTokens) {
+			statements.push({ sql: sql.slice(start, end).trim(), parameters, named })
+		}
+		start = end + 1
+		parameters = 0
+		named = false
+		hasTokens = false
+		words = []
+		depth = 0
+	}
+
+	// true if the current statement is CREATE [TEMP|TEMPORARY] TRIGGER, whose body may contain ";"
+	const inTrigger = (): boolean => words[0] === "CREATE" && (words[1] === "TRIGGER" || words[2] === "TRIGGER")
+
+	let i = 0
+	while (i < sql.length) {
+		const ch = sql[i]
+		const next = sql[i + 1]
+
+		// comments
+		if (ch === "-" && next === "-") {
+			const end = sql.indexOf("\n", i)
+			i = end === -1 ? sql.length : end + 1
+			continue
+		}
+		if (ch === "/" && next === "*") {
+			const end = sql.indexOf("*/", i + 2)
+			i = end === -1 ? sql.length : end + 2
+			continue
+		}
+
+		// whitespace
+		if (ch === undefined || /\s/.test(ch)) {
+			i++
+			continue
+		}
+
+		// end of statement
+		if (ch === ";" && depth === 0) {
+			push(i)
+			i++
+			continue
+		}
+
+		hasTokens = true
+
+		// quoted strings and identifiers, where a doubled quote is an escaped quote
+		if (ch === "'" || ch === "\"" || ch === "`" || ch === "[") {
+			const close = ch === "[" ? "]" : ch
+			let j = i + 1
+			while (j < sql.length) {
+				if (sql[j] === close) {
+					if (close !== "]" && sql[j + 1] === close) {
+						j += 2
+						continue
+					}
+					break
+				}
+				j++
+			}
+			i = j + 1
+			continue
+		}
+
+		// parameters
+		if (ch === "?") {
+			let j = i + 1
+			while (j < sql.length && /[0-9]/.test(sql[j] ?? "")) {
+				j++
+			}
+			if (j === i + 1) {
+				parameters++
+			} else {
+				named = true
+			}
+			i = j
+			continue
+		}
+		if ((ch === ":" || ch === "@" || ch === "$") && isWordChar(next)) {
+			named = true
+			i++
+			while (isWordChar(sql[i])) {
+				i++
+			}
+			continue
+		}
+
+		// keywords and identifiers
+		if (isWordChar(ch)) {
+			let j = i
+			while (isWordChar(sql[j])) {
+				j++
+			}
+			const word = sql.slice(i, j).toUpperCase()
+			if (words.length < 3) {
+				words.push(word)
+			}
+			if (inTrigger()) {
+				if (word === "BEGIN" || word === "CASE") {
+					depth++
+				} else if (word === "END" && depth > 0) {
+					depth--
+				}
+			}
+			i = j
+			continue
+		}
+
+		i++
+	}
+
+	push(sql.length)
+
+	return statements
+}
+
+/**
+ * Convert a value bound to a statement into one `node:sqlite` accepts, using
+ * the same conversions as Cloudflare D1.
+ */
+const toSqlValue = (value: unknown): SQLInputValue => {
+	if (value === null || typeof value === "number" || typeof value === "bigint" || typeof value === "string") {
+		return value
+	}
+	if (typeof value === "boolean") {
+		return value ? 1 : 0
+	}
+	if (value instanceof ArrayBuffer) {
+		return new Uint8Array(value)
+	}
+	if (ArrayBuffer.isView(value)) {
+		return new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
+	}
+	throw new TypeError(`unsupported type for SQL parameter: ${value === undefined ? "undefined" : typeof value}`)
+}
+
+const toNumber = (value: unknown): number => {
+	if (typeof value === "number") {
+		return value
+	}
+	if (typeof value === "bigint") {
+		return Number(value)
+	}
+	throw new TypeError(`expected a number from SQLite but got ${typeof value}`)
+}
+
+// counters used to report D1 style metadata for any statement
+const counters = (db: DatabaseSync): { changes: number, lastRowId: number } => {
+	const row = db.prepare("SELECT total_changes() AS changes, last_insert_rowid() AS last_row_id").get()
+	return { changes: toNumber(row?.changes), lastRowId: toNumber(row?.last_row_id) }
+}
+
+let savepointId = 0
+
+// run fn atomically, using a savepoint so it also works inside an existing transaction
+const atomically = <T>(db: DatabaseSync, fn: () => T): T => {
+	const name = `serverless_ssh_ca_${savepointId++}`
+	db.exec(`SAVEPOINT ${name}`)
+	try {
+		const result = fn()
+		db.exec(`RELEASE ${name}`)
+		return result
+	} catch (err) {
+		db.exec(`ROLLBACK TO ${name}`)
+		db.exec(`RELEASE ${name}`)
+		throw err
+	}
+}
+
+class NodeSqliteStatement implements CaPreparedStatement {
+	readonly db: DatabaseSync
+	private readonly sql: string
+	private readonly values: readonly SQLInputValue[]
+
+	constructor(db: DatabaseSync, sql: string, values: readonly SQLInputValue[] = []) {
+		this.db = db
+		this.sql = sql
+		this.values = values
+	}
+
+	bind(...values: unknown[]): NodeSqliteStatement {
+		return new NodeSqliteStatement(this.db, this.sql, values.map(toSqlValue))
+	}
+
+	async all(): Promise<CaDatabaseQueryResult> {
+		return this.execute()
+	}
+
+	async run(): Promise<CaDatabaseResult> {
+		const { success, meta } = this.execute()
+		return { success, meta }
+	}
+
+	// executes synchronously so no other query can run part way through
+	execute(): CaDatabaseQueryResult {
+		const started = performance.now()
+		const before = counters(this.db)
+		const results = this.query()
+		const after = counters(this.db)
+
+		return {
+			success: true,
+			results,
+			meta: {
+				changes: after.changes - before.changes,
+				last_row_id: after.lastRowId,
+				duration: performance.now() - started,
+			},
+		}
+	}
+
+	private query(): unknown[] {
+		const statements = splitStatements(this.sql)
+		if (statements.length <= 1) {
+			return this.db.prepare(this.sql).all(...this.values)
+		}
+
+		if (statements.some(s => s.named)) {
+			throw new Error("queries containing more than one statement only support anonymous (?) parameters")
+		}
+		const expected = statements.reduce((total, s) => total + s.parameters, 0)
+		if (expected !== this.values.length) {
+			throw new RangeError(`query expects ${expected} parameters but ${this.values.length} were bound`)
+		}
+
+		// give each statement its share of the bound values, returning the rows of the last statement
+		return atomically(this.db, () => {
+			let offset = 0
+			let results: unknown[] = []
+			for (const statement of statements) {
+				const values = this.values.slice(offset, offset + statement.parameters)
+				offset += statement.parameters
+				results = this.db.prepare(statement.sql).all(...values)
+			}
+			return results
+		})
+	}
+}
+
+/**
+ * Use a Node.js `node:sqlite` database as the CA's database.
+ *
+ * The returned object behaves like a Cloudflare D1 binding: queries containing
+ * several statements are run in full (see {@link splitStatements}) and
+ * {@link CaDatabase.batch} is atomic. The database's schema is created and
+ * migrated automatically when the CA first uses it.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseSync } from "node:sqlite"
+ * import { fromNodeSqlite } from "@andrewheberle/serverless-ssh-ca/node"
+ *
+ * const DB = fromNodeSqlite(new DatabaseSync("ssh-ca.sqlite"))
+ * ```
+ *
+ * @param db An open `node:sqlite` database
+ * @returns A database for the `DB` binding, see {@link CaDatabase}
+ */
+export const fromNodeSqlite = (db: DatabaseSync): CaDatabase => ({
+	prepare: (query: string): CaPreparedStatement => new NodeSqliteStatement(db, query),
+	batch: async (statements: CaPreparedStatement[]): Promise<CaDatabaseQueryResult[]> => {
+		const owned = statements.map(s => {
+			if (!(s instanceof NodeSqliteStatement) || s.db !== db) {
+				throw new TypeError("batch statements must be prepared by the same database")
+			}
+			return s
+		})
+		return atomically(db, () => owned.map(s => s.execute()))
+	},
+	exec: async (query: string): Promise<{ count: number, duration: number }> => {
+		const started = performance.now()
+		db.exec(query)
+		return { count: splitStatements(query).length, duration: performance.now() - started }
+	},
+})

package/src/types.ts

@@ -26,15 +26,61 @@ export type SSHExtension = {
     data: Buffer<ArrayBuffer>
 }
 
+/**
+ * The result of executing a statement via {@link CaPreparedStatement.run} or
+ * {@link CaDatabase.batch}, modelled on a Cloudflare D1 result.
+ */
+export interface CaDatabaseResult {
+    /** Whether the statement executed successfully */
+    success: boolean
+    meta?: {
+        /** The number of rows changed by the statement */
+        changes?: number
+        /** The rowid of the last row inserted */
+        last_row_id?: number
+        /** How long the statement took to execute in milliseconds */
+        duration?: number
+    }
+}
+
+/**
+ * The result of executing a statement that returns rows via
+ * {@link CaPreparedStatement.all}.
+ */
+export interface CaDatabaseQueryResult extends CaDatabaseResult {
+    /** The rows returned, one object per row keyed by column name */
+    results: unknown[]
+}
+
+/**
+ * The subset of a Cloudflare D1 prepared statement used by the CA.
+ */
+export interface CaPreparedStatement {
+    /** Bind positional (`?`) parameters, returning a statement to execute */
+    bind(...values: unknown[]): CaPreparedStatement
+    /** Execute the statement and return all rows */
+    all(): Promise<CaDatabaseQueryResult>
+    /** Execute the statement without returning rows */
+    run(): Promise<CaDatabaseResult>
+}
+
 /**
  * The subset of a Cloudflare D1 database binding used by the CA.
  *
  * A Workers `D1Database` binding satisfies this structurally, so the package
- * does not need to depend on `@cloudflare/workers-types`.
+ * does not need to depend on `@cloudflare/workers-types`. Any other SQLite
+ * compatible database may be used by implementing this interface.
+ *
+ * The SQL the CA runs is SQLite dialect, and statements passed to
+ * {@link CaDatabase.prepare} may contain more than one SQL statement (as used
+ * when applying schema migrations).
  */
 export interface CaDatabase {
-    prepare(query: string): unknown
-    batch(statements: never[]): Promise<unknown>
+    /** Prepare a SQL query for execution, see {@link CaPreparedStatement} */
+    prepare(query: string): CaPreparedStatement
+    /** Execute several prepared statements atomically, returning a result for each */
+    batch(statements: CaPreparedStatement[]): Promise<CaDatabaseResult[]>
+    /** Execute one or more SQL statements without parameters */
     exec(query: string): Promise<unknown>
 }