@andrewheberle/serverless-ssh-ca 0.23.0 → 0.24.0

package/src/db/index.ts

@@ -6,7 +6,7 @@ import { D1QB } from "workers-qb"
 import { z } from "zod"
 import { migrateOnce } from "./migrate.js"
 import { migrations } from "./migrations/index.js"
-import { CertificateType, type CertificateRecord, type DatabaseSchema, type KrlRecord } from "./types.js"
+import { CertificateType, type DatabaseSchema, type KrlRecord } from "./types.js"
 
 const connect = async (env: SshCaBindings): Promise<D1QB<DatabaseSchema>> => {
 	const l = logger(env)
@@ -25,6 +25,14 @@ const connect = async (env: SshCaBindings): Promise<D1QB<DatabaseSchema>> => {
 	}
 }
 
+// statements that increment the KRL revision, so a KRL cached for an earlier
+// revision is not used again
+const BumpAllRevisions = "UPDATE krl SET revision = revision + 1"
+
+// increments the revision of the KRL for a certificate type, but only if the
+// previous statement in the same batch changed a row
+const BumpRevisionIfChanged = "UPDATE krl SET revision = revision + 1 WHERE certificate_type = ? AND changes() = 1"
+
 export const dbCleanup = async (env: SshCaBindings) => {
 	const l = logger(env).with("retention", env.DB_CERTIFICATE_RETENTION)
 
@@ -44,28 +52,48 @@ export const dbCleanup = async (env: SshCaBindings) => {
 			}
 		}).execute()
 		l.info("completed database cleanup", "changes", res.meta?.changes)
+
+		// revoked certificates may have been removed from the KRLs, so cached
+		// KRLs must not be used again
+		if ((res.meta?.changes ?? 0) > 0) {
+			await env.DB.prepare(BumpAllRevisions).run()
+		}
 	} catch (err) {
 		l.error("error during database cleanup", "retention", env.DB_CERTIFICATE_RETENTION, "error", err)
 	}
 }
 
