@reportwright/pdf 0.1.0-beta.10 → 0.1.0-beta.11

package/examples/p12-signer.mjs

@@ -0,0 +1,30 @@
+// A signer for pdf.sign from a PKCS#12 file (.p12 / .pfx: a key and its certificates under a password), through
+// cmsSigner and node-forge (npm i node-forge; it is not a dependency of @reportwright/pdf). RSA keys, PKCS#1 v1.5.
+//
+//   import { p12Signer } from '@reportwright/pdf/examples/p12-signer.mjs';
+//   await pdf.sign({ name: 'Signature1' }, { signer: p12Signer(fs.readFileSync('id.p12'), 'password') });
+import forge from 'node-forge';
+import { cmsSigner } from '@reportwright/pdf';
+
+/** @param {Uint8Array} p12 the file's bytes @param {string} password */
+export function p12Signer(p12, password) {
+  const asn1 = forge.asn1.fromDer(forge.util.createBuffer(Buffer.from(p12).toString('binary')));
+  const box = forge.pkcs12.pkcs12FromAsn1(asn1, password); // a wrong password throws here
+  const bags = (type) => box.getBags({ bagType: type })[type] ?? [];
+  const key = [...bags(forge.pki.oids.pkcs8ShroudedKeyBag), ...bags(forge.pki.oids.keyBag)][0]?.key;
+  if (!key) throw new TypeError('p12Signer: no private key in the file');
+  const certs = bags(forge.pki.oids.certBag).map((b) => b.cert);
+  // the signer's certificate first: the one whose public key is the key's
+  const mine = certs.findIndex((c) => c.publicKey.n?.equals(key.n));
+  if (mine < 0) throw new TypeError("p12Signer: no certificate for the file's key");
+  certs.unshift(...certs.splice(mine, 1));
+  return cmsSigner({
+    certs: certs.map((c) => forge.pki.certificateToPem(c)).join('\n'),
+    keyAlgorithm: 'rsa',
+    sign(bytes, hash) {
+      const md = { 'SHA-256': forge.md.sha256, 'SHA-384': forge.md.sha384, 'SHA-512': forge.md.sha512 }[hash].create();
+      md.update(Buffer.from(bytes).toString('binary'));
+      return Uint8Array.from(Buffer.from(key.sign(md), 'binary'));
+    },
+  });
+}

package/index.d.ts

@@ -336,6 +336,9 @@ export interface Path {
   svg(d: string): this;
 }
 
+/** SVG path data `d` as PDF path operators (m, l, c, h) in SVG user space; scaleY -1 flips y. Malformed data throws a TypeError. */
+export function svgPathOps(d: string, opts?: { scaleY?: number }): string;
+
 /** A gradient or tiling pattern made by a page of this document (an opaque handle: copies and forgeries are refused). */
 export interface Gradient { readonly type: 'gradient' }
 export interface TilingPattern { readonly type: 'tiling' }
@@ -547,6 +550,22 @@ export interface Field {
   readonly type: 'field';
   readonly kind: 'text' | 'checkbox' | 'radio' | 'combo' | 'list' | 'button' | 'signature';
   readonly name: string;
+  /** the widget's object number (field and widget are one dictionary), for a structure tree's OBJR; 0 when flattened. Not on a radio group */
+  readonly widgetRef?: number;
+}
+/**
+ * A caller's own appearance for a field (pdf.core callers): each state's content-stream operators (Latin-1), written
+ * exactly as the normal appearance (/AP /N); resources: the object number of its Resources ("12 0 R", written through
+ * pdf.core), default the shared Resources (which hold every font registered with core.resource('Font', …)).
+ */
+export interface OwnAppearance { normal: string; resources?: string }
+/** A caller's appearance, /DA and structure link for a text-bearing field */
+export interface OwnTextLook {
+  appearance?: OwnAppearance;
+  /** the default appearance written as /DA ("/F1 12 Tf 0 g": printable ASCII with Tf); with appearance, font is not needed */
+  da?: string;
+  /** /StructParent, for a caller's own structure tree (not with tagged: the built-in tagger links fields itself) */
+  structParent?: number;
 }
 /** Where a widget goes: a page of this PDF and a box (top-left space). */
 export interface WidgetBox { page: Page; x?: number; y?: number; width: number; height: number }
