@c9up/vellum 0.1.0

package/src/native.ts

@@ -0,0 +1,358 @@
+/**
+ * Loader for the Rust PDF engine.
+ *
+ * The engine is not optional. Parsing, authoring and rendering PDF have no
+ * JavaScript implementation in this package, so a missing binary is a hard
+ * failure with an actionable message — never a silent degradation that lets
+ * one deployment behave differently from another.
+ */
+
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+import { VellumError } from "./errors.js";
+import type {
+	DocumentInfo,
+	DocumentMetadata,
+	FormField,
+	SignatureOptions as NativeSignatureOptions,
+	StampOptions as NativeStampOptions,
+	TextStampOptions as NativeTextStampOptions,
+	TrustOptions as NativeTrustOptions,
+	PageDimensions,
+	PageSize,
+	PreparedSignature,
+	RenderOptions,
+	RevocationAnswer,
+	SignatureReport,
+	TimestampQuery,
+} from "./native/generated.js";
+
+const requireNative = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url));
+
+const platformMap: Record<string, string> = {
+	"linux-x64": "linux-x64-gnu",
+	"linux-arm64": "linux-arm64-gnu",
+	"darwin-x64": "darwin-x64",
+	"darwin-arm64": "darwin-arm64",
+	"win32-x64": "win32-x64-msvc",
+};
+
+/**
+ * The engine's surface, as the Rust declares it.
+ *
+ * Derived from `./native/generated.js` — written by `pnpm build:napi-types`
+ * from napi-derive's own `type-def` output — rather than restated here, where
+ * nothing would notice a `pub fn` gaining a parameter or changing its return.
+ */
+type NativeVellum = typeof import("./native/generated.js");
+
+export type {
+	DocumentInfo,
+	DocumentMetadata,
+	FormField,
+	PageDimensions,
+	PageSize,
+	PreparedSignature,
+	RevocationAnswer,
+	SignatureReport,
+} from "./native/generated.js";
+
+let native: NativeVellum | undefined;
+let loadError: unknown;
+
+try {
+	const suffix = platformMap[`${platform}-${arch}`];
+	if (suffix) {
+		native = requireNative(join(here, `../index.${suffix}.node`));
+	}
+} catch (error) {
+	loadError = error;
+}
+
+export function isNativeAvailable(): boolean {
+	return native !== undefined;
+}
+
+/** Why the engine could not be loaded, phrased for whoever has to fix it. */
+function unavailableReason(): string {
+	const target = `${platform}-${arch}`;
+	if (loadError !== undefined) {
+		return `failed to load (${loadError instanceof Error ? loadError.message : String(loadError)})`;
+	}
+	return platformMap[target] !== undefined
+		? "binary not found"
+		: `no prebuilt binary for ${target}`;
+}
+
+/** Raised when an operation needs the Rust engine and it is not there. */
+export class VellumNativeRequiredError extends VellumError {
+	constructor() {
+		super(
+			"NAPI_REQUIRED",
+			`The Rust PDF engine is required but not loaded — ${unavailableReason()}.\n` +
+				"Install the prebuilt binary for this platform, or build it with `pnpm build:napi`.",
+		);
+		this.name = "VellumNativeRequiredError";
+	}
+}
+
+/** The engine, or a refusal explaining how to get one. */
+function engine(): NativeVellum {
+	if (native === undefined) throw new VellumNativeRequiredError();
+	return native;
+}
+
+/**
+ * Run engine work, translating its failures into coded errors.
+ *
+ * The engine reports failures as plain reasons. Without this, a caller
+ * catching a corrupt upload would get an `Error` it cannot branch on.
+ */
+function run<T>(code: string, work: (engine: NativeVellum) => T): T {
+	const loaded = engine();
+	try {
+		return work(loaded);
+	} catch (error) {
+		throw new VellumError(
+			code,
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+export function inspectNative(pdf: Buffer): DocumentInfo {
+	return run("INVALID_PDF", (loaded) => loaded.inspect(pdf));
+}
+
+export function createBlankNative(pages: ReadonlyArray<PageSize>): Buffer {
+	return run("WRITE_FAILED", (loaded) => loaded.createBlank([...pages]));
+}
+
+/**
+ * Rasterise one page, addressed from zero.
+ *
+ * The engine hands this to the libuv thread pool, so the returned promise
+ * settles without the calling thread ever blocking.
+ */
+export async function renderPageNative(
+	pdf: Buffer,
+	pageIndex: number,
+	options: RenderOptions,
+): Promise<Buffer> {
+	const loaded = engine();
+	try {
+		return await loaded.renderPage(pdf, pageIndex, options);
+	} catch (error) {
+		throw new VellumError(
+			"RENDER_FAILED",
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+/** Rasterise every page, in document order. */
+export async function renderAllNative(
+	pdf: Buffer,
+	options: RenderOptions,
+): Promise<Buffer[]> {
+	const loaded = engine();
+	try {
+		return await loaded.renderAll(pdf, options);
+	} catch (error) {
+		throw new VellumError(
+			"RENDER_FAILED",
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+export function pageDimensionsNative(pdf: Buffer): PageDimensions[] {
+	return run("INVALID_PDF", (loaded) => loaded.pageDimensions(pdf));
+}
+
+export function metadataNative(pdf: Buffer): DocumentMetadata {
+	return run("INVALID_PDF", (loaded) => loaded.metadata(pdf));
+}
+
+export async function extractTextNative(
+	pdf: Buffer,
+	pageIndex: number,
+): Promise<string> {
+	const loaded = engine();
+	try {
+		return await loaded.extractText(pdf, pageIndex);
+	} catch (error) {
+		throw new VellumError(
+			"EXTRACT_FAILED",
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+export async function extractTextAllNative(pdf: Buffer): Promise<string[]> {
+	const loaded = engine();
+	try {
+		return await loaded.extractTextAll(pdf);
+	} catch (error) {
+		throw new VellumError(
+			"EXTRACT_FAILED",
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+async function edit<T>(
+	code: string,
+	work: (engine: NativeVellum) => Promise<T>,
+): Promise<T> {
+	const loaded = engine();
+	try {
+		return await work(loaded);
+	} catch (error) {
+		throw new VellumError(
+			code,
+			error instanceof Error ? error.message : String(error),
+			{ cause: error },
+		);
+	}
+}
+
+export function mergeNative(documents: ReadonlyArray<Buffer>): Promise<Buffer> {
+	return edit("MERGE_FAILED", (loaded) => loaded.merge([...documents]));
+}
+
+export function selectPagesNative(
+	pdf: Buffer,
+	pageIndexes: ReadonlyArray<number>,
+): Promise<Buffer> {
+	return edit("SELECT_FAILED", (loaded) =>
+		loaded.selectPages(pdf, [...pageIndexes]),
+	);
+}
+
+export function splitNative(pdf: Buffer): Promise<Buffer[]> {
+	return edit("SPLIT_FAILED", (loaded) => loaded.split(pdf));
+}
+
+export function rotateNative(
+	pdf: Buffer,
+	degrees: number,
+	pageIndexes?: ReadonlyArray<number>,
+): Promise<Buffer> {
+	return edit("ROTATE_FAILED", (loaded) =>
+		loaded.rotate(pdf, degrees, pageIndexes ? [...pageIndexes] : undefined),
+	);
+}
+
+export function stampNative(
+	pdf: Buffer,
+	image: Buffer,
+	options: NativeStampOptions,
+): Promise<Buffer> {
+	return edit("STAMP_FAILED", (loaded) => loaded.stamp(pdf, image, options));
+}
+
+export function stampTextNative(
+	pdf: Buffer,
+	text: string,
+	options: NativeTextStampOptions,
+): Promise<Buffer> {
+	return edit("STAMP_TEXT_FAILED", (loaded) =>
+		loaded.stampText(pdf, text, options),
+	);
+}
+
+export function formFieldsNative(pdf: Buffer): FormField[] {
+	return run("INVALID_PDF", (loaded) => loaded.formFields(pdf));
+}
+
+export function fillFormNative(
+	pdf: Buffer,
+	values: Record<string, string>,
+): Promise<Buffer> {
+	return edit("FILL_FAILED", (loaded) => loaded.fillForm(pdf, values));
+}
+
+export function flattenFormNative(pdf: Buffer): Promise<Buffer> {
+	return edit("FLATTEN_FAILED", (loaded) => loaded.flattenForm(pdf));
+}
+
+export function prepareSignatureNative(
+	pdf: Buffer,
+	options: NativeSignatureOptions,
+): Promise<PreparedSignature> {
+	return edit("SIGN_FAILED", (loaded) => loaded.prepareSignature(pdf, options));
+}
+
+export function embedSignatureNative(
+	prepared: Buffer,
+	value: Buffer,
+): Promise<Buffer> {
+	return edit("SIGN_FAILED", (loaded) =>
+		loaded.embedSignature(prepared, value),
+	);
+}
+
+export function signCmsNative(
+	digest: Buffer,
+	key: Buffer,
+	certificates: ReadonlyArray<Buffer>,
+	signedAt: string,
+): Promise<Buffer> {
+	return edit("SIGN_FAILED", (loaded) =>
+		loaded.signCms(digest, key, [...certificates], signedAt),
+	);
+}
+
+export function timestampQueryNative(cms: Buffer): TimestampQuery {
+	return run("TIMESTAMP_FAILED", (loaded) => loaded.timestampQuery(cms));
+}
+
+export function attachTimestampNative(
+	cms: Buffer,
+	response: Buffer,
+	nonce: Buffer,
+): Buffer {
+	return run("TIMESTAMP_FAILED", (loaded) =>
+		loaded.attachTimestamp(cms, response, nonce),
+	);
+}
+
+export function verifySignaturesNative(
+	pdf: Buffer,
+	trust: NativeTrustOptions,
+): Promise<SignatureReport[]> {
+	return edit("VERIFY_FAILED", (loaded) => loaded.verifySignatures(pdf, trust));
+}
+
+export function responderUrlNative(certificate: Buffer): string | null {
+	return run("VERIFY_FAILED", (loaded) => loaded.responderUrl(certificate));
+}
+
+export function revocationQueryNative(
+	certificate: Buffer,
+	issuer: Buffer,
+): Buffer {
+	return run("VERIFY_FAILED", (loaded) =>
+		loaded.revocationQuery(certificate, issuer),
+	);
+}
+
+export function readRevocationNative(
+	response: Buffer,
+	certificate: Buffer,
+	issuer: Buffer,
+	at: number | null,
+): RevocationAnswer {
+	return run("VERIFY_FAILED", (loaded) =>
+		loaded.readRevocation(response, certificate, issuer, at ?? undefined),
+	);
+}

package/src/responder.ts

@@ -0,0 +1,116 @@
+/**
+ * Deciding whether a revocation responder may be contacted.
+ *
+ * The address comes out of the certificate inside the document being checked,
+ * which is to say: from whoever sent the document. Following it unconditionally
+ * turns "check whether this signature is still valid" into "make my server
+ * issue an HTTP request wherever this stranger points" — the cloud metadata
+ * endpoint, a Redis on loopback, or simply a URL that confirms the document was
+ * opened and reveals the address it was opened from.
+ *
+ * So the default is a public responder over HTTP, and an application whose
+ * authority answers on the internal network says so by name. Everything
+ * refused answers `"unknown"`, never `"good"`: a responder that was not asked
+ * has told us nothing.
+ */
+
+/** Who an application is willing to ask about revocation. */
+export type ResponderPolicy =
+	| ReadonlyArray<string>
+	| ((url: URL) => boolean | Promise<boolean>);
+
+/** Hosts that are never a public certificate authority. */
+function isPrivateHost(hostname: string): boolean {
+	const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	// IPv6 loopback, unspecified, unique-local (fc00::/7) and link-local (fe80::/10).
+	if (host === "::1" || host === "::") return true;
+	if (/^f[cd][0-9a-f]{2}:/.test(host)) return true;
+	if (/^fe[89ab][0-9a-f]:/.test(host)) return true;
+	// An IPv4-mapped IPv6 address is the same machine under another spelling,
+	// and the URL parser rewrites `::ffff:127.0.0.1` as `::ffff:7f00:1` — so a
+	// check that only reads dotted quads waves loopback straight through.
+	const mapped =
+		/^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(host) ??
+		(() => {
+			const hex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+			if (hex === null) return null;
+			const packed =
+				(Number.parseInt(hex[1] as string, 16) << 16) |
+				Number.parseInt(hex[2] as string, 16);
+			return [
+				host,
+				[24, 16, 8, 0].map((shift) => (packed >>> shift) & 0xff).join("."),
+			];
+		})();
+	const literal = mapped?.[1] ?? host;
+	const parts = literal.split(".");
+	if (parts.length !== 4 || !parts.every((p) => /^\d{1,3}$/.test(p)))
+		return false;
+	const [a, b] = parts.map(Number) as [number, number, number, number];
+	return (
+		a === 0 || // this network
+		a === 127 || // loopback
+		a === 10 || // private
+		(a === 172 && b >= 16 && b <= 31) || // private
+		(a === 192 && b === 168) || // private
+		(a === 169 && b === 254) || // link-local, and the cloud metadata address
+		(a === 100 && b >= 64 && b <= 127) || // carrier-grade NAT
+		a >= 224 // multicast and reserved
+	);
+}
+
+/** Why a responder was refused, in a sentence a caller can act on. */
+export interface ResponderRefusal {
+	refused: string;
+}
+
+/**
+ * Decide whether `url` may be asked.
+ *
+ * @param policy What the application allows: a list of hostnames, or a
+ *   predicate. Absent, only public hosts over http/https are contacted.
+ */
+export async function mayAsk(
+	url: string,
+	policy?: ResponderPolicy,
+): Promise<URL | ResponderRefusal> {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return { refused: `the certificate names "${url}", which is not a URL` };
+	}
+
+	if (typeof policy === "function") {
+		return (await policy(parsed))
+			? parsed
+			: { refused: `the configured policy refused ${parsed.origin}` };
+	}
+	if (policy !== undefined) {
+		return policy.includes(parsed.hostname)
+			? parsed
+			: {
+					refused:
+						`${parsed.hostname} is not among the responders this application allows` +
+						` (${policy.join(", ") || "none"})`,
+				};
+	}
+
+	// OCSP is defined over HTTP. Anything else is a scheme somebody wanted the
+	// server to speak, not a way to ask about a certificate.
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		return {
+			refused: `the certificate names a ${parsed.protocol.replace(":", "")} responder, which is not asked`,
+		};
+	}
+	if (isPrivateHost(parsed.hostname)) {
+		return {
+			refused:
+				`the certificate names ${parsed.hostname}, an address on this network — ` +
+				"a document does not get to choose which of your own services is contacted. " +
+				"Name it in `allowedResponders` if that really is your authority.",
+		};
+	}
+	return parsed;
+}

package/src/services/main.ts

@@ -0,0 +1,48 @@
+/**
+ * Container service accessor — `import vellum from '@c9up/vellum/services/main'`.
+ *
+ * Populated by `VellumProvider.boot()`. Reading it before the provider has
+ * booted throws rather than answering with an unconfigured service, which
+ * would render with defaults nobody chose.
+ */
+
+import type { Vellum } from "../Vellum.js";
+
+let instance: Vellum | undefined;
+
+/** @internal Called by the provider once the service exists. */
+export function setVellum(service: Vellum): void {
+	instance = service;
+}
+
+/** @internal Test helper — forget the service between cases. */
+export function clearVellum(): void {
+	instance = undefined;
+}
+
+function resolve(): Vellum {
+	if (!instance) {
+		throw new Error(
+			"[vellum] Vellum service accessed before VellumProvider.boot() ran. " +
+				"Check that `@c9up/vellum/provider` is listed in your reamrc.ts providers.",
+		);
+	}
+	return instance;
+}
+
+const vellum: Vellum = new Proxy(Object.create(null), {
+	get(_target, property) {
+		// A module loader probes an imported binding for `then` to see whether
+		// it is thenable, and for well-known symbols. Answering those by
+		// resolving the service would throw during the import itself, before
+		// any provider had a chance to boot.
+		if (property === "then" || typeof property === "symbol") {
+			return undefined;
+		}
+		const service = resolve();
+		const value = Reflect.get(service, property, service);
+		return typeof value === "function" ? value.bind(service) : value;
+	},
+});
+
+export default vellum;

package/src/signers.ts

@@ -0,0 +1,149 @@
+/**
+ * Signers that need nothing but a key you hold.
+ *
+ * A signer bound to a certified provider is not here and should not be: it
+ * belongs to whoever has the account, as an adapter of its own. This package
+ * ships the contract and the one implementation that has no vendor behind it.
+ */
+
+import { VellumError } from "./errors.js";
+import {
+	attachTimestampNative,
+	signCmsNative,
+	timestampQueryNative,
+} from "./native.js";
+import type { Signer } from "./Vellum.js";
+
+/** A key you hold, and the certificate that vouches for it. */
+export interface Pkcs8SignerOptions {
+	/** The private key, PKCS#8 DER. */
+	key: Buffer;
+	/** The signer's certificate, DER. */
+	certificate: Buffer;
+	/**
+	 * The rest of the chain, DER, nearest issuer first.
+	 *
+	 * Worth supplying: a verifier that has to go and find the issuers itself
+	 * will often decide it cannot.
+	 */
+	chain?: ReadonlyArray<Buffer>;
+}
+
+/**
+ * Sign with a key held by the application.
+ *
+ * ```ts
+ * // config/vellum.ts
+ * signers: {
+ *   internal: pkcs8Signer({
+ *     key: readFileSync(app.makePath('storage/signing.key.der')),
+ *     certificate: readFileSync(app.makePath('storage/signing.crt.der')),
+ *   }),
+ * }
+ * ```
+ *
+ * This is an *advanced* signature: it proves the document has not changed
+ * since a particular key signed it. Whether that is enough is a question about
+ * the document, not about the code — where the law requires a qualified
+ * signature, the key has to live with a certified provider, and that is an
+ * adapter rather than this.
+ *
+ * PKCS#8 and DER rather than a `.p12` bundle: reading PKCS#12 in Rust is not
+ * something to put underneath a signature, and
+ * `openssl pkcs12 -in bundle.p12 -nodes` gets you here in one command.
+ */
+export function pkcs8Signer(options: Pkcs8SignerOptions): Signer {
+	if (options.key.length === 0) {
+		throw new VellumError("SIGNER_INVALID", "The signing key is empty.");
+	}
+	if (options.certificate.length === 0) {
+		throw new VellumError("SIGNER_INVALID", "The certificate is empty.");
+	}
+
+	const certificates = [options.certificate, ...(options.chain ?? [])];
+	return {
+		async sign(digest: Buffer): Promise<Buffer> {
+			return signCmsNative(
+				digest,
+				options.key,
+				certificates,
+				new Date().toISOString(),
+			);
+		},
+	};
+}
+
+/** Where to ask for a timestamp, and how. */
+export interface TimestampOptions {
+	/** The authority's RFC 3161 endpoint. */
+	url: string;
+	/** Anything the authority needs, such as an Authorization header. */
+	headers?: Record<string, string>;
+	/** How long to wait before giving up. Default 10 seconds. */
+	timeoutMs?: number;
+}
+
+/**
+ * Add a trusted timestamp to whatever `inner` signs.
+ *
+ * ```ts
+ * signers: {
+ *   internal: timestamped(pkcs8Signer({ key, certificate }), {
+ *     url: 'https://freetsa.org/tsr',
+ *   }),
+ * }
+ * ```
+ *
+ * A signature proves a document has not changed since a key signed it, not
+ * *when*. Once the signing certificate expires, a verifier cannot tell a
+ * signature made while it was valid from one forged afterwards, and stops
+ * accepting it. For a document kept for years — which is most of the documents
+ * anyone bothers to sign — a timestamp is what keeps it verifiable.
+ *
+ * It wraps any signer, so it works over a provider's as well as the local one.
+ * The token goes on as an unsigned attribute, which is what lets it be added
+ * without disturbing the signature.
+ *
+ * The signature grows by a few kilobytes, so a document prepared with a tight
+ * `capacity` may need a larger one.
+ */
+export function timestamped(inner: Signer, options: TimestampOptions): Signer {
+	return {
+		async sign(digest: Buffer): Promise<Buffer> {
+			const cms = await inner.sign(digest);
+			const { query, nonce } = timestampQueryNative(cms);
+
+			let answer: Response;
+			try {
+				answer = await fetch(options.url, {
+					method: "POST",
+					headers: {
+						"content-type": "application/timestamp-query",
+						...options.headers,
+					},
+					body: new Uint8Array(query),
+					signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+				});
+			} catch (error) {
+				throw new VellumError(
+					"TIMESTAMP_UNREACHABLE",
+					`The timestamp authority at ${options.url} could not be reached.`,
+					{ cause: error },
+				);
+			}
+
+			if (!answer.ok) {
+				throw new VellumError(
+					"TIMESTAMP_REFUSED",
+					`The timestamp authority at ${options.url} answered ${answer.status}.`,
+				);
+			}
+
+			return attachTimestampNative(
+				cms,
+				Buffer.from(await answer.arrayBuffer()),
+				nonce,
+			);
+		},
+	};
+}