-export const recordCertificate = async (env: SshCaBindings, certificate: SshCertificate, keyid: string, certificateType: CertificateType = CertificateType.User) => {
+// the columns recorded for an issued certificate, in the order of the values
+// returned by certificateValues
+const CertificateColumns = ["serial", "key_id", "principals", "extensions", "valid_after", "valid_before", "certificate_type", "public_key"] as const
+
+const certificateRecord = (certificate: SshCertificate, keyid: string, certificateType: CertificateType) => {
 	// principals are recorded as distinguished names, as they were when
 	// certificates were created with sshpk
 	const principals = certificate.principals.map((p) => `${certificate.kind === "host" ? "CN" : "UID"}=${p}`).join(",")
+
+	return {
+		serial: `${certificate.serial}`,
+		key_id: keyid,
+		principals: principals,
+		extensions: certificate.extensions.join(","),
+		valid_after: certificate.validAfter.toISOString(),
+		valid_before: certificate.validBefore.toISOString(),
+		certificate_type: certificateType,
+		public_key: certificate.publicKey.toString()
+	}
+}
+
+const certificateValues = (certificate: SshCertificate, keyid: string, certificateType: CertificateType): (string | number)[] => {
+	const record = certificateRecord(certificate, keyid, certificateType)
+	return CertificateColumns.map((column) => record[column])
+}
+
+export const recordCertificate = async (env: SshCaBindings, certificate: SshCertificate, keyid: string, certificateType: CertificateType = CertificateType.User) => {
 	const qb = await connect(env)
 	const res = await qb.insert({
 		tableName: "certificates",
-		data: {
-			serial: `${certificate.serial}`,
-			key_id: keyid,
-			principals: principals,
-			extensions: certificate.extensions.join(","),
-			valid_after: certificate.validAfter.toISOString(),
-			valid_before: certificate.validBefore.toISOString(),
-			certificate_type: certificateType,
-			public_key: certificate.publicKey.toString()
-		},
+		data: certificateRecord(certificate, keyid, certificateType),
 	}).execute()
 
 	if (!res.success) {
@@ -73,6 +101,49 @@ export const recordCertificate = async (env: SshCaBindings, certificate: SshCert
 	}
 }
 
+/**
+ * Records a host certificate issued by renewing another, revoking the
+ * certificate that was renewed so it cannot be used or renewed again.
+ *
+ * This is done in a single transaction, and the renewed certificate is only
+ * recorded if this call revoked the previous certificate, so when a
+ * certificate is renewed more than once concurrently only one renewal is
+ * recorded. A previous certificate that was never recorded (for example one
+ * signed with the CA key outside of the CA) is recorded so that it can be
+ * revoked.
+ *
+ * @param env The CA bindings
+ * @param previous The certificate that was presented for renewal
+ * @param certificate The certificate issued by the renewal
+ * @returns true if the renewal was recorded, or false if the previous certificate was already revoked
+ */
+export const recordRenewal = async (env: SshCaBindings, previous: SshCertificate, certificate: SshCertificate): Promise<boolean> => {
+	// ensure migrations have been applied
+	await connect(env)
+
+	const columns = CertificateColumns.join(", ")
+	const placeholders = CertificateColumns.map(() => "?").join(", ")
+	const revokedAt = (new Date).toISOString()
+
+	const results = await env.DB.batch([
+		env.DB.prepare(`INSERT INTO certificates (${columns}) VALUES (${placeholders}) ON CONFLICT (serial) DO NOTHING`)
+			.bind(...certificateValues(previous, previous.keyId, CertificateType.Host)),
+		env.DB.prepare("UPDATE certificates SET revoked_at = ? WHERE serial = ? AND certificate_type = ? AND revoked_at IS NULL")
+			.bind(revokedAt, `${previous.serial}`, CertificateType.Host),
+		// changes() is the number of rows revoked by the previous statement
+		env.DB.prepare(`INSERT INTO certificates (${columns}) SELECT ${placeholders} WHERE changes() = 1`)
+			.bind(...certificateValues(certificate, certificate.keyId, CertificateType.Host)),
+		// the previous certificate was revoked if the renewed one was recorded
+		env.DB.prepare(BumpRevisionIfChanged).bind(CertificateType.Host),
+	])
+
+	if (results.some((res) => !res.success)) {
+		throw new Error("error during query")
+	}
+
+	return results[2]?.meta?.changes === 1
+}
+
 export const isRevoked = async (env: SshCaBindings, serial: bigint): Promise<boolean> => {
 	const qb = await connect(env)
 	const res = await qb.fetchOne({
@@ -163,38 +234,89 @@ export const getRevocationList = async (env: SshCaBindings, certificateType: Cer
 	return res.results.map(item => item.serial)
 }
 
-type RevokedCertificate = Pick<CertificateRecord, "revoked_at">
+/** The time a certificate was revoked, as an ISO 8601 string */
+type RevokedCertificate = { revoked_at: string }
 
+/**
+ * Revokes a certificate that has not already been revoked.
+ *
+ * A certificate that is already revoked is left unchanged, so when several
+ * requests revoke the same certificate concurrently only one of them revokes
+ * it and the time it was first revoked is kept.
+ *
+ * @param env The CA bindings
+ * @param serial The serial of the certificate to revoke
+ * @returns The revocation time of the certificate, or an empty array if it was not revoked by this call
+ */
 export const revokeCertificate = async (env: SshCaBindings, serial: bigint): Promise<RevokedCertificate[]> => {
-	const qb = await connect(env)
-	const res = await qb.update<RevokedCertificate>({
-		tableName: "certificates",
-		data: {
-			revoked_at: (new Date).toISOString()
-		},
-		where: {
-			conditions: "serial = ?",
-			params: `${serial}`
-		},
-		returning: ["revoked_at"]
-	}).execute()
+	// ensure migrations have been applied
+	await connect(env)
 
-	if (!res.success) {
+	const revokedAt = (new Date).toISOString()
+
+	// the KRL revision is incremented in the same transaction, so a cached KRL
+	// that does not include this certificate is never used again
+	const results = await env.DB.batch([
+		env.DB.prepare("UPDATE certificates SET revoked_at = ? WHERE serial = ? AND revoked_at IS NULL")
+			.bind(revokedAt, `${serial}`),
+		env.DB.prepare("UPDATE krl SET revision = revision + 1 WHERE certificate_type = (SELECT certificate_type FROM certificates WHERE serial = ?) AND changes() = 1")
+			.bind(`${serial}`),
+	])
+
+	if (results.some((res) => !res.success)) {
 		throw new Error("error during query")
 	}
 
-	if (res.results === undefined) {
-		return []
-	}
+	return results[0]?.meta?.changes === 1 ? [{ revoked_at: revokedAt }] : []
+}
 
-	return res.results
+const KrlRevisionRow = z.object({
+	revision: z.number().int().nonnegative(),
+})
+
+/**
+ * Returns the revision of the KRL for a certificate type, which is
+ * incremented whenever a certificate of that type is revoked.
+ *
+ * @param env The CA bindings
+ * @param certificateType The type of certificates in the KRL
+ * @returns The current revision
+ */
+export const getKrlRevision = async (env: SshCaBindings, certificateType: CertificateType): Promise<bigint> => {
+	const qb = await connect(env)
+	const res = await qb.fetchOne({
+		tableName: "krl",
+		fields: ["revision"],
+		where: {
+			conditions: "certificate_type = ?",
+			params: certificateType
+		}
+	}).execute()
+
+	return BigInt(KrlRevisionRow.parse(res.results).revision)
 }
 
 const KrlVersionRow = z.object({
 	version: z.number().int().nonnegative(),
 	digest: z.string().nullable(),
+	updated_at: z.string(),
 })
 
+/**
+ * Parses a timestamp from the database, which is either an ISO 8601 string or,
+ * when set by SQLite's CURRENT_TIMESTAMP, "YYYY-MM-DD HH:MM:SS" in UTC.
+ */
+const parseTimestamp = (value: string): Date => {
+	return new Date(/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value) ? `${value.replace(" ", "T")}Z` : value)
+}
+
+/** The version of a KRL and when that version was generated */
+export type KrlVersion = {
+	version: bigint
+	/** When the version was first generated, which is the same for every KRL with this version */
+	generatedAt: Date
+}
+
 // the number of times to retry when another request updates the KRL version concurrently
 const KRL_VERSION_ATTEMPTS = 5
 
@@ -209,15 +331,16 @@ const KRL_VERSION_ATTEMPTS = 5
  * @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
+ * @returns The version to use for the KRL, and when that version was first
+ * generated so that every KRL with the version has the same generation date
  */
-export const getKrlVersion = async (env: SshCaBindings, certificateType: CertificateType, digest: string): Promise<bigint> => {
+export const getKrlVersion = async (env: SshCaBindings, certificateType: CertificateType, digest: string): Promise<KrlVersion> => {
 	const qb = await connect(env)
 
 	for (let attempt = 0; attempt < KRL_VERSION_ATTEMPTS; attempt++) {
 		const res = await qb.fetchOne({
 			tableName: "krl",
-			fields: ["version", "digest"],
+			fields: ["version", "digest", "updated_at"],
 			where: {
 				conditions: "certificate_type = ?",
 				params: certificateType
@@ -226,17 +349,19 @@ export const getKrlVersion = async (env: SshCaBindings, certificateType: Certifi
 
 		const current = KrlVersionRow.parse(res.results)
 		if (current.digest === digest) {
-			return BigInt(current.version)
+			return { version: BigInt(current.version), generatedAt: parseTimestamp(current.updated_at) }
 		}
 
-		// only update if the version has not been changed by another request
+		// only update if the version has not been changed by another request,
+		// recording the time to the second as that is all a KRL records
 		const next = current.version + 1
+		const generatedAt = new Date(Math.floor(Date.now() / 1000) * 1000)
 		const updated = await qb.update<Pick<KrlRecord, "version">>({
 			tableName: "krl",
 			data: {
 				version: next,
 				digest: digest,
-				updated_at: (new Date).toISOString()
+				updated_at: generatedAt.toISOString()
 			},
 			where: {
 				conditions: "certificate_type = ? AND version = ?",
@@ -250,7 +375,7 @@ export const getKrlVersion = async (env: SshCaBindings, certificateType: Certifi
 		}
 
 		if (updated.results !== undefined && updated.results.length > 0) {
-			return BigInt(next)
+			return { version: BigInt(next), generatedAt }
 		}
 	}
 

package/src/db/migrations/0003_krl_revision.ts

@@ -0,0 +1,15 @@
+import type { Migration } from "../migrate.js"
+
+export const migration: Migration = {
+	name: "0003_krl_revision",
+	statements: [
+		// incremented whenever a certificate is revoked, so a cached KRL can be
+		// keyed by the revision it was generated for
+		"ALTER TABLE krl ADD COLUMN revision INTEGER NOT NULL DEFAULT 0",
+		// KRLs were previously generated at the time of each request, but are
+		// now generated at the time their version last changed. Starting each
+		// version again from now ensures a KRL fetched before this migration
+		// is never newer than the same version fetched afterwards.
+		"UPDATE krl SET updated_at = CURRENT_TIMESTAMP",
+	]
+}

package/src/db/migrations/index.ts

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

package/src/db/types.ts

@@ -31,6 +31,8 @@ export type KrlRecord = {
 	version: number
 	digest: string | null
 	updated_at: Date
+	/** Incremented whenever a certificate of this type is revoked */
+	revision: number
 }
 
 /** The tables in the database, used to type queries made with workers-qb */

package/src/index.ts

@@ -1,8 +1,9 @@
 import type { ExecutionContext } from "hono"
 import { dbCleanup } from "./db/index.js"
-import { createApp } from "./router.js"
+import { createApp, type SshCaOptions } from "./router.js"
 import type { SshCaBindings } from "./types.js"
-export type { CaDatabase, CaDatabaseQueryResult, CaDatabaseResult, CaPreparedStatement, CaSecret, SshCaBindings } from "./types.js"
+export type { CaCache, CaDatabase, CaDatabaseQueryResult, CaDatabaseResult, CaPreparedStatement, CaRateLimiter, CaSecret, SshCaBindings } from "./types.js"
+export { cloudflareClientIp, type RateLimitKey, type SshCaOptions } from "./router.js"
 
 // the handlers the CA exposes, compatible with a Cloudflare Workers ExportedHandler
 type SshCaHandler = {
@@ -35,10 +36,11 @@ export interface SshCa {
  * the runtime on each request.
  *
  * @param env The bindings (configuration, database and private key) for the CA, see {@link SshCaBindings}
+ * @param options Options for the CA, such as the key requests are rate limited by, see {@link SshCaOptions}
  * @returns The CA's request handler and database cleanup task, see {@link SshCa}
  */
-export const createSshCa = (env: SshCaBindings): SshCa => {
-    const app = createApp(env)
+export const createSshCa = (env: SshCaBindings, options: SshCaOptions = {}): SshCa => {
+    const app = createApp(env, options)
 
     return {
         fetch: async (req: Request): Promise<Response> => await app.fetch(req, env),

package/src/krl.ts

@@ -150,14 +150,15 @@ export class KRLBuilder {
      *
      * @param krlVersion  Optional KRL version number (default: 1).
      * @param comment     Optional comment string embedded in the header.
+     * @param generatedAt Optional time the KRL was generated (default: now).
      */
-    generate(krlVersion: bigint = 1n, comment = ""): ArrayBuffer {
+    generate(krlVersion: bigint = 1n, comment = "", generatedAt?: Date): ArrayBuffer {
         if (this._krl !== null) {
             return this._krl
         }
 
         // ── Header ──────────────────────────────────────────────────────────────
-        const generatedDate = BigInt(Math.floor(Date.now() / 1000))
+        const generatedDate = BigInt(Math.floor((generatedAt?.getTime() ?? Date.now()) / 1000))
 
         const header = concat(
             encodeUint64(KRL_MAGIC),

package/src/node/cache.ts

@@ -0,0 +1,62 @@
+import type { CaCache } from "../types.js"
+
+type Entry = {
+	value: string
+	/** When the entry expires in milliseconds since the Unix epoch, if it does */
+	expires: number | undefined
+}
+
+/**
+ * Create an in-memory cache for the `CACHE` binding, with the same shape as a
+ * Cloudflare Workers KV namespace (see {@link CaCache}).
+ *
+ * Entries are kept in memory by the process, so they are lost on restart and
+ * not shared between processes.
+ *
+ * @example
+ * ```ts
+ * const env = bindingsFromEnv({
+ *     DB: fromNodeSqlite(new DatabaseSync("ssh-ca.sqlite")),
+ *     PRIVATE_KEY: secretFromFile("/etc/ssh-ca/ca_key"),
+ *     CACHE: cacheInMemory(),
+ * })
+ * ```
+ *
+ * @returns A cache for the `CACHE` binding, see {@link CaCache}
+ */
+export const cacheInMemory = (): CaCache => {
+	const entries = new Map<string, Entry>()
+
+	const expired = (entry: Entry, now: number): boolean => entry.expires !== undefined && now >= entry.expires
+
+	return {
+		get: async (key: string): Promise<string | null> => {
+			const entry = entries.get(key)
+			if (entry === undefined) {
+				return null
+			}
+
+			if (expired(entry, Date.now())) {
+				entries.delete(key)
+				return null
+			}
+
+			return entry.value
+		},
+		put: async (key: string, value: string, options?: { expirationTtl?: number }): Promise<void> => {
+			const now = Date.now()
+
+			// remove entries that have expired, as they are not read again
+			for (const [k, entry] of entries) {
+				if (expired(entry, now)) {
+					entries.delete(k)
+				}
+			}
+
+			entries.set(key, {
+				value,
+				expires: options?.expirationTtl === undefined ? undefined : now + options.expirationTtl * 1000,
+			})
+		},
+	}
+}

package/src/node/env.ts

@@ -1,6 +1,6 @@
 import { seconds } from "itty-time"
 import z from "zod"
-import type { CaDatabase, CaSecret, SshCaBindings } from "../types.js"
+import type { CaCache, CaDatabase, CaRateLimiter, CaSecret, SshCaBindings } from "../types.js"
 
 const required = z.string().trim().min(1, { message: "must be set" })
 
@@ -32,7 +32,8 @@ export const EnvSchema = z.object({
 	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_AUD: required,
+	JWT_ACCESS_TOKEN_AUD: z.string().optional(),
 	JWT_ISSUER: required,
 	JWT_ALGORITHMS: required,
 	JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM: required,
@@ -72,13 +73,13 @@ export class InvalidConfigurationError extends Error {
  * })
  * ```
  *
- * @param bindings The database and private key, see {@link CaDatabase} and {@link CaSecret}
+ * @param bindings The database, private key, optional rate limiter and optional cache, see {@link CaDatabase}, {@link CaSecret}, {@link CaRateLimiter} and {@link CaCache}
  * @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 },
+	bindings: { DB: CaDatabase, PRIVATE_KEY: CaSecret, RATE_LIMITER?: CaRateLimiter, CACHE?: CaCache },
 	source: Record<string, string | undefined> = process.env,
 ): SshCaBindings => {
 	const result = EnvSchema.safeParse(source)
@@ -86,5 +87,5 @@ export const bindingsFromEnv = (
 		throw new InvalidConfigurationError(`invalid configuration:\n${z.prettifyError(result.error)}`)
 	}
 
-	return { ...result.data, DB: bindings.DB, PRIVATE_KEY: bindings.PRIVATE_KEY }
+	return { ...result.data, DB: bindings.DB, PRIVATE_KEY: bindings.PRIVATE_KEY, RATE_LIMITER: bindings.RATE_LIMITER, CACHE: bindings.CACHE }
 }

package/src/node/index.ts

@@ -16,6 +16,7 @@
  *
  * @packageDocumentation
  */
+export { cacheInMemory } from "./cache.js"
 export { bindingsFromEnv, EnvSchema, InvalidConfigurationError } from "./env.js"
 export type { CaEnv } from "./env.js"
 export { secretFromFile, secretFromString } from "./secret.js"

package/src/router.ts

@@ -4,12 +4,74 @@ import { createApi as apiv3 } from "./api/v3/index.js"
 import { BasePath as v4BasePath, createApi as apiv4 } from "./api/v4/index.js"
 import { HTTPException } from "hono/http-exception"
 import { logger } from "./logger.js"
+import { TooManyRequestsException } from "chanfana"
 import type { SshCaBindings } from "./types.js"
 
 export type AppContext = Context<{ Bindings: SshCaBindings }>
 
-export const createApp = (env: SshCaBindings) => {
-    const hono = new Hono()
+/**
+ * Returns the key a request is rate limited by, or undefined if the request
+ * should not be rate limited.
+ */
+export type RateLimitKey = (req: Request) => string | undefined
+
+/**
+ * Options for the CA that are not part of its bindings.
+ */
+export interface SshCaOptions {
+    /**
+     * Returns the key requests are rate limited by when `RATE_LIMITER` is
+     * set. Defaults to the client IP address in the `CF-Connecting-IP` header,
+     * which is set by Cloudflare, so other runtimes should provide one that
+     * suits their limiter, for example using a header set by a reverse proxy.
+     */
+    rateLimitKey?: RateLimitKey
+}
+
+/**
+ * Returns the client IP address set by Cloudflare in the `CF-Connecting-IP`
+ * header, which is the default key requests are rate limited by.
+ */
+export const cloudflareClientIp: RateLimitKey = (req) => req.headers.get("CF-Connecting-IP") ?? undefined
+
+// requests that only read from the CA, which are not rate limited
+const ReadMethods = new Set(["GET", "HEAD", "OPTIONS"])
+
+export const createApp = (env: SshCaBindings, options: SshCaOptions = {}) => {
+    const hono = new Hono<{ Bindings: SshCaBindings }>()
+    const rateLimitKey = options.rateLimitKey ?? cloudflareClientIp
+
+    // limit requests to issue, renew and revoke certificates
+    hono.use("/api/*", async (c, next) => {
+        const limiter = c.env.RATE_LIMITER
+        if (limiter === undefined || ReadMethods.has(c.req.method)) {
+            return await next()
+        }
+
+        const l = logger(env).with("in", "rateLimit")
+        const key = rateLimitKey(c.req.raw)
+        if (key === undefined) {
+            l.debug("no rate limit key for request")
+            return await next()
+        }
+
+        let success: boolean
+        try {
+            success = (await limiter.limit({ key })).success
+        } catch (err) {
+            // a failing limiter must not stop certificates being issued or revoked
+            l.error("rate limiter failed", "error", err)
+            return await next()
+        }
+
+        if (!success) {
+            l.warn("request was rate limited", "key", key, "method", c.req.method, "path", c.req.path)
+            const err = new TooManyRequestsException()
+            return c.json({ success: false, errors: err.buildResponse(), result: {} }, 429)
+        }
+
+        return await next()
+    })
 
     // add error handling
     hono.onError((err, c) => {

package/src/ssh/keys.ts

@@ -118,6 +118,39 @@ export class PublicKey {
 	}
 }
 
+/**
+ * The smallest RSA key, in bits, that the CA will issue a certificate for.
+ * This matches the minimum accepted by ssh-ca-client.
+ */
+export const MinimumRsaKeyBits = 2048
+
+/**
+ * Returns the size in bits of the modulus of an RSA public key, or undefined
+ * if the key is not an RSA key.
+ *
+ * @param key The public key
+ */
+export const rsaKeyBits = (key: PublicKey): number | undefined => {
+	if (key.type !== "ssh-rsa") {
+		return undefined
+	}
+
+	// the fields of an RSA key are the exponent and the modulus, an mpint
+	// that may have a leading zero byte to keep it positive
+	const modulus = decodePublicKey(key.blob).fields[1]
+	if (modulus === undefined) {
+		return undefined
+	}
+
+	const start = modulus.findIndex((byte) => byte !== 0)
+	const first = modulus[start]
+	if (start === -1 || first === undefined) {
+		return 0
+	}
+
+	return (modulus.length - start - 1) * 8 + first.toString(2).length
+}
+
 /** The ECDSA curves that can be used to sign */
 export type EcdsaCurve = "nistp256" | "nistp384" | "nistp521"
 

package/src/types.ts

@@ -89,13 +89,49 @@ export interface CaSecret {
 }
 
 /**
- * The bindings (environment) the CA expects, see {@link CaDatabase} and
- * {@link CaSecret} for the non-string bindings.
+ * A rate limiter, with the same shape as a Cloudflare Workers rate limit
+ * binding.
+ *
+ * A Workers `RateLimit` binding satisfies this structurally. On other
+ * runtimes any limiter with the same shape may be used.
+ */
+export interface CaRateLimiter {
+    /**
+     * Counts a request against the limit for a key
+     *
+     * @param options The key the request is counted against, for example the client IP address
+     * @returns Whether the request is within the limit
+     */
+    limit(options: { key: string }): Promise<{ success: boolean }>
+}
+
+/**
+ * A key-value cache, with the subset of a Cloudflare Workers KV namespace
+ * binding used by the CA.
+ *
+ * A Workers `KVNamespace` binding satisfies this structurally. On other
+ * runtimes any cache with the same shape may be used, such as the in-memory
+ * cache returned by `cacheInMemory` from `@andrewheberle/serverless-ssh-ca/node`.
+ */
+export interface CaCache {
+    /** Returns the value for a key, or null if there is none */
+    get(key: string): Promise<string | null>
+    /** Sets the value for a key, which may expire after `expirationTtl` seconds */
+    put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>
+}
+
+/**
+ * The bindings (environment) the CA expects, see {@link CaDatabase},
+ * {@link CaSecret}, {@link CaRateLimiter} and {@link CaCache} for the non-string
+ * bindings.
  */
 export interface SshCaBindings {
 	CERTIFICATE_REQUEST_TIME_SKEW_MAX: string
 	JWT_ALGORITHMS: string | string[]
-	JWT_AUD?: string | string[]
+	/** The audience the identity token, and unless {@link SshCaBindings.JWT_ACCESS_TOKEN_AUD} is set the access token, must be issued for */
+	JWT_AUD: string | string[]
+	/** The audience the access token must be issued for, when it differs from {@link SshCaBindings.JWT_AUD} */
+	JWT_ACCESS_TOKEN_AUD?: string | string[]
 	JWT_ISSUER: string
 	JWT_JWKS_URL: string
 	JWT_SSH_CERTIFICATE_PRINCIPALS_CLAIM: string
@@ -104,6 +140,16 @@ export interface SshCaBindings {
     DB: CaDatabase
     ISSUER_DN: string
     PRIVATE_KEY: CaSecret
+    /**
+     * Limits requests to issue, renew and revoke certificates, see
+     * {@link CaRateLimiter}. Requests are not limited when this is not set.
+     */
+    RATE_LIMITER?: CaRateLimiter
+    /**
+     * Caches KRLs until a certificate is revoked, see {@link CaCache}. KRLs
+     * are generated for every request when this is not set.
+     */
+    CACHE?: CaCache
     SSH_CERTIFICATE_EXTENSIONS: string
     SSH_CERTIFICATE_INCLUDE_SELF_EMAIL?: string | boolean
     SSH_CERTIFICATE_INCLUDE_SELF?: string | boolean