@ltorresu82/firmagob-client 0.1.2 → 0.1.3

package/README.md

@@ -53,7 +53,7 @@ const response = await client.signHashes([
 ]);
 ```
 
-El JWT incluye los claims `entity`, `run`, `purpose`, `expiration` e `iat`. Por defecto el token expira en 5 minutos, alineado con los ejemplos oficiales. `expiration` se serializa como `yyyy-MM-dd'T'HH:mm:ss`. Se puede ajustar con `tokenTtlSeconds` si el ambiente lo requiere.
+El JWT incluye los claims `entity`, `run`, `purpose`, `expiration` e `iat`. Por defecto el token expira en 5 minutos, alineado con los ejemplos oficiales. `expiration` se serializa como `yyyy-MM-dd'T'HH:mm:ss` en zona horaria `America/Santiago`, porque FirmaGob interpreta ese valor como fecha local sin zona. Se puede ajustar con `tokenTtlSeconds` y `tokenTimeZone` si el ambiente lo requiere.
 
 ## PDF con firma externa
 
@@ -107,7 +107,7 @@ Para solicitar credenciales a la institucion o al equipo FirmaGob, ver [docs/cre
 
 ## Ejemplos de integracion
 
-Ejemplos completos con CLI Node.js, API Hono y app Astro:
+Ejemplos completos con CLI Node.js, API Hono y app Angular:
 
 ```text
 https://github.com/ltorresu82/firmagob-client-examples

package/dist/firmagob-client.d.ts