@@ -572,7 +591,9 @@ export interface FieldTextOptions {
   align?: 'left' | 'center' | 'right';
 }
 export type CheckStyle = 'check' | 'cross' | 'circle' | 'square' | 'diamond' | 'star';
-export interface TextFieldOptions extends FieldOptions, FieldTextOptions {
+export interface TextFieldOptions extends FieldOptions, Omit<FieldTextOptions, 'font'>, OwnTextLook {
+  /** required unless both appearance and da are given */
+  font?: Font;
   /** at most 100,000 characters (and maxLen); line breaks only when multiline */
   value?: string;
   defaultValue?: string;
@@ -592,6 +613,10 @@ export interface CheckboxOptions extends FieldOptions {
   style?: CheckStyle;
   /** the mark's colour */
   color?: Color;
+  /** the caller's own on and off appearances (operators), instead of the drawn mark */
+  appearance?: { on: string; off: string; resources?: string };
+  /** /StructParent, for a caller's own structure tree */
+  structParent?: number;
 }
 export interface RadioGroupOptions extends Omit<FieldOptions, keyof WidgetBox> {
   /** 1–1000 buttons, each with its own export value (the same one only with radiosInUnison) */
@@ -607,7 +632,9 @@ export interface RadioGroupOptions extends Omit<FieldOptions, keyof WidgetBox> {
 }
 /** an option: one string (export value and display text), or [export value, display text] */
 export type ChoiceOption = string | readonly [string, string];
-export interface ChoiceOptions extends FieldOptions, FieldTextOptions {
+export interface ChoiceOptions extends FieldOptions, Omit<FieldTextOptions, 'font'>, OwnTextLook {
+  /** required unless both appearance and da are given */
+  font?: Font;
   /** at most 10,000, in the order given (the Sort flag is never set); export values unique */
   options: ChoiceOption[];
 }
@@ -633,7 +660,11 @@ export interface ButtonOptions extends FieldOptions, Partial<FieldTextOptions> {
   /** the face when pressed (/D; not in PDF/A, whose appearances have /N only) */
   pressedBackground?: Color;
 }
-export interface SignatureOptions extends FieldOptions {
+/** No width and height: an invisible field (a zero /Rect, /F 132), on page when given (still open), else on no page (AcroForm only) */
+export interface SignatureOptions extends Omit<FieldOptions, 'page' | 'width' | 'height'> {
+  page?: Page;
+  width?: number;
+  height?: number;
   /** /Lock: the fields signing locks */
   lock?: { action?: 'All' } | { action: 'Include' | 'Exclude'; fields: (string | Field)[] };
 }
@@ -651,6 +682,78 @@ export interface FormScope {
   signature(name: string, o: SignatureOptions): Field;
 }
 
+/**
+ * The extension API (`pdf.core`): the object writer, the shared Resources, the catalog and the end-of-document hooks
+ * that every feature module works through (ARCHITECTURE.md, "Extension points"). A caller writing its own content
+ * streams and objects (the ReportWright engine) uses it beside the Pdf methods. Not covered by semver in 0.x.
+ * Object text is PDF syntax: `"12 0 R"`, `"<< /Type /XObject … >>"`. In an encrypted file every string in it (literal
+ * or hex) is encrypted when the object is written.
+ */
+export interface PdfCore {
+  /** a new object number, for an object written later with write() (or writeStream, writeBig) */
+  reserve(): number;
+  /** write object n now: a dictionary or any value, and for a stream its bytes already filtered (/Length is added). Small objects go into object streams */
+  write(n: number, dict: string, stream?: Uint8Array): Promise<void> | undefined;
+  /** write object n as a stream of raw bytes, Flate-compressed (adding /Filter) unless compress is off */
+  writeStream(n: number, dict: string, raw: Uint8Array): Promise<void> | undefined;
+  /** write object n whose text may be too long to hold (head, the parts as they come, tail) */
+  writeBig(n: number, head: string, parts: Iterable<string>, tail: string): Promise<void>;
+  /** reserve and write */
+  object(dict: string, stream?: Uint8Array): Promise<number>;
+  /** a name (without the slash) in the shared Resources dictionary of every page for a value ("12 0 R" or an inline dictionary); the same value gets the same name */
+  resource(kind: 'Font' | 'XObject' | 'ExtGState' | 'Pattern' | 'Shading' | 'ColorSpace' | 'Properties', value: string, name?: string): string;
+  /**
+   * an embedded image (pdf.embedImage) for a caller's own content stream: its name in the shared Resources, its object
+   * number, whether it has transparency (the page then needs a transparency /Group, as page.image sets) and its EXIF
+   * orientation as a unit-square matrix. Draw it with `q w 0 0 h x y cm <orientation> cm /<name> Do Q`
+   */
+  imageResource(image: Image): { name: string; ref: number; alpha: boolean; orientation: [number, number, number, number, number, number] };
+  /** the shared Resources dictionary's object number (a form XObject drawing with page resources uses it) */
+  readonly resourcesRef: number;
+  /** a catalog entry (key without the slash), read when the catalog is written: finishers may still set it */
+  catalog(key: string, value: string): void;
+  /** run fn at end(), after the last page is written and before the fonts and the catalog; in registration order */
+  onFinish(fn: () => Promise<void> | void): void;
+  /** a font object written after every finisher (see Font in src/document.js) */
+  addFont(font: unknown): void;
+  /** page i's object number (0-based), reserved ahead when the page does not exist yet */
+  pageRef(i: number): number;
+  /** page i's height, once the page exists */
+  pageHeight(i: number): number | undefined;
+  readonly pageCount: number;
+  /** a warning in end()'s result */
+  warn(message: string): void;
+  /** run fn after every write queued before it (writes outside a page or a finisher must go through it: the object writer is not re-entrant) */
+  serial<T>(fn: () => Promise<T>): Promise<T>;
+  /** the first failure of a queued write, or null */
+  readonly failed: unknown;
+  /** the options a module must respect */
+  readonly compress: boolean;
+  readonly pdfa: boolean;
+  readonly pdfaLevel: { part: 1 | 2 | 3; conformance: 'a' | 'b' | 'u'; unicode: boolean } | null;
+  readonly tagged: boolean;
+  readonly signal: AbortSignal;
+  /** the Info dictionary's text to write instead of the one made from the options (null: made from the options) */
+  info: string | null;
+  /** the XMP packet to write instead of the one made from the options */
+  xmp: Uint8Array | null;
+  /** more XMP schemas (standards/xmp.js Extension), pushed before the end */
+  xmpExtensions: unknown[];
+  /** made to be signed (createPdf's sign option): every byte is hashed */
+  readonly signing: boolean;
+  /** the AcroForm's /SigFlags (pdf.sign sets 3) */
+  sigFlags: number;
+  /** the signature dictionary written as the file's last object (security/sign.js); internal */
+  last: unknown;
+  /** the structure tree (tags/tags.js) when tagged, else null: tags.link(page, annotRef, 'Link' | 'Annot') gives an annotation its element (with an OBJR) and returns its /StructParent */
+  tags: { link(page: Page, annotRef: number, type?: 'Link' | 'Annot'): number; [k: string]: unknown } | null;
+  /** internal: the page queue (used by Page and createPdf) */
+  newPage(page: unknown): number;
+  opened(page: unknown): void;
+  queuePage(page: unknown): Promise<void>;
+  finish(blank: () => unknown): Promise<{ pages: number; bytes: number; warnings: string[] }>;
+}
+
 export interface Pdf {
   standardFont(name: StandardFontName): Font;
   /** a TrueType or OpenType/CFF font; subset by default; shaper: text goes through it (complex scripts);
@@ -691,7 +794,7 @@ export interface Pdf {
   /** end open pages, write the rest, end the sink */
   end(): Promise<{ pages: number; bytes: number; warnings: string[] }>;
   /** the extension API (ARCHITECTURE.md); not covered by semver in 0.x */
-  readonly core: unknown;
+  readonly core: PdfCore;
 }
 
 export function createPdf(sink: Sink, options?: PdfOptions): Pdf;
@@ -699,6 +802,38 @@ export function createPdf(sink: Sink, options?: PdfOptions): Pdf;
 export function toBytes(build: (pdf: Pdf) => unknown, options?: PdfOptions): Promise<Uint8Array>;
 export const STANDARD_NAMES: StandardFontName[];
 
+/** A font file read for metrics and glyph lookup. Throws a TypeError on bytes that are not a TrueType or OpenType font. */
+export interface FontInfo {
+  /** glyph count (maxp) */
+  readonly numGlyphs: number;
+  /** PostScript name (name ID 6), as written in the file */
+  readonly postscriptName: string;
+  /** OS/2 fsType embedding flags (0 means installable embedding) */
+  readonly fsType: number;
+  readonly unitsPerEm: number;
+  /** hhea ascent, in font units */
+  readonly ascent: number;
+  /** hhea descent, in font units (negative) */
+  readonly descent: number;
+  /** true for an OpenType font with CFF outlines */
+  readonly isCFF: boolean;
+  /** horizontal advance of a glyph ID, in font units; 0 for an ID past numGlyphs */
+  advance(glyphId: number): number;
+  /** whether the Unicode cmap maps this code point to a glyph */
+  hasGlyph(codePoint: number): boolean;
+  /** the glyph ID for a code point, 0 when none */
+  glyphForCodePoint(codePoint: number): number;
+}
+
+/** Read a font file's metrics and cmap. */
+export function readFont(bytes: Uint8Array): FontInfo;
+
+/**
+ * Check a font subset before embedding it. Returns a description of the first problem (header, table directory, loca
+ * order, CFF INDEXes), or null when the subset is well formed. Never throws.
+ */
+export function checkSubset(bytes: Uint8Array): string | null;
+
 // ---- reading and modifying (group H) ----
 
 export type PdfReadErrorCode = 'E_MALFORMED' | 'E_BUDGET' | 'E_DEPTH' | 'E_CYCLE' | 'E_TIMEOUT' | 'E_ABORTED' | 'E_PASSWORD' | 'E_ENCRYPTED' | 'E_UNSUPPORTED' | 'E_ACTIVE' | 'E_SIGNED';

package/package.json

@@ -1,23 +1,83 @@
 {
   "name": "@reportwright/pdf",
-  "version": "0.1.0-beta.10",
+  "version": "0.1.0-beta.11",
   "description": "A streaming PDF writer for Node and browsers with no runtime dependencies: flat memory, PDF/A-1b to 3a, PDF/UA-1, Factur-X, embedded TrueType with Unicode text.",
   "type": "module",
   "license": "MIT",
   "author": "Arun Mallikarjun",
   "homepage": "https://github.com/MrArun005/reportwright/tree/main/packages/pdf#readme",
-  "bugs": { "url": "https://github.com/MrArun005/reportwright/issues" },
-  "repository": { "type": "git", "url": "git+https://github.com/MrArun005/reportwright.git", "directory": "packages/pdf" },
-  "keywords": ["pdf", "pdf-writer", "streaming", "pdf-a", "pdf-ua", "factur-x", "zugferd", "accessibility", "truetype", "encryption", "aes", "pades", "digital-signature", "reportwright"],
-  "publishConfig": { "access": "public" },
+  "bugs": {
+    "url": "https://github.com/MrArun005/reportwright/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrArun005/reportwright.git",
+    "directory": "packages/pdf"
+  },
+  "keywords": [
+    "pdf",
+    "pdf-writer",
+    "streaming",
+    "pdf-a",
+    "pdf-ua",
+    "factur-x",
+    "zugferd",
+    "accessibility",
+    "truetype",
+    "encryption",
+    "aes",
+    "pades",
+    "digital-signature",
+    "reportwright"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
-    ".": { "types": "./index.d.ts", "default": "./dist/index.js" },
-    "./fflate": { "types": "./fflate.d.ts", "default": "./dist/fflate.js" },
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./write": {
+      "types": "./write.d.ts",
+      "default": "./dist/write.js"
+    },
+    "./fflate": {
+      "types": "./fflate.d.ts",
+      "default": "./dist/fflate.js"
+    },
     "./examples/*": "./examples/*",
     "./package.json": "./package.json"
   },
   "types": "./index.d.ts",
-  "files": ["dist", "index.d.ts", "fflate.d.ts", "examples", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md"],
-  "engines": { "node": ">=20.16" },
-  "sideEffects": false
+  "files": [
+    "dist",
+    "index.d.ts",
+    "write.d.ts",
+    "fflate.d.ts",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=20.16"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "vitest run",
+    "format": "prettier --write \"src/**/*.{js,mjs}\" \"tests/**/*.{js,mjs}\" \"tools/**/*.{js,mjs}\"",
+    "format:check": "prettier --check \"src/**/*.{js,mjs}\" \"tests/**/*.{js,mjs}\" \"tools/**/*.{js,mjs}\""
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "fflate": "^0.8.3",
+    "harfbuzzjs": "^1.6.2",
+    "node-forge": "^1.4.0",
+    "pdf-lib": "^1.17.1",
+    "prettier": "3.9.9",
+    "sharp": "^0.34.3",
+    "vitest": "^5.0.3"
+  }
 }

package/write.d.ts

@@ -0,0 +1,89 @@
+// Types of @reportwright/pdf/write: the writer subset of index.d.ts (same declarations, no reader or bulk types).
+export {
+  cmyk,
+  nodeSigner,
+  cmsSigner,
+  createPdf,
+  toBytes,
+  STANDARD_NAMES,
+  svgPathOps,
+  readFont,
+  checkSubset,
+} from './index.js';
+export type {
+  AFRelationship,
+  Annotation,
+  AnnotationOptions,
+  ArtifactOptions,
+  AttachOptions,
+  BlendMode,
+  Box,
+  ButtonAction,
+  ButtonOptions,
+  CheckStyle,
+  CheckboxOptions,
+  ChoiceOption,
+  ChoiceOptions,
+  Color,
+  ColorStops,
+  ComboBoxOptions,
+  DrawOptions,
+  EncryptOptions,
+  FacturXProfile,
+  Field,
+  FieldOptions,
+  FieldTextOptions,
+  Fit,
+  Font,
+  FontInfo,
+  FormScope,
+  Gradient,
+  HashName,
+  IccColor,
+  IccColorSpace,
+  Image,
+  ImageOptions,
+  Layer,
+  LayerOptions,
+  LineEnding,
+  LinkOptions,
+  LinkTarget,
+  ListBoxOptions,
+  MeasureOptions,
+  NoteIcon,
+  OutlineEntry,
+  OwnAppearance,
+  OwnTextLook,
+  Page,
+  PageLabelRange,
+  PageOptions,
+  Paint,
+  Path,
+  Pdf,
+  PdfCore,
+  PdfOptions,
+  Permissions,
+  Point,
+  RadioGroupOptions,
+  Rect,
+  RenderMode,
+  ShapeOptions,
+  ShapedGlyph,
+  Shaper,
+  SignOptions,
+  SignRequest,
+  SignatureOptions,
+  Signer,
+  Sink,
+  SpotColor,
+  StampName,
+  StandardFontName,
+  Subsetter,
+  TagOptions,
+  TextBoxOptions,
+  TextFieldOptions,
+  TextOptions,
+  TilingPattern,
+  ViewerOptions,
+  WidgetBox,
+} from './index.js';