lib/datekeys.dart exports the key of words, as Go exports its package
wordkey: normalizeWords, checkWords, wordKey, WordKeyException, minWords,
minLetters and wordKeyRounds. wordIdentity stays internal, since it
returns an identity of age.dart, and so do the rules of paths and texts,
as internal/pathrule does in Go: the head and the public note of stage 4c
will use them.
The README says what stage 4a ports and how: the bytes of Go, the
platform's Unicode left aside, the errors, the round of 53 bits, the one
difference with datekeys-ts and what is exported; the integer rule of the
tables; the timings; and how the vectors are written, the generator of
the paths in an export of datekeys-go. The changelog has the entry of the
stage.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ -4,6 +4,22 @@ Cambios notables de la librería Dart. El proyecto usa versionado semántico; mi
## Especificación 0.11, en la rama `v0.11` — sin versión
### Etapa 4a: rutas, textos y llave de palabras (05-10-2026)
- **Las reglas de rutas y de textos** (`lib/src/pathrule.dart`), port de `internal/pathrule` de `datekeys-go` en `c531e93`, sobre las tablas de Unicode 18.0.0 y WindowsBestFit que genera `datekeys-go` (`lib/src/pathrule_tables.dart`):
- NFD con el orden canónico y Hangul, el pliegue de CaseFolding con U+0131 → U+0069, la minúscula simple y `Default_Ignorable` con la lista blanca de R4;
- las reglas de una ruta, de R2 a R6c y R10, con las proyecciones de las 15 tablas best-fit; las del árbol, R7 con su clave y las dos rutas que nombra, y R9; y las de los textos del §29.6, el comentario y el autor declarado;
- los textos de error de Go, en `PathRuleException`, sin código normativo: la cabecera y la nota lo pondrán en la etapa 4c. Como en Go, cada regla devuelve su violación y solo las funciones públicas lanzan;
- `canonicalTables`, el texto de `pathrule.Canonical`: una prueba recalcula `tablesDigest` desde las listas.
- **Bytes, como Go.** Las funciones acabadas en `Utf8` toman los bytes de un string de Go, donde un byte que no es UTF-8 válido es U+FFFD, y las demás un `String` como lo escribe `utf8Bytes`. Los límites cuentan bytes, y R6b puntos de código, nunca unidades UTF-16. Así cualquier entrada da el resultado de Go, también el final de R4b tras bytes no válidos, que Go cuenta como U+FFFD de tres bytes.
- **La llave de palabras del §38.1** (`lib/src/wordkey.dart`), port de `wordkey`: `normalizeWords`, `checkWords` con los textos de Go, `wordKey`, con el PBKDF2-HMAC-SHA256 de la etapa 2 y 600 000 iteraciones, `wordKeyPassword` y `wordKeySalt`, la P y la S del §38.1, y `wordIdentity`. `lib/datekeys.dart` exporta `normalizeWords`, `checkWords`, `wordKey`, `WordKeyException` y sus constantes, como el paquete público `wordkey` de Go; `wordIdentity` queda interna, porque devuelve una identity de `age.dart`.
- **Vectores de Go** en `test/vectors/`, con su copia en Dart para Node.js:
- `pathrule_vectors.json`, de `tool/pathrule_go_vectors.go`, que corre en una exportación de `datekeys-go` porque `internal/pathrule` no se puede importar desde fuera de su árbol: los casos de las pruebas de Go y de `datekeys-ts`, los dos lados de cada límite de R2, R3 y R6b, 1300 cadenas y 350 árboles de una semilla fija, también con bytes que no son UTF-8 válido, los casos de R9 y, por plano, el SHA-256 de una línea por punto de código de cada función;
- `wordkey_vectors.json`, de `tool/wordkey_go_vectors.go`: 400 textos y sus palabras, 515 listas de palabras con el resultado de `Check` y cuatro llaves, la primera la del §38.1.
- **Pruebas.** 31 nuevas en la VM y 18 en Node.js. Integrada encima de la 4b, el total es de 802 pruebas en la VM, sin ninguna aplazada, y 208 en Node.js. Cada punto de código de los 17 planos da el resultado de Go en las siete funciones; los de los planos 0, 1 y 14, también en Node.js. Las llaves de 600 000 iteraciones corren solo en la VM.
- **Fallos inyectados**, uno a uno y revertidos: 45, en el orden canónico, los ignorables, la lista blanca, el pliegue y la minúscula, las descomposiciones, los límites, las cuentas en UTF-16, las tablas best-fit, Hangul, los bytes no válidos, R4b, R6, R7, R9, R10, los textos, el texto canónico, y en la llave de palabras el separador, los espacios, las marcas, la cuenta de letras, las palabras repetidas y la sal. Las pruebas los detectan todos, cada uno con una prueba que corre también en Node.js. Cuatro se escapaban al principio, uno de R2, uno de R3 en unidades UTF-16, U+036F en las palabras y DEL en `checkWords`: los vectores llevan ahora los dos lados de cada límite.
- **`tool/pathrule_bench.dart`** mide las reglas y la llave de palabras: en la VM, una ruta tarda de 9,5 a 28 µs, un comentario de 16 KiB 0,7 ms y la llave 1,1 s. Las cifras, en el README.
### Etapa 4b: los formatos de la cápsula y de la llave de acceso (05-10-2026)
- **Las tramas** (`lib/src/framing.dart`): el PRELUDE de un `.dkc` y la trama de una `.dkk`, con las comprobaciones de los §23 y §40 en su orden y los textos de Go; `splitCapsule`, los pasos 1 a 3 de la inspección, con su `FramingException`; y `headerBinding`. El formato de una cápsula es el enum `CapsuleFormat`.
@ -6,14 +6,15 @@ Es la tercera implementación de la especificación, después de la de referenci
## Estado
Están hechas las etapas 0 a 3 del plan (`docs/PLAN_dart.md` del espacio de trabajo) y la parte 4b de la etapa 4:
Están hechas las etapas 0 a 3 del plan (`docs/PLAN_dart.md` del espacio de trabajo) y las partes 4a y 4b de la etapa 4:
- la etapa 0, el paquete, sus herramientas y `testdata/` sincronizado;
- la etapa 1, los errores normativos, los bytes, el perfil CBOR del §58 y el DER estricto, también el de los tiempos;
- la etapa 2, las primitivas y la lectura de `age`;
- la etapa 3, BLS12-381 y tlock: el emparejamiento, el hash a G1, el IBE de drand y la verificación de la firma de la ronda;
- la parte 4a, las reglas de rutas y de textos con las tablas de Unicode 18.0.0, y la llave de palabras;
- la parte 4b, los formatos de la cápsula y de la llave de acceso: las tramas, `PUBLIC_HEADER`, `CONTROL_CBOR` de los tres formatos, la `.dkk`, las extensiones, el Provider Profile, la DateKey con sus rondas y el relleno.
Las etapas 2 y 3 se hicieron en paralelo, en ramas aparte desde la etapa 1, y se integraron el 5 de octubre de 2026.
Las etapas 2 y 3 se hicieron en paralelo, en ramas aparte desde la etapa 1, y se integraron el 5 de octubre de 2026. Las partes 4a y 4b también: la 4a, en la rama `stage4a`, se integró encima de la 4b el mismo día. La parte 4c, el head, la nota pública, la inspección y la apertura, viene después.
La etapa 1 porta tres ficheros de `datekeys-go` en `601e6d2`, con las mismas lecturas, las mismas comprobaciones en el mismo orden y los mismos textos de error:
@ -65,6 +66,26 @@ Notas de la etapa 3:
- **La fuente de releases.** La librería no trae cliente HTTP: recibe una `ReleaseSource`, como `OpenOptions.Source` en Go. `fetchRelease` aplica la regla del paso 9: lo que lance la fuente es `ERR_RELEASE_UNAVAILABLE`, con su texto y ningún otro código.
- **Lo que se exporta.**`lib/datekeys.dart` exporta la verificación de releases y `checkCompressedPoint`, como `datekeys-ts`. El IBE y el stanza tlock son internos: los usará la apertura de la etapa 4. El cifrado no se exporta todavía: es del escritor, la etapa 6.
La parte 4a de la etapa 4 porta `internal/pathrule` y `wordkey` de `datekeys-go` en `c531e93`, la cabeza de la rama `v0.12`, que sigue la v0.11 con las correcciones de la revisión del 2 de octubre; los dos paquetes no cambian desde el tag `spec-v0.11`. Tienen las mismas comprobaciones, en el mismo orden y con los mismos textos de error:
| Módulo | Contenido | En Go |
|---|---|---|
| `lib/src/pathrule_tables.dart` | Las tablas de Unicode 18.0.0 y de WindowsBestFit del §29.5.1, que escribe `internal/pathrule/gen -dart` de `datekeys-go`; no se editan | `internal/pathrule/tables.go` |
| `lib/src/pathrule.dart` | NFD con el orden canónico y la descomposición de Hangul, el pliegue de CaseFolding con U+0131 → U+0069, la minúscula simple, `Default_Ignorable` con la lista blanca de R4 y las proyecciones best-fit; las reglas de una ruta (R2 a R6c y R10), las del árbol (R7 con su clave, y R9) y las de los textos del §29.6, el comentario y el autor declarado; y `canonicalTables`, cuyo SHA-256 es `tablesDigest` | `internal/pathrule` |
| `lib/src/wordkey.dart` | La llave de palabras del §38.1: `normalizeWords`, `checkWords`, `wordKey`, con el PBKDF2-HMAC-SHA256 de `sha256.dart` y 600 000 iteraciones sobre `wordKeyPassword` y `wordKeySalt`, la P y la S del §38.1, y `wordIdentity` | `wordkey` |
Notas de la parte 4a:
- **Bytes, como Go.** Go lee un string como bytes, y estas funciones también:
- las acabadas en `Utf8` toman los bytes de un string de Go. Un byte que no es UTF-8 válido es la runa U+FFFD, como en el `for range` de Go. Los límites cuentan bytes, salvo el de R3 sobre el NFD, en unidades UTF-16, como dice el spec, y el de R6b, en puntos de código;
- las demás toman un `String` como lo escribe `utf8Bytes`, que pone un surrogate suelto como los tres bytes de su punto de código, y dan lo que da Go con esos bytes.
Un lector solo ve UTF-8 válido (§58), y un escritor rechaza antes un `String` mal formado, como el de Go. Aun así, cualquier entrada da el resultado de Go, rarezas incluidas. R4b busca el final de un segmento sumando el tamaño de cada runa, así que Go cuenta cada byte no válido como los tres bytes de U+FFFD: acepta los bytes `ff 61 e2 80 8d`, con el ZWJ al final, y dice «U+200D at the end» de un ZWJ que no lo está. Los vectores lo fijan.
- **Ninguna función de Unicode de la plataforma** (§29.5.1): ni `toLowerCase` ni `RegExp`. La expresión regular de R6b se comprueba a mano: la base acaba en `~` y de 1 a 6 dígitos ASCII.
- **Los errores.**`PathRuleException` es `pathrule.Error`: la regla, el detalle y, en R7, las dos rutas que nombra, la posterior primero. No lleva código normativo: la cabecera lo dará como `ERR_HEAD_INVALID` y la nota pública como `ERR_EXTENSION_DATA_INVALID`, en la etapa 4c. Como en Go, cada regla devuelve su violación y solo las funciones públicas lanzan. `WordKeyException` lleva el texto de `wordkey.Check`.
- **La ronda** de la llave de palabras es un `int` de 0 a 2^53-1, como toda ronda de un perfil pinneado; en Go es un `uint64`.
- **Una diferencia con `datekeys-ts`:** con un `String` mal formado, que ningún lector ni escritor pasa a estas reglas, `datekeys-ts` toma un surrogate suelto como un punto de código; aquí son los tres bytes que daría Go.
- **Lo que se exporta.**`lib/datekeys.dart` exporta la llave de palabras, como el paquete público `wordkey` de Go: `normalizeWords`, `checkWords`, `wordKey`, `WordKeyException` y sus constantes. La CLI de Go y `datekeys-ts` derivan la llave fuera de la apertura y la pasan como una identity más. `wordIdentity` es interna, porque devuelve una identity de `age.dart`; las reglas de rutas y textos también lo son, como `internal/pathrule`, y las usarán la cabecera y la nota de la etapa 4c.
La parte 4b de la etapa 4 porta los formatos de la cápsula y de la llave de acceso de `datekeys-go` en `c531e93` (la rama `v0.12`: la v0.11 con los arreglos de la revisión del 2 de octubre), con las mismas comprobaciones en el mismo orden, las mismas capas del §69.1 y los mismos textos de error. El API sigue al de `datekeys-ts`:
| Módulo | Contenido | En Go |
@ -96,7 +117,8 @@ Los enteros son exactos en la VM y en la web. El `int` de Dart tiene 64 bits con
- SHA-256, ChaCha20 y Salsa20 trabajan con palabras de 32 bits: suman de dos a cinco y enmascaran la suma, y en cada rotación enmascaran la mitad desplazada a la izquierda, así que la VM y la web dan los mismos 32 bits;
- Poly1305 guarda el acumulador y r en diez limbs de 13 bits: cada producto queda por debajo de 2^31 y cada suma por debajo de 2^35, y sus acarreos se toman con `~/`, no con un desplazamiento, que en la web truncaría a 32 bits;
- el cuerpo de curve25519 es el de TweetNaCl en su versión de JavaScript: dieciséis limbs de 16 bits en un `Float64List`, con sumas de productos por debajo de 2^44;
- en BLS12-381 los elementos del cuerpo y los escalares son `BigInt`, y una ronda es un `int` hasta 2^53-1, cuyos 8 bytes se escriben como dos mitades de 32 bits.
- en BLS12-381 los elementos del cuerpo y los escalares son `BigInt`, y una ronda es un `int` hasta 2^53-1, cuyos 8 bytes se escriben como dos mitades de 32 bits;
- en las tablas de Unicode, la clase de combinación de un punto de código va en una entrada que vale el punto por 256 más la clase, por debajo de 2^29, así que sus desplazamientos quedan en 32 bits.
**`BigInt` no es de tiempo constante.** En las primitivas se usa solo con datos públicos: la reducción de escalares módulo ℓ y las comprobaciones de `onCurve` en Ed25519, que solo verifica, y el factor de trabajo de un stanza scrypt. Los secretos de las primitivas (el escalar de X25519, las claves de HMAC, ChaCha20 y Poly1305) van en la aritmética de limbs, sin ramas ni índices que dependan de ellos; ni la VM ni un motor de JavaScript prometen tiempo constante, aun así.
@ -168,6 +190,32 @@ La verificación hace el hash a G1, decodifica la firma y comprueba e(H(m), clav
Una estimación para un móvil: si uno de gama media, con Dart compilado AOT para ARM64, va de dos a cuatro veces más lento que esta VM, la verificación y el descifrado tardarán entre 30 y 80 ms cada uno, y los pasos 10 y 11 juntos, entre 70 y 150 ms. La app los llama en un `Isolate` (plan, «Rendimiento»). En la web, el `BigInt` de dart2js es unas veinte veces más lento que el de la VM; una capa del cuerpo de limbs fijos sería la forma de acelerarlo.
### Rutas, textos y llave de palabras
`dart run tool/pathrule_bench.dart` mide las reglas de rutas y textos y la llave de palabras en la VM. Compilado a JavaScript:
Son medianas de tres ejecuciones, el 5 de octubre de 2026:
| Operación | VM | Node.js |
|---|---|---|
| `checkPath` de una ruta ASCII de 38 caracteres | 9,5 µs | 12 µs |
| `checkPath` de una ruta de 28 caracteres con acentos y U+2665, que R6c proyecta con sus 15 tablas | 28 µs | 38 µs |
| `checkComment` de un comentario de 16 351 bytes, casi el máximo | 0,7 ms | 0,6 ms |
| `checkTree` de 1000 rutas | 5,3 ms | 6,1 ms |
| La cabecera más grande: `checkPath` de 65 535 rutas como la segunda, y `checkTree` | 2,0 s | 2,3 s |
| `normalizeWords` y `checkWords` de seis palabras | 6,6 µs | 9,2 µs |
| `wordKey`: PBKDF2-HMAC-SHA256 con 600 000 iteraciones (§38.1) | 1,1 s | 0,7 s |
La llave de palabras tarda un segundo, y una cabecera de 65 535 rutas que R6c proyecta, dos: la app llama a las dos en un `Isolate` (plan, «Rendimiento»). R6c comprueba la proyección de cada tabla aunque sea igual a la de una tabla anterior, como Go; saltarse las repetidas da el mismo resultado y baja la segunda ruta de 28 a 18 µs, y la cabecera más grande a 1,45 s.
## Versiones
| Número | Dónde | Hoy |
@ -218,7 +266,7 @@ dart run tool/sync_testdata.dart check --against ../datekeys-go
- Los ficheros de `testdata/` no se editan ni se generan aquí.
- En cada `dart test`, `test/testdata_test.dart` comprueba la copia, y que cada fichero nombre `specVersion`.
`test/vectors/` tiene los vectores de las primitivas, de `age`, de BLS12-381, de tlock y de los formatos. Los escribe Go, con las librerías de la caché de módulos que usa `datekeys-go` (`x/crypto`, `filippo.io/age`, `kilic/bls12-381`, `drand/kyber`, `kyber-bls12381` y `tlock`) y sus paquetes`provider` y `agewrap`; ningún valor esperado se escribe a mano. Los generadores van en `tool/`, con `//go:build ignore`, y se ejecutan en el contexto del módulo de `datekeys-go`, sin cambiar nada en él. Los de BLS12-381 y tlock dan la misma salida con el tag `spec-v0.11` y con el borrador v0.12, y leen ficheros congelados de `datekeys-ts`, cuya carpeta en esta máquina se llama todavía `App`:
`test/vectors/` tiene los vectores de las primitivas, de `age`, de BLS12-381, de tlock, de las reglas de rutas y textos, de la llave de palabras y de los formatos. Los escribe Go, con las librerías de la caché de módulos que usa `datekeys-go` (`x/crypto`, `filippo.io/age`, `kilic/bls12-381`, `drand/kyber`, `kyber-bls12381` y `tlock`) y sus paquetes, como `provider`, `agewrap`, `internal/pathrule` y `wordkey`; ningún valor esperado se escribe a mano. Los generadores van en `tool/`, con `//go:build ignore`, y se ejecutan en el contexto del módulo de `datekeys-go`, sin cambiar nada en él; el de las rutas, en una exportación suya. Los de BLS12-381 y tlock dan la misma salida con el tag `spec-v0.11` y con el borrador v0.12, y leen ficheros congelados de `datekeys-ts`, cuya carpeta en esta máquina se llama todavía `App`:
```bash
cd ../datekeys-go && go run ../datekeys-dart/tool/gen_primitive_vectors.go -out ../datekeys-dart/test/vectors
@ -248,6 +296,22 @@ cd ../datekeys-go && go run ../datekeys-dart/tool/release_go_vectors.go ../datek
cd ../datekeys-go && go run ../datekeys-dart/tool/formats_go_vectors.go -testdata ../datekeys-dart/testdata -out ../datekeys-dart/test/vectors
```
```bash
cd ../datekeys-go && go run ../datekeys-dart/tool/wordkey_go_vectors.go -out ../datekeys-dart/test/vectors
```
`internal/pathrule` solo se puede importar desde el árbol de `datekeys-go`, así que el generador de las rutas corre en una exportación suya, hecha con `git archive`, sin tocar el repositorio:
```bash
commit=$(git -C ../datekeys-go rev-parse v0.12)
out=$PWD/test/vectors
tmp=$(mktemp -d)
git -C ../datekeys-go archive "$commit" | tar -x -C "$tmp"
cp tool/pathrule_go_vectors.go "$tmp"
(cd "$tmp" && go run ./pathrule_go_vectors.go -source "$commit" -out "$out")
rm -rf "$tmp"
```
| Fichero | Contenido |
|---|---|
| `primitives.json` | SHA-256, HMAC, HKDF (RFC 5869), PBKDF2 (con el vector del §38.1), scrypt (RFC 7914), ChaCha20, Poly1305 y ChaCha20-Poly1305 (RFC 8439), X25519 (RFC 7748, BoringSSL y los puntos de orden pequeño), Ed25519 (las 64 primeras líneas de `sign.input` de Go, cuyas tres primeras son las de la RFC 8032, y sus mutaciones), el Base64 de Go y el Bech32 de `age` |
@ -260,11 +324,15 @@ cd ../datekeys-go && go run ../datekeys-dart/tool/formats_go_vectors.go -testdat
| `release_vectors.json` | Los veredictos, códigos y textos de `provider.Verify`, de `NewTimeIdentity` con su `Unwrap` y de `NewTimeRecipient` |
| `formats_*.json` | El diferencial de los formatos, de `datekeys-go` en `c531e93`: el resultado, el código y el texto de Go en unos 6 400 casos, válidos y rotos en cada capa del §69.1, con una semilla fija y sobre los fixtures editados. Las tramas, `PUBLIC_HEADER`, `CONTROL_CBOR` de los tres formatos, la `.dkk`, los perfiles, las extensiones con sus registros, `dk1_`, el RFC 3339, las rondas, el relleno hasta L_MAX, la comprobación del relleno de `capsule.Open`, los codificadores, los límites del §57, `BODY` y, para la precedencia del §69.1, cada fallo de una lista, solo y con cada otro |
| `formats_vectors.g.dart` | Uno de cada ocho casos de cada sección de `formats_*.json`, como constantes de Dart para las pruebas compiladas a JavaScript |
| `pathrule_vectors.json` | Las reglas de `internal/pathrule`: los casos de las pruebas de Go y de `datekeys-ts` y los dos lados de los límites de R2, R3 y R6b; 1300 cadenas y 350 árboles de una semilla fija (marcas combinantes, Hangul, ignorables, emoji, sosias best-fit de ASCII, nombres de dispositivo, alias 8.3, textos y bytes que no son UTF-8 válido) con el resultado de `CheckPath`, `CheckComment` y `CheckAuthor`, su NFD y su clave; los casos de R9; y, por plano, el SHA-256 de una línea por punto de código de cada función |
| `pathrule_vectors.g.dart` | El mismo JSON como constante de Dart |
| `wordkey_vectors.json` | La llave de palabras de `wordkey`: 400 textos con sus palabras, 515 listas de palabras con el resultado de `Check`, y cuatro llaves con su contraseña P y su sal S, el PBKDF2 de 1000 iteraciones para Node.js y el recipient; la primera es el vector del §38.1 |
| `wordkey_vectors.g.dart` | El mismo JSON como constante de Dart |
- Los fixtures que leen los generadores son los de `testdata/` de este repositorio, la copia sincronizada.
- `primitives.json`, los cuatro ficheros de BLS12-381 y tlock y los de los formatos salen iguales en cada ejecución. Lo aleatorio de tlock, los ciphertexts de kyber con su sigma y los de `datekeys-ts`, se lee de los ficheros congelados de `datekeys-ts` en `289fe71`, y Go los descifra otra vez. `age`, en cambio, saca sus claves y nonces de `crypto/rand`, así que `age.json` y `age_fixtures.json` cambian en cada ejecución; las pruebas leen lo que esté en el repositorio.
- `primitives.json`, los cuatro ficheros de BLS12-381 y tlock, `pathrule_vectors.json`, `wordkey_vectors.json` y los de los formatos salen iguales en cada ejecución. Lo aleatorio de tlock, los ciphertexts de kyber con su sigma y los de `datekeys-ts`, se lee de los ficheros congelados de `datekeys-ts` en `289fe71`, y Go los descifra otra vez. `age`, en cambio, saca sus claves y nonces de `crypto/rand`, así que `age.json` y `age_fixtures.json` cambian en cada ejecución; las pruebas leen lo que esté en el repositorio.
- Un fichero `age` de más de un chunk se guarda como su cabecera, su nonce y su file key: la prueba cifra otra vez el texto documentado y comprueba el SHA-256 del fichero entero antes de leerlo. Las cabeceras de megabytes se escriben como partes que se repiten.
- Las pruebas que corren en Node.js no leen ficheros. Los valores de Go que usan están en `primitives.g.dart`, `formats_vectors.g.dart`, `test/bls12381_constants.dart` y `test/ibe_constants.dart`. Una prueba en la VM compara los tres últimos con los JSON.
- Las pruebas que corren en Node.js no leen ficheros. Los valores de Go que usan están en `primitives.g.dart`, `pathrule_vectors.g.dart`, `wordkey_vectors.g.dart`, `formats_vectors.g.dart`, `test/bls12381_constants.dart` y `test/ibe_constants.dart`. Unas pruebas en la VM comparan con los JSON los de las rutas, la llave de palabras, los formatos, BLS12-381 y el IBE.