@@ -12,6 +12,7 @@ export type FirmaGobClientConfig = {
     purpose?: Purpose;
     environment?: Environment;
     tokenTtlSeconds?: number;
+    tokenTimeZone?: string;
     fetch?: typeof fetch;
     testUrl?: string;
     productionUrl?: string;

package/dist/firmagob-client.js

@@ -16,6 +16,7 @@ export class FirmaGobClientError extends Error {
 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;
+const DEFAULT_TOKEN_TIME_ZONE = "America/Santiago";
 export class FirmaGobClient {
     config;
     fetchImpl;
@@ -63,7 +64,7 @@ export class FirmaGobClient {
             entity: this.config.entity,
             run: this.config.run,
             purpose: this.config.purpose ?? Purpose.Unattended,
-            expiration: formatFirmaGobDateTime(expiration),
+            expiration: formatFirmaGobDateTime(expiration, this.config.tokenTimeZone ?? DEFAULT_TOKEN_TIME_ZONE),
             iat: Math.floor(now.getTime() / 1000),
         });
         const unsignedToken = `${header}.${payload}`;
@@ -110,8 +111,25 @@ function assertRequired(name, value) {
 function base64UrlEncodeJson(value) {
     return Buffer.from(JSON.stringify(value)).toString("base64url");
 }
-function formatFirmaGobDateTime(date) {
-    return date.toISOString().slice(0, 19);
+function formatFirmaGobDateTime(date, timeZone) {
+    const parts = new Intl.DateTimeFormat("sv-SE", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hour12: false,
+    }).formatToParts(date);
+    const get = (type) => {
+        const value = parts.find((part) => part.type === type)?.value;
+        if (!value) {
+            throw new FirmaGobClientError(`Could not format FirmaGob expiration date for time zone: ${timeZone}`);
+        }
+        return value;
+    };
+    return `${get("year")}-${get("month")}-${get("day")}T${get("hour")}:${get("minute")}:${get("second")}`;
 }
 function parseJsonResponse(body) {
     try {

package/docs/adr/ADR-0001-public-generic-package.md

@@ -0,0 +1,23 @@
+# ADR-0001: Mantener firmagob-client como paquete público y genérico
+
+## Status
+
+Accepted
+
+## Context
+
+`firmagob-client` es un repositorio público orientado a integrar FirmaGob Chile desde TypeScript. `AGENTS.md` define que debe mantenerse genérico, sin referencias a clientes, proyectos internos, instituciones específicas, conversaciones privadas ni documentos no públicos.
+
+El README presenta el paquete como cliente TypeScript para FirmaGob Chile y aclara que no es un SDK oficial.
+
+## Decision
+
+Mantener el repositorio público, genérico y reutilizable por cualquier institución pública habilitada.
+
+Los ejemplos, tests y documentación deben usar nombres genéricos como `Institución de Prueba`. Las fuentes normativas o técnicas deben ser públicas y oficiales cuando existan.
+
+## Consequences
+
+- No introducir referencias a clientes, instituciones específicas, proyectos internos ni evidencia institucional.
+- Si aparece una referencia institucional específica, limpiarla antes de publicar o distribuir.
+- Revisar documentación, ejemplos y tests como superficie pública, no como material interno.

package/docs/adr/ADR-0002-official-firmagob-sources.md

@@ -0,0 +1,23 @@
+# ADR-0002: Las fuentes oficiales FirmaGob prevalecen sobre el cliente
+
+## Status
+
+Accepted
+
+## Context
+
+El README lista como fuentes oficiales el manual de integración API FirmaGob y repositorios `digital-gob-cl`. También declara que, si existe diferencia entre este paquete y una fuente oficial vigente, debe prevalecer la fuente oficial.
+
+El código modela endpoints de certificación y producción de FirmaGob v2.
+
+## Decision
+
+El contrato funcional del cliente debe seguir la documentación y ejemplos oficiales vigentes de FirmaGob.
+
+Cuando exista una discrepancia, se debe actualizar este paquete o documentar la incompatibilidad. No se debe inventar un contrato propio ni mantener comportamiento divergente como default.
+
+## Consequences
+
+- Cambios de API, claims JWT, endpoints, formatos de payload o reglas de firma deben contrastarse con fuentes oficiales.
+- El README puede citar fuentes oficiales; no debe basarse en conocimiento privado.
+- Las decisiones futuras de compatibilidad deben dejar explícita la versión o fuente pública usada.

package/docs/adr/ADR-0003-zero-runtime-dependencies.md

@@ -0,0 +1,21 @@
+# ADR-0003: Mantener cero dependencias runtime salvo justificación técnica clara
+
+## Status
+
+Accepted
+
+## Context
+
+`AGENTS.md` exige mantener el paquete sin dependencias runtime salvo razón técnica clara. El README lista `sin dependencias runtime` como parte del estado inicial, y `package.json` actualmente solo declara `devDependencies`.
+
+## Decision
+
+Mantener el paquete liviano y sin dependencias runtime por defecto.
+
+Las dependencias de desarrollo para TypeScript, tipos, tests o tooling son aceptables. Cualquier dependencia runtime debe justificarse por una necesidad técnica clara y quedar documentada.
+
+## Consequences
+
+- No agregar librerías PDF, JWT, HTTP o criptográficas runtime si Node.js ya cubre el caso de uso.
+- Evaluar cualquier dependencia runtime nueva por seguridad, mantenimiento, tamaño de paquete y compatibilidad ESM/Node.
+- Mantener la validación del contenido empacado antes de publicar.

package/docs/adr/ADR-0004-explicit-configuration-failures.md

@@ -0,0 +1,23 @@
+# ADR-0004: Configuración y secretos deben fallar de forma explícita
+
+## Status
+
+Accepted
+
+## Context
+
+`src/firmagob-client.ts` valida `apiTokenKey`, `secret`, `entity` y `run` en el constructor. El ejemplo `examples/sign-hash-sandbox.js` falla cuando faltan variables de entorno requeridas. `docs/credentials.md` documenta variables requeridas y manejo seguro.
+
+`AGENTS.md` prohíbe commitear credenciales, RUN reales, tokens y evidencia con datos institucionales.
+
+## Decision
+
+Credenciales, RUN, entidad, propósito y endpoint deben venir de configuración externa.
+
+El runtime y los ejemplos deben fallar con errores claros cuando falte configuración requerida. No se deben agregar credenciales dummy, usuarios de prueba, endpoints locales o fallbacks silenciosos como comportamiento productivo.
+
+## Consequences
+
+- Los ejemplos pueden usar dry-run explícito, pero no deben simular credenciales reales.
+- Las respuestas o evidencias reales de FirmaGob no deben quedar versionadas.
+- Cualquier bypass de desarrollo debe estar nombrado como tal y no ser el camino por defecto.

package/docs/adr/ADR-0005-external-pdf-signature-boundary.md

@@ -0,0 +1,23 @@
+# ADR-0005: La firma PDF se modela como preparación ByteRange más PKCS#7 externo
+
+## Status
+
+Accepted
+
+## Context
+
+El README describe el flujo de preparar el PDF, calcular hash, enviar a FirmaGob y recibir PKCS#7 base64. `src/pdf-external-signature.ts` implementa preparación de `ByteRange`, exclusión de `/Contents` y embebido de firma PKCS#7.
+
+Los tests validan placeholder, bytes de hash y rechazo de firmas mayores al espacio reservado.
+
+## Decision
+
+El paquete se encarga de preparar PDFs para firma externa y de insertar una firma PKCS#7 emitida fuera del paquete.
+
+No administra certificados, llaves privadas ni firma criptográfica local.
+
+## Consequences
+
+- El límite del paquete es preparación, hashing e inyección de firma externa.
+- No introducir llaves privadas, certificados reales o almacenamiento de secretos en este repositorio.
+- Cambios al helper PDF deben conservar el contrato de `ByteRange`, placeholder y validaciones de tamaño de firma.

package/docs/adr/README.md

@@ -0,0 +1,23 @@
+# Architecture Decision Records
+
+Este directorio contiene decisiones técnicas durables del repositorio `firmagob-client`.
+
+Los ADRs se usan para preservar decisiones que futuros mantenedores o agentes necesitan conocer antes de cambiar contratos, límites del paquete, seguridad, dependencias o comportamiento público.
+
+## Índice
+
+| ADR | Estado | Decisión |
+| --- | --- | --- |
+| [ADR-0001](./ADR-0001-public-generic-package.md) | Accepted | Mantener `firmagob-client` como paquete público y genérico |
+| [ADR-0002](./ADR-0002-official-firmagob-sources.md) | Accepted | Las fuentes oficiales FirmaGob prevalecen sobre el cliente |
+| [ADR-0003](./ADR-0003-zero-runtime-dependencies.md) | Accepted | Mantener cero dependencias runtime salvo justificación técnica clara |
+| [ADR-0004](./ADR-0004-explicit-configuration-failures.md) | Accepted | Configuración y secretos deben fallar de forma explícita |
+| [ADR-0005](./ADR-0005-external-pdf-signature-boundary.md) | Accepted | La firma PDF se modela como preparación ByteRange más PKCS#7 externo |
+
+## Candidatos pendientes
+
+No hay candidatos pendientes al momento de crear este índice.
+
+## Origen
+
+Estos ADRs se originan desde la auditoría de memoria durable en [`docs/decision-memory-audit.md`](../decision-memory-audit.md).

package/docs/credentials.md

@@ -13,6 +13,8 @@ Este paquete no incluye credenciales de prueba ni productivas. Para ejecutar una
 | `FIRMAGOB_PURPOSE` | Proposito del certificado: `Desatendido` o `Propósito General`. |
 | `FIRMAGOB_ENDPOINT_API` | Endpoint API del ambiente correspondiente. |
 
+El token JWT usa `expiration` como fecha local sin zona horaria. Por defecto este paquete usa `America/Santiago`, que replica el comportamiento esperado por los ejemplos oficiales Java cuando se ejecutan en Chile.
+
 Endpoint de certificacion usado por los ejemplos oficiales:
 
 ```text

package/docs/decision-memory-audit.md

@@ -0,0 +1,136 @@
+# Auditoría de memoria durable de decisiones
+
+Fecha: 2026-05-30
+
+## Alcance
+
+Auditoría del repositorio `firmagob-client` para identificar decisiones que conviene preservar como memoria durable del repositorio. No se crean ADRs en este reporte; se proponen candidatos y estados.
+
+## Hallazgos
+
+No existe una carpeta ADR o decision-record vigente. Si se decide formalizar estas decisiones, la ubicación recomendada es `docs/adr/`.
+
+El repositorio ya contiene varias decisiones implícitas distribuidas entre `AGENTS.md`, `README.md`, `docs/credentials.md`, `package.json`, CI y código fuente. Las decisiones siguientes cumplen el criterio de memoria durable: si otro agente cambia estas áreas en dos meses, necesita conocerlas para no romper el contrato público del paquete.
+
+## Propuestas de memoria durable
+
+### ADR-0001: Mantener firmagob-client como paquete público y genérico
+
+Estado sugerido: Accepted
+
+Evidencia:
+
+- `AGENTS.md`: declara que el repositorio es público y debe mantenerse genérico.
+- `AGENTS.md`: prohíbe referencias a clientes, proyectos internos, instituciones específicas, conversaciones privadas y documentos no públicos.
+- `README.md`: define el paquete como cliente TypeScript para integrar FirmaGob Chile y declara que no es un SDK oficial.
+
+Decisión:
+
+El repositorio debe mantenerse público, genérico y reutilizable por cualquier institución pública habilitada. Los ejemplos, tests y documentación deben usar nombres genéricos como `Institución de Prueba`. Las fuentes normativas o técnicas deben ser públicas y oficiales cuando existan.
+
+Consecuencias:
+
+- No se deben introducir referencias a clientes, instituciones específicas, proyectos internos ni evidencia institucional.
+- Si aparece una referencia institucional específica, debe limpiarse antes de publicar o distribuir.
+- Los cambios de documentación y ejemplos deben revisarse como superficie pública, no como material interno.
+
+### ADR-0002: Las fuentes oficiales FirmaGob prevalecen sobre el cliente
+
+Estado sugerido: Accepted
+
+Evidencia:
+
+- `README.md`: lista como fuentes oficiales el manual de integración API FirmaGob y repositorios `digital-gob-cl`.
+- `README.md`: indica que, si existe diferencia entre el paquete y una fuente oficial vigente, debe prevalecer la fuente oficial.
+- `src/firmagob-client.ts`: modela endpoints de certificación y producción de FirmaGob v2.
+
+Decisión:
+
+El contrato funcional del cliente debe seguir la documentación y ejemplos oficiales vigentes de FirmaGob. Cuando exista una discrepancia, se debe actualizar este paquete o documentar la incompatibilidad; no se debe inventar un contrato propio ni mantener comportamiento divergente como default.
+
+Consecuencias:
+
+- Cambios de API, claims JWT, endpoints, formatos de payload o reglas de firma deben contrastarse con fuentes oficiales.
+- El README puede citar fuentes oficiales; no debe basarse en conocimiento privado.
+- Las decisiones futuras de compatibilidad deben dejar explícita la versión o fuente pública usada.
+
+### ADR-0003: Cero dependencias runtime salvo justificación técnica clara
+
+Estado sugerido: Accepted
+
+Evidencia:
+
+- `AGENTS.md`: exige mantener el paquete sin dependencias runtime salvo razón técnica clara.
+- `README.md`: lista `sin dependencias runtime` como parte del estado inicial.
+- `package.json`: actualmente solo declara `devDependencies`.
+
+Decisión:
+
+El paquete debe conservarse liviano y sin dependencias runtime por defecto. Las dependencias de desarrollo para TypeScript, tipos, tests o tooling son aceptables; cualquier dependencia runtime debe justificarse por una necesidad técnica clara y quedar documentada.
+
+Consecuencias:
+
+- No agregar librerías PDF, JWT, HTTP o criptográficas runtime si Node.js ya cubre el caso de uso.
+- Una dependencia runtime nueva debe evaluarse por superficie de seguridad, mantenimiento, tamaño de paquete y compatibilidad ESM/Node.
+- La validación de publicación debe seguir revisando el contenido empacado.
+
+### ADR-0004: Configuración y secretos fallan de forma explícita
+
+Estado sugerido: Accepted
+
+Evidencia:
+
+- `src/firmagob-client.ts`: valida `apiTokenKey`, `secret`, `entity` y `run` en el constructor.
+- `examples/sign-hash-sandbox.js`: falla si faltan variables de entorno requeridas.
+- `docs/credentials.md`: documenta variables requeridas y manejo seguro.
+- `AGENTS.md`: prohíbe commitear credenciales, RUN reales, tokens y evidencia con datos institucionales.
+
+Decisión:
+
+Credenciales, RUN, entidad, propósito y endpoint deben venir de configuración externa. El runtime y los ejemplos deben fallar con errores claros cuando falte configuración requerida. No se deben agregar credenciales dummy, usuarios de prueba, endpoints locales o fallbacks silenciosos como comportamiento productivo.
+
+Consecuencias:
+
+- Los ejemplos pueden usar dry-run explícito, pero no deben simular credenciales reales.
+- Las respuestas o evidencias reales de FirmaGob no deben quedar versionadas.
+- Cualquier bypass de desarrollo debe estar nombrado como tal y no ser el camino por defecto.
+
+### ADR-0005: La firma PDF se modela como preparación ByteRange más PKCS#7 externo
+
+Estado sugerido: Accepted
+
+Evidencia:
+
+- `README.md`: describe preparar el PDF, calcular hash, enviar a FirmaGob y recibir PKCS#7 base64.
+- `src/pdf-external-signature.ts`: implementa preparación de `ByteRange`, exclusión de `/Contents` y embebido de firma PKCS#7.
+- `src/pdf-external-signature.test.ts`: valida placeholder, bytes de hash y rechazo de firmas mayores al espacio reservado.
+
+Decisión:
+
+El paquete debe encargarse de preparar PDFs para firma externa y de insertar una firma PKCS#7 emitida fuera del paquete. No administra certificados, llaves privadas ni firma criptográfica local.
+
+Consecuencias:
+
+- El límite del paquete es preparación, hashing e inyección de firma externa.
+- No se deben introducir llaves privadas, certificados reales o almacenamiento de secretos en este repositorio.
+- Cambios al helper PDF deben conservar el contrato de `ByteRange`, placeholder y validaciones de tamaño de firma.
+
+## Validación realizada
+
+Comandos ejecutados:
+
+```bash
+npm test
+npm audit
+git status --short --ignored
+```
+
+Resultados:
+
+- `npm test`: pasó con 7 tests.
+- `npm audit`: `found 0 vulnerabilities`.
+- `git status --short --ignored`: solo mostró `dist/` y `node_modules/` como ignorados luego de la validación.
+
+## Resultado posterior
+
+Esta propuesta fue aceptada y materializada como ADRs en `docs/adr/`, con un índice en `docs/adr/README.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ltorresu82/firmagob-client",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Cliente TypeScript para integrar FirmaGob Chile con firma por hash y PDFs firmados externamente",
   "type": "module",
   "main": "dist/index.js",