# Nota para el autor: el paquete de la revisión externa
*6 de octubre de 2026. Borrador sin commit. Nada fuera de esta carpeta ha cambiado.*
*6 de octubre de 2026. En el repo `docs`, corregida el mismo día con una revisión del paquete y con tus decisiones.*
## Qué contiene
@ -15,25 +15,24 @@ En inglés, porque el revisor puede no leer español:
| `artifacts.md` | Repos, commits, cómo pasar los gates, los vectores uno a uno, las dependencias con versión y la trazabilidad |
| `precedence_and_language.md` | **Propuesta**: español normativo, precedencia texto > CDDL > testdata > implementación, y los cambios de texto para la próxima versión |
## Lo que falta antes de enviarlo
### Decisiones tuyas
1. **Idioma normativo y precedencia.** La propuesta está en `precedence_and_language.md`. Si la apruebas, entra en la v0.15 (la v0.14 tiene tag y no cambia). Hay que elegir entre un §0 o un párrafo en §1.
2. **Las etiquetas del §76.** Cinco pasajes presentan como externas o independientes revisiones hechas por IA: «revisión formal e independiente» (v0.8.2), «revisión de seguridad externa» (v0.10), la revisión de Fable y Astra sin decir que son IA (v0.11), «tres revisiones independientes» (v0.11) y «segunda implementación independiente» (TypeScript, escrita con Go a la vista). La carta ya lo dice; el texto se corregiría en la v0.15. Recomiendo hacerlo antes de enviar, para que el revisor no lo encuentre primero.
3. **Qué TypeScript se congela.**`v0.2.0` implementa la spec **0.13**; la 0.14 está en `4e23f88`, sin tag. La v0.14 no cambia ningún formato ni veredicto de Quicknet, así que las dos sirven, pero lo limpio es cerrar una `0.3.0` en `4e23f88` y congelar esa. La carta dice hoy `v0.2.0`, como pediste.
4. **Traducción completa al inglés.** La spec v0.14 tiene 4 412 líneas y unas 52 600 palabras (325 KB). De ellas, §76 (el historial de cambios) son unas 12 300 y §64 (las mutaciones) unas 2 100. Opciones:
- traducirla entera: unas 50 000 palabras en inglés. A ritmo de un traductor técnico, del orden de 3 a 5 semanas; con un borrador de IA y una revisión humana, menos, pero la revisión sigue siendo larga. Es una estimación, no un presupuesto;
- traducir §1 a §75, §77 y §78, y resumir §76: unas 40 000 palabras;
- no traducir y enviar `design_overview.md` como guía, con el texto en español como referencia: sirve solo si el revisor lee español o acepta trabajar con una traducción automática que no es normativa.
Recomiendo la segunda si el revisor no lee español.
5. **Revisor y presupuesto.** Falta elegir quién y cuánto. El paquete pide un informe con hallazgos por §, severidad y caso, y el nombre, el alcance y la fecha para anotarlo en §76 (§75.10). El núcleo tlock, el formato 3 y el lector CMS son las tres áreas que pide la revisión de completitud; el lector CMS puede ser un encargo aparte, porque es el que más horas lleva.
6. **Qué se comparte y cómo.** Los repos son privados y están en el Gitea de la red local, que no es tuyo y no se toca: el revisor no puede clonarlos. Opciones: `git bundle` de los tres repos en los commits congelados, o archivos `.tar` con su SHA-256, entregados por un canal privado. A decidir:
- si va el código entero o solo la spec, el CDDL, `testdata/` y la trazabilidad;
- si va el repo `docs` (está en español y tiene notas internas) o solo esta carpeta y las dos revisiones de completitud;
- un acuerdo de confidencialidad, si el código no es público todavía; la spec es CC-BY-4.0 y el código Apache-2.0, pero no están publicados;
- el contacto de seguridad: `SECURITY.md` da info@activething.com.
## Tus decisiones (6-10)
1. **Idioma y precedencia: aprobada la propuesta**, con dos cambios: un párrafo al final de §1, no un §0, para no descolocar la numeración; y la regla 4 sin «vectores disputados». Una discrepancia es un defecto, decide el texto, se anota en el HANDOFF y se corrige en la versión siguiente con su caso en §76; hasta entonces los vectores no se tocan, porque los gates no lo permiten. Entre implementaciones, la de referencia primero, como dicen §16 y §67. Si el inglés pasa a normativo se decide en la v1.0.
2. **Las etiquetas del §76: la v0.15 no se abre ahora.** La carta ya declara que todas las revisiones anteriores son de IA. El texto corregido, con la precedencia y el registro de la revisión externa (§75, punto 10), va en la versión que se abra con los hallazgos del revisor. Así se evita un ciclo de tres repos antes de enviar.
3. **TypeScript: cerrar la `0.3.0` en `4e23f88`**, con el tag `v0.3.0` y `main` avanzado, y ese commit en la tabla congelada de la carta y en `artifacts.md`. No es estética: `v0.2.0` tiene el `testdata` en `spec-v0.13` y no tiene la prueba de `tlock_steps.json`, así que el revisor no podría pasar el TypeScript contra los vectores congelados. Renombrar la carpeta `App` no hace falta: el revisor ve el nombre del bundle.
4. **Traducción: primero, buscar un revisor que lea español.** Elimina la decisión y el trabajo de contrastar cada hallazgo con el texto normativo. Si no lo hay, traducir solo el núcleo normativo, con un borrador de IA y tu revisión: §4 a §7, §10 a §13, §26 a §44.1, §51 a §57, §62.1, §63 y §69 a §72, unas 30 600 palabras de las 52 600 del texto. El resto lo cubre `design_overview.md`, y §76 se resume en una página. La carta dice que toda traducción es informativa y que tú contrastas cada hallazgo con el texto español: ese trabajo es tuyo.
5. **Revisor y alcance: dos niveles, con presupuesto cerrado por nivel.**
- Nivel 1, obligatorio: el protocolo y el Go de referencia como evidencia, con Q1 a Q4, Q6 a Q8 y Q10 a Q12.
- Nivel 2, aparte u opcional: Q5 y Q9, el lector CMS/X.509/RFC 3161 y las reglas del localizador, que son revisión de parsers y piden otro perfil.
- TypeScript y Dart, fuera del alcance pagado, disponibles si el revisor quiere mirarlos.
El paquete sirve tal cual como pliego para pedir precio. Una opción gratuita antes de pagar: enseñar Q1 y Q10 al equipo de drand, que son preguntas sobre su propio IBE. Es decisión tuya, porque supone enseñar el proyecto fuera.
6. **Qué se comparte y cómo.**
- `git bundle` de los tres repos con todo el historial y los tags, porque §76 cita commits y el `testdata` de TypeScript apuntaba a `spec-v0.13`; y un `.tar` de cada árbol en el commit congelado, con su SHA-256, para quien no quiera bundles.
- El código entero: sin él no puede decir dónde discrepa la implementación ni pasar los gates.
- El repo `docs`, no. Si el revisor lee español, los cinco ficheros que cita `artifacts.md` §6, en una carpeta aparte; si no, se quitan esas referencias.
- Un NDA mutuo simple hasta la publicación, y en el encargo, el consentimiento para nombrarle en §76.
- La entrega, cifrada con `age` a la clave pública del revisor, con el SHA-256 del archivo por otro canal. El contacto de la revisión es tu dirección directa; `info@` queda como contacto de seguridad del repo.
### Documentación atrasada: arreglada
@ -41,16 +40,16 @@ La sesión corrigió el 6-10 lo que el paquete encontró atrasado en `datekeys-g
### Lo que no he podido comprobar
- Que el H3 del texto coincide con `h3` de kyber: lo dice el spec y lo comprueban los vectores, pero no he leído kyber. Está como pregunta Q10.
- Que los gates pasan hoy en los commits congelados: lo tomo de HANDOFF, no los he ejecutado.
- Que el H3 del texto coincide con `h3` de kyber: lo dice el spec y lo comprueban los vectores (`tlock_steps.json`, generado contra kyber), pero quien escribió el paquete no leyó kyber. Está como pregunta Q10.
## Orden recomendado
## Orden
1. Decidir el TypeScript que se congela (punto 3) y, si es `4e23f88`, cerrar la `0.3.0`.
2. Arreglar los retrasos de documentación de arriba (en Go, sin cambio normativo).
3. Decidir idioma y precedencia, y preparar la v0.15 con la precedencia y las etiquetas del §76 (puntos 1 y 2). Es solo texto.
4. Elegir revisor y alcance (punto 5) y, según su idioma, la traducción (punto 4).
5. Decidir qué se comparte y prepararlo (punto 6); actualizar en `README.md` y `artifacts.md` los commits y los SHA-256 si cambian en los pasos 1 a 3.
6. Enviar.
1. Cerrar la `0.3.0` de TypeScript.
2. Pasar los tres gates en los commits congelados, con el fuzzing de Go en `39b2033`, que el último fuzzing dejó cuatro commits atrás.
3. Corregir la nota y el paquete: hecho el 6-10 (la cabecera, el paso duplicado, `artifacts.md` §5, la propuesta, los dos hashes del CDDL); falta la tabla congelada con la `0.3.0`, tras el paso 1.
4. Elegir revisor y nivel de alcance, y pedir presupuesto.
5. Traducir el núcleo, solo si el revisor no lee español.
6. NDA, bundles y envío.
7. Tras el informe: la versión siguiente, con la precedencia, las etiquetas del §76 y el registro de la revisión (§75, punto 10).
La medida del área de 32 KiB con firmas reales (§74, §75.13) sigue abierta. No bloquea la revisión, pero el revisor la verá como K2; si se hace antes, el perfil CMS que revisa sería el definitivo.
La medida del área de 32 KiB con firmas reales (§74, §75, punto 13) sigue abierta. No bloquea la revisión, pero el revisor la verá como K2; si se hace antes, el perfil CMS que revisa sería el definitivo.
@ -28,7 +28,9 @@ We ask for a cryptographic review of the protocol as specified, with the referen
3. Whether the byte-level description of the root of trust (spec §12.2, §63 steps 10 and 11 and the paragraphs after the flow) is complete and correct, so that an implementer needs no other source.
4. Whether the parsing surfaces (CBOR profile, age headers, the CMS/X.509/RFC 3161 reader of §29.10–§29.11, locator addresses) are specified tightly enough to avoid divergence and attack.
The ranked questions are in `scope_and_questions.md`. Known open problems are listed there too, so that you do not spend time rediscovering them.
The ranked questions are in `scope_and_questions.md`, in two levels of scope: level 1, the protocol with the Go reference as evidence, and level 2, the parsers of the CMS/X.509/RFC 3161 reader and of the locator, which may be commissioned separately. Known open problems are listed there too, so that you do not spend time rediscovering them.
The normative text is the Spanish specification. Any English text, this package or a translation of parts of the specification, is informative: the author checks each finding against the Spanish text before it is accepted.
### Deliverable we expect
@ -45,9 +47,9 @@ Scope, budget and timeline are to be agreed with the author.
|---|---|
| Specification | `datekeys-go/spec/DateKeys_Protocol_Specification_v0.14.md`, tag `spec-v0.14`, commit `39b2033e3ccf54a91bda8d7e3ced39b26dbfa58c`, approved 6 October 2026 |
| Its SHA-256 | `390922135931dd61a263ed90259c7a978b5d92944405e641e94cc194f84fb459` (recorded in `spec/README.md`; checked on 6 October 2026) |
| CBOR schemas | `datekeys-go/spec/datekeys.cddl` at the same tag (SHA-256 `35c6e5fb74d65907bcb436242079bcc99cfb81a654a1174f2cac68576bf24a51` on 6 October 2026) |
| CBOR schemas | `datekeys-go/spec/datekeys.cddl`: SHA-256 `35c6e5fb74d65907bcb436242079bcc99cfb81a654a1174f2cac68576bf24a51` at the tag, and `9607d1c7ebd2c09df3969a2749a588cf39bc24fe49a05a5f308b798a3ca621fa` at `22f184c`, which changes only its header comment |
| Shared test data | `datekeys-go/testdata/` at the same tag: 136 files, documented in `testdata/README.md` |
| Reference implementation (Go) | `datekeys-go` at `spec-v0.14` / `39b2033`; its documentation (README, SECURITY.md, `docs/traceability.md`, the header comment of `spec/datekeys.cddl`) brought up to v0.14 at `22f184c`, the head of branch `v0.14`, with no change to the specification, the schemas or the code |
| Reference implementation (Go) | `datekeys-go` at `spec-v0.14` / `39b2033`; its documentation (README, SECURITY.md, `docs/traceability.md`, the header comment of `spec/datekeys.cddl`) brought up to v0.14 at `22f184c`, the head of branch `v0.14`. That commit changes no specification text, no schema rule and no code: in `datekeys.cddl` only its header comment, so its SHA-256 differs from the tag's (row above) |
| TypeScript implementation | `datekeys-ts` 0.2.0, tag `v0.2.0`, commit `8cf0685fb016ae05afcd5b96387b4b884f3ad972` (see the note below) |
| `spec/datekeys.cddl` (322 lines, English comments) | `35c6e5fb74d65907bcb436242079bcc99cfb81a654a1174f2cac68576bf24a51` |
| `spec/datekeys.cddl` (322 lines, English comments) | `35c6e5fb74d65907bcb436242079bcc99cfb81a654a1174f2cac68576bf24a51`at the tag; `9607d1c7ebd2c09df3969a2749a588cf39bc24fe49a05a5f308b798a3ca621fa` at `22f184c`, which changes only its header comment |
`spec/README.md` lists the SHA-256 of every frozen version from v0.8.2 to v0.14. Earlier versions are in the same folder; §76 records each normative change with its reproducible case. The specification is CC-BY-4.0; the code is Apache-2.0.
@ -144,7 +144,7 @@ Runtime:
`datekeys-go/docs/traceability.md` (258 lines) maps every normative section of the specification to the Go code that implements it and the tests that exercise it, row by row from §3 to §76, and marks cases of §64 not yet in the repository as *pending*. It is intended for the external reviewer.
Two known lags, to be fixed before sending: its title still says «v0.12» while its body refers to v0.14; and its row §12.1 still lists «the three unchained tlock schemes», which v0.14 reduced to one (§76 v0.14 change 7). `datekeys-go/README.md` has the same lag in «any profile on the three drand schemes that tlock supports», and says «18 normative errors» where §69 lists 19. The header comment of `spec/datekeys.cddl` still names v0.11 and says the reference implements v0.9.
Brought up to v0.14 at `22f184c` (branch `v0.14`): the title and the row §12.1, which lists the one scheme of v0.14 (§76 v0.14 change 7). The same commit fixed `datekeys-go/README.md` (one drand scheme, 19 normative errors), `SECURITY.md` (no release exists yet) and the header comment of `spec/datekeys.cddl`.
@ -20,16 +20,16 @@ So in practice, until now, a gap between sources was closed by writing the rule
1. the specification text;
2. `datekeys.cddl`;
3. the test vectors and fixtures of `testdata/`, with `testdata/README.md`;
4. the reference implementation, then the other implementations.
4. the reference implementation, then the other implementations, as §16 and §67 already put the reference first.
3. **Delegation is not disagreement.** A normative rule of the CDDL that the text does not state, and does not contradict, is normative, as §57 and §69.1 already say. Rules the CDDL marks as implementation limits stay non-normative (§74). Precedence applies only when two sources say different things.
4. **A disagreement is a defect.** Any disagreement found between the sources is recorded as a defect, with its reproducible case, and fixed in a new version according to §76. Until it is fixed, implementations follow the higher source, and the vectors that encode the lower one are marked as disputed.
4. **A disagreement is a defect.** Any disagreement found between the sources is a defect: the text decides. It is recorded in the project's working notes (`docs/HANDOFF.md`) and fixed in the next version, with its reproducible case in §76. Until then the vectors and fixtures are not touched: the gates regenerate `testdata/` from the reference and fail on any change, and the TypeScript guard fails on a file that no test runs.
5. **Reviews are labelled by who did them.** §76 names each review with its kind: internal and AI-assisted, or external and human, with the reviewer's name, scope and date for an external one (§75 item 10).
## 3. Spec text changes this would need (next version, v0.15 or later)
The v0.14 text is tagged and does not change. These changes would go into the next version, each recorded in its §76 block:
1. **A new paragraph on language and precedence.** Either a new «§0 Estado, idioma y precedencia» before §1, or a paragraph at the end of §1. Draft wording in Spanish (the normative language), for the author to edit:
1. **A new paragraph on language and precedence, at the end of §1** (decided by the author on 6 October 2026: not a §0, which would shift the numbering every document cites). Draft wording in Spanish (the normative language), for the author to edit:
> El texto normativo es esta especificación en español. Toda traducción es informativa: si una traducción y este texto difieren, decide este texto. Si este texto, `datekeys.cddl`, los vectores y fixtures de `testdata/` y la implementación de referencia difieren sobre una misma regla, decide, en este orden: este texto, `datekeys.cddl`, `testdata/` con `testdata/README.md`, y la implementación de referencia. Una regla normativa de `datekeys.cddl` que este texto no contradice es normativa (§57, §69.1); los límites de implementación que marca no lo son (§74). Toda discrepancia es un defecto, que se corrige con un cambio registrado en §76.
@ -53,11 +53,11 @@ Not normative; they can be done in the repositories at any time, and the externa
- `spec/datekeys.cddl`, header comment: the current version, and a line pointing to the precedence rule.
- `testdata/README.md`: one line stating the precedence rule.
- `spec/README.md`: one line stating that the Spanish text is normative.
- `docs/traceability.md` and `README.md` of `datekeys-go`: the lags listed in `artifacts.md` section 5.
- `docs/traceability.md` and `README.md` of `datekeys-go`: brought up to v0.14 at `22f184c` (`artifacts.md` section 5).
## 5. Open choices for the author
## 5. Decided by the author (6 October 2026)
- §0 or a paragraph in §1.
- Whether the implementations are ordered among themselves (reference first) or all equal below the vectors.
- Whether a disputed vector is removed, kept and marked, or kept unchanged until the next version.
- Whether to make English normative later (for example at v1.0), with Spanish informative; that would need a full translation and a review of it.
- The proposal is approved, with a paragraph at the end of §1 and rule 4 as written above.
- Among implementations, the reference first.
- Whether English becomes normative is left for v1.0.
- These text changes do not open a version now: they go into the version that records the findings of the external review, together with the labels of §76 and the record of the review (§75 item 10). The cover letter already states that every prior review was by AI.
*Section numbers (§) refer to `DateKeys_Protocol_Specification_v0.14.md`, tag `spec-v0.14`. "Known" marks a problem the project already knows about, with its source, so that you do not spend time rediscovering it; your opinion on it is still welcome.*
## 0. Levels of scope
- **Level 1, required:** the protocol, with the Go reference implementation as evidence. Questions Q1 to Q4, Q6 to Q8 and Q10 to Q12.
- **Level 2, separate or optional:** Q5 and Q9, the CMS/X.509/RFC 3161 reader and the rules of the locator addresses. They are parser reviews and may need another profile of reviewer.
- **Not in the paid scope:** the TypeScript and Dart implementations. They are available, with the same vectors, if the reviewer wants to look at them.
## 1. In scope
- **The tlock core:** the composition of tlock with age, the time-only and time-and-key nesting, the three file keys, and the stanza rules (§28 to §36, §63 steps 5 to 13).
