@emiyalee/pdf-sign

Node.js wrapper for the pdf-sign-gm native executable (SM2/SES PDF signature).

As of 0.1.3, platform-specific binaries are bundled inside this package and auto-resolved at runtime. You can still override the executable path via API options or environment variable when needed.

Install

npm install @emiyalee/pdf-sign

API

registerExecutable(executablePath: string): Promise

Optionally register a custom pdf-sign-gm path for subsequent usage (persisted under the OS-specific config directory). This is rarely needed now that the package bundles binaries, but remains supported.

getRegisteredExecutable(): Promise

Get the registered executable path (if any). You can always override by env PDF_SIGN_GM_EXE or by passing options.executablePath.

sign(config: object, options?: SignOptions): Promise<{ stdout: string; stderr: string; exitCode: number }>

Invoke the native executable with the provided JSON config. By default the bundled binary matching your OS/arch is used; see Binary Resolution below.

type SignOptions = {
  executablePath?: string;   // Optional override path; by default auto-selects bundled binary
  timeoutMs?: number;         // Optional process timeout
  env?: NodeJS.ProcessEnv;    // Optional env overrides
  cwd?: string;               // Optional working directory
  useConfigFile?: boolean;    // If true, writes config to a temp JSON file and passes its path
};

Usage

const { registerExecutable, sign } = require('@emiyalee/pdf-sign');

// Register once per machine/user (persists under the user's config dir)
await registerExecutable('/absolute/path/to/pdf-sign-gm-macos-arm64');

// Later in any project/process:
await sign({
  type: 'SM2',
  pdfInputPath: './assets/unsigned.pdf',
  pdfOutputPath: './output/signed.pdf',
  tsaUrl: 'https://tsa.example.com/api',
  certPath: './cert-sm2/Emiya.cert.pem',
  keyPath: './cert-sm2/Emiya.key.pem',
  positions: [{ page: 1, x: 100, y: 100, width: 120, height: 120, path: './assets/seal1.png' }]
});

Binary resolution

At runtime, the library resolves the executable in this order:

1. options.executablePath (if provided)
2. PDF_SIGN_GM_EXE environment variable
3. Bundled binary under bin/<platform>/<arch>/pdf-sign-gm[.exe]
4. Registered executable from registerExecutable

Currently bundled targets:

• darwin/arm64/pdf-sign-gm (macOS Apple Silicon)
• darwin/x64/pdf-sign-gm (macOS Intel)
• linux/arm64/pdf-sign-gm (+ any lib*.so in same dir)
• linux/x64/pdf-sign-gm (+ any lib*.so in same dir)

More platforms can be added later.

Override executable path per call

await sign(config, { executablePath: '/another/path/to/pdf-sign-gm-linux-x64' });

Use a temp config file instead of an inline JSON argument

await sign(config, { useConfigFile: true });

Environment variable overrides

• PDF_SIGN_GM_EXE: Absolute path to the native executable. Takes precedence over registered config and bundled binary.
• PDF_SIGN_GM_CONFIG_DIR: Override the directory where the config file is stored.

Notes

• On POSIX systems, the library will attempt to set the executable bit on the resolved binary.
• Output files are controlled by your JSON config (pdfOutputPath, etc.).