@erseco/autofirma-client 1.9.3-canary.20260802075844.ee23ef2

package/LICENSE

@@ -0,0 +1,255 @@
+GNU GENERAL PUBLIC LICENSE
+Version 2, June 1991
+
+Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this license
+document, but changing it is not allowed.
+
+Preamble
+
+The licenses for most software are designed to take away your freedom to share
+and change it. By contrast, the GNU General Public License is intended to
+guarantee your freedom to share and change free software--to make sure the
+software is free for all its users. This General Public License applies to most
+of the Free Software Foundation's software and to any other program whose
+authors commit to using it. (Some other Free Software Foundation software is
+covered by the GNU Lesser General Public License instead.) You can apply it to
+your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our
+General Public Licenses are designed to make sure that you have the freedom to
+distribute copies of free software (and charge for this service if you wish),
+that you receive source code or can get it if you want it, that you can change
+the software or use pieces of it in new free programs; and that you know you can
+do these things.
+
+To protect your rights, we need to make restrictions that forbid anyone to deny
+you these rights or to ask you to surrender the rights. These restrictions
+translate to certain responsibilities for you if you distribute copies of the
+software, or if you modify it.
+
+For example, if you distribute copies of such a program, whether gratis or for
+a fee, you must give the recipients all the rights that you have. You must make
+sure that they, too, receive or can get the source code. And you must show them
+these terms so they know their rights.
+
+We protect your rights with two steps: (1) copyright the software, and (2) offer
+you this license which gives you legal permission to copy, distribute and/or
+modify the software.
+
+Also, for each author's protection and ours, we want to make certain that
+everyone understands that there is no warranty for this free software. If the
+software is modified by someone else and passed on, we want its recipients to
+know that what they have is not the original, so that any problems introduced by
+others will not reflect on the original authors' reputations.
+
+Finally, any free program is threatened constantly by software patents. We wish
+to avoid the danger that redistributors of a free program will individually
+obtain patent licenses, in effect making the program proprietary. To prevent
+this, we have made it clear that any patent must be licensed for everyone's free
+use or not licensed at all.
+
+The precise terms and conditions for copying, distribution and modification
+follow.
+
+TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+0. This License applies to any program or other work which contains a notice
+placed by the copyright holder saying it may be distributed under the terms of
+this General Public License. The "Program", below, refers to any such program or
+work, and a "work based on the Program" means either the Program or any
+derivative work under copyright law: that is to say, a work containing the
+Program or a portion of it, either verbatim or with modifications and/or
+translated into another language. (Hereinafter, translation is included without
+limitation in the term "modification".) Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not covered by
+this License; they are outside its scope. The act of running the Program is not
+restricted, and the output from the Program is covered only if its contents
+constitute a work based on the Program (independent of having been made by
+running the Program). Whether that is true depends on what the Program does.
+
+1. You may copy and distribute verbatim copies of the Program's source code as
+you receive it, in any medium, provided that you conspicuously and appropriately
+publish on each copy an appropriate copyright notice and disclaimer of warranty;
+keep intact all the notices that refer to this License and to the absence of any
+warranty; and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and you may at
+your option offer warranty protection in exchange for a fee.
+
+2. You may modify your copy or copies of the Program or any portion of it, thus
+forming a work based on the Program, and copy and distribute such modifications
+or work under the terms of Section 1 above, provided that you also meet all of
+these conditions:
+
+a) You must cause the modified files to carry prominent notices stating that
+you changed the files and the date of any change.
+
+b) You must cause any work that you distribute or publish, that in whole or in
+part contains or is derived from the Program or any part thereof, to be licensed
+as a whole at no charge to all third parties under the terms of this License.
+
+c) If the modified program normally reads commands interactively when run, you
+must cause it, when started running for such interactive use in the most ordinary
+way, to print or display an announcement including an appropriate copyright
+notice and a notice that there is no warranty (or else, saying that you provide a
+warranty) and that users may redistribute the program under these conditions,
+and telling the user how to view a copy of this License. (Exception: if the
+Program itself is interactive but does not normally print such an announcement,
+your work based on the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole. If identifiable
+sections of that work are not derived from the Program, and can be reasonably
+considered independent and separate works in themselves, then this License, and
+its terms, do not apply to those sections when you distribute them as separate
+works. But when you distribute the same sections as part of a whole which is a
+work based on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the entire whole,
+and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest your rights
+to work written entirely by you; rather, the intent is to exercise the right to
+control the distribution of derivative or collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program with the
+Program (or with a work based on the Program) on a volume of a storage or
+distribution medium does not bring the other work under the scope of this
+License.
+
+3. You may copy and distribute the Program (or a work based on it, under Section
+2) in object code or executable form under the terms of Sections 1 and 2 above
+provided that you also do one of the following:
+
+a) Accompany it with the complete corresponding machine-readable source code,
+which must be distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+b) Accompany it with a written offer, valid for at least three years, to give any
+third party, for a charge no more than your cost of physically performing source
+distribution, a complete machine-readable copy of the corresponding source code,
+to be distributed under the terms of Sections 1 and 2 above on a medium
+customarily used for software interchange; or,
+
+c) Accompany it with the information you received as to the offer to distribute
+corresponding source code. (This alternative is allowed only for noncommercial
+distribution and only if you received the program in object code or executable
+form with such an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for making
+modifications to it. For an executable work, complete source code means all the
+source code for all modules it contains, plus any associated interface
+definition files, plus the scripts used to control compilation and installation
+of the executable. However, as a special exception, the source code distributed
+need not include anything that is normally distributed (in either source or
+binary form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component itself
+accompanies the executable.
+
+If distribution of executable or object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the source code
+from the same place counts as distribution of the source code, even though third
+parties are not compelled to copy the source along with the object code.
+
+4. You may not copy, modify, sublicense, or distribute the Program except as
+expressly provided under this License. Any attempt otherwise to copy, modify,
+sublicense or distribute the Program is void, and will automatically terminate
+your rights under this License. However, parties who have received copies, or
+rights, from you under this License will not have their licenses terminated so
+long as such parties remain in full compliance.
+
+5. You are not required to accept this License, since you have not signed it.
+However, nothing else grants you permission to modify or distribute the Program
+or its derivative works. These actions are prohibited by law if you do not accept
+this License. Therefore, by modifying or distributing the Program (or any work
+based on the Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying the Program
+or works based on it.
+
+6. Each time you redistribute the Program (or any work based on the Program),
+the recipient automatically receives a license from the original licensor to
+copy, distribute or modify the Program subject to these terms and conditions.
+You may not impose any further restrictions on the recipients' exercise of the
+rights granted herein. You are not responsible for enforcing compliance by third
+parties to this License.
+
+7. If, as a consequence of a court judgment or allegation of patent infringement
+or for any other reason (not limited to patent issues), conditions are imposed on
+you (whether by court order, agreement or otherwise) that contradict the
+conditions of this License, they do not excuse you from the conditions of this
+License. If you cannot distribute so as to satisfy simultaneously your
+obligations under this License and any other pertinent obligations, then as a
+consequence you may not distribute the Program at all. For example, if a patent
+license would not permit royalty-free redistribution of the Program by all those
+who receive copies directly or indirectly through you, then the only way you
+could satisfy both it and this License would be to refrain entirely from
+distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply and the
+section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any patents or
+other property right claims or to contest validity of any such claims; this
+section has the sole purpose of protecting the integrity of the free software
+distribution system, which is implemented by public license practices. Many
+people have made generous contributions to the wide range of software
+distributed through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing to
+distribute software through any other system and a licensee cannot impose that
+choice.
+
+This section is intended to make thoroughly clear what is believed to be a
+consequence of the rest of this License.
+
+8. If the distribution and/or use of the Program is restricted in certain
+countries either by patents or by copyrighted interfaces, the original copyright
+holder who places the Program under this License may add an explicit geographical
+distribution limitation excluding those countries, so that distribution is
+permitted only in or among countries not thus excluded. In such case, this
+License incorporates the limitation as if written in the body of this License.
+
+9. The Free Software Foundation may publish revised and/or new versions of the
+General Public License from time to time. Such new versions will be similar in
+spirit to the present version, but may differ in detail to address new problems
+or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies
+a version number of this License which applies to it and "any later version", you
+have the option of following the terms and conditions either of that version or
+of any later version published by the Free Software Foundation. If the Program
+does not specify a version number of this License, you may choose any version
+ever published by the Free Software Foundation.
+
+10. If you wish to incorporate parts of the Program into other free programs
+whose distribution conditions are different, write to the author to ask for
+permission. For software which is copyrighted by the Free Software Foundation,
+write to the Free Software Foundation; we sometimes make exceptions for this.
+Our decision will be guided by the two goals of preserving the free status of all
+derivatives of our free software and of promoting the sharing and reuse of
+software generally.
+
+NO WARRANTY
+
+11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
+PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED
+IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
+WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
+ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
+PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
+SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
+TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
+THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
+PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,303 @@
+# AutoFirma Client
+
+Cliente TypeScript para usar la API oficial **AutoScript** con promesas,
+tipado estricto, conversión de datos, errores normalizados y dobles de prueba.
+
+> [!IMPORTANT]
+> Este proyecto no pertenece al Gobierno de España, no incluye AutoFirma y no
+> sustituye la validación criptográfica en servidor.
+
+## Estado
+
+El proyecto está en una fase inicial. La versión del paquete refleja el tag
+del repositorio oficial `ctt-gob-es/clienteafirma`, no una línea propia de
+AutoScript (ver [ADR-0004](docs/arquitectura/adr/ADR-0004-versionado-en-espejo.md)).
+La versión de AutoScript realmente empaquetada, y sus constantes, son las que
+registra `autoscript.lock.json`, la única fuente de verdad al respecto: hoy
+fija el tag `v1.9.2`, que corresponde a AutoScript `1.9.0`. Consulta la
+política de compatibilidad en
+[AGENTS.md](AGENTS.md#compatibilidad-y-versiones) antes de actualizar.
+
+## Instalación
+
+```bash
+npm install @erseco/autofirma-client
+```
+
+El paquete incluye una copia fijada y verificada por hash de `autoscript.js`
+en `vendor/autoscript.js`; no hace falta descargarla aparte. Ese fichero no es
+un módulo: es un script clásico que no declara UMD ni exporta nada, sino que
+confía en que su `var` de nivel superior se convierta en global. Por eso no
+puede importarse con un empaquetador y hay que insertarlo como etiqueta
+`<script>`. `loadAutoScript(url)` hace justo eso: sirve `vendor/autoscript.js`
+desde tu propia infraestructura estática y pásale esa URL.
+
+```ts
+import { AutoFirmaClient, loadAutoScript } from "@erseco/autofirma-client";
+
+const autoScript = await loadAutoScript("/vendor/autoscript.js");
+const client = new AutoFirmaClient({ autoScript });
+```
+
+### Si lo sirves desde otro origen
+
+El paquete fija `autoscript.js` por sha256 (ver
+[ADR-0005](docs/arquitectura/adr/ADR-0005-empaquetar-autoscript.md)), pero esa
+garantía termina donde empieza la red: si lo sirves desde un CDN o un dominio de
+estáticos, quien controle ese origen controla el fichero. `loadAutoScript`
+acepta los atributos de Subresource Integrity para recuperarla.
+
+```ts
+const autoScript = await loadAutoScript(
+  "https://cdn.example.org/autoscript.js",
+  {
+    integrity: "sha256-…",
+    crossOrigin: "anonymous",
+  },
+);
+```
+
+`autoscript.lock.json` guarda la huella en hexadecimal y SRI la quiere en base64
+con prefijo `sha256-`:
+
+```bash
+printf 'sha256-%s\n' "$(node -p "require('./autoscript.lock.json').sha256" \
+  | xxd -r -p | base64)"
+```
+
+## Uso
+
+```ts
+import { AutoFirmaClient } from "@erseco/autofirma-client";
+
+const client = new AutoFirmaClient();
+client.initialize();
+
+const file = document.querySelector<HTMLInputElement>("#document")?.files?.[0];
+
+if (!file) {
+  throw new Error("Selecciona un documento.");
+}
+
+const result = await client.sign({
+  data: file,
+  format: "PAdES",
+  parameters: {
+    mode: "implicit",
+    signingReason: "Aprobación del documento",
+  },
+});
+
+console.log(result.signature);
+```
+
+Las cadenas se interpretan como Base64. Para datos sin codificar usa `File`,
+`Blob`, `ArrayBuffer` o `Uint8Array`.
+
+### Servicios intermedios
+
+```ts
+const client = new AutoFirmaClient({
+  storageUrl: "https://example.org/storage",
+  retrieveUrl: "https://example.org/retrieve",
+});
+```
+
+Estos servicios pertenecen al protocolo de transporte de AutoFirma. No son un
+repositorio documental.
+
+### Guardar ficheros y comprobar el reloj
+
+```ts
+await client.saveDataToFile({
+  data: base64Data,
+  title: "Guardar firma",
+  filename: "firma",
+  extension: "csig",
+  description: "Firma electrónica (*.csig)",
+});
+```
+
+`saveDataToFile` pide a AutoFirma que guarde datos en un fichero elegido por
+la persona usuaria; rechaza si la versión fijada de AutoScript no expone la
+operación.
+
+```ts
+await client.checkTime({ checkType: "CT_RECOMMENDED" });
+```
+
+`checkTime` no informa del resultado a través de la promesa que devuelve:
+AutoScript hace una petición **síncrona** que bloquea la página mientras
+espera respuesta y solo avisa de un desfase con un `alert()` nativo;
+cualquier error (incluido uno de red) se silencia. Con
+`checkType: "CT_OBLIGATORY"` puede además impedir en silencio que una llamada
+posterior a `initialize()` cargue AutoFirma, así que el orden de las llamadas
+importa. El docblock de `checkTime` en [`src/client.ts`](src/client.ts)
+documenta el detalle completo.
+
+### Ficheros de ejemplo
+
+Para probar una integración local sin usar documentos reales:
+
+- [Texto para CAdES](docs/ejemplos/files/ejemplo.txt)
+- [XML para XAdES](docs/ejemplos/files/ejemplo.xml)
+- [PDF para PAdES](docs/ejemplos/files/ejemplo.pdf)
+
+Contienen datos ficticios. Una firma generada con ellos no demuestra que la
+integración valide certificados, cadenas de confianza o revocación.
+
+## Errores
+
+Todo fallo llega como `AutoFirmaError`, que conserva intactos `nativeType` y
+`nativeMessage` tal y como los devolvió AutoFirma. El campo `code` clasifica los
+casos sobre los que se puede actuar:
+
+| `code`                   | Cuándo                                                                 |
+| ------------------------ | ---------------------------------------------------------------------- |
+| `USER_CANCELLED`         | La persona usuaria canceló la operación o la selección de certificado. |
+| `DATA_TOO_LARGE`         | El fichero excede la memoria disponible de AutoFirma.                  |
+| `NATIVE_TIMEOUT`         | AutoFirma no respondió: no está instalada o no llegó a abrirse.        |
+| `NATIVE_ERROR`           | Cualquier otro fallo de AutoFirma, incluidos sus códigos `SAF_xx`.     |
+| `UNSUPPORTED_OPERATION`  | La versión fijada de AutoScript no expone esa operación.               |
+| `AUTOSCRIPT_UNAVAILABLE` | `window.AutoScript` no existe o no es la API de AutoScript.            |
+
+No existe un tamaño máximo declarado en ninguna parte. El fichero viaja entero
+en una sola pieza codificado en Base64, que lo agranda un tercio, y el límite
+real es la memoria de la aplicación nativa: al superarla responde `MEMORY_ERROR`
+y el cliente lo entrega como `DATA_TOO_LARGE`.
+
+## Qué aporta
+
+- API basada en `Promise`.
+- Tipos para PAdES, CAdES, XAdES y FacturaE.
+- Entradas `Blob`, `File`, `ArrayBuffer`, `Uint8Array` y Base64.
+- Serialización segura de parámetros en el formato de AutoScript.
+- Errores normalizados sin perder el tipo y mensaje nativos.
+- `MockAutoFirmaClient` para pruebas de aplicaciones consumidoras.
+- Acceso a `client.raw` para funciones oficiales no cubiertas todavía.
+
+## Seguridad y privacidad
+
+La librería transforma los datos en memoria y los entrega al objeto AutoScript
+de la página. **No incluye telemetría, backend, cookies ni almacenamiento**. Que
+un documento salga o no del equipo depende de la configuración de AutoScript,
+de los servicios intermedios configurados por la aplicación y del código de la
+aplicación consumidora.
+
+No confíes en los datos devueltos por el navegador para decisiones jurídicas o
+de autorización. Valida en servidor la firma, la integridad del documento, el
+certificado, la cadena de confianza y, cuando proceda, la revocación.
+
+## Desarrollo
+
+```bash
+make install
+make check
+```
+
+La CI ejecuta formato, TypeScript, tests con cobertura y construcción en Node
+20, 22 y 24.
+
+### Symlinks en Windows
+
+Los procedimientos recurrentes del proyecto viven como skills en
+`.agents/skills/`, la ruta que leen Codex y Grok. Como Claude Code y GitHub
+Copilot buscan en `.claude/skills/` y `.github/skills/`, esos dos directorios
+contienen enlaces simbólicos a los mismos ficheros en vez de copias.
+
+Git guarda esos enlaces como tales, pero **en Windows solo los recrea al clonar
+si el soporte está activado**; de lo contrario aparecen como ficheros de texto
+que contienen la ruta de destino, y ni Claude Code ni Copilot encontrarán las
+skills. La copia real de `.agents/skills/` sigue funcionando en cualquier caso.
+
+```bash
+git config --global core.symlinks true
+```
+
+Hay que fijarlo **antes de clonar**: en un clon ya hecho no basta con activarlo,
+hay que volver a clonar o restaurar esas rutas. Además, Windows exige modo de
+desarrollador o privilegios de administrador para crear enlaces simbólicos.
+
+> [!NOTE]
+> `prepack` (y por tanto `npm pack` y `npm publish`) ejecuta
+> `scripts/vendor-autoscript.ts` directamente con `node`, que necesita el
+> soporte nativo de tipos activado por defecto (Node ≥22.18 o ≥23.6; en
+> versiones anteriores de la línea 22 existe solo tras la flag
+> `--experimental-strip-types`). Es intencional: la librería en sí es
+> compatible con Node 20 (`engines.node`), pero los scripts de mantenimiento
+> no. Empaquetar con una versión de Node anterior a esa falla con un error de
+> sintaxis poco claro; usa Node 22.18 o superior para generar el tarball o
+> publicar.
+
+Los objetivos rápidos son:
+
+- `make lint`: comprueba Prettier y TypeScript.
+- `make fix`: aplica Prettier.
+- `make test`: ejecuta Vitest con cobertura.
+- `make build`: genera ESM, CommonJS y tipos.
+- `make check`: ejecuta lint, tests y build.
+
+## Publicación
+
+Cada tag `v*` ejecuta `.github/workflows/release.yml`: comprueba que el tag
+coincide con la versión de `package.json` y con el tag fijado en
+`autoscript.lock.json`, repite todos los controles, verifica que el tarball
+generado contiene `vendor/autoscript.js` con el `sha256` que registra el
+lock y publica ese mismo tarball ya verificado (`npm publish artifacts/*.tgz`,
+sin volver a empaquetar) en tres sitios: el registro público de npm, el gestor
+de paquetes de GitHub y GitHub Releases.
+
+La publicación en npm usa **npm Trusted Publishing con OIDC**, sin tokens. Antes
+de la primera publicación hay que registrar en npm el repositorio
+`erseco/autofirma-client` y los workflows `release.yml` y `canary.yml` como
+publicadores de confianza.
+
+### Canal canary
+
+Cada push a `main` que pueda cambiar el paquete ejecuta
+`.github/workflows/canary.yml`, que repite los mismos controles y la misma
+verificación del tarball y publica bajo el dist-tag **`canary`**:
+
+```bash
+npm install @erseco/autofirma-client@canary
+```
+
+La versión se calcula sobre el **patch siguiente** al de `package.json`, no
+sobre el actual: una preversión ordena por debajo de su versión, así que
+`1.9.2-canary.x` quedaría por detrás de la `1.9.2` ya publicada pese a contener
+más código. Con `1.9.3-canary.<sello>.<sha>` ordena por encima de `1.9.2`, por
+debajo de un futuro `1.9.3`, y no ocupa ese número.
+
+`latest` queda reservado a los tags de release, y un rango como `^1.9.2` no
+acepta preversiones, así que quien instale de la forma habitual nunca recibirá
+un canary sin pedirlo. Este canal es además la única vía para publicar
+correcciones del wrapper entre dos tags de AutoFirma, que ADR-0004 registró como
+la contrapartida del versionado en espejo.
+
+Mientras no exista ninguna versión estable publicada, `npm install
+@erseco/autofirma-client` sin sufijo no resuelve, porque no hay dist-tag
+`latest`: hasta el primer tag hay que instalar con `@canary`.
+
+GitHub Packages no admite Trusted Publishing, así que ese paso se autentica con
+el `GITHUB_TOKEN` efímero del propio workflow y necesita el permiso
+`packages: write`. Para instalar desde ahí hay que apuntar el ámbito `@erseco`
+a ese registro y autenticarse, porque incluso los paquetes públicos de GitHub
+Packages exigen credenciales para descargarse:
+
+```
+@erseco:registry=https://npm.pkg.github.com
+```
+
+Quien no quiera ese paso adicional tiene el paquete en npm sin autenticación.
+
+## Documentación
+
+Una página con una demo ejecutable se publica en
+<https://erseco.github.io/autofirma-client/>, generada con
+`npm run build:web` a partir de `web/`. Las decisiones de arquitectura (ADR y
+SDD) están en [`docs/arquitectura/`](docs/arquitectura/).
+
+## Licencia
+
+GPL-2.0-or-later. AutoFirma y AutoScript conservan sus propias licencias y
+marcas.

package/dist/autoscript-adapter.d.ts

@@ -0,0 +1,30 @@
+import type { AutoScriptApi, SignatureOperation, SignResult } from "./types.js";
+declare global {
+    interface Window {
+        AutoScript?: AutoScriptApi;
+    }
+}
+/**
+ * Comprueba que un candidato sea la API de AutoScript y no cualquier otra cosa
+ * que ocupe el mismo nombre global.
+ *
+ * `window.AutoScript` no requiere ejecutar JavaScript para existir: un elemento
+ * con `id="AutoScript"` o `name="AutoScript"` lo define solo (DOM clobbering),
+ * y los saneadores de HTML habituales permiten `id`. Comprobar únicamente que
+ * el global sea *truthy* aceptaba ese elemento como si fuera la API: la firma
+ * no fallaba al construir el cliente sino mucho después, con un `TypeError`
+ * sin `code` al invocar una operación inexistente.
+ *
+ * `sign` es la única operación que AutoScript garantiza en todas sus versiones
+ * —el resto son opcionales en `AutoScriptApi`—, así que es lo mínimo que puede
+ * exigirse sin rechazar versiones legítimas.
+ */
+export declare function isAutoScriptApi(candidate: unknown): candidate is AutoScriptApi;
+/**
+ * Resuelve la API inyectada o el objeto global oficial.
+ */
+export declare function resolveAutoScript(injected?: AutoScriptApi): AutoScriptApi;
+/**
+ * Adapta una operación nativa basada en callbacks a una promesa.
+ */
+export declare function invokeSignatureOperation(operation: SignatureOperation, data: string, algorithm: string, format: string, parameters: string): Promise<SignResult>;

package/dist/base64.d.ts

@@ -0,0 +1,6 @@
+import type { SignableData } from "./types.js";
+/**
+ * Convierte datos binarios o texto Base64 en el formato esperado por
+ * AutoScript. Las cadenas se consideran ya codificadas en Base64.
+ */
+export declare function toBase64(data: SignableData): Promise<string>;

package/dist/client.d.ts

@@ -0,0 +1,80 @@
+import type { AutoFirmaClientOptions, AutoScriptApi, CertificateResult, CheckTimeOptions, ExtraParameters, SaveOptions, SignatureClient, SignOptions, SignResult } from "./types.js";
+/**
+ * Cliente moderno y fino sobre la API oficial AutoScript.
+ */
+export declare class AutoFirmaClient implements SignatureClient {
+    private readonly autoScript;
+    constructor(options?: AutoFirmaClientOptions);
+    /**
+     * Solicita a AutoScript que prepare o abra AutoFirma.
+     */
+    initialize(): void;
+    /**
+     * Firma los datos proporcionados.
+     */
+    sign(options: SignOptions): Promise<SignResult>;
+    /**
+     * Añade una firma al mismo nivel cuando AutoScript expone la operación.
+     */
+    coSign(options: SignOptions): Promise<SignResult>;
+    /**
+     * Contrafirma cuando AutoScript expone la operación.
+     */
+    counterSign(options: SignOptions): Promise<SignResult>;
+    /**
+     * Abre la selección de certificado sin iniciar una firma.
+     */
+    selectCertificate(parameters?: ExtraParameters): Promise<CertificateResult>;
+    /**
+     * Pide a AutoFirma que guarde datos en un fichero elegido por la persona
+     * usuaria.
+     */
+    saveDataToFile(options: SaveOptions): Promise<void>;
+    /**
+     * Comprueba la sincronía del reloj del equipo contra un servidor.
+     *
+     * AutoScript lo implementa con una petición XHR **síncrona** que bloquea el
+     * hilo principal (`xhr.open('GET', url, false)`) hasta obtener respuesta.
+     * Si no se indica `checkUrl`, la petición se envía contra
+     * `document.URL + '/' + Math.random()`: una URL inventada contra el propio
+     * origen de la página, un acceso de red no documentado en ningún otro sitio
+     * y que este método no evita ni controla, pese a que esta librería no hace
+     * ningún acceso de red propio.
+     *
+     * El único efecto observable de un desfase es un `alert()` nativo; AutoScript
+     * captura y silencia cualquier error (por ejemplo, que la petición falle).
+     * Por eso la promesa devuelta nunca informa del resultado de la
+     * comprobación: se resuelve siempre que la operación exista, haya o no
+     * desfase y haya o no error de red.
+     *
+     * Con `checkType: "CT_OBLIGATORY"` y un desfase detectado, AutoScript marca
+     * un estado interno (`severeTimeDelay`) que hace que su función de carga
+     * (`cargarAppAfirma`, a la que invoca `initialize()`) registre un aviso y
+     * retorne sin hacer nada la siguiente vez que se ejecute. El orden de
+     * llamadas importa y no está documentado: invocar
+     * `checkTime({ checkType: "CT_OBLIGATORY" })` antes de `initialize()` puede
+     * convertir `initialize()` en un no-op silencioso; invocarlo después de
+     * `initialize()` no afecta a una carga que ya se ha iniciado.
+     *
+     * Si no se indica `maxMillis`, se reenvía tal cual: AutoScript aplica
+     * entonces su propio valor por defecto (300000 ms, 5 minutos) en vez de uno
+     * impuesto aquí.
+     */
+    checkTime(options?: CheckTimeOptions): Promise<void>;
+    /**
+     * Devuelve el objeto oficial para casos que el wrapper todavía no cubra.
+     */
+    get raw(): AutoScriptApi;
+    /**
+     * Valida que exista la operación opcional antes de ejecutarla.
+     */
+    private executeRequired;
+    /**
+     * Rechazo homogéneo para operaciones ausentes en la versión fijada.
+     */
+    private unsupported;
+    /**
+     * Normaliza datos y parámetros antes de delegar en AutoScript.
+     */
+    private execute;
+}