@unknownncat/curve25519-node 1.0.1 → 2.1.0

package/README.md

@@ -1,56 +1,28 @@
 # @unknownncat/curve25519-node
 
+> 🇺🇸 English version: [README.en.md](./README.en.md)
+
+Implementação sem dependências de runtime de:
+
+- X25519 + Ed25519 (modo moderno via OpenSSL em `node:crypto`)
+- X25519 + Ed25519 (modo moderno opcional via WASM)
+- axlsign legado (modo opcional via WASM, compatível com `curve25519-js`)
+
 [![npm](https://img.shields.io/npm/v/@unknownncat/curve25519-node)](https://www.npmjs.com/package/@unknownncat/curve25519-node)
-[![downloads](https://img.shields.io/badge/downloads-new%20package-lightgrey)](https://www.npmjs.com/package/@unknownncat/curve25519-node)
-[![types](https://img.shields.io/badge/types-included-blue)](./dist/index.d.ts)
-[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![types](https://img.shields.io/badge/types-included-blue)](./dist/index.d.ts)
 ![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
 ![esm+cjs](https://img.shields.io/badge/ESM%20%2B%20CJS-compatible-blue)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 
-Modern **zero-dependency** X25519 + Ed25519 for Node.js using OpenSSL via `node:crypto`.
-
-- **Node:** `>= 20`
-- **Runtime deps:** `0`
-- **TypeScript:** `strict`, **ESM-first**
-- **Compat:** ESM + CJS (`import` e `require`)
-
----
-
-## Why
-
-O projeto original ([curve25519-js](https://github.com/harveyconnor/curve25519-js)) faz aritmética de campo manual em `Float64Array` (derivado de TweetNaCl) para Curve25519/Ed25519.
-
-Este pacote troca isso por primitivas nativas do OpenSSL (via `node:crypto`), com foco em:
-
-- **segurança** por implementação consolidada
-- **performance** melhor em Node moderno
-- **API pequena** e **bem tipada**
-
----
-
-## Compatibility notes (importante)
-
-Este pacote **não replica o esquema `axlsign`** do `curve25519-js`.
-
-Aqui a API é **padrão moderna**:
-
-- acordo de chave: **X25519**
-- assinatura: **Ed25519**
-
-Consequências:
-
-- Chaves de X25519 e Ed25519 são **diferentes** (public keys diferentes).
-- `sign`/`verify` usam chaves **Ed25519**.
-- Conversão X25519 public key ↔ Ed25519 public key **não é exposta** por `node:crypto`.
-- `opt_random` (64 bytes) do legado **não é suportado** em Ed25519 com `node:crypto`.
-  - O compat layer aceita um 3º argumento apenas por compatibilidade de chamada, mas **sempre lança erro** se ele for fornecido.
-- As assinaturas Ed25519 aqui são determinísticas (comportamento padrão do OpenSSL para Ed25519).
-- No legado, `openMessage` pode alterar o `signedMsg` recebido (bit de sinal); nesta implementação, as entradas não são modificadas.
+- Node: `>= 20`
+- Dependências de runtime: `0`
+- TypeScript: `strict`
+- Formatos de módulo: ESM + CJS
 
 ---
 
-## Install
+## Instalação
 
 ```bash
 npm i @unknownncat/curve25519-node
@@ -58,152 +30,266 @@ npm i @unknownncat/curve25519-node
 
 ---
 
-## Usage
-
-### ESM (TypeScript / Node moderno)
+## Uso Rápido
 
 ```ts
-import {
-  asBytes32,
-  x25519,
-  ed25519,
-  sign, // compat top-level (Ed25519)
-  verify, // compat top-level (Ed25519)
-} from "@unknownncat/curve25519-node";
+import { randomBytes } from "node:crypto";
+import { asBytes32, x25519, ed25519 } from "@unknownncat/curve25519-node";
 
-const aliceSeed = asBytes32(crypto.getRandomValues(new Uint8Array(32)));
-const bobSeed = asBytes32(crypto.getRandomValues(new Uint8Array(32)));
+const aliceSeed = asBytes32(randomBytes(32));
+const bobSeed = asBytes32(randomBytes(32));
 
 const aliceX = x25519.generateKeyPair(aliceSeed);
 const bobX = x25519.generateKeyPair(bobSeed);
 
-const s1 = x25519.sharedKey(aliceX.private, bobX.public);
-const s2 = x25519.sharedKey(bobX.private, aliceX.public);
-// s1 e s2 devem ser iguais
-
-const signerSeed = asBytes32(crypto.getRandomValues(new Uint8Array(32)));
-const ed = ed25519.generateKeyPair(signerSeed);
+const segredo1 = x25519.sharedKey(aliceX.private, bobX.public);
+const segredo2 = x25519.sharedKey(bobX.private, aliceX.public);
+// segredo1 === segredo2
 
+const signerSeed = asBytes32(randomBytes(32));
+const signer = ed25519.generateKeyPair(signerSeed);
 const msg = new TextEncoder().encode("hello");
 
 const sig = ed25519.sign(signerSeed, msg);
-const ok = verify(ed.public, msg, sig);
-
-const signedMsg = ed25519.signMessage(signerSeed, msg);
-const opened = ed25519.openMessage(ed.public, signedMsg);
+const ok = ed25519.verify(signer.public, msg, sig);
 ```
 
-### CommonJS
+CommonJS:
 
 ```js
 const { x25519, ed25519, asBytes32 } = require("@unknownncat/curve25519-node");
+```
 
-const seed = asBytes32(new Uint8Array(32));
-const kp = x25519.generateKeyPair(seed);
+Legado axlsign via WASM:
 
-const sig = ed25519.sign(seed, Buffer.from("hello"));
+```ts
+import { asBytes32, axlsign } from "@unknownncat/curve25519-node";
+
+const seed = asBytes32(new Uint8Array(32));
+const kp = axlsign.generateKeyPair(seed); // X25519 keypair compatível com curve25519-js
+const sig = axlsign.sign(kp.private, new TextEncoder().encode("hello"), new Uint8Array(64));
+const ok = axlsign.verify(kp.public, new TextEncoder().encode("hello"), sig);
 ```
 
-### Subpath imports (opcional)
+Moderno via WASM (`wasm`):
 
 ```ts
-import { generateKeyPair as xGenerateKeyPair, sharedKey } from "@unknownncat/curve25519-node/x25519";
-import { sign, verify } from "@unknownncat/curve25519-node/ed25519";
-import type { Bytes32, Bytes64 } from "@unknownncat/curve25519-node/types";
+import { asBytes32, wasm } from "@unknownncat/curve25519-node";
+
+const seed = asBytes32(new Uint8Array(32));
+const kp = wasm.x25519.generateKeyPair(seed);
+const shared = wasm.x25519.sharedKey(kp.private, kp.public);
+
+const msg = new TextEncoder().encode("hello");
+const sig = wasm.ed25519.sign(seed, msg);
+const ok = wasm.ed25519.verify(wasm.ed25519.publicKey(seed), msg, sig);
 ```
 
 ---
 
 ## API
 
-### Namespace `x25519`
+### `x25519`
+
+- `createPrivateKeyObject(secretKey32: Bytes32): KeyObject`
+- `createPublicKeyObject(publicKey32: Bytes32): KeyObject`
+- `publicKeyFromPrivateKeyObject(privateKey: KeyObject): Bytes32`
+- `publicKey(secretKey32: Bytes32): Bytes32`
+- `sharedKeyFromKeyObjects(privateKey: KeyObject, publicKey: KeyObject): Bytes32`
+- `sharedKey(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32`
+- `sharedKeyStrict(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32` (rejeita segredo all-zero)
+- `sharedKeyStrictFromKeyObjects(privateKey: KeyObject, publicKey: KeyObject): Bytes32` (rejeita segredo all-zero)
+- `isAllZero32(bytes32: Bytes32): boolean`
+- `generateKeyPair(seed32: Bytes32): { public: Bytes32; private: Bytes32 }`
+
+### `ed25519`
+
+- `createPrivateKeyObject(secretSeed32: Bytes32): KeyObject`
+- `createPublicKeyObject(publicKey32: Bytes32): KeyObject`
+- `publicKeyFromPrivateKeyObject(privateKey: KeyObject): Bytes32`
+- `publicKey(secretSeed32: Bytes32): Bytes32`
+- `generateKeyPair(seed32: Bytes32): { public: Bytes32; private: Bytes32 }`
+- `sign(secretSeed32: Bytes32, msg: Uint8Array): Bytes64`
+- `signWithPrivateKey(privateKey: KeyObject, msg: Uint8Array): Bytes64`
+- `verify(publicKey32: Bytes32, msg: Uint8Array, signature64: Bytes64): boolean`
+- `verifyWithPublicKey(publicKey: KeyObject, msg: Uint8Array, signature64: Bytes64): boolean`
+- `signMessage(secretSeed32: Bytes32, msg: Uint8Array): Uint8Array` (`assinatura || mensagem`)
+- `openMessage(publicKey32: Bytes32, signedMsg: Uint8Array): Uint8Array | null`
+
+### `axlsign` (compatibilidade legado, via WASM)
+
+- `publicKey(secretKey32: Bytes32): Bytes32`
+- `sharedKey(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32`
+- `generateKeyPair(seed32: Bytes32): { public: Bytes32; private: Bytes32 }`
+- `sign(secretKey32: Bytes32, msg: Uint8Array, opt_random?: Bytes64): Bytes64`
+- `verify(publicKey32: Bytes32, msg: Uint8Array, signature64: Bytes64): boolean`
+- `signMessage(secretKey32: Bytes32, msg: Uint8Array, opt_random?: Bytes64): Uint8Array`
+- `openMessage(publicKey32: Bytes32, signedMsg: Uint8Array): Uint8Array | null`
+
+### `wasm` (modo moderno opcional, via WASM)
 
+`wasm.x25519`:
+
+- `createPrivateKeyObject(secretKey32: Bytes32): WasmX25519PrivateKeyObject`
+- `createPublicKeyObject(publicKey32: Bytes32): WasmX25519PublicKeyObject`
+- `publicKeyFromPrivateKeyObject(privateKey: WasmX25519PrivateKeyObject): Bytes32`
 - `publicKey(secretKey32: Bytes32): Bytes32`
+- `sharedKeyFromKeyObjects(privateKey: WasmX25519PrivateKeyObject, publicKey: WasmX25519PublicKeyObject): Bytes32`
 - `sharedKey(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32`
+- `sharedKeyStrict(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32` (rejeita segredo all-zero)
+- `sharedKeyStrictFromKeyObjects(privateKey: WasmX25519PrivateKeyObject, publicKey: WasmX25519PublicKeyObject): Bytes32` (rejeita segredo all-zero)
+- `isAllZero32(bytes32: Bytes32): boolean`
 - `generateKeyPair(seed32: Bytes32): { public: Bytes32; private: Bytes32 }`
 
-### Namespace `ed25519`
+`wasm.ed25519`:
 
+- `createPrivateKeyObject(secretSeed32: Bytes32): WasmEd25519PrivateKeyObject`
+- `createPublicKeyObject(publicKey32: Bytes32): WasmEd25519PublicKeyObject`
+- `publicKeyFromPrivateKeyObject(privateKey: WasmEd25519PrivateKeyObject): Bytes32`
 - `publicKey(secretSeed32: Bytes32): Bytes32`
 - `generateKeyPair(seed32: Bytes32): { public: Bytes32; private: Bytes32 }`
 - `sign(secretSeed32: Bytes32, msg: Uint8Array): Bytes64`
+- `signWithPrivateKey(privateKey: WasmEd25519PrivateKeyObject, msg: Uint8Array): Bytes64`
 - `verify(publicKey32: Bytes32, msg: Uint8Array, signature64: Bytes64): boolean`
+- `verifyWithPublicKey(publicKey: WasmEd25519PublicKeyObject, msg: Uint8Array, signature64: Bytes64): boolean`
 - `signMessage(secretSeed32: Bytes32, msg: Uint8Array): Uint8Array`
 - `openMessage(publicKey32: Bytes32, signedMsg: Uint8Array): Uint8Array | null`
 
-### Top-level compat layer
+### Aliases de compatibilidade (top-level)
 
 - `sharedKey = x25519.sharedKey`
+- `sharedKeyStrict = x25519.sharedKeyStrict`
 - `generateKeyPair = x25519.generateKeyPair`
-- `sign`, `verify`, `signMessage`, `openMessage` (**Ed25519**)
+- `sign`, `verify`, `signMessage`, `openMessage` (semântica Ed25519)
 - `generateKeyPairX25519`, `generateKeyPairEd25519`
 
-> `sign` e `signMessage` aceitam um terceiro argumento opcional **apenas para compatibilidade de chamada**, mas **sempre lançam erro** se ele for fornecido (`opt_random` legado não suportado).
+---
+
+## Notas de Compatibilidade
+
+Este pacote suporta três modos:
+
+- **moderno nativo (recomendado):** `x25519` + `ed25519` via `node:crypto`
+- **moderno WASM (opcional):** namespace `wasm` (`wasm.x25519` + `wasm.ed25519`)
+- **legado:** `axlsign` via WASM para compatibilidade com `curve25519-js`
+
+| Recurso                             | `curve25519-js` | `curve25519-node`                            |
+| ----------------------------------- | --------------- | -------------------------------------------- |
+| Esquema de assinatura (moderno)     | axlsign         | Ed25519 (padrão)                             |
+| Esquema moderno alternativo         | não             | Ed25519 via WASM (`wasm.ed25519`)            |
+| Esquema de assinatura (legado)      | axlsign         | axlsign (namespace `axlsign`)                |
+| Acordo de chave                     | X25519          | X25519                                       |
+| Acordo moderno alternativo          | não             | X25519 via WASM (`wasm.x25519`)              |
+| Mesma chave para assinatura + ECDH  | sim             | apenas no namespace `axlsign`                |
+| `opt_random` nas APIs de assinatura | sim             | sim no `axlsign`, não no top-level/`ed25519` |
+| Backend OpenSSL                     | não             | sim                                          |
+
+Importante:
+
+- Chaves públicas X25519 e Ed25519 são diferentes.
+- Para fluxos de protocolo mais rígidos (estilo Signal), prefira `sharedKeyStrict` para rejeitar segredo compartilhado all-zero.
+- `node:crypto` não expõe API para converter public key X25519 ↔ Ed25519.
+- Top-level `sign`/`signMessage` e namespace `ed25519` continuam com semântica Ed25519 e rejeitam `opt_random`.
+- Para compatibilidade com `curve25519-js` (incluindo `opt_random`), use o namespace `axlsign`.
+- Assinaturas Ed25519 continuam determinísticas (comportamento padrão do OpenSSL).
+- Os módulos WASM (`axlsign` e `wasm`) são carregados sob demanda na primeira chamada (importar apenas `x25519`/`ed25519` não inicializa WASM).
 
 ---
 
-## Branded types
+## Motivação
+
+O `curve25519-js` é um projeto importante, mas usa aritmética de campo manual em JS (`Float64Array`, estilo TweetNaCl).
+
+Este pacote foca em Node moderno com primitivas do OpenSSL:
+
+- caminho de implementação mais seguro
+- melhor desempenho em Node >= 20
+- API menor e explícita
+- tipagem forte com zero dependências de runtime
+
+Além disso:
+
+- o namespace `axlsign` via WASM permite migração progressiva de código legado;
+- o namespace `wasm` via WASM oferece uma alternativa moderna sem dependência de `node:crypto` no caminho criptográfico.
+
+---
+
+## Tipos Branded
 
 - `Bytes32`
 - `Bytes64`
 
-Helpers:
+Helpers (validam sem copiar):
 
 - `asBytes32(u8)`
 - `asBytes64(u8)`
 
-✅ Os helpers validam tamanho e retornam o **mesmo objeto** (sem cópia).
-
 ---
 
-## Technical details (RFC 8410 DER)
+## Mapa de RFCs (uso no projeto)
 
-Prefixos usados para importar/exportar RAW(32) ↔ `KeyObject` via DER prealocado:
+| RFC                               | Seções usadas                                                                                                 | Uso no projeto                                                                                                                                  | Onde no código          |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| RFC 7748 (X25519)                 | Seção 5 (`The X25519 and X448 Functions`)                                                                     | Regras de clamping/decoding do escalar e comportamento da função X25519 (zera 3 bits baixos, zera bit mais alto, seta o segundo bit mais alto). | `src/x25519.ts`         |
+| RFC 7748 (X25519)                 | Seção 5.2 (`Test Vectors`), Seção 6.1 (`Diffie-Hellman / Curve25519`)                                         | Vetores oficiais para validação de interoperabilidade e corretude.                                                                              | `test/x25519.test.mjs`  |
+| RFC 8032 (Ed25519)                | Seção 5.1.5 (`Key Generation`), 5.1.6 (`Sign`), 5.1.7 (`Verify`)                                              | Semântica de keygen/sign/verify Ed25519 (executada por OpenSSL via `node:crypto`).                                                              | `src/ed25519.ts`        |
+| RFC 8032 (Ed25519)                | Seção 7.1 (`Test Vectors for Ed25519`)                                                                        | Vetores determinísticos para validação de chave pública e assinatura.                                                                           | `test/ed25519.test.mjs` |
+| RFC 8410 (X25519/Ed25519 em PKIX) | Seção 3 (identificadores de algoritmo), Seção 4 (`Subject Public Key Fields`), Seção 7 (`Private Key Format`) | Estrutura DER para import/export de chaves raw de 32 bytes em SPKI/PKCS#8 com OIDs de X25519 e Ed25519.                                         | `src/internal/der.ts`   |
 
-- X25519 PKCS#8 prefix: `302e020100300506032b656e04220420`
-- X25519 SPKI prefix: `302a300506032b656e032100`
-- Ed25519 PKCS#8 prefix: `302e020100300506032b657004220420`
-- Ed25519 SPKI prefix: `302a300506032b6570032100`
+Referências indiretas por estrutura ASN.1/PKIX:
 
-As operações usam buffers DER prealocados + `.set`, sem loops byte-a-byte.
+- RFC 5958 (OneAsymmetricKey / família PKCS#8)
+- RFC 5280, Seção 4.1.2.7 (`Subject Public Key Info`)
 
----
+Observações:
 
-## Performance notes
+- O projeto não reimplementa aritmética de curva em JS; as operações criptográficas usam OpenSSL via `node:crypto`.
+- A suíte de testes cobre vetores oficiais do RFC 7748 e RFC 8032.
 
-- Sem `Buffer.concat` no hot path; buffers montados por prealloc + `.set`.
-- `Uint8Array` → `Buffer` usa view zero-copy:
-  - `Buffer.from(u8.buffer, u8.byteOffset, u8.byteLength)`
+Rodar testes:
 
-- `signMessage` monta `signature || msg` com `Uint8Array` prealocado e `.set`.
-- Para throughput máximo em loops longos, considere cachear `KeyObject` no nível da aplicação (evita parse ASN.1 repetido).
+```bash
+npm test
+```
 
 ---
 
-## Security
+## Detalhes Técnicos (DER / RFC 8410)
 
-- Validação de tipo/tamanho em todas as entradas públicas.
-- Sem logs de segredo.
-- Comparações internas de DER prefix usam `timingSafeEqual`.
+Chaves raw de 32 bytes são importadas/exportadas com prefixos fixos:
+
+- X25519 PKCS#8: `302e020100300506032b656e04220420`
+- X25519 SPKI: `302a300506032b656e032100`
+- Ed25519 PKCS#8: `302e020100300506032b657004220420`
+- Ed25519 SPKI: `302a300506032b6570032100`
+
+Notas de implementação:
+
+- buffers prealocados + `.set`
+- views zero-copy de `Uint8Array` quando seguro
+- sem `Buffer.concat` em hot path
 
 ---
 
-## Tests
+## Notas de Performance
 
-```bash
-npm test
-```
+- Evita cópias desnecessárias de bytes nos caminhos críticos.
+- `signMessage` monta `assinatura || mensagem` com um único `Uint8Array` prealocado.
+- Para throughput máximo em loops longos, use os helpers de `KeyObject` (`create*KeyObject`, `*FromKeyObjects`) para reduzir overhead de parse ASN.1.
 
-Cobertura inclui vetores RFC:
+---
+
+## Notas de Segurança
 
-- X25519: RFC 7748
-- Ed25519: RFC 8032
+- validação estrita de tipo/tamanho nas APIs públicas
+- sem log de segredos
+- `timingSafeEqual` em comparações internas de tamanho fixo quando necessário
 
 ---
 
 ## Benchmarks
 
-Há um subprojeto isolado em `bench/` para comparar este pacote com `curve25519-js` sem adicionar dependências ao pacote principal.
+A suíte de benchmark fica isolada em `bench/` (subprojeto separado) e compara com `curve25519-js`.
 
 ```bash
 npm run build
@@ -212,14 +298,125 @@ npm install
 npm run bench
 ```
 
+### Snapshot real de benchmark (`npm run bench:ci`) no GitHub Codespaces
+
+Comando:
+
+```bash
+node --expose-gc bench.mjs --rounds=16 --roundMs=350 --warmupMs=500 --vectors=64 --variants=raw,cached --strict --verifyEvery=64 --jsonFile=results/bench-results.json
+```
+
+Ambiente:
+
+- Node: `v24.11.1`
+- OpenSSL: `3.5.4`
+- CPU: `AMD EPYC 7763 64-Core Processor`
+- Cores lógicos: `4`
+- Vetores: `64`
+
+### Tabela 1 - API moderna (`x25519` + `ed25519`)
+
+`sign`/`verify` abaixo comparam throughput de API, não equivalência criptográfica (Ed25519 vs axlsign legado).
+
+| Operação                       | Moderno raw | Legado raw (`curve25519-js`) | Speedup raw | Moderno cached | Legado cached (`curve25519-js`) | Speedup cached |
+| ------------------------------ | ----------: | ---------------------------: | ----------: | -------------: | ------------------------------: | -------------: |
+| `x25519.generateKeyPair`       |      14,378 |                        1,591 |       9.04x |         41,120 |                           1,478 |         27.83x |
+| `x25519.sharedKey`             |       9,970 |                        1,591 |       6.27x |         23,995 |                           1,554 |         15.44x |
+| `ed25519.sign (msg32)`         |      11,273 |                          143 |      78.95x |         23,696 |                             133 |        178.10x |
+| `ed25519.sign (msg1024)`       |      10,800 |                          138 |      78.07x |         22,502 |                             147 |        152.92x |
+| `ed25519.verify (msg32)`       |       7,280 |                          136 |      53.36x |          8,271 |                             155 |         53.37x |
+| `ed25519.verify (msg1024)`     |       7,160 |                          132 |      54.33x |          8,159 |                             154 |         52.90x |
+| `ed25519.signMessage (msg256)` |      10,624 |                          131 |      81.09x |         23,304 |                             148 |        156.97x |
+| `ed25519.openMessage (msg256)` |       6,574 |                          124 |      52.93x |          8,129 |                             154 |         52.64x |
+
+### Tabela 2 - Compatibilidade `axlsign` (equivalente ao `curve25519-js`)
+
+Aqui a comparação é de mesmo esquema criptográfico (equivalência + throughput).
+
+| Operação                                  | Moderno raw | Legado raw (`curve25519-js`) | Speedup raw | Moderno cached | Legado cached (`curve25519-js`) | Speedup cached |
+| ----------------------------------------- | ----------: | ---------------------------: | ----------: | -------------: | ------------------------------: | -------------: |
+| `axlsign.generateKeyPair`                 |       8,429 |                        1,583 |       5.33x |          8,384 |                           1,585 |          5.29x |
+| `axlsign.sharedKey`                       |       8,452 |                        1,583 |       5.34x |          8,396 |                           1,570 |          5.35x |
+| `axlsign.sign (msg32)`                    |       3,973 |                          144 |      27.61x |          3,952 |                             140 |         28.28x |
+| `axlsign.sign (msg32,opt_random)`         |       3,969 |                          147 |      27.03x |          3,984 |                             139 |         28.58x |
+| `axlsign.sign (msg1024)`                  |       3,881 |                          143 |      27.16x |          3,864 |                             139 |         27.72x |
+| `axlsign.verify (msg32)`                  |       6,527 |                          146 |      44.70x |          6,534 |                             143 |         45.72x |
+| `axlsign.verify (msg32,opt_random)`       |       6,506 |                          144 |      45.07x |          6,469 |                             141 |         45.80x |
+| `axlsign.verify (msg1024)`                |       6,361 |                          141 |      45.03x |          6,337 |                             135 |         46.92x |
+| `axlsign.signMessage (msg256)`            |       3,902 |                          140 |      27.79x |          3,935 |                             141 |         27.98x |
+| `axlsign.signMessage (msg256,opt_random)` |       3,885 |                          142 |      27.40x |          3,864 |                             145 |         26.60x |
+| `axlsign.openMessage (msg256)`            |       6,441 |                          138 |      46.57x |          6,300 |                             131 |         47.93x |
+| `axlsign.openMessage (msg256,opt_random)` |       6,362 |                          141 |      45.24x |          6,285 |                             130 |         48.22x |
+
+Notas:
+
+- `raw` inclui custo fim-a-fim da API.
+- `cached` reduz overhead de setup para evidenciar melhor o throughput criptográfico.
+- Fonte dos números: saída JSON de `bench:ci` (`results/bench-results.json`).
+
+---
+
+## Build dos namespaces WASM (`axlsign` e `wasm`)
+
+No pacote publicado no npm, os artefatos WASM já vêm prontos em `dist/`.
+
+Para buildar a partir do código-fonte, você precisa:
+
+- Rust toolchain
+- `wasm-pack` instalado
+
+Com isso, `npm run build` executa:
+
+1. `wasm-pack build` (`wasm/axlsign`)
+2. `wasm-pack build` (`wasm/curve25519-wasm`)
+3. `tsc` ESM + CJS
+4. cópia dos artefatos WASM para `dist/internal/axlsign-wasm` e `dist/internal/curve25519-wasm`
+
+Referência dos crates Rust: [wasm/README.md](./wasm/README.md)
+
 ---
 
-## License
+## Contribuição
 
-MIT © unknownncat — veja [LICENSE](./LICENSE)
+- Guia: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Código de conduta: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- Segurança: [SECURITY.md](./SECURITY.md)
+
+Validação local completa:
+
+```bash
+npm run ci
+```
 
 ---
 
-## Thanks
+## Licença
+
+MIT
+
+Documentos complementares:
+
+- [NOTICE.md](./NOTICE.md) (aviso oficial de terceiros)
+- [THIRD_PARTY_NOTICE.md](./THIRD_PARTY_NOTICE.md) e [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) (aliases de compatibilidade)
+- [SECURITY.md](./SECURITY.md) (política de segurança e reporte de vulnerabilidades)
+
+---
 
-❤️ [curve25519-js](https://github.com/harveyconnor/curve25519-js)
+## Créditos
+
+- [curve25519-js](https://github.com/harveyconnor/curve25519-js) (Harvey Connor, Dmitry Chestnykh)
+- [TweetNaCl.js](https://tweetnacl.js.org/)
+- Trevor Perrin, ideia de assinaturas Curve25519: <https://moderncrypto.org/mail-archive/curves/2014/000205.html>
+- [Documentação Node.js `crypto`](https://nodejs.org/api/crypto.html)
+- [OpenSSL](https://www.openssl.org/)
+- [RustCrypto](https://github.com/RustCrypto)
+- [wasm-bindgen](https://github.com/wasm-bindgen/wasm-bindgen)
+- [curve25519-dalek](https://github.com/dalek-cryptography/curve25519-dalek)
+- [ed25519-dalek](https://github.com/dalek-cryptography/ed25519-dalek)
+- [x25519-dalek](https://github.com/dalek-cryptography/x25519-dalek)
+- [zeroize](https://github.com/RustCrypto/utils/tree/master/zeroize)
+- [RFC 7748](https://www.rfc-editor.org/rfc/rfc7748)
+- [RFC 8032](https://www.rfc-editor.org/rfc/rfc8032)
+- [RFC 8410](https://www.rfc-editor.org/rfc/rfc8410)
+- [RFC 5958](https://www.rfc-editor.org/rfc/rfc5958)
+- [RFC 5280](https://www.rfc-editor.org/rfc/rfc5280)

package/SECURITY.md

@@ -0,0 +1,23 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 2.x     | Yes       |
+| < 2.0.0 | No        |
+
+## Reporting a Vulnerability
+
+Please use GitHub private vulnerability reporting whenever possible:
+
+1. Go to the repository `Security` tab.
+2. Click `Report a vulnerability`.
+3. Submit impact details and a minimal proof-of-concept.
+
+If private reporting is not available, open a public issue without sensitive details and request private contact.
+
+## Scope
+
+- Cryptographic flaws, incorrect input validation, and integrity/confidentiality issues are high priority.
+- Include package version, runtime environment, and reproducible steps.

package/THIRD_PARTY_NOTICE.md

@@ -0,0 +1,3 @@
+# Third-Party Notice
+
+Canonical notice file: [NOTICE.md](./NOTICE.md)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# Third-Party Notices
+
+This file is kept for compatibility.
+
+Canonical notice file: [NOTICE.md](./NOTICE.md)

package/dist/axlsign.d.ts

@@ -0,0 +1,31 @@
+import type { Bytes32, Bytes64, KeyPair32 } from "./types.js";
+/**
+ * Derives an axlsign-compatible public key (Montgomery/X25519 format).
+ */
+export declare function publicKey(secretKey32: Bytes32): Bytes32;
+/**
+ * Computes an axlsign-compatible X25519 shared key.
+ */
+export declare function sharedKey(secretKey32: Bytes32, publicKey32: Bytes32): Bytes32;
+/**
+ * Generates an axlsign-compatible key pair from a 32-byte seed.
+ */
+export declare function generateKeyPair(seed32: Bytes32): KeyPair32;
+/**
+ * Detached axlsign signature using X25519-format secret key.
+ * opt_random (64 bytes) enables randomized signing as in curve25519-js.
+ */
+export declare function sign(secretKey32: Bytes32, msg: Uint8Array, opt_random?: Uint8Array): Bytes64;
+/**
+ * Verifies detached axlsign signature.
+ */
+export declare function verify(publicKey32: Bytes32, msg: Uint8Array, signature64: Bytes64): boolean;
+/**
+ * Returns signature || message (axlsign mode).
+ */
+export declare function signMessage(secretKey32: Bytes32, msg: Uint8Array, opt_random?: Uint8Array): Uint8Array;
+/**
+ * Verifies signature || message and returns original message on success.
+ */
+export declare function openMessage(publicKey32: Bytes32, signedMsg: Uint8Array): Uint8Array | null;
+//# sourceMappingURL=axlsign.d.ts.map

package/dist/axlsign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axlsign.d.ts","sourceRoot":"","sources":["../src/axlsign.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAqD9D;;GAEG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,CAIvD;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAK7E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAQ1D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,OAAO,CAU5F;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAK3F;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,OAAO,EACpB,GAAG,EAAE,UAAU,EACf,UAAU,CAAC,EAAE,UAAU,GACtB,UAAU,CAUZ;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAe1F"}