|
|
# datekeys-ts
|
|
|
|
|
|
Implementación en TypeScript del protocolo DateKeys v0.10 y página de prueba en el navegador. Sustituye al prototipo, archivado en `../archive/prototype` (API Quicknet en Go, CLI tlock y cliente Svelte, commit `4d2b0a1`).
|
|
|
|
|
|
La implementación de referencia es la librería Go `g.activething.com/go/DateKeys`, en `../datekeys-go`. Los planes y el estado del trabajo están en `../docs`, el repositorio privado de documentación del proyecto.
|
|
|
|
|
|
## Contenido
|
|
|
|
|
|
| Parte | Ubicación | Paso del plan | Estado |
|
|
|
|---|---|---|---|
|
|
|
| Codec CBOR del subconjunto, parsers de schema, DateKey, `inspect` | `src/lib/dkc/` | 4 | hecho |
|
|
|
| Página inspector, sin red | SvelteKit estático: `src/routes/`, `src/lib/inspector/`, `src/lib/components/` | 5 | hecho |
|
|
|
| Apertura de cápsulas en el navegador, y la acción "abrir" de la página | fase 2 (`PLAN_fase2_ibe_noble2.md`, en `../docs`) | 6 | hecho (pasos 2 a 8 de la fase 2) |
|
|
|
| Escritura de cápsulas en TypeScript | fase 3 (`PLAN_fase3_escritura.md`, en `../docs`) | 7 | hecho: la librería, su interoperabilidad con Go y la página `/create` (pasos 0 a 7 del plan) |
|
|
|
| Formato 3, especificación 0.10 (entrega 1) | `PLAN_formato3_ts.md`, en `../docs`, rama `v0.10` | — | hecho: la lectura y la escritura del formato 3, las reglas de las rutas, el ZIP de la página, `/inspect` y `/create` con ficheros y carpetas (pasos 0 a 8 del plan) |
|
|
|
|
|
|
## Versiones
|
|
|
|
|
|
Hay tres números de versión, cada uno con su significado, como en la referencia Go:
|
|
|
|
|
|
| Versión | Dónde | Cambia cuando |
|
|
|
|---|---|---|
|
|
|
| Formato | Dentro de los objetos: el formato de la cápsula, el `VERSION` del prelude de DKC1, 1, 2 o 3 al leer, que fija también la versión de schema de CONTROL_CBOR; y 1 en la trama DKK1 y en el schema de los demás objetos | Cambia el formato. Un lector rechaza una versión que no conoce (§22, §70) |
|
|
|
| Especificación | `SPEC_VERSION` de `src/lib/dkc/version.ts`, hoy `0.10`: la del tag `spec-v0.10` de `datekeys-go` | Cambia el texto normativo |
|
|
|
| Librería | `VERSION` de `src/lib/dkc/version.ts`, igual al campo `version` de `package.json` | Cambia la API o el comportamiento. Versionado semántico, sin promesa de estabilidad antes de 1.0.0 |
|
|
|
|
|
|
`version.test.ts` comprueba que `VERSION` coincide con `package.json` y con su lockfile, y que `SPEC_VERSION` es la versión que nombran los vectores y fixtures compartidos; `vectors.test.ts` exige esa versión a cada fichero. El pie de la página muestra las dos.
|
|
|
|
|
|
La versión actual es `0.2.0-dev`: la fase 3 añade la escritura de cápsulas de formato 2 y, en la rama `v0.10`, el plan del formato 3 (`PLAN_formato3_ts.md`, en `../docs`) añade la especificación 0.10: lee los formatos 1 a 3, escribe el 3, y el 2 solo como generador de vectores (§62.1, regla 1), y las páginas abren y crean cápsulas de formato 3 con ficheros y carpetas. El número de la versión que lo publique lo decide el autor. La última publicada es `0.1.0`, del 29 de septiembre de 2026, con el tag `v0.1.0`, que cubre:
|
|
|
- la especificación 0.9: lee los formatos de cápsula 1 y 2 (escribir, que solo escribirá el formato 2, llega en la fase 3);
|
|
|
- solo el scheme de Quicknet (`bls-unchained-g1-rfc9380`): un perfil de otro scheme se inspecciona, pero su release no se verifica (decisión 3 del plan de la fase 2);
|
|
|
- la inspección de los pasos 1 a 8 y la apertura de los pasos 9 a 18 (`open.ts`), desde un `Uint8Array` o un `Blob` y hacia memoria o hacia un stream de salida, como el de un fichero OPFS, también desde la página `/inspect`. Escribir cápsulas llega en la fase 3;
|
|
|
- todos los vectores y fixtures compartidos de `datekeys-go` en `7e2d83c` (`spec-v0.9`);
|
|
|
- navegadores con Web Crypto y Node 20 o posterior.
|
|
|
|
|
|
[CHANGELOG.md](CHANGELOG.md) recoge los cambios de cada versión.
|
|
|
|
|
|
## `src/lib/dkc`
|
|
|
|
|
|
La inspección (pasos 1 a 8) no importa ninguna dependencia. Funciona en navegadores y en Node 20+: solo usa `Uint8Array`, `DataView`, `TextEncoder`/`TextDecoder`, `BigInt` y `crypto.subtle` (SHA-256). La apertura (fase 2) usa las dependencias de ejecución de su sección: noble solo lo importan `digest.ts`, `ibe.ts`, `release.ts` y `x25519.ts`, y `age-encryption` solo `open.ts` y `tlock.ts`.
|
|
|
|
|
|
`crypto.subtle` solo existe en contextos seguros: `https`, o `http` en `localhost`. La página del paso 5 servida por `http` desde una IP de la red local (por ejemplo `vite --host` para probar en un móvil) no lo tiene, y `inspect` rechaza entonces con un `Error` que lo dice (`SHA-256 needs Web Crypto (crypto.subtle), …`) en vez de dar un veredicto. El registro por defecto no memoriza ese fallo: la siguiente llamada lo vuelve a intentar.
|
|
|
|
|
|
| Fichero | Contenido | Equivale en Go (`spec-v0.10`) |
|
|
|
|---|---|---|
|
|
|
| `errors.ts` | `DateKeysError` con el código normativo de §69 (`ERR_*`); mensajes con la forma `contexto: CÓDIGO` de Go | `errors.go` |
|
|
|
| `bytes.ts` | Hex, UTF-8 estricto, `goQuote` (el `%q` de Go, con la tabla de `strconv.IsPrint` de Go 1.26 fijada en el código) y `sha256` (Web Crypto) | `strconv`, `unicode/utf8` |
|
|
|
| `cbor.ts` | El codec propio de la referencia, con las mismas lecturas, las mismas comprobaciones en el mismo orden y los mismos textos de error: `Encoder` con error persistente; `Decoder`, cursor estricto (`map`/`key`/`endMap`, `array`, `uint`/`uint64`, `bstr`, `text`, `done`); `unmarshal` (decodifica, reencodifica y compara; `onReject` para borrar secretos); `peek`/`checkSchema` (capa 2 de §69.1: tipo y versión antes que nada) y `walk` (lector genérico acotado en profundidad y longitud) | `codec` |
|
|
|
| `schema.ts` | Lo que comparten los decodificadores de PUBLIC_HEADER, CONTROL_CBOR y el cuerpo de la `.dkk`: `key N: ` en los errores, claves obligatorias y arrays de extensiones | `capsule/framing.go`, `accesskey` |
|
|
|
| `extension.ts` | Arrays de extensiones, leídos con su objeto (capa 3 de §69.1). Registros con ubicación opcional (`registeredIn`): una extensión conocida fuera de los objetos y arrays de su registro cuenta allí como desconocida (§54, §72), como `extension.Placement` en Go. Reglas del array: de 1 a 64, en orden estrictamente ascendente de los bytes UTF-8 de `extension_id` (nunca por unidades UTF-16), `extension_version` hasta 2³² − 1, `data` ausente o `bstr` no vacío, ningún id en los dos arrays; registros, críticas y no críticas (capa 4) | `extension` |
|
|
|
| `profile.ts` | Provider Profile: CBOR exacto, `profile_hash`, reglas 1 a 4 de §12.1 en su orden (el límite de `period` de §74 en la capa del esquema; alfabetos, clave pública del grupo del scheme y fórmula de `chain_hash`), registro pinneado; Quicknet fijado por su CBOR y su hash | `profile` |
|
|
|
| `bls12381.ts` | Pertenencia de claves públicas BLS12-381 comprimidas (G1 y G2) al subgrupo, como `FromCompressed` de kilic | `kyber-bls12381` |
|
|
|
| `ibe.ts` | IBE-CCA de tlock sobre G2 para Quicknet (§63 paso 11): `decryptOnG2` y `encryptOnG2RFC9380` (Qid = H(id) en G1 con el DST de RFC 9380, sigma aleatorio, U = r·G2), con la puerta de codificación canónica de `bls12381.ts` sobre la firma y U; H2 sobre GT serializado en el orden de kilic (nunca `Fp12.toBytes` de noble), H3 y H4; `roundIdentity`; el cuerpo `U ‖ V ‖ W` de 128 bytes del stanza. Errores `IbeError` con motivo (`length`, `encoding`, `identity`, `proof`) y texto fijos, sin ningún valor del cálculo; borra sigma y los hashes derivados. Sobre `@noble/curves` 2.4.0; lleva el aviso MIT de `tlock-js`, cuya estructura sigue. Lo usa la apertura (`open.ts`) | `encrypt/ibe` de drand/kyber (`DecryptCCAonG2`), `tlock.BytesToCiphertext` y `TimeUnlock` |
|
|
|
| `release.ts` | Verificación local del release (§17, §51, §63 paso 10), en el orden y con los textos de `provider.Verify`:<br>1. el rango de la ronda (`ERR_DATEKEY_INVALID`);<br>2. la ronda del release antes que la firma (`ERR_ROUND_MISMATCH`);<br>3. la longitud de la firma;<br>4. la clave pinneada (`ERR_UNKNOWN_PROFILE`);<br>5. la firma: codificación canónica de un punto de G1 que no sea el infinito, y firma BLS válida de la ronda sobre `@noble/curves` 2.4.0, con el DST de RFC 9380 para G1 (`ERR_RELEASE_INVALID`).<br>Nada de noble se copia a los errores. Solo verifica el scheme de Quicknet: un perfil de otro scheme falla con `ERR_UNKNOWN_PROFILE` tras las comprobaciones de ronda, donde la referencia sí lo verificaría (decisión 3 del plan de la fase 2). También define `ReleaseSource`, con su contrato de fuentes de red y de la corrección 6, y `suppliedRelease`, el release que entrega quien llama | `provider` (`Verify`, `ReleaseSource`) |
|
|
|
| `open.ts` | Los pasos 9 a 18 de §63 sobre los pasos 1 a 8 de `inspectWith`, con los checks, códigos y textos de `capsule.Open`:<br>- las credenciales y el release (paso 9), que cualquier fallo de la fuente convierte en `ERR_RELEASE_UNAVAILABLE` (corrección 6);<br>- la verificación del release (10);<br>- `OUTER_TIME_AGE` (11), la estructura frente a `access_policy` (12) e `INNER_ACCESS_AGE` (13);<br>- `CONTROL_CBOR` (14), `header_binding` (15), `I_PAYLOAD` (16), `PAYLOAD_AGE` (17) y el commit (18).<br>Lee los dos formatos (§22, §70). En el formato 2, `INNER_ACCESS_AGE` tiene exactamente 16 stanzas (paso 12); `CONTROL_CBOR` es de la versión de schema 2, con L y la regla de relleno (14); el paso 16 calcula P, y el 17 exige un texto en claro de exactamente P bytes con ceros tras el contenido, `ERR_INTEGRITY` en otro caso. Solo se entregan los L primeros bytes, nunca el relleno (§29.1, §56). `Opened` da el formato y, en los formatos 2 y 3, L, la regla y P.<br>En el formato 3, el paso 17 lo hace `open3.ts`, y los ficheros van a `sink`; sin él, `open` rechaza con un `TypeError` justo tras el paso 2, antes de pedir nada, como `ErrSinkRequired`. `Opened` da entonces el head, los veredictos del área de seguridad y el tamaño del área.<br>Abre los tres ficheros `age` con el `Decrypter` de `age-encryption` y con identidades propias que aplican las reglas de `agewrap`: la de tiempo, sobre `ibe.ts`; las de acceso y payload, sobre `x25519.ts`, stanza a stanza. Los fallos de `age` que no informa una identidad son `ERR_INTEGRITY` con el motivo fijo de su fase, cabecera o STREAM, sin copiar el texto de `age-encryption`.<br>La entrada puede ser un `Uint8Array` o un `Blob`, como un `File`. De un `Blob` solo se lee el prefijo de los pasos 1 a 8 (`prefix.ts`), el `capsule_digest` de la `.dkk` se calcula sobre su stream (`digest.ts`) y `PAYLOAD_AGE` se descifra en streaming.<br>El texto en claro va a memoria o a `output`, un `WritableStream`. Se escribe a medida que `age` autentica cada chunk, se cierra solo tras el paso 18 y se aborta ante cualquier fallo, en cualquier paso (§56). Un fallo del stream de salida es `ERR_INTEGRITY` con su texto, como en Go. El `WritableStream` de un fichero OPFS guarda lo escrito en un fichero de intercambio hasta el cierre: comprobado en el navegador, un fallo de STREAM deja intacto el contenido anterior | `capsule.Open`, `agewrap` (`TimeIdentity`, `AccessIdentity`, `PayloadIdentity`) |
|
|
|
| `encrypt.ts`, `writer.ts` | Los writers. `encryptFiles(files, opts)` escribe un `.dkc` de formato 3, como `capsule.EncryptFiles`: comprueba las rutas y los textos con las reglas del lector y con los textos de Go, pone los ficheros en el orden de los bytes de sus rutas, mide L con un head de sal y hashes a cero, lee cada fichero dos veces y falla si cambió entre las dos lecturas; el head, el control y el área de seguridad se decodifican antes de escribir. Reproduce byte a byte `PRELUDE`, PUBLIC_HEADER, CONTROL_CBOR y `BODY` de los cinco fixtures que escribió `EncryptFiles`. `fileSource` hace la fuente de un `File`.<br>`encrypt(src, opts)`, el writer de la fase 3, escribe un `.dkc` de formato 2, desde la v0.10 solo con `testVectors`, porque solo un generador de vectores puede escribirlo (§62.1, regla 1), y sin head, y, si se pide, una `.dkk` portable (§61, §62, §62.1), en el orden y con los textos y códigos de `capsule.Encrypt`:<br>- el formato 2 siempre; L conocida de antemano (el tamaño de un `Uint8Array` o un `Blob`, o `length` con un `ReadableStream`), y una fuente que da más o menos bytes falla con los textos de Go;<br>- el relleno `reforzado` por defecto, o `bloque256`;<br>- de 1 a 16 credenciales, canónicas y no de orden bajo, un señuelo en cada hueco libre, cuyo escalar se borra al derivar su clave pública, y un orden uniforme de los 16 (`random.ts`);<br>- `SEALED_CONTROL_LEN` con la fórmula del §62.1, comprobada con el sellado real;<br>- las autocomprobaciones de la regla 11 y dos más: `OUTER_TIME_AGE` con las reglas del lector, y la cabecera de `PAYLOAD_AGE`, que `I_PAYLOAD` abre antes de escribir nada.<br>Nada se escribe hasta que todo lo anterior al contenido está comprobado. El contenido va en trozos de 64 KiB, seguido de los ceros del relleno, con presión inversa, hacia memoria (hasta `MAX_MEMORY_DKC`, 1 GiB) o hacia `output`, que se cierra solo con la cápsula completa y comprobada y se aborta ante cualquier fallo. Los errores de la fuente y de la salida se relanzan tal cual.<br>El núcleo, `writer.ts`, recibe la aleatoriedad de quien lo llama: `encrypt.ts` le da la de `crypto.getRandomValues`, y solo `testing/encrypt.ts` la fija, para reproducir los fixtures de Go | `capsule.Encrypt`, `accesskey.Encode` |
|
|
|
| `tlock.ts` | `timeRecipient`, el `Recipient` de `age-encryption` para `OUTER_TIME_AGE` (§32, §35), como `agewrap.TimeRecipient`: cifra la file key con `ibe.ts` para una ronda de un perfil pinneado y escribe el stanza `tlock <ronda> <chain hash>` de tlock. Comprueba el perfil y luego el rango de la ronda, con los textos de `NewTimeRecipient`. `age-encryption` no tiene etiquetas, así que quien escriba `OUTER_TIME_AGE` (fase 3) lo añade como único recipient | `agewrap.TimeRecipient` |
|
|
|
| `lengths.ts` | El tamaño de un `.dkc` de formato 2 o 3 antes de escribirlo. Para el formato 3, `bodyLength` da L con `headLength`, que mide el head por los tamaños de sus elementos CBOR sin codificarlo ni cargar las tablas de Unicode, y `mtimeSeconds` y `headComment` dan la mtime y el comentario tal como el writer los guarda. Para los dos formatos: `sealedControlLength`, la fórmula de `SEALED_CONTROL_LEN` del §62.1 con la que el writer comprueba su sellado, y `capsuleLength`, el tamaño exacto que escribe `encrypt` para una ronda, una política, L, el relleno y las extensiones, que la página muestra antes de cifrar porque cualquiera con el fichero lo ve (§55.2). Sin noble ni `age-encryption` | `capsule.Encrypt`, que mide un borrador sellado |
|
|
|
| `padding.ts` | El relleno del formato 2 (§29.1): los códigos 1 (`bloque256`) y 2 (`reforzado`), `paddedLength`, exacta hasta L_MAX = 2⁵³ − 2⁴⁶ (`bitlen` con `BigInt` y los redondeos con `ceil`, exactos en doubles; nunca operaciones de 32 bits, `Math.clz32` ni `Math.log2`), y la longitud de `PAYLOAD_AGE` | `capsule/padding.go` |
|
|
|
| `digest.ts` | SHA-256 incremental con `@noble/hashes` (`sha256Hasher`, `sha256Stream`), para el `capsule_digest` de un `.dkc` que no está en memoria o que se está escribiendo (Web Crypto solo calcula el hash de buffers enteros) | |
|
|
|
| `agefile.ts` | Ficheros `age` enteros con el `Decrypter` de `age-encryption`, compartidos por la apertura y las autocomprobaciones del writer: los errores de una identidad conservan su código, y cualquier otro fallo de `age` es `ERR_INTEGRITY` con el motivo fijo de su fase, cabecera o STREAM. Lo que se lee en memoria se borra trozo a trozo | `capsule.Open` |
|
|
|
| `recipient.ts` | Recipients `age1…` como los lee y escribe `age` 1.3.2, con sus textos, y las reglas de §37 y §62.1 (regla 3) con los de `agewrap.CheckX25519Recipient`: se rechazan los no canónicos (bit 255, u ≥ p) y los de orden bajo, comprobados con la lista de sus cinco coordenadas u, sin aritmética de curva; un punto del twist se acepta, como en Go. También lee la lista de recipients que escribe una persona, como un fichero `-R` de `age` algo más tolerante, con errores por número de línea que nunca citan su contenido. Sin noble, para que una página valide las líneas sin cargar el writer | `age` (`ParseX25519Recipient`), `agewrap.CheckX25519Recipient` |
|
|
|
| `random.ts` | Un índice uniforme sin sesgo (rechaza las palabras de 32 bits desde ⌊2³²/n⌋·n) y la permutación de Fisher–Yates, para el orden de los 16 huecos de `INNER_ACCESS_AGE` (§39) | `capsule.permute` |
|
|
|
| `x25519.ts` | El stanza X25519 de `age`, abierto de uno en uno como `X25519Identity.Unwrap` de `age`: argumentos, share, acuerdo de claves, longitud del cuerpo y autenticación, en ese orden, con las primitivas que usa `age-encryption` (X25519 de `@noble/curves`, HKDF-SHA-256 de `@noble/hashes` y ChaCha20-Poly1305 de `@noble/ciphers`). También lee identidades `AGE-SECRET-KEY-1…`, genera identidades nuevas en bytes crudos (`newX25519Identity`) y deriva su clave pública (`x25519PublicKey`) | `filippo.io/age` (`X25519Identity`), `agewrap` |
|
|
|
| `bech32.ts` | Bech32 (BIP 173) tal como `internal/bech32` de `age`, que la referencia copia como `codec/bech32`; conserva su aviso MIT | `codec/bech32` |
|
|
|
| `datekey.ts` | `dk1_` canónico con las reglas de lectura de §19 (CR, LF y todo carácter fuera del alfabeto fallan el paso 1; números JSON por su valor decimal exacto), ronda desde una fecha con precisión de nanosegundos y cota de 9999-12-31T23:59:59Z (§15), parser RFC 3339 equivalente a `time.Parse(time.RFC3339Nano, …)`; `compareInstants` e `isInstant`; `LONG_HORIZON_SECONDS` e `isLongHorizon`, el umbral de 365 días de los avisos de §53 y §50, una política de producto | `datekey` |
|
|
|
| `header.ts`, `control.ts`, `accesskey.ts` | PUBLIC_HEADER, CONTROL_CBOR y `.dkk` (cuerpo y trama), decodificar y codificar, con las capas de §69.1. CONTROL_CBOR se lee y se escribe para un formato: versión de schema 1 sin las claves 6 y 7, o 2 y 3 con `payload_length` (8 bytes, hasta L_MAX) y `padding` (1 o 2); 103 bytes sin extensiones sea cual sea L | `capsule`, `accesskey` |
|
|
|
| `body.ts`, `security.ts`, `head.ts` | El formato 3 (§29.2 a §29.7): la trama de `BODY` (`AREA_LEN`, `SECURITY_LEN` y `HEAD_LEN`) y los ceros del área, `ERR_INTEGRITY`; el `SECURITY_CBOR` vacío que escriben los writers y los veredictos X, F0, F1, S0, S1 y S2 con sus textos, que nunca fallan; y el head, con las capas de §69.1: R1 y R8 en el CDDL, R8 por los bytes UTF-8 y no por el orden UTF-16 de las cadenas de JavaScript, y luego el comentario, el autor declarado, las rutas, la maquetación, R7 y R9, todo `ERR_HEAD_INVALID`, y las extensiones críticas del objeto `head` | `capsule/format3.go` |
|
|
|
| `pathrule.ts`, `pathrule-tables.ts` | Las reglas de las rutas y de los textos del head (§29.5, §29.6), de R1 a R10 con R4b, R6b, R6c y R9, NFD, el pliegue y la clave de R7, con los textos de error de Go. Nunca usa `normalize`, `toLowerCase`, `localeCompare`, `Intl` ni las clases `\p{…}`, cuya versión de Unicode cambia con el motor: las tablas de Unicode 18.0.0 y WindowsBestFit las genera `datekeys-go` (`pathrule/gen -ts`), y una prueba recalcula su digest | `internal/pathrule` |
|
|
|
| `open3.ts`, `sink.ts` | El paso 17 del formato 3 en sus subpasos 17.2 a 17.8, con la precedencia de Go: un fallo de `age` o un texto en claro que no mide P prevalecen, manda el primer subpaso que falla, y los códigos distintos de `ERR_INTEGRITY` solo se dan tras leer `PAYLOAD_AGE` hasta el final. `Sink` (`begin`, `create`, `commit`, `abort`) recibe los ficheros y solo los publica en el paso 18; `MemorySink` los guarda en memoria, que crece con los bytes recibidos y nunca con los tamaños que declara el head | `capsule/open3.go` |
|
|
|
| `framing.ts` | Prelude DKC1 (16 bytes), con el formato de la cápsula, de 1 a 3, y DKK1 (12 bytes) en el orden de §23 y §40, longitudes de 1 byte hasta los límites de §57, y troceo de secciones | `capsule/framing.go` |
|
|
|
| `age.ts` | Parser estricto de la cabecera `age` v1 (§28.1) sobre los ficheros binarios, con los textos de error de `age`; reglas de stanzas, con los 16 de `INNER_ACCESS_AGE` en el formato 2 (`ACCESS_SLOTS`); `MAX_AGE_HEADER_LEN` (2 MiB), el límite que usa la página para leer solo el prefijo de un `.dkc` grande | `agewrap`, `filippo.io/age/internal/format` |
|
|
|
| `inspect.ts` | Pasos 1 a 8 de §63 y la vista JSON de `datekeys inspect -json` (`inspectView`, `inspectJSON`) | `capsule/inspect.go`, `internal/inspectview` |
|
|
|
| `prefix.ts` | Lecturas acotadas de un `Blob`: el prefijo de un `.dkc` que necesitan los pasos 1 a 8 (`readCapsule`) y, de una `.dkk`, como mucho 12 bytes + 16 MiB + 1 (`readAccessKey`), que dan el mismo resultado que el fichero entero | |
|
|
|
| `index.ts` | Reexporta todo salvo la fase 2 (`ibe.ts`, `release.ts`, `open.ts`, `tlock.ts`, `x25519.ts`, `bech32.ts`, `digest.ts` y `agefile.ts`), la fase 3 (`encrypt.ts`, `writer.ts`, `recipient.ts` y `random.ts`) y el formato 3 (`open3.ts`, `sink.ts`, `head.ts`, `pathrule.ts` y sus tablas, que pesan 136 KB), y una guarda lo comprueba. La página importa `index.ts`, y reexportarlos metería noble o `age-encryption` en la primera carga de `/inspect` aunque no los use, porque noble ejecuta código al cargarse. La página carga la apertura bajo demanda (`src/lib/inspector/opener.ts`) | |
|
|
|
| `testing/` | Solo para tests: lectura de `testdata/` y de sus formatos (`vectors.ts`: ediciones, vectores), constructores de CBOR en hex, cirugía de cápsulas | |
|
|
|
|
|
|
Los tests (`*.test.ts`) están junto a cada fichero.
|
|
|
|
|
|
### Equivalencia con la referencia Go
|
|
|
|
|
|
El comportamiento se contrastó con la librería Go en `3820066` (`692cf87` solo cambia la regla de UTF-8 de `dk1_` descrita abajo) mediante un oráculo diferencial fuera del repositorio: 483 527 entradas de tres semillas. Son mutaciones de los cinco `.dkc` oficiales de todas las clases (bits, bytes, truncados, inserciones, borrados, longitudes y campos del prelude, cabeceras reescritas con cambios de CBOR, DateKeys, arrays de extensiones con y sin registro de extensiones, cabeceras `age` de SEALED_CONTROL y de PAYLOAD_AGE, argumentos del stanza tlock, rondas, secciones cambiadas de sitio y combinaciones de varios defectos); CBOR de cada esquema (PUBLIC_HEADER, CONTROL_CBOR, cuerpo y fichero `.dkk`, Provider Profile, arrays de extensiones); `walk`, `peek` y `checkSchema`; cabeceras `age`, preludes, cadenas `dk1_`, rondas y fechas. En todas coinciden el veredicto, el código y el paso, y también el texto del error, el valor decodificado y la salida entera de `datekeys inspect -json`, byte a byte. Un segundo diferencial con otro generador, de 407 196 entradas, se repitió contra `f6f2e9f` (la enmienda de canonicidad de puntos) con el mismo resultado, textos incluidos.
|
|
|
|
|
|
Con la v0.9 se contrastaron contra `spec-v0.9` los 125 casos de `mutations.json`, en memoria y desde un `Blob` con salida, y coinciden el código, el paso y el texto del error de `capsule.Open` en todos. Desde la v0.10 ese contraste está en el repositorio: `src/lib/dkc/testing/mutation-texts.json` congela el texto de `capsule.Open` en `spec-v0.10` para los 209 casos, y `vectors.test.ts` exige el mismo en las dos aperturas. El validador de extensiones del arnés da los textos de `testkit.KnownExtensions`, así que ya coinciden también los casos de extensiones conocidas con datos inválidos.
|
|
|
|
|
|
Como la referencia desde `f6f2e9f`, los errores no copian el texto de una librería: una cabecera `age` que no se puede leer da siempre `agewrap: not an age v1 header: malformed, truncated or beyond the parser limits` (`ERR_INTEGRITY`). El motivo del parser, con las palabras de `age`, queda en `cause` del error, fuera del mensaje, y los tests lo comparan con los textos de `age` para comprobar que se rechaza por la misma razón.
|
|
|
|
|
|
Precedencia de errores (§69.1): primero la trama; después el tipo y la versión de esquema (`checkSchema`); después el perfil CBOR y el CDDL, con los límites de implementación de §74, en una sola decodificación (`unmarshal` con el decodificador del esquema, que ya comprueba tipos, tamaños, rangos, `access_policy`, `extension_version`, el máximo de 64 extensiones y su orden); y solo entonces los campos con código propio, en orden de clave: DateKey, perfil fijado y extensiones críticas en PUBLIC_HEADER; `access_type` y `access_material` en la `.dkk`; los campos y la autocomprobación de `chain_hash` en el Provider Profile. Entre pasos decide el orden de §63. Un PUBLIC_HEADER que rompe a la vez el CDDL y la DateKey da `ERR_NON_CANONICAL_CBOR`, como en la referencia de `3820066`; la de `afb44a3` leía `access_policy` y `extension_version` como `uint64` y los acotaba después de la DateKey, y la vía `wideUint` que lo imitaba ya no existe.
|
|
|
|
|
|
Enteros: el decodificador lee cada entero hasta 2⁶⁴ − 1 (un `bigint` por encima de 2⁵³ − 1) y lo compara con el máximo de su campo, con el texto de la referencia (`unsigned integer 9007199254740992 above 9007199254740991`). Ningún campo de un objeto del protocolo admite más de 2⁵³ − 1; `walk` admite cualquier `uint64`, como `codec.Walk`.
|
|
|
|
|
|
`peek` lee la capa 2 de §69.1 como `codec.Peek`: una cabecera de mapa de longitud definida que anuncia al menos dos entradas y no más de la mitad de los bytes que la siguen, la clave 0 con un texto de hasta 64 bytes y la clave 1 con un entero de hasta 2⁵³ − 1, todo en su forma más corta. No lee nada más: una versión que no es la esperada es `ERR_UNSUPPORTED_VERSION` sea lo que sea lo que venga detrás (en CONTROL_CBOR, la esperada es el formato de la cápsula), y cualquier otra cosa en esas posiciones, `ERR_NON_CANONICAL_CBOR`.
|
|
|
|
|
|
UTF-8 inválido en el JSON de un `dk1_` hace fallar el paso 2 de §19 (`ERR_DATEKEY_INVALID`) en las dos implementaciones, también en un miembro que un nombre repetido reemplaza después. Hasta `692cf87` la referencia Go lo sustituía por U+FFFD (`encoding/json`) y en ese caso daba `ERR_DATEKEY_NON_CANONICAL`; el diferencial de esta implementación lo encontró y la referencia se corrigió para seguir al spec. `datekey.test.ts` y el vector *invalid UTF-8 in a member a repeated name overwrites* de `dk1.json` lo fijan.
|
|
|
|
|
|
`goQuote` escribe como Go 1.26 (Unicode 15.0.0) los textos entre comillas de los detalles de fallo: usa una tabla de `strconv.IsPrint` generada con Go y no `\p{…}`, porque cada motor JavaScript trae su propia versión de Unicode (V8 en Node 24 ya imprime runas de Unicode 16 que Go escapa, como U+31E4). `bytes.test.ts` fija el SHA-256 del conjunto completo de runas imprimibles. Si el toolchain de la referencia cambia de versión de Unicode, se regenera con `go run scripts/go-isprint-table.go` y se actualizan la tabla y el hash.
|
|
|
|
|
|
Secretos: `access_material` de un `.dkk` e `I_PAYLOAD` de CONTROL_CBOR se borran en todos los caminos, también cuando la decodificación falla a medias o `unmarshal` rechaza el valor, como el `clear` diferido de Go.
|
|
|
|
|
|
## Página inspector
|
|
|
|
|
|
Sitio SvelteKit estático (`@sveltejs/adapter-static`, `strict`): las tres páginas se prerenderizan a HTML y no hay código de servidor.
|
|
|
|
|
|
| Ruta | Contenido |
|
|
|
|---|---|
|
|
|
| `/` | Qué es el inspector y qué garantiza; enlaza con `/inspect` y `/create` |
|
|
|
| `/inspect` | El inspector |
|
|
|
| `/create` | Crear una cápsula (fase 3, paso 7) |
|
|
|
|
|
|
`/inspect` carga un `.dkc` con el selector de ficheros, soltándolo en cualquier parte de la página o desde la lista de fixtures oficiales, y ejecuta `inspect` (pasos 1 a 8 de §63) sin registro de extensiones, como `datekeys inspect`. Muestra:
|
|
|
|
|
|
- cada paso con su número, su nombre de la CLI, `superado` o el código normativo, y el detalle (los caracteres invisibles o de control se escriben como `\uXXXX`);
|
|
|
- el veredicto, `capsule_id`, la DateKey compacta y decodificada (red y ronda), el perfil fijado, la fecha de apertura en UTC y en la hora local del navegador, `access_policy`, los campos del prelude con el formato de la cápsula (con un aviso en el veredicto si es el 1, que no oculta el número de credenciales ni la longitud exacta del contenido, §55.2), los argumentos del stanza `tlock` frente al perfil fijado y el número y tipo de stanzas de OUTER_TIME_AGE y PAYLOAD_AGE;
|
|
|
- las extensiones de PUBLIC_HEADER según el contrato del plan §8: id (entre comillas y escapado si tiene caracteres no imprimibles), versión, crítica o no, conocida o no, longitud y hex (plegado si pasa de 64 bytes); texto si los bytes son UTF-8 imprimible; vista CBOR con `walk` si son un ítem del perfil de §58, marcada "informativo, no validado por el protocolo"; y el aviso de que son públicas, de que nada las vincula al resto de la cápsula antes del paso 15 y de que ni entonces prueban autoría (§55.1);
|
|
|
- **Copiar JSON**, que copia exactamente la salida de `datekeys inspect -json` (`cliJSON`: el `json.Encoder` de Go con sangría de dos espacios, `<`, `>`, `&`, U+2028 y U+2029 escapados y salto de línea final). `file` es el nombre del fichero.
|
|
|
|
|
|
Todo el texto leído de la cápsula pasa por interpolación de texto de Svelte (nunca `{@html}`), y ni las entradas de mapas CBOR ni los identificadores de extensión se usan nunca como claves de objetos o `Map` de JavaScript.
|
|
|
|
|
|
### Abrir
|
|
|
|
|
|
Tras los pasos 1 a 8, si la cápsula es válida y su fecha de apertura ya pasó según el reloj del dispositivo, la página ofrece abrirla: pasos 9 a 18 de §63 con `open` (fase 2, paso 8). Antes de la fecha dice que nadie puede abrirla todavía y no pide nada.
|
|
|
|
|
|
- **El release lo da quien abre** (decisión 4 del plan de la fase 2, confirmada el 28-09-2026): la página nunca lo pide a la red. Se pega la respuesta JSON de drand o la firma sola en hexadecimal (`release-input.ts`), y solo se leen `round` y `signature`: cualquier otro campo, como una clave pública, se ignora, porque la raíz de confianza es el perfil fijado (§11, §13). La página enlaza la URL de drand de esa ronda (`https://api.drand.sh/<chain hash>/public/<ronda>`, con `rel="noopener noreferrer"`), que abre la persona en otra pestaña. Es un release que suministra quien llama: el paso 10 lo verifica y da sus códigos (`ERR_ROUND_MISMATCH`, `ERR_RELEASE_INVALID`). En los fixtures oficiales el campo viene relleno con el release de su registro, que es el que publicó drand.
|
|
|
- **Credenciales**, solo en `time_and_key`: una `.dkk` (se leen como mucho 16 MiB + 13 bytes, `readAccessKey`) o identidades `AGE-SECRET-KEY-1…`, una por línea, como un fichero de identidades de `age`. La página explica de dónde sale la identidad: del fichero que se creó con `age-keygen`, que se puede pegar entero. Un error de una línea se da por su número, nunca por su contenido, y el foco va al campo; las identidades se borran tras usarlas. En `time_only` la página no las pide y `open` no las usa.
|
|
|
- **El código de la apertura se carga bajo demanda**: la página importa `opener.ts` con `import()` al pulsar "Abrir", y con él `open.ts`, noble y `age-encryption`. `opening.ts`, que construye lo que se muestra, solo importa tipos de `open.ts`. `check-build.mjs` comprueba que ninguna página carga noble, `@scure/base` ni `age-encryption` en la primera carga.
|
|
|
- **El texto en claro** se muestra, cuando la cápsula se abre y es texto (`plaintextPreview`): UTF-8 imprimible, hasta 100 000 caracteres de sus primeros 128 KiB. Se muestra el CR LF de Windows como salto de línea y se omite el BOM, como hace un editor; la descarga conserva los bytes exactos. Lo que no es texto solo se ofrece para descargar. El de un fixture se abre en memoria, con su SHA-256 comparado con el del registro. El contenido va justo debajo del veredicto, antes de los pasos 9 a 18.
|
|
|
- **El nombre de la descarga.** La cápsula no guarda el nombre del fichero que sella (§6, §55.2), así que se ofrece el del `.dkc` sin la extensión, como hace `age` con `informe.pdf.age`. Si ese nombre no tiene extensión propia, como el `capsula-<fecha>.dkc` de `/create`, toma la del contenido (`contentExtension`): `.txt` para un texto, y `.pdf`, `.png`, `.jpg`, `.gif`, `.webp`, `.wav`, `.zip`, `.7z`, `.gz`, `.mp3`, `.mp4` u `.ogg` por sus primeros bytes. El de un fichero propio va a un fichero temporal del almacenamiento privado del navegador (OPFS, `tempfile.ts`), escrito con `createWritable`. El navegador guarda lo escrito en un fichero de intercambio que solo se confirma al cerrarlo, y `open` lo cierra tras el paso 18 y lo aborta ante cualquier fallo (§56). Después se ofrece para descargar, con el nombre del `.dkc` sin la extensión, como hace `age`, y cada carácter no imprimible cambiado por `_`, para que un carácter de control bidireccional no disfrace la extensión. Antes de empezar se compara el tamaño de `PAYLOAD_AGE` con la cuota libre (`navigator.storage.estimate()`).
|
|
|
- **El fichero temporal se borra** al pulsar "Borrar", al abrir o cargar otra cápsula y al salir de la página (`pagehide`). Si el navegador terminó antes, se borra en la siguiente visita. Cada pestaña escribe en su propio directorio, `datekeys-open/<id>`, y tiene un Web Lock con ese nombre mientras existe. Así la limpieza de otra pestaña nunca borra un fichero en uso; sin Web Locks, solo borra lo que tiene más de un día. Si el navegador no tiene OPFS o `createWritable`, o los rechaza (una ventana privada, datos del sitio bloqueados), o la cuota no alcanza, la página abre en memoria hasta 64 MiB. Una apertura en curso se detiene si se carga otra cápsula: su salida deja de aceptar datos, `open` falla en el paso 17 y su fichero se borra. Si la página vuelve de la caché de atrás y adelante tras borrar el fichero, ya no lo ofrece.
|
|
|
- **El formato 3** guarda ficheros con sus rutas (§29.2 a §29.7). Van al mismo fichero temporal por un `ZipSink`: un fichero de un solo segmento, tal cual; en los demás casos, un ZIP propio, y cada fichero es un tramo de ese ZIP (apartado 5 del diseño del formato 3). Sin OPFS, van a la memoria de la página, y el ZIP se compone allí con `zipOf`. Lo que se muestra sale de `files.ts`, que se carga con la apertura porque compara claves de R7:
|
|
|
- primero, las líneas de los veredictos del área de seguridad; después, el autor declarado y el comentario, como texto del creador sin comprobar, en un recuadro (§29.7);
|
|
|
- cada ruta como texto, en un `<bdi dir=auto>`, con los invisibles escritos como `\u…`, su tamaño y la fecha que declaró el creador; hasta 500 en la lista, y todas en el ZIP;
|
|
|
- los avisos de la CLI de la referencia, comparados por la clave de R7: un acceso directo (`.lnk`, `.url`, `.library-ms`, `.searchConnector-ms`), `desktop.ini`, una carpeta `.git`, un programa o un script, y un segmento que empieza por '-';
|
|
|
- las descargas: el fichero, con su nombre pasado por `safeFileName`, si es el único, con el ZIP de su carpeta como segunda opción; si hay varios, el ZIP, llamado `<primer segmento común>.zip` o como el `.dkc`, y cada fichero por separado.
|
|
|
|
|
|
Si el ZIP no cabe en el espacio que deja el navegador, `ZipSink` falla al empezar, con la longitud exacta, y la página lo dice. `check-build.mjs` comprueba que las tablas de `pathrule-tables.ts` no entran en la primera carga de ninguna página y sí en la carga bajo demanda de `/inspect` y `/create`.
|
|
|
- **La fecha** se vuelve a mirar cuando llega y cuando la pestaña vuelve a verse, así que una cápsula inspeccionada antes de su fecha se puede abrir sin cargarla otra vez. `open` comprueba de nuevo el reloj en el paso 9.
|
|
|
- **El resultado** muestra cada paso de 9 a 18 como muestra los de 1 a 8, con los checks que registra la referencia (desde la v0.9, también el 17 cuando se supera), el release verificado, las extensiones de CONTROL_CBOR, el tamaño y el SHA-256 del texto en claro y, en el formato 2, la regla de relleno y P. También avisa de que el texto está autenticado, pero no prueba quién lo escribió ni que sea el original si otros abrieron la cápsula antes (§55.1).
|
|
|
|
|
|
Medido en Chromium (el navegador de la app de escritorio) sobre la compilación de producción: los pasos 9 a 18 tardan 0,34 s en `time_only`, la primera apertura de la página, y 0,11 s en `time_and_key_portable`, la siguiente, sin contar la descarga del código y en el hilo principal (la política no permite workers).
|
|
|
|
|
|
### Crear
|
|
|
|
|
|
`/create` (plan de la fase 3, sección 9, con las decisiones del paso 6, y apartados 3 y 5 del diseño del formato 3) cifra ficheros y carpetas propios, con un comentario y un autor declarado, en un `.dkc` de formato 3 (§62.1, regla 1) y, si se pide, en una `.dkk` portable, todo en el navegador y sin red.
|
|
|
|
|
|
- **Lo que guarda** (`create-files.ts`, con la primera carga): ficheros elegidos con `multiple`, una carpeta con `webkitdirectory` o lo que se suelte en la página, carpetas incluidas, que se recorren con `webkitGetAsEntry` hasta el final. Un fichero va con su nombre, y el de una carpeta con el nombre de la carpeta delante, como `webkitRelativePath` y la CLI de la referencia. Las carpetas vacías no se guardan, y un recorrido se detiene en cuanto pasa de 65 535 ficheros. Una ruta que ya está en la lista se sustituye. Los ficheros que crean los sistemas dentro de una carpeta (`.DS_Store`, `Thumbs.db` y `desktop.ini`, comparados como `strings.EqualFold`, `._*` y lo que hay bajo `__MACOSX`) quedan fuera, tachados, con una casilla para marcarlos, como los deja fuera `collect.go`; uno elegido suelto, no.
|
|
|
- **Las rutas se pueden editar**, y se comprueban a medida que se escriben con las reglas del lector (`create-check.ts`, bajo demanda con las tablas de Unicode): cada problema en su fila, en español y con su regla, y un choque de R7 en las dos rutas. Una prueba de propiedad exige que la página no vea ningún problema exactamente cuando `checkPath` y `checkTree` aceptan las rutas. Una lista de más de 2000 ficheros se vuelve a comprobar tras una pausa al escribir, con el problema de cada ruta y la clave de cada segmento en memoria; se muestran los 500 primeros y los que han tenido un problema. Cada fila da el tamaño, la fecha y la ruta original si cambió.
|
|
|
- **El comentario y el autor declarado** son opcionales, se comprueban igual (§29.6) y van cifrados en el head, con el comentario en LF. La casilla de la fecha de modificación, marcada por defecto, guarda la de cada fichero, que se omite si cae fuera de 1970 a 9999 (§62.1, regla 16). Una cápsula puede guardar solo un comentario (decisión 9).
|
|
|
- **El formulario** (`create-input.ts`) mide los ficheros una vez por cambio de la lista (`measureFiles`), y con ellos da el tamaño exacto del `.dkc` a cada cambio del comentario, del autor o de la fecha. Después, el día y la hora, en la zona del dispositivo, en otra de las que conoce el navegador o en UTC. Y la política: «solo con la fecha» (`time_only`, la de por defecto) o «con la fecha y una clave» (`time_and_key`). Esta lleva destinatarios `age1…`, uno por línea y comprobados mientras se escriben (`recipient.ts`, sin noble), y la casilla de la clave portable, marcada por defecto; como mucho 16 credenciales. Una ayuda plegable explica qué es un destinatario de `age` y cómo se consigue: quien abrirá la cápsula crea su par con `age-keygen` y envía solo su `age1…`. Los campos se comprueban en su orden, y el foco va al campo del primer problema: una ruta que no vale lleva el foco a su fila.
|
|
|
- **La hora local** (`localtime.ts`) se convierte al instante UTC con `Intl` y las reglas de zona que conoce hoy el navegador. Una hora que la zona se salta al adelantar los relojes se rechaza. De una que repite al atrasarlos se toma la más tardía, para no abrir nunca antes de lo querido. La cápsula no guarda la zona.
|
|
|
- **Antes de cifrar**, la página muestra el instante efectivo, que es el de la ronda, en la zona elegida y en UTC, y cuánto cae después del pedido. También la ronda, la `dk1_`, la hora del dispositivo junto a la UTC, el contenido, el tamaño exacto del `.dkc` (`capsuleLength` con `bodyLengthOf`) y lo que la cápsula deja ver hasta la fecha (§55.2). Y los avisos: el de protocolo preliminar (§74), siempre; los de §53 y §50, con sus textos, si el instante efectivo está a más de 365 días (`LONG_HORIZON_SECONDS`); y uno informativo si está a menos de una hora. La hora del dispositivo se lee cada segundo mientras la pestaña se ve y al crear la cápsula; la página no la pregunta a ningún servidor. Si el navegador no conoce la zona del dispositivo (V8 da entonces `Etc/Unknown`), la página empieza en UTC.
|
|
|
- **El writer se carga bajo demanda**: la página importa `creator.ts` con `import()` al pulsar «Crear la cápsula», y con él `encrypt.ts`, noble, `age-encryption` y las tablas de Unicode de las rutas. El relleno es siempre `reforzado`, y no hay extensiones. `encryptFiles` lee cada fichero dos veces, y la página muestra el progreso de las dos pasadas: la primera, en bytes de los ficheros, contada por `creator.ts` con un stream propio que lee a demanda; la segunda, en bytes del `.dkc`. «Cancelar» detiene cualquiera de las dos, y un fichero que cambia entre ellas hace fallar la escritura. Lo escrito no se ofrece si no mide lo que se mostró o si los pasos 1 a 8 lo rechazan, y ante cualquier fallo se borra la `.dkk`. Si la fecha llega mientras la página se prepara para escribir, el writer la rechaza con su propio reloj (§62.1, regla 2), y la página lo dice en el campo de la fecha.
|
|
|
- **El `.dkc`** se escribe en un fichero temporal de OPFS, `datekeys-create/<id>/capsule` (`tempfile.ts`), que el navegador solo confirma cuando el writer lo cierra con la cápsula completa y comprobada. Si el navegador no tiene OPFS o lo rechaza, o la cuota no alcanza, se escribe en memoria, hasta 64 MiB. La cuota se comprueba con el tamaño exacto antes del primer byte. «Cancelar» detiene la escritura tras el trozo en curso: la salida se aborta y el fichero se borra. El fichero temporal se borra al pulsar «Borrar el fichero temporal», al crear otra cápsula y al salir de la página. Si el navegador terminó antes, se borra en la siguiente visita a `/create` o a `/inspect`, que limpian las dos zonas.
|
|
|
- **La `.dkk`** (152 bytes sin extensiones) vive solo en la memoria de la página: nunca en OPFS, y nunca se muestra como `AGE-SECRET-KEY-1…`. Sus bytes se borran al pulsar «Olvidar la clave», al crear otra cápsula y al salir, y con ellos las URL de sus descargas. Junto a ella va el aviso de §7.4. Si la cápsula solo se abre con su `.dkk` y no se ha descargado, la página pide confirmación antes de borrarla, al olvidarla o al crear otra, y avisa antes de salir: el navegador pregunta al cerrar o recargar, y la página, al seguir un enlace del sitio. Salir de la página también cancela una escritura en curso.
|
|
|
- **Las descargas** van por separado, con nombres que se pueden editar. Por defecto son `capsula-<apertura en UTC>.dkc` y `.dkk`, que no dicen cuándo se creó la cápsula. La URL `blob:` de cada descarga se revoca un minuto después del clic.
|
|
|
- **El resultado** muestra el `capsule_id`, la política, el contenido, el tamaño y el relleno, y el informe de los pasos 1 a 8 del `.dkc` escrito, con el componente del inspector.
|
|
|
|
|
|
Comprobado el 30-09-2026 en Chromium, con el formato 3:
|
|
|
- una lista de dos ficheros y una carpeta con `.DS_Store`, un fichero bajo `__MACOSX`, una ruta con «:», dos nombres que solo cambian en mayúsculas y una fecha de 1969: los dos del sistema, tachados; el problema de R4 y el choque de R7, en sus filas; la fecha de 1969, omitida;
|
|
|
- con las rutas corregidas, el comentario y el autor, la cápsula midió los 2.084 bytes del plan y se escribió en 0,47 s sobre la compilación de producción;
|
|
|
- pasada la fecha, `datekeys decrypt` de Go la abrió con los relays públicos: los seis ficheros con sus rutas y fechas, el autor y el comentario. `/inspect` la abrió con el release pegado de drand, con un ZIP y la descarga de cada fichero;
|
|
|
- al crear, una ruta `CON.txt` lleva el foco a su fila, y después un autor con un espacio inicial, a su campo;
|
|
|
- en el servidor de desarrollo, con el panel del navegador oculto, cada actualización del progreso retrasaba la escritura casi 2 s; la compilación de producción no lo hace.
|
|
|
|
|
|
Comprobado el 29-09-2026 en Chromium (el navegador de la app de escritorio), sobre la compilación de producción:
|
|
|
- un fichero de 77 bytes se cifró en `time_and_key`, con clave portable, para dentro de cuatro minutos, sin ninguna petición fuera del origen, y el informe pasó los pasos 1 a 8 con el formato 2;
|
|
|
- pasada la fecha, la cápsula se abrió en `/inspect`, con el release pegado de drand y la `.dkk`, y con `datekeys decrypt` de Go, con red y la `.dkk`: el mismo contenido, con el mismo SHA-256;
|
|
|
- los avisos de §53 y §50 salen solo a partir de 365 días;
|
|
|
- cancelar a mitad de 200 MB no deja fichero, y sin `createWritable` la cápsula se escribe en memoria;
|
|
|
- la página avisa al salir sin la `.dkk`;
|
|
|
- a 375 px ningún elemento desborda el ancho, ni con un nombre de fichero largo sin espacios.
|
|
|
|
|
|
Una revisión adversarial del 29-09-2026 encontró un fallo mayor: la `.dkk` que era la única credencial se podía borrar sin confirmación. Encontró también ocho menores, entre ellos una zona del dispositivo desconocida, el reloj de la página parado mientras la pestaña se veía, un mensaje equivocado con el reloj del dispositivo anterior a Quicknet y el foco durante la escritura. Todos se contrastaron y se corrigieron, y los del navegador se volvieron a comprobar en él. La revisión comparó además `localToEpochMs` con una búsqueda exhaustiva en las 418 zonas, sin ninguna diferencia en 26 114 horas locales. `localtime.test.ts` repite esa comparación en cada ejecución, alrededor de los 260 cambios de hora de 2030.
|
|
|
|
|
|
Rendimiento, informativo, en ese navegador con la ventana en segundo plano: una cápsula pequeña tarda 0,14 s en `time_and_key` y 0,2 s en `time_only`. 64 MiB tardan 5,4 s hacia OPFS (unos 12 MiB/s), y 60 MiB, 3,2 s en memoria; 1 GiB, 74,5 s hacia OPFS. Escribir 64 MiB en OPFS cuesta 1 s en trozos de 64 KiB, los del writer, y 0,55 s en trozos de 1 MiB.
|
|
|
|
|
|
| Fichero | Contenido |
|
|
|
|---|---|
|
|
|
| `src/lib/inspector/report.ts` | `buildReport`: el modelo de la página a partir de `Inspection`, sin DOM ni reloj |
|
|
|
| `src/lib/inspector/format.ts` | Nombres y glosas de pasos, códigos y políticas; texto imprimible y escapado; números y fechas en español; `cliJSON` |
|
|
|
| `src/lib/inspector/diagnostic.ts` | Notación de diagnóstico CBOR (RFC 8949 §8) de `walk`, acotada a 16 384 caracteres |
|
|
|
| `src/lib/dkc/prefix.ts` | Lectura por prefijo, que también usa la apertura: de un `.dkc` grande solo se leen 16 + PUBLIC_HEADER_LEN + SEALED_CONTROL_LEN + 2 MiB + 1 bytes, y solo 16 si los pasos 1 y 2 rechazan el prelude (otro tipo de fichero, un `.dkk`, longitudes fuera de §57), siempre con el mismo resultado que el fichero entero (lo comprueba `prefix.test.ts`) |
|
|
|
| `src/lib/inspector/fixtures.ts` | Los fixtures oficiales, empaquetados desde `testdata/fixtures` |
|
|
|
| `src/lib/inspector/release-input.ts` | Lee el release pegado (respuesta de drand o firma sola) y construye la URL de drand de la ronda |
|
|
|
| `src/lib/inspector/opener.ts` | La apertura, cargada bajo demanda: identidades, `.dkk`, `open` con el release suministrado, SHA-256 del texto en claro |
|
|
|
| `src/lib/inspector/opening.ts` | `buildOpenReport`: el modelo de la apertura (pasos 9 a 18, release, extensiones de CONTROL_CBOR, texto en claro), sin DOM ni reloj; nombre del fichero descifrado |
|
|
|
| `src/lib/inspector/tempfile.ts` | El fichero temporal de OPFS, con un directorio y un Web Lock por pestaña y por zona (la apertura y crear), la cuota libre y la limpieza de lo que quedó. Su `writable` acepta además trozos con posición (`TempChunk`), como `FileSystemWritableFileStream`, para parchear el CRC-32 del ZIP |
|
|
|
| `src/lib/inspector/crc32.ts`, `zip.ts` | El CRC-32 de ZIP, por trozos, y la disposición de un ZIP cuyas entradas se conocen de antemano: almacenadas, con nombres UTF-8 (bit 11), sin descriptores de datos ni entradas de carpeta; la hora DOS en UTC entre 1980 y 2107, el campo NTFS 0x000A, que manda, y 0x5455 cuando cabe en 32 bits con signo; ZIP64 por tamaño, posición o número de entradas |
|
|
|
| `src/lib/inspector/files.ts` | Lo que la página muestra de los ficheros de una cápsula de formato 3: cada ruta como texto, sus avisos por la clave de R7 con los textos de la CLI de la referencia, y el nombre y el orden de las descargas. Se carga bajo demanda con la apertura, porque trae las tablas de las rutas |
|
|
|
| `src/lib/inspector/zipsink.ts` | El sumidero de la página para el formato 3 (apartado 5 del diseño): un fichero de un segmento va tal cual al fichero temporal, y los demás casos a un ZIP en ese fichero, con cada cabecera en su posición, el CRC-32 parcheado al cerrar cada fichero y el directorio central al hacer commit; cada fichero queda como un tramo continuo. `zipOf` hace el mismo ZIP en memoria, como un `Blob` de sus partes |
|
|
|
| `src/lib/inspector/localtime.ts` | Una fecha y una hora locales de una zona como instante UTC, con `Intl`: las horas que no existen y las repetidas; la lista de zonas |
|
|
|
| `src/lib/inspector/create-files.ts` | La lista de ficheros de `/create`, sin tablas: lo elegido y lo soltado, carpetas recorridas incluidas, los ficheros de un sistema fuera por defecto como en `collect.go`, las rutas editadas y lo que la cápsula guarda |
|
|
|
| `src/lib/inspector/create-check.ts` | Las reglas de las rutas y de los textos (§29.5, §29.6) como las explica `/create`: todos los problemas de todas las rutas, en español, con los de `pathrule.ts`. Se carga bajo demanda, con las tablas |
|
|
|
| `src/lib/inspector/create-input.ts` | El formulario de `/create`, sin DOM, reloj ni writer: `planCapsule` comprueba los campos en su orden y da lo que se muestra antes de cifrar, con los ficheros medidos una vez (`chooseFiles`); los destinatarios y los nombres de los ficheros |
|
|
|
| `src/lib/inspector/creator.ts` | La escritura, cargada bajo demanda: `encryptFiles` con los ficheros, el comentario y el autor hacia el fichero temporal o la memoria, con el progreso de las dos lecturas, la cancelación y la cuota, y los pasos 1 a 8 de lo escrito |
|
|
|
| `src/lib/components/` | `InspectionReport`, `OpenPanel`, `StepList`, `ExtensionList`, `DataView`, `Mark` |
|
|
|
| `src/routes/` | Layout, portada, inspector y crear |
|
|
|
|
|
|
### Fixtures
|
|
|
|
|
|
`fixtures.ts` importa con `import.meta.glob` los `.dkc` de `testdata/fixtures` como URL (`?url`) y, de cada registro JSON, solo tres campos públicos: `description`, `release` (la ronda y la firma que publicó drand, con las que la página abre el fixture) y `plaintext_sha256` (para comparar con lo descifrado). `testdata/` sigue siendo la única fuente: Vite copia cada `.dkc` como fichero con hash en `_app/immutable/assets/` y nunca lo incrusta como `data:` (`assetsInlineLimit: 0`), y no se copia nada más. Los `.dkk`, los textos en claro y los demás campos de los registros (`payload_identity`, `control_cbor`…) no llegan al sitio; `check-build.mjs` lo comprueba. En desarrollo, `server.fs.allow` deja que Vite sirva `testdata/fixtures`.
|
|
|
|
|
|
### Sin red: la Content-Security-Policy
|
|
|
|
|
|
`kit.csp` (`svelte.config.js`, modo `hash`) pone en cada página prerenderizada, como primer elemento que carga algo, un `<meta http-equiv="content-security-policy">`:
|
|
|
|
|
|
```
|
|
|
default-src 'self'; frame-src 'none'; worker-src 'none'; connect-src 'self' https://api.drand.sh https://api2.drand.sh https://api3.drand.sh; font-src 'self';
|
|
|
img-src 'self'; manifest-src 'self'; object-src 'none'; script-src 'self' 'sha256-…';
|
|
|
style-src 'self'; style-src-attr 'unsafe-hashes' 'sha256-…'; base-uri 'none'; form-action 'none'
|
|
|
```
|
|
|
|
|
|
- `connect-src`: `fetch` llega al propio origen, para los fixtures, y a los tres relays públicos de drand que usa la CLI de la referencia, solo cuando la persona pulsa «Pedir la firma a drand» en `/inspect` (`drand.ts`: en carrera, 6 s, como mucho 8 KiB, sin redirecciones, y la aleatoriedad comprobada contra la firma, que el paso 10 verifica con la clave fijada). El relay ve la IP y la ronda pedida. Tampoco llega a URL `blob:`: la descarga del texto en claro es una navegación.
|
|
|
- `script-src`: los módulos del sitio y el hash SHA-256 del único script en línea, el arranque de SvelteKit (los nonces no sirven en HTML prerenderizado).
|
|
|
- `style-src 'self'`: solo hojas de estilo del sitio; sin fuentes web ni CDN, con las fuentes del sistema.
|
|
|
- `style-src-attr`: solo el atributo `style` del anunciador de rutas de SvelteKit, por su hash (`ANNOUNCER_STYLE_HASH`, válido para `@sveltejs/kit` 2.70.3; `app.css` lo oculta también si el navegador bloquea el atributo).
|
|
|
|
|
|
`npm run build` ejecuta después `scripts/check-build.mjs` (`postbuild`; también `npm run build:check`), que falla si una ruta no tiene su HTML prerenderizado; si una página no tiene exactamente esa política, con la etiqueta antes de cualquier elemento que cargue recursos; si un script en línea no está en `script-src` o sobra un hash; si `style-src-attr` no coincide con los atributos `style` del bundle; si hay estilos en línea, manejadores de eventos en atributos, `@import` o URL a otro origen; si algún `.dkc` oficial no está byte a byte; si aparece en el sitio algún secreto de los fixtures (`.dkk`, textos en claro, identidades, `payload_identity`, `access_material`, `control_cbor`); si el bundle del cliente contiene `tlock-js`, `drand-client` o helpers de Babel, o una copia anidada de un paquete que no sea la de noble bajo `@noble/post-quantum`; si una página carga noble, `@scure/base` o `age-encryption` en su primera carga, o si `/inspect` y `/create` no pueden cargar bajo demanda `age-encryption`, `@noble/curves` y `@noble/ciphers`, y `/create` también `@noble/hashes`; o si a `licenses.txt` le falta el aviso de un paquete del bundle, las líneas de copyright de un módulo de `src/` derivado de otro proyecto o la licencia del sitio. `vite.config.ts` registra los módulos de cada chunk en `.svelte-kit/output/client-modules.json`, fuera del sitio. Al terminar informa del JavaScript que carga cada página, en bytes y con gzip, en la primera carga y bajo demanda, y de los paquetes npm que lleva el bundle.
|
|
|
|
|
|
### Avisos de licencia: `licenses.txt`
|
|
|
|
|
|
El JavaScript minimizado no conserva comentarios, así que el sitio publica `licenses.txt`, enlazado desde el pie de cada página. Lo escribe un plugin de `vite.config.ts` al compilar el cliente, con tres partes:
|
|
|
- los módulos de `src/` derivados de otros proyectos, con el aviso de su cabecera: `ibe.ts` (de `tlock-js`, MIT) y `bech32.ts` (de `age`, MIT);
|
|
|
- el fichero de licencia de cada paquete npm con algún módulo en el bundle;
|
|
|
- la licencia Apache-2.0 del sitio.
|
|
|
|
|
|
En un hosting estático basta con servir `build/`. Las directivas que solo funcionan como cabecera HTTP (`frame-ancestors`, `sandbox`, `report-to`) quedan para el servidor que la aloje. `crypto.subtle` exige contexto seguro: `https`, o `http` en `localhost`.
|
|
|
|
|
|
## Reglas
|
|
|
|
|
|
- Los fixtures y vectores del Go son la verdad. Este proyecto nunca genera fixtures propios: `testdata/` es una copia exacta de un commit de la librería Go.
|
|
|
- Dependencias de ejecución: solo `age`, `drand`, `tlock` y lo que ellas arrastran; hoy, las de la sección «Dependencias de ejecución». El sitio lleva compilado además el runtime de cliente de Svelte y SvelteKit, el tooling que el plan elige para la página (sección 13).
|
|
|
- Tooling de desarrollo: solo el de la lista siguiente. Cualquier otra dependencia se propone por escrito y no se instala sin aprobación.
|
|
|
|
|
|
## Comandos
|
|
|
|
|
|
```bash
|
|
|
npm test # vitest, todos los tests
|
|
|
npm run coverage # tests con cobertura v8; falla por debajo de los umbrales
|
|
|
npm run typecheck # svelte-kit sync y tsc sobre todo y sobre la librería sin tipos de Node
|
|
|
npm run check # svelte-kit sync y svelte-check (componentes y rutas), falla con avisos
|
|
|
npm run dev # servidor de desarrollo: http://localhost:5173/inspect
|
|
|
npm run build # sitio estático en build/ y, después, scripts/check-build.mjs
|
|
|
npm run preview # sirve build/: http://localhost:4173/inspect
|
|
|
npm run build:check # solo la comprobación del sitio ya construido
|
|
|
npm run verify # check, typecheck, coverage y build (con su comprobación)
|
|
|
```
|
|
|
|
|
|
Umbrales de cobertura (`vitest.config.ts`), al 100 % en líneas, ramas, funciones y sentencias: de la librería, `cbor.ts`, `ibe.ts`, `release.ts`, `x25519.ts`, `bech32.ts`, `digest.ts`, `tlock.ts`, `prefix.ts`, `recipient.ts`, `random.ts`, `agefile.ts`, `padding.ts`, `writer.ts`, `encrypt.ts` y `lengths.ts`, y los del formato 3, `pathrule.ts`, `body.ts`, `security.ts`, `head.ts`, `open3.ts` y `sink.ts`; de la página, `fixtures.ts`, `opener.ts`, `opening.ts`, `release-input.ts`, `tempfile.ts`, `localtime.ts`, `create-input.ts` y `creator.ts`, y los del formato 3, `crc32.ts`, `zip.ts`, `zipsink.ts`, `files.ts`, `create-files.ts` y `create-check.ts`. El conjunto de `src/lib/dkc` al 95/90/95/95, y el de `src/lib/inspector` también.
|
|
|
|
|
|
`vitest.config.ts` es la configuración de los tests; `vite.config.ts`, la del sitio con el plugin de SvelteKit. Vitest prefiere la primera, así que los tests de `src/lib` corren sin SvelteKit, y `src/lib/inspector` importa la librería por rutas relativas, sin el alias `$lib`. `tsconfig.json` extiende el que genera `svelte-kit sync` (por eso `typecheck` y `check` lo ejecutan antes, y `npm install` también, con `prepare`).
|
|
|
|
|
|
`npm run typecheck` pasa dos veces: `tsconfig.json` (todo, con tipos de Node para los tests) y `tsconfig.lib.json` (solo la librería y sin tipos de Node, para que no se cuele ninguna API que no exista en el navegador).
|
|
|
|
|
|
### Vectores y fixtures
|
|
|
|
|
|
- `testdata/fixtures/*.json`: cada `.dkc`, de los tres formatos, pasa los pasos 1 a 8 con los valores registrados (formato, prelude, PUBLIC_HEADER, DateKey, `capsule_id`, política, `unlock_at`, extensiones con sus bytes exactos, stanzas, `header_binding`, CONTROL_CBOR) y abre con `open` a su contenido; L, y en los formatos 2 y 3 la regla y P, cuadran con la longitud de `PAYLOAD_AGE`, y cada credencial abre justo el stanza que el registro le asigna. En el formato 3, `BODY` se recompone del registro: la trama, el área con sus veredictos, el head, que se decodifica y se reescribe a sus bytes, y cada fichero en su tramo con su SHA-256; `open` entrega esos ficheros a un `MemorySink`, con sus veredictos. Cada `.dkk` se decodifica campo a campo y se reencodifica byte a byte. Los fixtures nuevos se recogen solos.
|
|
|
- `testdata/fixtures/*.inspect.json`: la vista de `inspect` de cada `.dkc`, escrita con `inspectJSON` como la imprime la CLI (`file` incluido), es idéntica byte a byte al fichero, también el texto de cada paso.
|
|
|
- `testdata/vectors/dk1.json` (con los tres vectores de los refinamientos de §19: LF dentro del Base64, CR y LF después, y la versión `1.0000000000000001`), `quicknet_rounds.json` y `profile_quicknet.json`: se ejecutan todos.
|
|
|
- `testdata/vectors/cbor.json`: cada vector genérico (`accept` y `reject`) pasa por `walk` con los `max_depth` y `max_len` del fichero; los enteros aceptados comparan su `value` (número o, por encima de 2⁵³ − 1, `bigint`), y los rechazados «above max_len» o «above max_depth» se aceptan sin ese límite. Cada vector de `schemas` pasa por el decodificador de su esquema (`decodeProfile`, `decodeHeader`, `decodeControl` con el formato del vector, 1 si no lo trae, también el 3, `decodeAccessKeyBody`) con el código exacto, y un objeto aceptado se reescribe a los mismos bytes.
|
|
|
- `testdata/vectors/padding.json`: P con las dos reglas y la longitud de `PAYLOAD_AGE` de cada L, incluidas las fronteras en que fallan las operaciones de 32 bits y un logaritmo en coma flotante, y las longitudes por encima de L_MAX, que se rechazan. `padding.test.ts` contrasta además `paddedLength` con el §29.1 escrito en `BigInt` sobre 20 000 longitudes de todo el rango.
|
|
|
- `testdata/vectors/tlock_ibe.json`: el vector de H2 del IBE de tlock (§63 paso 11). Hasta que llegue `ibe.ts` (fase 2), el test lo recalcula con `@noble/curves` 2.4.0: los puntos son canónicos para `bls12381.ts`, el pairing serializado en el orden de kilic es el GT del vector y su H2 coincide; el orden propio de noble (`Fp12.toBytes`) da otro hash.
|
|
|
- `testdata/vectors/mutations.json`: se leen los 209 casos enteros (ediciones sobre un fixture o hex congelado, release, reloj, registro, extensiones, `.dkk`, identidades y, en los tres que abren, sus veredictos). Los 209 pasan por `open` con su release, su reloj, su registro, sus extensiones, su `.dkk`, sus identidades y un `MemorySink`, y dan el mismo código en el mismo paso que Go y el mismo texto que `capsule.Open` (`testing/mutation-texts.json`); los tres de seguridad del formato 3 abren con los veredictos X, F1 y S1 del registro. También pasan como `Blob` con un stream de salida, que termina abortado en los 206 que fallan, y un sumidero que nunca se publica. Son los 169 del §64: las 33 mutaciones de las dos primeras listas en cada formato, las 23 de la lista del formato 2 y las 47 de la del formato 3; y 40 más. Ninguno de los que fallan sin red pide un release. Los 57 de los pasos 1 a 8 pasan además por `inspect`, y un test fija los recuentos y el orden. Las `.dkk` ofrecidas se decodifican.
|
|
|
- `testdata/vectors/inspect_differential.json`: las 5 110 mutaciones de los catorce fixtures de base dan el mismo veredicto, código y paso que Go; los `bases` se comprueban por su SHA-256.
|
|
|
- `testdata/vectors/paths.json` y `path_fold.json`, con las tablas cuyo digest nombran: cada ruta pasa por las reglas de una entrada con el texto exacto, cada árbol por la decodificación de un head de ficheros de 0 bytes, y cada segmento da su NFD y su clave de R7.
|
|
|
- `testdata/vectors/head_schema.json` y `security.json`: cada head pasa por `decodeHead` con el código de la primera capa que falla y el texto exacto de `ERR_HEAD_INVALID`, y un head válido se reescribe a sus bytes; cada área de seguridad da sus veredictos.
|
|
|
- `src/lib/dkc/testing/zip-vectors.json`: cómo lee `archive/zip` de Go los ZIP de la página. `scripts/zip-ts-samples.mjs` escribe con `ZipSink` las muestras de `testing/zip.ts` en un directorio: ficheros en carpetas con nombres fuera de ASCII y todas las clases de fecha (1970, 2³¹ − 1, 2³¹, 9999 y ninguna, que toma la hora de la ronda), un fichero dentro de una carpeta, y 65 535 ficheros, que hacen el ZIP64 por número de entradas. `scripts/zip-go-read.go`, solo con la biblioteca estándar, registra el SHA-256 de cada ZIP y una línea por entrada: nombre, bit 11, método, CRC-32, tamaños, fecha leída de los campos extra y SHA-256 del contenido, leído con el CRC comprobado. `zipsink.test.ts` vuelve a escribir cada muestra, exige su SHA-256 y calcula las líneas que Go tiene que dar. Para regenerarlo: `node scripts/zip-ts-samples.mjs DIR > zip-samples.json` y `go run scripts/zip-go-read.go DIR zip-samples.json > zip-vectors.json`.
|
|
|
- `src/lib/dkc/testing/mutation-texts.json`: el texto del error de `capsule.Open` para cada caso de `mutations.json`, u `ok`. Lo escribe `scripts/mutation-go-texts.go`, que reproduce los casos como `internal/testkit` de la referencia, que un módulo de fuera no puede importar: el perfil de Quicknet o ninguno, una fuente con el release del caso, la `.dkk` ya decodificada, las identidades, las extensiones del caso con los textos de `testkit.KnownExtensions` y un sumidero que descarta. Comprueba cada código contra el corpus. Para regenerarlo, desde un módulo Go temporal como el de abajo: `go run mutation-go-texts.go ../datekeys-ts/testdata > mutation-texts.json`.
|
|
|
- `src/lib/dkc/testing/ibe-vectors.json`: los valores de referencia de `ibe.ts`. Los escribe `scripts/ibe-go-vectors.go` con kyber, tlock y `age`, las librerías de la referencia Go, y `ibe.test.ts` los comprueba todos:
|
|
|
- el GT de e(G1, G2) y de su cuadrado, con H2 de 16 y 32 bytes;
|
|
|
- H3 y H4 sobre entradas fijas, entre ellas una H3 aceptada en la segunda iteración y otra en la tercera;
|
|
|
- la identidad de varias rondas;
|
|
|
- para el stanza tlock de cada fixture oficial, el pairing, sigma, r y la file key. La file key es la que devuelve `tlock.TimeUnlock`, y con ella `age` abre el `OUTER_TIME_AGE`. El test lo repite con `age-encryption`: el MAC de la cabecera y STREAM verifican, y el contenido es el `control_cbor` del registro o un `INNER_ACCESS_AGE`;
|
|
|
- mensajes de 0, 1, 16 y 32 bytes cifrados por `EncryptCCAonG2` de kyber;
|
|
|
- el veredicto de `DecryptCCAonG2` sobre copias editadas del stanza de `time_only`: U con c0 + p, en el infinito o negado, V o W alterados, la firma de otra ronda, negada o en el infinito, y longitudes erróneas.
|
|
|
|
|
|
El mismo tratamiento tiene `src/lib/dkc/testing/tlock-vectors.json`, los valores de referencia del cifrado (paso 7 de la fase 2), que escribe `scripts/tlock-go-vectors.go` y comprueba `tlock.test.ts`:
|
|
|
- cifrados con sigma fijo de mensajes de 1, 16 y 32 bytes para las rondas 1000 y 1001. Go reescribe `EncryptCCAonG2` porque kyber toma sigma de `crypto/rand`, y comprueba su reescritura descifrando con `ibe.DecryptCCAonG2` y, en los de 16 bytes, con `tlock.TimeUnlock`. `encryptOnG2WithSigma` los reproduce byte a byte;
|
|
|
- la interoperabilidad de TypeScript a Go. `scripts/tlock-ts-samples.mjs` cifra con esta librería un cuerpo IBE y un fichero `age` escrito con `timeRecipient`, para las rondas 1000 y 1001. Go abre los cuerpos con `tlock.TimeUnlock` y los ficheros con `age.Decrypt` y `agewrap.NewTimeIdentity`, la identidad del paso 11, y obtiene la misma file key y el mismo texto. Esas muestras son aleatorias, así que se congelan con el veredicto de Go.
|
|
|
|
|
|
Para regenerarlo: `node scripts/tlock-ts-samples.mjs > ts-samples.json`, y desde el mismo módulo Go temporal, `go run tlock-go-vectors.go ts-samples.json > tlock-vectors.json`.
|
|
|
|
|
|
En `ibe-vectors.json`, H2, H3 y H4 no son públicas en kyber: el script las reescribe con sus etiquetas y las comprueba en cada fixture contra la file key de tlock y contra U = r·G2. Los cifrados de kyber usan un sigma aleatorio, así que el fichero se genera una vez y se congela. Para regenerarlo, desde un módulo Go temporal que requiera la referencia (`replace g.activething.com/go/DateKeys => ../datekeys-go`, `GOFLAGS=-mod=mod`, y la directiva `go` de la referencia, para que se use su toolchain): `go run ibe-go-vectors.go ../datekeys-ts/testdata/fixtures > ibe-vectors.json`. Los siete fixtures del formato 2 se añadieron el 29-09-2026 así, sobre `spec-v0.9`, tomando solo el bloque `fixtures`: los valores de los cinco anteriores salieron idénticos, y el resto del fichero no cambió. Los nueve del formato 3 se añadieron igual el 30-09-2026, sobre `spec-v0.10`, con los doce anteriores idénticos.
|
|
|
- El writer (`encrypt.test.ts`, `encrypt.stream.test.ts`, `encrypt.internal.test.ts`, `encrypt.property.test.ts`):
|
|
|
- con los valores de su registro, reproduce byte a byte el PRELUDE, PUBLIC_HEADER, `header_binding` y CONTROL_CBOR de los siete fixtures de formato 2 de Go, con las mismas longitudes; cada credencial cae en el hueco del registro y la `.dkk` sale igual, salvo su `capsule_digest`;
|
|
|
- lo que escribe se abre con `open`: las dos políticas, de 1 a 16 credenciales, cada una sola y todas juntas; contenidos en todos los bordes de trozo y de relleno, hasta 5 000 000 de bytes, con las dos reglas; rondas 1000, 1001 y 2000;
|
|
|
- las opciones inválidas dan los textos y códigos de `capsule.Encrypt` sin escribir nada y con la salida abortada;
|
|
|
- streaming desde `Uint8Array`, `Blob` y `ReadableStream` con cualquier troceado; una fuente de otra longitud, una fuente o una salida que fallan y un `progress` que lanza dejan la salida abortada;
|
|
|
- las autocomprobaciones, con entradas malas y con un `age-encryption` sustituido que falla, alarga, cambia o corta lo que sella;
|
|
|
- un bucle de propiedades con opciones aleatorias, a veces inválidas: 50 semillas en cada ejecución y 500 con `DATEKEYS_PROPERTY_SEEDS=500` (pasó el 29-09-2026, en 203 s).
|
|
|
|
|
|
Rendimiento en Node 24.9, informativo: `time_only`, unos 120 ms por cápsula en caliente (470 ms la primera, con la carga del código); `time_and_key` con clave portable, unos 200 ms; 64 MiB desde un `Blob` hacia una salida, 50 MiB/s con el SHA-256 en la misma pasada.
|
|
|
- `src/lib/dkc/testing/capsule-vectors.json`: la interoperabilidad de los writers con Go a nivel de cápsula (plan de la fase 3, sección 8, punto 9, y paso 4 del plan del formato 3), que comprueba `interop.test.ts`. `scripts/capsule-ts-samples.mjs` escribe con `encrypt`, como generador de vectores, trece cápsulas de formato 2 para las rondas 1000, 1001 y 2000:
|
|
|
- `time_only` de 0, 46, 65 536 y 78 000 bytes, con las dos reglas de relleno;
|
|
|
- `time_and_key` con una clave portable, con tres recipients y una clave portable, y con dieciséis recipients;
|
|
|
- una con extensiones en PUBLIC_HEADER, CONTROL_CBOR y la `.dkk`;
|
|
|
- una para un instante un nanosegundo posterior a la ronda 1000.
|
|
|
|
|
|
Y con `encryptFiles`, seis de formato 3: un fichero con su mtime; un árbol de siete ficheros, uno sobre dos trozos STREAM, con rutas fuera de ASCII y el par U+FFFD y U+10000, que UTF-8 y UTF-16 ordenan al revés, con comentario y autor; un comentario sin ficheros; `bloque256`; `time_and_key` con tres destinatarios y una clave portable; y extensiones del head.
|
|
|
|
|
|
`scripts/capsule-go-verdicts.go` las pasa por `capsule.Inspect` y las abre con `capsule.Open` con cada credencial sola y con todas juntas: todas abren al mismo contenido, con el formato, L, la regla y P pedidos. En el formato 3 abre en un `Sink`, y los ficheros que recibe, con su SHA-256, el head reencodificado con `capsule.EncodeHead` y los veredictos son los de lo que se escribió. Además abre `SEALED_CONTROL` capa a capa con las identidades de `agewrap`, cuenta los 16 stanzas de `INNER_ACCESS_AGE`, y reencodifica PUBLIC_HEADER, CONTROL_CBOR y la `.dkk` a los mismos bytes. El test comprueba esos veredictos y repite cada apertura con `open` sobre los bytes congelados, con el mismo resultado. El fichero lleva también:
|
|
|
- cuatro mezclas de dos cápsulas de la ronda 1000, que Go y `open` rechazan con el mismo código en el mismo paso: `ERR_HEADER_BINDING` en el 15 (dos de ellas), `ERR_INTEGRITY` en el 17 y `ERR_POLICY_STRUCTURE_MISMATCH` en el 12;
|
|
|
- el diferencial de los codificadores: 500 entradas válidas sacadas de una semilla (`testing/interop.ts`), que `capsule.EncodeHeader`, `capsule.EncodeControl` y `AccessKey.MarshalBody` codifican a los mismos bytes que esta librería. Se congelan la semilla, el número de entradas y el SHA-256 de todas las codificaciones, que el test recalcula;
|
|
|
- 22 cadenas de recipient, que `parseX25519Recipient` y `checkX25519Recipient` leen con los textos de `age.ParseX25519Recipient` y `agewrap.CheckX25519Recipient`;
|
|
|
- las 21 opciones inválidas de `encrypt` que tienen equivalente en Go, con el texto de `capsule.Encrypt` como generador de vectores.
|
|
|
|
|
|
Las cápsulas son aleatorias, así que se generan una vez y se congelan con los veredictos de Go. Para regenerarlo: `node scripts/capsule-ts-samples.mjs > ts-samples.json`, y desde el mismo módulo Go temporal, `go run capsule-go-verdicts.go ts-samples.json > capsule-vectors.json`.
|
|
|
- Todo se lee con los formatos de `testdata/README.md` (`testing/vectors.ts`): una clave desconocida o que falta, un valor de otro tipo, un código que no es de §69 o una edición fuera de su base hacen fallar el fichero con su motivo; nada se salta en silencio.
|
|
|
- Todo fichero de `testdata/` tiene que ejecutarlo algún test: un nombre nuevo exportado por Go (otro `vectors/*.json`, un fichero de fixture que ningún JSON nombra) hace fallar `testdata/ holds no file that no test runs` hasta que se le añade su bloque.
|
|
|
|
|
|
## Dependencias de ejecución
|
|
|
|
|
|
Aprobadas en el plan de la fase 2 (sección 3 y decisión 5) e instaladas con su versión exacta. La página solo las carga al abrir una cápsula (ver [Abrir](#abrir)).
|
|
|
|
|
|
| Paquete | Versión | Licencia | Uso |
|
|
|
|---|---|---|---|
|
|
|
| `age-encryption` | 0.3.1 | BSD-3-Clause | las tres envolturas `age` (§28), con `Identity` y `Recipient` propios para el stanza `tlock` |
|
|
|
| `@noble/curves` | 2.4.0 | MIT | BLS12-381 del núcleo IBE y de la verificación de releases; también el oráculo de `bls12381.contrast.test.ts` |
|
|
|
| `@noble/hashes` | 2.4.0 | MIT | los hashes del IBE y el HKDF de los stanzas X25519; se declara porque se importa directamente |
|
|
|
| `@noble/ciphers` | 2.4.0 | MIT | el ChaCha20-Poly1305 de los stanzas X25519 (`x25519.ts`): la misma copia que usa `age-encryption`, así que no añade nada al bundle. Aprobada el 28-09-2026 para abrir los stanzas de uno en uno, como exige §36 |
|
|
|
|
|
|
`age-encryption` arrastra `@noble/ciphers` 2.4.0, `@scure/base` 2.4.0 y `@noble/post-quantum` 0.5.4, todos con licencia MIT. `@noble/post-quantum` fija `@noble/curves` y `@noble/hashes` a `~2.0.0` y trae su propia copia 2.0.1, que usa para el ML-KEM híbrido. La decisión 5 la acepta, sin overrides de npm.
|
|
|
|
|
|
Guardas de `src/lib/dependencies.test.ts`, en cada `npm test`:
|
|
|
- `package.json` declara exactamente estas cuatro dependencias, con versión exacta;
|
|
|
- `package-lock.json` no contiene `tlock-js` ni `drand-client`, ningún noble 1.x, ni más copias 2.x de `@noble/curves` o `@noble/hashes` que la 2.4.0 de la raíz y la 2.0.1 bajo `@noble/post-quantum`;
|
|
|
- ningún fichero de `src/` importa `tlock-js` ni `drand-client`;
|
|
|
- solo `digest.ts`, `ibe.ts`, `release.ts`, `x25519.ts` y los tests nombran `@noble/`, siempre con subrutas de `@noble/curves`, `@noble/hashes` y `@noble/ciphers` que resuelven a la copia 2.4.0 de la raíz;
|
|
|
- solo `agefile.ts`, `open.ts`, `tlock.ts`, `writer.ts` y los tests importan `age-encryption`; solo `encrypt.ts`, `testing/` y los tests importan `writer.ts`, cuyo núcleo recibe la aleatoriedad de quien lo llama (plan de la fase 3, decisiones 4 y 13); e `index.ts` no reexporta la apertura ni el writer;
|
|
|
- cada comprobación se ejecuta también sobre entradas malas, así que una guarda que dejara de detectar algo fallaría.
|
|
|
|
|
|
`check-build.mjs` hace la misma comprobación sobre el bundle del cliente.
|
|
|
|
|
|
Coste medido en el bundle el 28-09-2026, con una compilación de prueba de Vite 8 minificada (gzip de nivel 9):
|
|
|
|
|
|
| Qué se importa | Minificado | gzip |
|
|
|
|---|---|---|
|
|
|
| `Decrypter` de `age-encryption` | 153 645 B | 48 032 B |
|
|
|
| `Decrypter` y `Encrypter` | 183 650 B | 55 915 B |
|
|
|
| `bls12_381` y `sha256` de noble | 92 637 B | 28 090 B |
|
|
|
| Todo lo anterior | 239 454 B | 72 783 B |
|
|
|
|
|
|
`age-encryption` importa de forma estática sus recipients ML-KEM híbridos, P-256 y scrypt. Por eso el `Decrypter` arrastra `@noble/post-quantum` y la copia 2.0.1 de noble, aunque DateKeys no los use: son unos 99 KB de los 212 KB de código antes de minificar.
|
|
|
|
|
|
En el sitio, según `check-build.mjs` el 28-09-2026:
|
|
|
|
|
|
| `/inspect` | JavaScript | gzip |
|
|
|
|---|---|---|
|
|
|
| Primera carga, antes del paso 8 | unos 157 KB | 58,7 KB |
|
|
|
| Primera carga, con la acción "abrir" | 187 700 B | 68 197 B |
|
|
|
| Bajo demanda, al abrir: `opener.ts`, `open.ts`, noble y `age-encryption` | 183 747 B | 66 882 B |
|
|
|
|
|
|
Y según `check-build.mjs` el 29-09-2026, con la página de crear, y el 30-09-2026, con el formato 3:
|
|
|
|
|
|
| `/create` | JavaScript | gzip |
|
|
|
|---|---|---|
|
|
|
| Primera carga, con el formulario y el informe de los pasos 1 a 8 | 208 755 B | 76 942 B |
|
|
|
| Bajo demanda, al crear: `creator.ts`, `encrypt.ts`, noble y `age-encryption` | 212 685 B | 76 617 B |
|
|
|
| Primera carga, con la lista de ficheros (formato 3) | 224 367 B | 82 345 B |
|
|
|
| Bajo demanda (formato 3): lo anterior, `create-check.ts` y las tablas de las rutas | 353 788 B | 125 503 B |
|
|
|
|
|
|
Los 9,5 KB con gzip que crece la primera carga de `/inspect` son la interfaz de la apertura (`OpenPanel.svelte`) y sus módulos sin noble. Las cifras exactas cambian unos bytes en cada compilación, por la versión que SvelteKit incrusta.
|
|
|
|
|
|
`npm audit --omit=dev` no encuentra vulnerabilidades. El `npm audit` completo encuentra 2 de gravedad baja en el tooling: `cookie` < 0.7.0 (GHSA-pxg6-pf52-xh8x), que llega a través de `@sveltejs/kit` 2.70.3. Esa es la última versión y sigue pidiendo `cookie` ^0.6.0. Solo afecta a la gestión de cookies del servidor de SvelteKit, que un sitio estático no usa.
|
|
|
|
|
|
## Tooling de desarrollo
|
|
|
|
|
|
| Paquete | Versión | Estado |
|
|
|
|---|---|---|
|
|
|
| `typescript` | 5.9.3 | en `package.json`; ya usado en el prototipo |
|
|
|
| `vitest` | 5.0.1 | en `package.json`; ya usado en el prototipo |
|
|
|
| `@vitest/coverage-v8` | 5.0.1 | en `package.json`; cobertura del 100 % del codec |
|
|
|
| `@types/node` | 24.13.6 | en `package.json`; tests que leen `testdata/` desde disco |
|
|
|
| `vite` | 8.3.0 | en `package.json`; dependencia peer obligatoria de `vitest` 5.0.1 y base del paso 5; la versión del prototipo |
|
|
|
| `svelte` | 5.57.1 | en `package.json`; paso 5 |
|
|
|
| `@sveltejs/kit` | 2.70.3 | en `package.json`; paso 5 |
|
|
|
| `@sveltejs/vite-plugin-svelte` | 7.3.0 | en `package.json`; paso 5 |
|
|
|
| `svelte-check` | 4.7.6 | en `package.json`; paso 5, `npm run check` |
|
|
|
| `@sveltejs/adapter-static` | 3.0.10 | en `package.json`; paso 5: la página es estática y no necesita servidor |
|
|
|
|
|
|
`@noble/curves` 2.4.0 estaba en esta lista como oráculo de `bls12381.contrast.test.ts` y ha pasado a dependencia de ejecución en la fase 2.
|
|
|
|
|
|
Todas las versiones se fijan exactas y `package-lock.json` se versiona. `.npmrc` activa `legacy-peer-deps` porque npm 11.5.2 falla al resolver los peers opcionales de `vitest` 5.0.1 (`Cannot read properties of null (reading 'edgesOut')`); con esa opción npm no instala peers, así que el peer obligatorio `vite` está declarado explícitamente.
|
|
|
|
|
|
## testdata
|
|
|
|
|
|
```bash
|
|
|
npm run testdata:sync
|
|
|
```
|
|
|
|
|
|
Copia `testdata/` de `../datekeys-go` en `HEAD`, leyendo los blobs con git para no arrastrar cambios sin commit, y escribe `testdata/SOURCE.json` con el commit completo y el SHA-256 de cada fichero. Para fijar otro commit: `node scripts/sync-testdata.mjs sync --commit <rev>`.
|
|
|
|
|
|
```bash
|
|
|
npm run testdata:check
|
|
|
```
|
|
|
|
|
|
Comprueba que los ficheros coinciden con `SOURCE.json`, sin faltantes ni sobrantes, y vuelve a leerlos del repositorio Go en el commit registrado. Sin la opción `--against`, `node scripts/sync-testdata.mjs check` verifica solo la copia local. Ambos comandos usan solo Node y git.
|
|
|
|
|
|
`.gitattributes` marca `testdata/**` como binario para que git no altere ningún byte.
|
|
|
|
|
|
Copia actual: la de `testdata/SOURCE.json` (tag `spec-v0.10`, `cc35d2c`), que se sincroniza con `node scripts/sync-testdata.mjs sync --commit spec-v0.10`.
|
|
|
|
|
|
## Licencia
|
|
|
|
|
|
Apache-2.0 ([LICENSE](LICENSE)), como la librería Go de referencia. El código que se derive de terceros conserva su aviso de copyright y licencia en el propio fichero: el núcleo IBE (`ibe.ts`), derivado de `tlock-js` (Apache-2.0 OR MIT, usado bajo MIT), y `bech32.ts`, portado de `age` (MIT). El sitio publica esos avisos y los de sus paquetes npm en `licenses.txt`.
|
