@c9up/vellum 0.1.0

package/src/VellumProvider.ts

@@ -0,0 +1,51 @@
+/**
+ * Wires `config/vellum.ts` into the container.
+ *
+ * Vellum does not import `@c9up/ream`: the slice of the host it needs is
+ * duck-typed below, which is what keeps the package publishable on its own and
+ * usable from a host that is not Ream.
+ */
+
+import { setVellum } from "./services/main.js";
+import "./augmentations.js";
+import type { VellumConfig } from "./Vellum.js";
+import { Vellum } from "./Vellum.js";
+
+interface VellumContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): Promise<T>;
+}
+
+interface VellumConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+
+export interface VellumAppContext {
+	container: VellumContainer;
+	config: VellumConfigStore;
+}
+
+export default class VellumProvider {
+	constructor(protected app: VellumAppContext) {}
+
+	register(): void {
+		this.app.container.singleton(Vellum, () => {
+			// An absent config is not an error: every rendering option has a
+			// defensible default, so a provider registered without
+			// `config/vellum.ts` still renders PNG at natural size.
+			const config = this.app.config.get<VellumConfig>("vellum") ?? {};
+			return new Vellum(config);
+		});
+		// String alias, so a consumer that cannot import Vellum still resolves
+		// it — the same convention the other providers follow.
+		this.app.container.singleton("vellum", () =>
+			this.app.container.resolve<Vellum>(Vellum),
+		);
+	}
+
+	async boot(): Promise<void> {
+		setVellum(await this.app.container.resolve<Vellum>(Vellum));
+	}
+
+	async shutdown(): Promise<void> {}
+}

package/src/augmentations.ts

