@ltorresu82/firmagob-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Torres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @ltorresu82/firmagob-client
+
+Cliente TypeScript para integrar FirmaGob Chile sin depender de librerias PDF deprecadas.
+
+Estado inicial:
+
+- cliente HTTP/JWT para FirmaGob v2;
+- soporte para firma por hash;
+- utilidades para preparar e inyectar una firma PKCS#7 externa en PDFs;
+- sin dependencias runtime.
+
+Este paquete no es un SDK oficial de Gobierno Digital.
+
+## Fuentes oficiales
+
+El diseño del cliente se guia por la documentacion y ejemplos publicados por Gobierno Digital:
+
+- [Manual de Integracion API FirmaGob, v.17 - Febrero 2026](https://firma.digital.gob.cl/biblioteca/manuales-firmagob/manual-api-firma/)
+- [Organizacion oficial digital-gob-cl en GitHub](https://github.com/digital-gob-cl)
+- [digital-gob-cl/firma-hash-ejemplo](https://github.com/digital-gob-cl/firma-hash-ejemplo)
+- [digital-gob-cl/firma-pdf-ejemplo](https://github.com/digital-gob-cl/firma-pdf-ejemplo)
+- [digital-gob-cl/firma-pdf-layout-ejemplo](https://github.com/digital-gob-cl/firma-pdf-layout-ejemplo)
+- [digital-gob-cl/firma-json-ejemplo](https://github.com/digital-gob-cl/firma-json-ejemplo)
+- [digital-gob-cl/firma-xml-ejemplo](https://github.com/digital-gob-cl/firma-xml-ejemplo)
+
+Cuando exista diferencia entre este paquete y una fuente oficial vigente, debe prevalecer la fuente oficial.
+
+## Instalacion
+
+```bash
+npm install @ltorresu82/firmagob-client
+```
+
+## Firma de hashes
+
+```ts
+import { FirmaGobClient, Purpose } from "@ltorresu82/firmagob-client";
+
+const client = new FirmaGobClient({
+  apiTokenKey: process.env.FIRMAGOB_API_TOKEN_KEY!,
+  secret: process.env.FIRMAGOB_SECRET!,
+  entity: process.env.FIRMAGOB_ENTITY!,
+  run: process.env.FIRMAGOB_RUN!,
+  purpose: Purpose.Unattended,
+  environment: "test",
+});
+
+const response = await client.signHashes([
+  { content: "sha256-base64-del-pdf-preparado", contentType: "application/pdf" },
+]);
+```
+
+El JWT incluye los claims `entity`, `run`, `purpose` y `expiration`. Por defecto el token expira en 5 minutos, alineado con los ejemplos oficiales. Se puede ajustar con `tokenTtlSeconds` si el ambiente lo requiere.
+
+## PDF con firma externa
+
+```ts
+import {
+  embedExternalSignature,
+  preparePdfForExternalSignature,
+  sha256Base64,
+} from "@ltorresu82/firmagob-client";
+
+const prepared = preparePdfForExternalSignature(pdfWithPlaceholder);
+const hash = sha256Base64(prepared.bytesToHash);
+
+// Enviar hash a FirmaGob y recibir PKCS#7 base64.
+const signedPdf = embedExternalSignature({
+  preparedPdf: prepared.bytesToHash,
+  pkcs7Signature: firmaGobPkcs7Base64,
+  placeholderLength: prepared.placeholderLength,
+  signatureOffset: prepared.signatureOffset,
+});
+```
+
+## Validacion sandbox
+
+El repositorio incluye un ejemplo de firma por hash basado en el flujo oficial. Por seguridad, no trae credenciales embebidas; las lee desde variables de entorno.
+
+Variables requeridas:
+
+- `FIRMAGOB_ENTITY`
+- `FIRMAGOB_API_TOKEN_KEY`
+- `FIRMAGOB_RUN`
+- `FIRMAGOB_PURPOSE`
+- `FIRMAGOB_SECRET`
+- `FIRMAGOB_ENDPOINT_API`
+
+Validacion local sin llamada a FirmaGob:
+
+```bash
+npm run validate:sandbox:dry-run
+```
+
+Validacion real contra sandbox:
+
+```bash
+npm run validate:sandbox
+```
+
+El ejemplo escribe evidencia temporal en `tmp/sandbox-hash/`.
+
+Para solicitar credenciales a la institucion o al equipo FirmaGob, ver [docs/credentials.md](docs/credentials.md).
+
+## Desarrollo
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```

package/dist/firmagob-client.d.ts

@@ -0,0 +1,71 @@
+export type Environment = "test" | "production";
+export declare const Purpose: {
+    readonly Attended: "Propósito General";
+    readonly Unattended: "Desatendido";
+};
+export type Purpose = (typeof Purpose)[keyof typeof Purpose];
+export type FirmaGobClientConfig = {
+    apiTokenKey: string;
+    secret: string;
+    entity: string;
+    run: string;
+    purpose?: Purpose;
+    environment?: Environment;
+    tokenTtlSeconds?: number;
+    fetch?: typeof fetch;
+    testUrl?: string;
+    productionUrl?: string;
+};
+export type FirmaGobFileInput = {
+    content: string;
+    contentType: string;
+    checksum?: string;
+    description?: string;
+    layout?: string;
+    references?: string[];
+    xmlObjects?: string[];
+};
+export type FirmaGobHashInput = {
+    content: string;
+    contentType?: "application/pdf";
+    description?: string;
+};
+export type FirmaGobSignOutput = {
+    metadata: {
+        otpExpired: boolean;
+        filesSigned: number;
+        signedFailed: number;
+        objectReceived: number;
+    };
+    status: number;
+    error?: string;
+    idSolicitud?: number;
+    files?: Array<Record<string, unknown>>;
+    hashes?: Array<{
+        content: string;
+        status: "OK" | "error";
+        contentType: string;
+        documentStatus: string;
+        checksum_original: string | null;
+        hashOriginal?: string;
+    }>;
+};
+export declare class FirmaGobClientError extends Error {
+    readonly status?: number | undefined;
+    readonly responseBody?: string | undefined;
+    constructor(message: string, status?: number | undefined, responseBody?: string | undefined);
+}
+export declare class FirmaGobClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: FirmaGobClientConfig);
+    signHashes(hashes: FirmaGobHashInput[], options?: {
+        otp?: string;
+    }): Promise<FirmaGobSignOutput>;
+    signFiles(files: FirmaGobFileInput[], options?: {
+        otp?: string;
+    }): Promise<FirmaGobSignOutput>;
+    createToken(now?: Date): string;
+    private sign;
+    private get url();
+}

package/dist/firmagob-client.js

@@ -0,0 +1,118 @@
+import { createHmac } from "node:crypto";
+export const Purpose = {
+    Attended: "Propósito General",
+    Unattended: "Desatendido",
+};
+export class FirmaGobClientError extends Error {
+    status;
+    responseBody;
+    constructor(message, status, responseBody) {
+        super(message);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.name = "FirmaGobClientError";
+    }
+}
+const TEST_URL = "https://api.firma.cert.digital.gob.cl/firma/v2/files/tickets";
+const PRODUCTION_URL = "https://api.firma.digital.gob.cl/firma/v2/files/tickets";
+const DEFAULT_TOKEN_TTL_SECONDS = 5 * 60;
+export class FirmaGobClient {
+    config;
+    fetchImpl;
+    constructor(config) {
+        this.config = config;
+        assertRequired("apiTokenKey", config.apiTokenKey);
+        assertRequired("secret", config.secret);
+        assertRequired("entity", config.entity);
+        assertRequired("run", config.run);
+        this.fetchImpl = config.fetch ?? fetch;
+    }
+    async signHashes(hashes, options = {}) {
+        if (hashes.length === 0) {
+            throw new FirmaGobClientError("At least one hash is required");
+        }
+        return this.sign({
+            hashes: hashes.map((hash) => ({
+                "content-type": hash.contentType ?? "application/pdf",
+                content: hash.content,
+                description: hash.description,
+            })),
+        }, options.otp);
+    }
+    async signFiles(files, options = {}) {
+        if (files.length === 0) {
+            throw new FirmaGobClientError("At least one file is required");
+        }
+        return this.sign({
+            files: files.map((file) => ({
+                "content-type": file.contentType,
+                content: file.content,
+                checksum: file.checksum,
+                description: file.description,
+                layout: file.layout,
+                references: file.references,
+                xmlObjects: file.xmlObjects,
+            })),
+        }, options.otp);
+    }
+    createToken(now = new Date()) {
+        const tokenTtlSeconds = this.config.tokenTtlSeconds ?? DEFAULT_TOKEN_TTL_SECONDS;
+        const header = base64UrlEncodeJson({ alg: "HS256", typ: "JWT" });
+        const payload = base64UrlEncodeJson({
+            entity: this.config.entity,
+            run: this.config.run,
+            purpose: this.config.purpose ?? Purpose.Unattended,
+            expiration: new Date(now.getTime() + tokenTtlSeconds * 1000).toISOString(),
+        });
+        const unsignedToken = `${header}.${payload}`;
+        const signature = createHmac("sha256", this.config.secret)
+            .update(unsignedToken)
+            .digest("base64url");
+        return `${unsignedToken}.${signature}`;
+    }
+    async sign(payload, otp) {
+        const purpose = this.config.purpose ?? Purpose.Unattended;
+        if (purpose === Purpose.Attended && !otp) {
+            throw new FirmaGobClientError("Attended signatures require an OTP");
+        }
+        const response = await this.fetchImpl(this.url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...(otp ? { otp } : {}),
+            },
+            body: JSON.stringify({
+                api_token_key: this.config.apiTokenKey,
+                token: this.createToken(),
+                ...payload,
+            }),
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            throw new FirmaGobClientError(`FirmaGob request failed with HTTP ${response.status}`, response.status, body);
+        }
+        return parseJsonResponse(body);
+    }
+    get url() {
+        if ((this.config.environment ?? "test") === "production") {
+            return this.config.productionUrl ?? PRODUCTION_URL;
+        }
+        return this.config.testUrl ?? TEST_URL;
+    }
+}
+function assertRequired(name, value) {
+    if (!value || value.trim().length === 0) {
+        throw new FirmaGobClientError(`Missing required config: ${name}`);
+    }
+}
+function base64UrlEncodeJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+function parseJsonResponse(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new FirmaGobClientError("FirmaGob returned a non-JSON response", undefined, body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { FirmaGobClient, FirmaGobClientError, Environment, Purpose, type FirmaGobClientConfig, type FirmaGobFileInput, type FirmaGobHashInput, type FirmaGobSignOutput, } from "./firmagob-client.js";
+export { DEFAULT_BYTE_RANGE_PLACEHOLDER, embedExternalSignature, preparePdfForExternalSignature, type PreparedPdfForExternalSignature, } from "./pdf-external-signature.js";
+export { sha256Base64 } from "./sha256.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { FirmaGobClient, FirmaGobClientError, Purpose, } from "./firmagob-client.js";
+export { DEFAULT_BYTE_RANGE_PLACEHOLDER, embedExternalSignature, preparePdfForExternalSignature, } from "./pdf-external-signature.js";
+export { sha256Base64 } from "./sha256.js";

package/dist/pdf-external-signature.d.ts

@@ -0,0 +1,16 @@
+export declare const DEFAULT_BYTE_RANGE_PLACEHOLDER = "********** ********** **********";
+export type PreparedPdfForExternalSignature = {
+    bytesToHash: Buffer;
+    placeholderLength: number;
+    signatureOffset: number;
+    byteRange: [number, number, number, number];
+};
+export declare function preparePdfForExternalSignature(pdfBuffer: Buffer | Uint8Array, options?: {
+    byteRangePlaceholder?: string;
+}): PreparedPdfForExternalSignature;
+export declare function embedExternalSignature(input: {
+    preparedPdf: Buffer | Uint8Array;
+    pkcs7Signature: Buffer | Uint8Array | string;
+    placeholderLength: number;
+    signatureOffset: number;
+}): Buffer;

package/dist/pdf-external-signature.js

@@ -0,0 +1,72 @@
+export const DEFAULT_BYTE_RANGE_PLACEHOLDER = "********** ********** **********";
+export function preparePdfForExternalSignature(pdfBuffer, options = {}) {
+    const placeholder = options.byteRangePlaceholder ?? DEFAULT_BYTE_RANGE_PLACEHOLDER;
+    let pdf = removeTrailingNewLine(Buffer.from(pdfBuffer));
+    const byteRangePosition = pdf.indexOf(placeholder);
+    if (byteRangePosition < 0) {
+        throw new Error(`Could not find ByteRange placeholder: ${placeholder}`);
+    }
+    const byteRangeEnd = byteRangePosition + placeholder.length;
+    const contentsPosition = pdf.indexOf("/Contents ", byteRangeEnd);
+    if (contentsPosition < 0) {
+        throw new Error("Could not find /Contents after /ByteRange");
+    }
+    const signatureStart = pdf.indexOf("<", contentsPosition);
+    const signatureEnd = pdf.indexOf(">", signatureStart);
+    if (signatureStart < 0 || signatureEnd < 0) {
+        throw new Error("Could not find /Contents hex placeholder");
+    }
+    const placeholderLengthWithBrackets = signatureEnd + 1 - signatureStart;
+    const placeholderLength = placeholderLengthWithBrackets - 2;
+    const byteRange = [
+        0,
+        signatureStart,
+        signatureStart + placeholderLengthWithBrackets,
+        pdf.length - (signatureStart + placeholderLengthWithBrackets),
+    ];
+    const byteRangeText = `/ByteRange [${byteRange.join(" ")}]`;
+    if (byteRangeText.length > placeholder.length) {
+        throw new Error("Calculated /ByteRange does not fit in placeholder");
+    }
+    const paddedByteRangeText = byteRangeText + " ".repeat(placeholder.length - byteRangeText.length);
+    pdf = Buffer.concat([
+        pdf.subarray(0, byteRangePosition),
+        Buffer.from(paddedByteRangeText),
+        pdf.subarray(byteRangeEnd),
+    ]);
+    const bytesToHash = Buffer.concat([
+        pdf.subarray(0, byteRange[1]),
+        pdf.subarray(byteRange[2], byteRange[2] + byteRange[3]),
+    ]);
+    return {
+        bytesToHash,
+        placeholderLength,
+        signatureOffset: byteRange[1],
+        byteRange,
+    };
+}
+export function embedExternalSignature(input) {
+    const pdf = Buffer.from(input.preparedPdf);
+    const signature = Buffer.isBuffer(input.pkcs7Signature)
+        ? input.pkcs7Signature
+        : typeof input.pkcs7Signature === "string"
+            ? Buffer.from(input.pkcs7Signature, "base64")
+            : Buffer.from(input.pkcs7Signature);
+    const signatureHex = signature.toString("hex");
+    if (signatureHex.length > input.placeholderLength) {
+        throw new Error("PKCS#7 signature is larger than PDF placeholder");
+    }
+    const paddedSignatureHex = signatureHex.padEnd(input.placeholderLength, "0");
+    return Buffer.concat([
+        pdf.subarray(0, input.signatureOffset),
+        Buffer.from(`<${paddedSignatureHex}>`),
+        pdf.subarray(input.signatureOffset),
+    ]);
+}
+function removeTrailingNewLine(pdf) {
+    let end = pdf.length;
+    while (end > 0 && (pdf[end - 1] === 0x0a || pdf[end - 1] === 0x0d)) {
+        end -= 1;
+    }
+    return end === pdf.length ? pdf : pdf.subarray(0, end);
+}

package/dist/sha256.d.ts

@@ -0,0 +1 @@
+export declare function sha256Base64(input: Buffer | Uint8Array | string): string;

package/dist/sha256.js

@@ -0,0 +1,4 @@
+import { createHash } from "node:crypto";
+export function sha256Base64(input) {
+    return createHash("sha256").update(input).digest("base64");
+}

package/docs/credentials.md

@@ -0,0 +1,58 @@
+# Credenciales de integracion FirmaGob
+
+Este paquete no incluye credenciales de prueba ni productivas. Para ejecutar una validacion real contra FirmaGob se debe solicitar una aplicacion API habilitada para la institucion.
+
+## Variables requeridas
+
+| Variable | Descripcion |
+| --- | --- |
+| `FIRMAGOB_ENTITY` | Codigo o nombre de entidad registrado para la institucion en FirmaGob. |
+| `FIRMAGOB_API_TOKEN_KEY` | Identificador publico de la aplicacion API registrada. |
+| `FIRMAGOB_SECRET` | Secreto de la aplicacion API usado para firmar el JWT HS256. |
+| `FIRMAGOB_RUN` | RUN del firmante habilitado, sin puntos, guion ni digito verificador. |
+| `FIRMAGOB_PURPOSE` | Proposito del certificado: `Desatendido` o `Propósito General`. |
+| `FIRMAGOB_ENDPOINT_API` | Endpoint API del ambiente correspondiente. |
+
+Endpoint de certificacion usado por los ejemplos oficiales:
+
+```text
+https://api.firma.cert.digital.gob.cl/firma/v2/files/tickets
+```
+
+Endpoint productivo:
+
+```text
+https://api.firma.digital.gob.cl/firma/v2/files/tickets
+```
+
+## Preguntas que deben quedar resueltas
+
+- Si la integracion usara firma desatendida o firma atendida con OTP.
+- Que funcionario o certificado institucional quedara autorizado para firmar en certificacion.
+- Si existiran credenciales separadas para desarrollo, QA, UAT y produccion.
+- Quien custodia el secreto y cual es el procedimiento de rotacion/revocacion.
+- Si los documentos se firmaran por hash o por archivo completo. Para PDFs de mas de 5 MB se debe usar firma por hash.
+- Que metadata debe conservar el sistema: hash, `idSolicitud`, fecha/hora, firmante, proposito, respuesta de FirmaGob y documento final.
+
+## Solicitud sugerida
+
+```text
+Necesitamos las credenciales de integracion API FirmaGob para ambiente de certificacion de la institucion:
+
+- Codigo de entidad/institucion registrado en FirmaGob
+- API token key de la aplicacion
+- Secret de la aplicacion
+- RUN del firmante habilitado para pruebas, sin puntos, guion ni digito verificador
+- Purpose autorizado: Desatendido o Propósito General
+- Endpoint API de certificacion
+- Confirmacion de si el certificado requiere OTP
+
+Estas credenciales seran usadas inicialmente para validar firma por hash de PDFs en ambiente de desarrollo, sin documentos productivos.
+```
+
+## Manejo seguro
+
+- No commitear valores reales en este repositorio.
+- No imprimir secretos en logs ni evidencia.
+- Cargar las variables desde el gestor de secretos del ambiente o desde un archivo local fuera del repositorio.
+- Rotar el secreto si se comparte por canales no controlados.

package/examples/sign-hash-sandbox.js

@@ -0,0 +1,179 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  DEFAULT_BYTE_RANGE_PLACEHOLDER,
+  FirmaGobClient,
+  Purpose,
+  embedExternalSignature,
+  preparePdfForExternalSignature,
+  sha256Base64,
+} from "../dist/index.js";
+
+const dryRun = process.argv.includes("--dry-run");
+const outputDir = join("tmp", "sandbox-hash");
+const placeholderLength = 15000 * 2;
+
+mkdirSync(outputDir, { recursive: true });
+
+const sourcePdf = createMinimalPdfWithSignaturePlaceholder({
+  reason: "Validacion sandbox FirmaGob",
+  placeholderLength,
+});
+const prepared = preparePdfForExternalSignature(sourcePdf);
+const hash = sha256Base64(prepared.bytesToHash);
+
+writeFileSync(join(outputDir, "source-with-placeholder.pdf"), sourcePdf);
+writeFileSync(join(outputDir, "hash.txt"), `${hash}\n`);
+
+if (dryRun) {
+  const signedPdf = embedExternalSignature({
+    preparedPdf: prepared.bytesToHash,
+    pkcs7Signature: Buffer.from("dry-run-signature"),
+    placeholderLength: prepared.placeholderLength,
+    signatureOffset: prepared.signatureOffset,
+  });
+
+  writeFileSync(join(outputDir, "dry-run-signed.pdf"), signedPdf);
+  console.log(`Dry run OK. Evidence written to ${outputDir}`);
+  process.exit(0);
+}
+
+const config = readConfigFromEnv();
+const client = new FirmaGobClient({
+  apiTokenKey: config.apiTokenKey,
+  secret: config.secret,
+  entity: config.entity,
+  run: config.run,
+  purpose: config.purpose,
+  environment: "test",
+  testUrl: config.endpointApi,
+});
+
+console.log("Signing prepared PDF hash with FirmaGob sandbox...");
+const response = await client.signHashes([
+  { content: hash, contentType: "application/pdf" },
+]);
+
+if (response.status !== 200 || response.metadata.signedFailed > 0) {
+  writeFileSync(
+    join(outputDir, "firmagob-error.json"),
+    `${JSON.stringify(response, null, 2)}\n`
+  );
+  throw new Error("FirmaGob sandbox signing failed");
+}
+
+const pkcs7 = response.hashes?.[0]?.content;
+
+if (!pkcs7) {
+  throw new Error("FirmaGob response did not include hashes[0].content");
+}
+
+const signedPdf = embedExternalSignature({
+  preparedPdf: prepared.bytesToHash,
+  pkcs7Signature: pkcs7,
+  placeholderLength: prepared.placeholderLength,
+  signatureOffset: prepared.signatureOffset,
+});
+
+writeFileSync(join(outputDir, "firmagob-response.json"), `${JSON.stringify(response, null, 2)}\n`);
+writeFileSync(join(outputDir, "signed.pdf"), signedPdf);
+console.log(`Signed PDF written to ${join(outputDir, "signed.pdf")}`);
+
+function readConfigFromEnv() {
+  const required = {
+    entity: "FIRMAGOB_ENTITY",
+    apiTokenKey: "FIRMAGOB_API_TOKEN_KEY",
+    run: "FIRMAGOB_RUN",
+    purpose: "FIRMAGOB_PURPOSE",
+    secret: "FIRMAGOB_SECRET",
+    endpointApi: "FIRMAGOB_ENDPOINT_API",
+  };
+  const missing = Object.values(required).filter((name) => !process.env[name]);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
+  }
+
+  return {
+    entity: process.env[required.entity],
+    apiTokenKey: process.env[required.apiTokenKey],
+    run: process.env[required.run],
+    purpose: normalizePurpose(process.env[required.purpose]),
+    secret: process.env[required.secret],
+    endpointApi: process.env[required.endpointApi],
+  };
+}
+
+function normalizePurpose(value) {
+  if (value === Purpose.Attended || value === Purpose.Unattended) {
+    return value;
+  }
+
+  throw new Error(
+    `Unsupported FIRMAGOB_PURPOSE. Expected "${Purpose.Unattended}" or "${Purpose.Attended}".`
+  );
+}
+
+function createMinimalPdfWithSignaturePlaceholder({ reason, placeholderLength }) {
+  const contents = "0".repeat(placeholderLength);
+  const objects = [
+    "<< /Type /Catalog /Pages 2 0 R /AcroForm << /Fields [5 0 R] /SigFlags 3 >> >>",
+    "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+    [
+      "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792]",
+      "/Resources << /Font << /F1 4 0 R >> >>",
+      "/Contents 6 0 R",
+      "/Annots [5 0 R] >>",
+    ].join(" "),
+    "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    [
+      "<< /Type /Annot /Subtype /Widget /FT /Sig /Rect [72 72 260 120]",
+      "/T (Signature1) /F 4 /P 3 0 R /V 7 0 R >>",
+    ].join(" "),
+    "<< /Length 63 >>\nstream\nBT /F1 16 Tf 72 700 Td (Documento sandbox FirmaGob) Tj ET\nendstream",
+    [
+      "<< /Type /Sig /Filter /Adobe.PPKLite /SubFilter /adbe.pkcs7.detached",
+      `/ByteRange [0 ${DEFAULT_BYTE_RANGE_PLACEHOLDER}]`,
+      `/Contents <${contents}>`,
+      `/Reason (${escapePdfString(reason)})`,
+      `/M (D:${formatPdfDate(new Date())}) >>`,
+    ].join(" "),
+  ];
+
+  return buildPdf(objects);
+}
+
+function buildPdf(objects) {
+  const chunks = ["%PDF-1.7\n"];
+  const offsets = [0];
+
+  for (const [index, object] of objects.entries()) {
+    offsets.push(Buffer.byteLength(chunks.join(""), "latin1"));
+    chunks.push(`${index + 1} 0 obj\n${object}\nendobj\n`);
+  }
+
+  const xrefOffset = Buffer.byteLength(chunks.join(""), "latin1");
+  chunks.push(`xref\n0 ${objects.length + 1}\n`);
+  chunks.push("0000000000 65535 f \n");
+
+  for (const offset of offsets.slice(1)) {
+    chunks.push(`${String(offset).padStart(10, "0")} 00000 n \n`);
+  }
+
+  chunks.push(
+    `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`
+  );
+
+  return Buffer.from(chunks.join(""), "latin1");
+}
+
+function escapePdfString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
+}
+
+function formatPdfDate(date) {
+  return date
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d{3}Z$/, "Z");
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@ltorresu82/firmagob-client",
+  "version": "0.1.0",
+  "description": "Cliente TypeScript para integrar FirmaGob Chile con firma por hash y PDFs firmados externamente",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"import('node:fs').then(fs => fs.rmSync('dist', { recursive: true, force: true }))\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build:test": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build:test && node --test dist/**/*.test.js",
+    "validate:sandbox": "npm run build && node examples/sign-hash-sandbox.js",
+    "validate:sandbox:dry-run": "npm run build && node examples/sign-hash-sandbox.js --dry-run",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "prepublishOnly": "npm test && npm audit",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "firma",
+    "digital",
+    "firma-gob",
+    "chile",
+    "pdf"
+  ],
+  "author": "Luis Torres",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ltorresu82/firmagob-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ltorresu82/firmagob-client/issues"
+  },
+  "homepage": "https://github.com/ltorresu82/firmagob-client#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "typescript": "^5.4.5"
+  }
+}