Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

VDR v1 / DIDMan v1: guard against silent subject desync when did:web is enabled

Abierto
  • ¿Algo no está bien?
#4,298 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
38/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
go
Área
api, backend, documentation, security

Línea de trabajo

Empieza por vdr/api/v1/api.go, didman/api/v1/api.go y vdr/vdr.go para rastrear el registro de rutas, los controladores de escritura y los métodos DID activos. Revisa core/server_config.go y las pruebas de migración existentes antes de elegir y documentar el comportamiento del guard. Se considera terminado cuando la política seleccionada está cubierta por pruebas para lecturas y escrituras de v1, migration.rst no es ambiguo y las notas de la versión están actualizadas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

Context

Follow-up from review of #4265 (v5→v6 migration guide). Three review threads from @stevenvegt on the "Mixing VDR v1 and v2 APIs" section converge on one product question: the v1 footgun is currently handled with documentation only, and the docs themselves are ambiguous.

  • r3272036014 — wording is ambiguous: reads as "v1 is fine, just don't mix v1+v2", while the deprecation note implies "don't use v1 at all".
  • r3272042569 — "If this is a footgun, shouldn't we make either one available by a config param?"
  • r3272058944 — "should we disable the didman api's or error/warn when did:web is enabled?"

Problem

When a subject owns more than one DID document — i.e. did:web is enabled alongside did:nuts — VDR v1 / DIDMan v1 writes only touch the did:nuts document. They never propagate to the did:web in the same subject. The two silently desync, and the startup migrations do not repair this on later restarts. Reads compound it: v1 and v2 resolve from different views, so a v1 caller and a v2 caller see different state for the same subject.

Nothing in the node prevents this today. Critically, didmethods is not a guard: it selects which DID methods the node creates and manages per subject — it does not enable or disable the v1/v2 API surface or any specific endpoint. The v1 and DIDMan v1 APIs remain fully callable no matter what didmethods is set to. So an operator on the v6 default (["web", "nuts"]) who keeps scripting against v1 silently desyncs every subject, with no error and no config knob to stop it.

Subject composition v1 / DIDMan v1 write Result
did:nuts only (didmethods=["nuts"]) touches the only doc consistent — v1 use is safe
did:nuts + did:web (default) touches did:nuts only did:web silently desyncs from subject; not repaired on restart

Proposal

Make the node enforce the constraint instead of documenting it. When more than one DID method is active for subjects (web enabled), refuse or warn on v1/DIDMan v1 write operations rather than letting them silently desync the subject.

Options to decide between:

  1. Hard-disable the v1 VDR + DIDMan v1 write routes when web is enabled — return 404/501 or don't register them. Strongest guarantee, but breaks any operator still scripting against v1 during a transition.
  2. Fail writes loud — keep routes registered, but have v1/DIDMan v1 write endpoints return an error (e.g. 409/412) when web is enabled, while reads stay available. Lets /internal/vdr/v1/did/conflicted and other read paths keep working during migration.
  3. Warn only — log a warn on each v1/DIDMan write when web is enabled. Lowest friction, weakest protection.

Position: option 2 (fail writes loud, keep reads). Confirmed safe for the migration flow — conflict resolution only reads via v1 (did:nuts state written through v2 lands on the gRPC network, which the v1 read endpoints then surface), so blocking v1 writes doesn't break it. Open for discussion.

Whatever is chosen, also fix the migration-guide wording (r3272036014) so it is unambiguous: v1/DIDMan v1 is deprecated; it is only safe in a single-method (did:nuts-only) deployment; with did:web enabled it must not be used for writes.

Scope

  • vdr/api/v1/api.go — Wrapper.Routes / write handlers (CreateDID, AddNewVerificationMethod, DeleteVerificationMethod, etc.); gate on whether more than one method is active.
  • didman/api/v1/api.go — Wrapper.Routes / write handlers; same gating.
  • vdr/vdr.go:66,139 — supportedDIDMethods is the source of truth for which methods are active (slices.Contains(r.supportedDIDMethods, "web"), cf. vdr/vdr.go:453); expose a check the API wrappers can consume.
  • core/server_config.go:62 — DIDMethods (koanf:"didmethods"). Note this currently does not gate any API; a dedicated opt-out (e.g. vdr.enablev1api) could be added if keying off method count is too implicit.
  • docs/pages/deployment/migration.rst — fix the v1 deprecation/footgun wording.
  • Tests + release notes.

Considerations

  • v1 reads stay valid even with web enabled: a v2 write to the did:nuts document propagates over the gRPC network and is then served by the v1 read endpoints. So only v1 writes desync subjects — reads (GET /internal/vdr/v1/did/conflicted, GET /status/diagnostics) are safe to keep. This is what makes option 2 viable.
  • Gate implicitly on "is web active" vs. an explicit vdr.enablev1api toggle — implicit needs no new config but couples two concerns; explicit is clearer but adds surface.
  • v1 / DIDMan v1 are already slated for removal in a future major — is a guard worth building, or just sharpen the docs and accept the footgun until removal?

Related

Lenguaje dominante
Go
Estrellas
29
Forks
24
Merge medio
2 d 18 h
PR fusionados (30 d)
45

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de nuts-foundation/nuts-node

Todos los issues de nuts-foundation/nuts-node

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.