@@ -0,0 +1,25 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make('vellum')` returns.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute its own — the comment on the
+ * interface names `auth` (warden), `logger` (spectrum) and `db` (atlas) as
+ * exactly this. Without the augmentation, resolving by the string token falls
+ * back to `unknown` and every call site has to assert a type it cannot prove.
+ *
+ * AdonisJS does the same from its own packages' providers.
+ *
+ * Loaded from the package barrel and from the provider, so registering vellum
+ * is enough — an application writes no `declare module` of its own.
+ */
+
+// Referenced so the augmentation below resolves the module it augments.
+import type {} from "@c9up/ream/types";
+import type { Vellum } from "./Vellum.js";
+
+declare module "@c9up/ream/types" {
+	interface ContainerBindings {
+		/** The PDF service, bound by `VellumProvider`. */
+		vellum: Vellum;
+	}
+}

package/src/config.ts

@@ -0,0 +1,47 @@
+import type { ImageFormat, VellumConfig } from "./Vellum.js";
+
+/**
+ * The config as it is WRITTEN, before validation.
+ *
+ * `format` is a plain string here because that is what an environment yields:
+ * `env.get('VELLUM_FORMAT', 'png')` is a `string`, and a config that only
+ * accepted the union could not read one — the generated `config/vellum.ts` did
+ * not typecheck in the project it was written into.
+ */
+export interface VellumConfigInput extends Omit<VellumConfig, "format"> {
+	format?: string;
+}
+
+/**
+ * Define the rendering defaults, in `config/vellum.ts`.
+ *
+ * ```ts
+ * import { defineConfig } from '@c9up/vellum'
+ *
+ * export default defineConfig({
+ *   format: 'jpeg',
+ *   quality: 82,
+ *   width: 1200,
+ * })
+ * ```
+ *
+ * Named deviation: there is no `default` + service list here, because there is
+ * one rendering engine rather than several. Should a second one ever exist,
+ * that is when the manager gains `use()` — not before, when it would only be
+ * an indirection over a single implementation.
+ */
+export function defineConfig(config: VellumConfigInput): VellumConfig {
+	const { format, ...rest } = config;
+	if (format === undefined) return rest;
+	if (format !== "png" && format !== "jpeg") {
+		// Named at boot, with the value, rather than at the first render of a
+		// document nobody was looking at.
+		throw new Error(
+			`[vellum] config/vellum.ts asks for format ${JSON.stringify(format)}; ` +
+				'it is "png" or "jpeg".',
+		);
+	}
+	return { ...rest, format: format as ImageFormat };
+}
+
+export type { VellumConfig };

package/src/configure.ts

@@ -0,0 +1,92 @@
+/**
+ * `ream configure @c9up/vellum` — wire PDF rendering in one command.
+ *
+ * The provider alone is not enough: it reads `config/vellum.ts`, and a package
+ * registered without one renders with defaults the application never chose.
+ * Writing both together is what makes `ream add` mean installed AND working.
+ */
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	// The config below reads these, so they are declared here. Writing the file
+	// without them leaves an application whose config asks the environment for
+	// something nothing ever put there.
+	await codemods.addEnvVars({
+		VELLUM_FORMAT: "png",
+	});
+
+	await codemods.addProvider("@c9up/vellum/provider");
+	await codemods.writeFile(
+		"config/vellum.ts",
+		`import { defineConfig } from '@c9up/vellum'
+import env from '#start/env'
+
+export default defineConfig({
+  // Defaults for every render. Any call can override them.
+  format: env.get('VELLUM_FORMAT', 'png'),
+
+  // 1 is 72 DPI — the page's natural size. Raise it for print, or set
+  // \`width\` instead when what matters is the pixel width of a preview.
+  scale: 1,
+
+  // Only read when the format is 'jpeg'.
+  quality: 82,
+
+  // A PDF paints no background of its own, so rendering it transparent
+  // makes black text invisible over a dark viewer.
+  background: '#ffffff',
+
+  // Fonts to write text with, by the name you ask for them by. A font
+  // declared here is embedded in the document, subsetted to the characters
+  // written, which lifts the WinAnsi limit of the standard fonts.
+  //
+  // fonts: {
+  //   body: app.makePath('resources/fonts/Inter-Regular.ttf'),
+  // },
+
+  // Who may sign a document. A signer is handed the digest of what the
+  // signature covers and returns the CMS to embed — it never sees the
+  // document, which is what makes a key you hold and a key held by a
+  // certified provider the same interface.
+  //
+  // Wrap a signer in timestamped() to add a trusted timestamp, without which
+  // a signature stops being verifiable once its certificate expires.
+  //
+  // signers: {
+  //   internal: pkcs8Signer({
+  //     key: readFileSync(app.makePath('storage/signing.key.der')),
+  //     certificate: readFileSync(app.makePath('storage/signing.crt.der')),
+  //   }),
+  //   stamped: timestamped(pkcs8Signer({ ... }), {
+  //     url: 'https://freetsa.org/tsr',
+  //   }),
+  //   qualified: myProviderAdapter({ ... }),
+  // },
+
+  // Certificates to trust when CHECKING a signature — typically the roots
+  // your jurisdiction's supervisory body publishes as a trusted list. With
+  // none, every signature comes back untrusted, which is the honest answer.
+  //
+  // trustedAnchors: [
+  //   readFileSync(app.makePath('storage/anchors/authority.pem')),
+  // ],
+
+  // Which revocation responders may be contacted when checkRevocation is
+  // asked for. The address comes out of the certificate inside the document
+  // being checked, so by default only public hosts are asked — a document
+  // does not get to point this server at your own network. Name yours here
+  // when your authority answers somewhere that rule excludes.
+  //
+  // allowedResponders: ['ocsp.internal.example'],
+})`,
+	);
+}

package/src/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * VellumError — structured error for PDF operations.
+ */
+export class VellumError extends Error {
+	readonly code: string;
+
+	constructor(code: string, message: string, options?: ErrorOptions) {
+		super(message, options);
+		this.name = "VellumError";
+		// One namespace, one prefix. `E_` is what every framework code carries,
+		// and the package name after it says which package raised it. A code
+		// that already starts with `E_` passes through untouched, so a shared
+		// identifier keeps its exact spelling.
+		this.code = code.startsWith("E_") ? code : `E_VELLUM_${code}`;
+	}
+
+	override toString(): string {
+		return `${this.name} [${this.code}]: ${this.message}`;
+	}
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @c9up/vellum — PDF toolkit.
+ *
+ * Rendering pages to images, reading text and metadata, reshaping documents,
+ * stamping them, filling and flattening their forms, and signing them. The
+ * engine is Rust behind NAPI, because PDF has no adequate JavaScript
+ * implementation — a capability the platform lacks, not an optimisation.
+ *
+ * ```ts
+ * import vellum from '@c9up/vellum/services/main'
+ *
+ * const preview = await vellum.render(pdf, { page: 1, width: 1200 })
+ * const pages = await vellum.renderAll(pdf, { format: 'jpeg' })
+ * ```
+ */
+
+import "./augmentations.js";
+
+export { defineConfig } from "./config.js";
+export { VellumError } from "./errors.js";
+export type {
+	DocumentInfo,
+	DocumentMetadata,
+	FormField,
+	PageDimensions,
+	PageSize,
+	RevocationAnswer,
+	SignatureReport,
+} from "./native.js";
+export { isNativeAvailable, VellumNativeRequiredError } from "./native.js";
+export type { ResponderPolicy } from "./responder.js";
+export type { Pkcs8SignerOptions, TimestampOptions } from "./signers.js";
+export { pkcs8Signer, timestamped } from "./signers.js";
+export type {
+	CheckedSignature,
+	ImageFormat,
+	PageOptions,
+	RenderOptions,
+	Signer,
+	SignOptions,
+	StampOptions,
+	StandardFont,
+	TextStampOptions,
+	VellumConfig,
+	VerifyOptions,
+} from "./Vellum.js";
+export { Vellum } from "./Vellum.js";
+
+import type { DocumentInfo, PageSize } from "./native.js";
+import { createBlankNative, inspectNative } from "./native.js";
+
+/**
+ * Report the shape of a PDF: how many pages it has, which version of the
+ * format it claims, and whether it is encrypted.
+ *
+ * The `/Info` strings are read by {@link Vellum.metadata} instead, which has
+ * the decoder they need: they are stored in UTF-16BE, UTF-8 or
+ * PDFDocEncoding, and guessing between them mangles every accent.
+ */
+export function inspect(pdf: Buffer): DocumentInfo {
+	return inspectNative(pdf);
+}
+
+/**
+ * Author a document of blank pages, sized in points (72 per inch).
+ *
+ * Draw onto them with {@link Vellum.stamp} and {@link Vellum.stampText}.
+ */
+export function createBlank(pages: ReadonlyArray<PageSize>): Buffer {
+	return createBlankNative(pages);
+}
+
+/** A4 in points, the size every document here starts from. */
+export const A4: PageSize = { width: 595.28, height: 841.89 };

package/src/native/generated.ts

@@ -0,0 +1,375 @@
+// GENERATED FROM THE RUST — do not edit.
+//
+// Produced by scripts/generate-napi-types.mjs from napi-derive's type-def
+// output. Editing this file by hand puts it back where it started: a
+// description that can disagree with the code it describes.
+
+export interface DocumentInfo {
+	pageCount: number;
+	version: string;
+	encrypted: boolean;
+}
+
+export interface PageSize {
+	/** Width in points (72 per inch). A4 is 595.28. */
+	width: number;
+	/** Height in points. A4 is 841.89. */
+	height: number;
+}
+
+/** Rasterising options, as a plain JavaScript object. */
+
+export interface RenderOptions {
+	/**
+	 * Multiplier over the page's natural size, 1 being 72 DPI. Default 1.
+	 * Ignored when `width` is given.
+	 */
+	scale?: number;
+	/** Target width in pixels. Wins over `scale`. */
+	width?: number;
+	/** `"png"` (default) or `"jpeg"`. */
+	format?: string;
+	/** JPEG quality, 1-100. Only valid alongside `format: "jpeg"`. */
+	quality?: number;
+	/** `#rgb`, `#rrggbb`, `#rrggbbaa` or `"transparent"`. Default opaque white. */
+	background?: string;
+	/**
+	 * The most pixels one page may rasterise to. 50 million by default —
+	 * room for A4 at 600 DPI. A page declares its own size, so without a
+	 * ceiling a document alone could ask for gigabytes.
+	 */
+	maxPixels?: number;
+}
+
+export interface PageDimensions {
+	/** Width in points, before scaling. */
+	width: number;
+	/** Height in points, before scaling. */
+	height: number;
+}
+
+/** What the `/Info` dictionary says about a document. */
+
+export interface DocumentMetadata {
+	title?: string;
+	author?: string;
+	subject?: string;
+	keywords?: string;
+	/** The application that authored the content. */
+	creator?: string;
+	/** The application that wrote the PDF. */
+	producer?: string;
+	/**
+	 * ISO 8601 when the producer wrote a conforming date, otherwise the raw
+	 * string it did write.
+	 */
+	createdAt?: string;
+	modifiedAt?: string;
+}
+
+/** Where and how an image is laid onto a page. */
+
+export interface StampOptions {
+	/** Which page, counting from zero. Absent stamps every page. */
+	page?: number;
+	/** Points from the left edge. Default 0. */
+	x?: number;
+	/** Points from the TOP edge. Default 0. */
+	y?: number;
+	/** Drawn width in points. With `height` absent, the ratio is kept. */
+	width?: number;
+	/** Drawn height in points. With `width` absent, the ratio is kept. */
+	height?: number;
+	/** 0 is invisible, 1 is opaque. Default 1. */
+	opacity?: number;
+}
+
+/** Where and how a line of text is written onto a page. */
+
+export interface TextStampOptions {
+	/** Which page, counting from zero. Absent writes on every page. */
+	page?: number;
+	/** Points from the left edge. Default 0. */
+	x?: number;
+	/** Points from the TOP edge, to the text's baseline. Default 0. */
+	y?: number;
+	/** Type size in points. Default 12. */
+	size?: number;
+	/**
+	 * One of the 14 standard fonts, e.g. `"Helvetica"`, `"Times-Roman"`.
+	 * Ignored when `fontData` is given.
+	 */
+	font?: string;
+	/**
+	 * A TrueType or OpenType file to embed, subsetted to the text. Lifts the
+	 * WinAnsi limit of the standard fonts, at the cost of carrying the glyphs
+	 * in the document.
+	 */
+	fontData?: Buffer;
+	/** `#rgb` or `#rrggbb`. Default black. */
+	color?: string;
+	/** 0 is invisible, 1 is opaque. Default 1. */
+	opacity?: number;
+}
+
+/** One interactive field of a document's form. */
+
+export interface FormField {
+	/**
+	 * The fully qualified name — every ancestor's partial name joined with
+	 * dots. This is the name used to fill the field in.
+	 */
+	name: string;
+	/**
+	 * `"text"`, `"checkbox"`, `"radio"`, `"pushButton"`, `"dropdown"`,
+	 * `"listBox"` or `"signature"`.
+	 */
+	kind: string;
+	value?: string;
+	/**
+	 * What a choice field offers, or the states a checkbox and radio accept.
+	 * A checkbox's "on" state is chosen by the document, so ticking it means
+	 * writing one of these.
+	 */
+	options: Array<string>;
+	readOnly: boolean;
+	required: boolean;
+	multiline: boolean;
+	password: boolean;
+	maxLength?: number;
+}
+
+/** What the signature says about itself. */
+
+export interface SignatureOptions {
+	/** Why the document was signed. */
+	reason?: string;
+	/** Where it was signed. */
+	location?: string;
+	/** How to reach the signatory. */
+	contact?: string;
+	/** Who signed, as it should be displayed. */
+	name?: string;
+	/** When, as an ISO 8601 instant. */
+	signedAt?: string;
+	/** Bytes reserved for the signature value. Default 16384. */
+	capacity?: number;
+}
+
+/** A document with room for a signature, and the digest to sign. */
+
+export interface PreparedSignature {
+	document: Buffer;
+	/** SHA-256 of everything the signature covers. */
+	digest: Buffer;
+}
+
+/** A query for a timestamp authority, and the nonce it has to echo back. */
+
+export interface TimestampQuery {
+	/** The DER to post to the authority. */
+	query: Buffer;
+	/** Opaque: hand it back to `attachTimestamp` unchanged. */
+	nonce: Buffer;
+}
+
+/** What one signature on a document turns out to be. */
+
+export interface SignatureReport {
+	/** The field the signature sits in. */
+	field: string;
+	/** The signed range runs to the last byte, so nothing was appended after. */
+	coversWholeDocument: boolean;
+	/** The document's bytes hash to what the signature committed to. */
+	digestMatches: boolean;
+	/** The signature verifies against the certificate it carries. */
+	signatureVerifies: boolean;
+	/** Who the certificate says signed. */
+	signer?: string;
+	/** When the signature says it was made. */
+	signedAt?: string;
+	/** An authority has vouched for when, so it outlives the certificate. */
+	timestamped: boolean;
+	/** A path was found from the signer's certificate to a trusted anchor. */
+	trusted: boolean;
+	/** That path, the signer first and the anchor last. */
+	chain: Array<string>;
+	/**
+	 * Where the instant used to judge the path came from: `"timestamp"`,
+	 * `"claimed"` or `"unknown"`.
+	 */
+	moment: string;
+	/** That instant, in seconds since the epoch. */
+	momentAt?: number;
+	/** The certificate that signed, DER. */
+	signerCertificate?: Buffer;
+	/** The certificate that issued it, DER — who answers about revocation. */
+	issuerCertificate?: Buffer;
+	/** Everything that could not be checked, or checked out wrong. */
+	problems: Array<string>;
+}
+
+/** What a caller is willing to believe. */
+
+export interface TrustOptions {
+	/**
+	 * Certificates to trust as roots, DER or PEM. Without them nothing can be
+	 * trusted, which is what the report will say.
+	 */
+	anchors?: Array<Buffer>;
+}
+
+/** What a responder's answer says. */
+
+export interface RevocationAnswer {
+	/** `"good"`, `"revoked"` or `"unknown"`. */
+	status: string;
+	/** When it was withdrawn, or why nobody could be believed. */
+	detail?: string;
+}
+
+export declare function inspect(bytes: Buffer): DocumentInfo;
+
+export declare function createBlank(pages: Array<PageSize>): Buffer;
+
+export declare function renderPage(
+	bytes: Buffer,
+	pageIndex: number,
+	options?: RenderOptions | undefined | null,
+): Promise<Buffer>;
+
+export declare function renderAll(
+	bytes: Buffer,
+	options?: RenderOptions | undefined | null,
+): Promise<Buffer[]>;
+
+export declare function pageDimensions(bytes: Buffer): Array<PageDimensions>;
+
+export declare function metadata(bytes: Buffer): DocumentMetadata;
+
+export declare function extractText(
+	bytes: Buffer,
+	pageIndex: number,
+): Promise<string>;
+
+export declare function extractTextAll(bytes: Buffer): Promise<string[]>;
+
+export declare function merge(documents: Array<Buffer>): Promise<Buffer>;
+
+export declare function selectPages(
+	bytes: Buffer,
+	pages: Array<number>,
+): Promise<Buffer>;
+
+export declare function split(bytes: Buffer): Promise<Buffer[]>;
+
+export declare function rotate(
+	bytes: Buffer,
+	degrees: number,
+	pages?: Array<number> | undefined | null,
+): Promise<Buffer>;
+
+export declare function stamp(
+	pdf: Buffer,
+	image: Buffer,
+	options?: StampOptions | undefined | null,
+): Promise<Buffer>;
+
+export declare function stampText(
+	pdf: Buffer,
+	text: string,
+	options?: TextStampOptions | undefined | null,
+): Promise<Buffer>;
+
+export declare function formFields(bytes: Buffer): Array<FormField>;
+
+/**
+ * Fill the named fields. Keys are the fully qualified names `formFields`
+ * reports.
+ */
+
+export declare function fillForm(
+	pdf: Buffer,
+	values: Record<string, string>,
+): Promise<Buffer>;
+
+/** Paint every field into the page and drop the interactive layer. */
+
+export declare function flattenForm(pdf: Buffer): Promise<Buffer>;
+
+/** Write a document with room for a signature, and say what has to be signed. */
+
+export declare function prepareSignature(
+	pdf: Buffer,
+	options?: SignatureOptions | undefined | null,
+): Promise<PreparedSignature>;
+
+/** Put the signature value into the space that was reserved for it. */
+
+export declare function embedSignature(
+	prepared: Buffer,
+	value: Buffer,
+): Promise<Buffer>;
+
+/**
+ * Turn a digest into the CMS a PDF signature carries, with a key we hold.
+ *
+ * The key is PKCS#8 DER and the certificates are DER, the signer's first.
+ */
+
+export declare function signCms(
+	digest: Buffer,
+	key: Buffer,
+	certificates: Array<Buffer>,
+	signedAt: string,
+): Promise<Buffer>;
+
+/** Build the query to post to a timestamp authority. */
+
+export declare function timestampQuery(cms: Buffer): TimestampQuery;
+
+/** Attach the authority's answer to the signature. */
+
+export declare function attachTimestamp(
+	cms: Buffer,
+	response: Buffer,
+	nonce: Buffer,
+): Buffer;
+
+/**
+ * Report on every signature the document carries.
+ *
+ * This establishes integrity and authorship, not trust: it does not ask
+ * whether the certificate comes from an authority you accept, nor whether it
+ * has been revoked.
+ */
+
+export declare function verifySignatures(
+	pdf: Buffer,
+	trust?: TrustOptions | undefined | null,
+): Promise<SignatureReport[]>;
+
+/** The responder a certificate names, if it names one. */
+
+export declare function responderUrl(certificate: Buffer): string | null;
+
+/** Build the question to post to a revocation responder. */
+
+export declare function revocationQuery(
+	certificate: Buffer,
+	issuer: Buffer,
+): Buffer;
+
+/**
+ * Read a responder's answer about a certificate.
+ *
+ * `at` is the instant the document was signed: a certificate withdrawn after
+ * that does not taint what it signed before.
+ */
+
+export declare function readRevocation(
+	response: Buffer,
+	certificate: Buffer,
+	issuer: Buffer,
+	at?: number | undefined | null,
+): RevocationAnswer;