dateKeys-dart/README.md

datekeys-dart

Librería Dart del protocolo DateKeys: DateKey, DateKeyCap (.dkc) y DateKeys Access Key (.dkk). Es Dart puro, sin Flutter ni plataforma, para que la app Flutter la use como dependencia de ruta (datekeys: { path: ../datekeys-dart }).

Es la tercera implementación de la especificación, después de la de referencia en Go (datekeys-go) y la de TypeScript (datekeys-ts). Como la de TypeScript, no genera datos de prueba propios: se contrasta con el testdata/ de datekeys-go.

Estado

Están hechas las etapas 0 y 1 del plan (docs/PLAN_dart.md del espacio de trabajo):

• 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 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:

Módulo	Contenido	En Go
lib/src/errors.dart	Los 19 códigos del §69 en su orden (ErrorCode), DateKeysException con el mensaje contexto: CÓDIGO, wrap, withContext y errorCode	errors.go
lib/src/bytes.dart	Hexadecimal, comparación y concatenación; UTF-8 estricto que conserva un U+FEFF inicial; utf8.DecodeRune y el %q de Go, con la tabla de strconv.IsPrint de Go 1.26	unicode/utf8, strconv
lib/src/cbor.dart	CborEncoder, CborDecoder, unmarshalCbor, peekSchema, checkSchema y walkCbor	codec/codec.go
lib/src/der.dart	check, split, content, setOfSorted y parseTime, con UTCTime y GeneralizedTime exactos al nanosegundo. Es interno, como en Go	internal/der/der.go, ya del borrador v0.12

lib/datekeys.dart exporta los errores, el CBOR y las funciones de bytes que necesita quien use la librería.

Los enteros son exactos en la VM y en la web. El int de Dart tiene 64 bits con signo en la VM y en la web es un double, exacto hasta 2^53. Por eso la librería no usa un int por encima de 2^53-1, ni desplazamientos u operaciones de bits de más de 31 bits:

• un entero de CBOR es un int hasta 2^53-1 y un BigInt por encima, como el number | bigint de datekeys-ts;
• CborDecoder.uint devuelve un int, porque todos los esquemas acotan sus enteros en 2^53-1, y uint64 devuelve un BigInt.

Las etapas siguientes traen el resto del protocolo en este orden:

Etapa	Contenido
2	Primitivas: HKDF, PBKDF2, scrypt, ChaCha20-Poly1305, X25519, Ed25519 estricto y age
3	BLS12-381 y tlock
4	Formatos, inspección (pasos 1 a 8) y apertura (pasos 9 a 18)
5	Firma y sello, con los textos de los veredictos
6	Escritor
7	Localizador y claves de autor

Versiones

Número	Dónde	Hoy
Librería	version de lib/src/version.dart y de pubspec.yaml, que una prueba mantiene iguales	0.1.0-dev
Especificación	specVersion de lib/src/version.dart: la que nombra el campo spec de cada fichero de testdata/	0.11

La rama sigue la versión de la especificación: v0.11, hasta que datekeys-go cierre la v0.12. La etapa 5 se sincronizará ya con la v0.12.

Dependencias

• En ejecución: solo package:crypto, para SHA-1, SHA-2 y HMAC. Todo lo demás es código propio: HKDF, PBKDF2, scrypt, ChaCha20-Poly1305, X25519, Ed25519, BLS12-381, ECDSA, RSA, DER, CMS y CBOR.
• En desarrollo: solo package:test, aprobado el 5 de octubre de 2026. No hay paquete de lints: las reglas del análisis están en analysis_options.yaml.
• pubspec.lock va en el repositorio, para que las pruebas usen siempre las mismas versiones.

Nada nuevo sin aprobación escrita del autor.

Comprobar

dart pub get

tool/check.sh

tool/check.sh es el gate local, como scripts/check.sh en datekeys-go y npm run verify en datekeys-ts. Comprueba:

• el formato;
• dart analyze --fatal-infos;
• dart test;
• la copia de testdata/ frente al repositorio de Go, que debe estar al lado, en ../datekeys-go.

Las pruebas que no leen ficheros corren también compiladas a JavaScript, en Node.js. Así se comprueba que los enteros son exactos en la web. No forman parte del gate:

dart test -p node

Las que leen ficheros llevan @TestOn('vm').

Datos de prueba

testdata/ es una copia de datekeys-go/testdata en un commit fijo. testdata/SOURCE.json registra el commit y el SHA-256 de cada fichero, igual que en datekeys-ts. La copia actual es la del tag spec-v0.11 (ae33434).

dart run tool/sync_testdata.dart sync --commit spec-v0.11

dart run tool/sync_testdata.dart check --against ../datekeys-go

• sync lee los ficheros con git en ese commit, así que nunca entran cambios sin commit del repositorio de 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.

Licencia

Apache-2.0 (LICENSE), como datekeys-go y datekeys-ts. La especificación tiene su propia licencia, CC-BY-4.0.