feat(zgw): OpenZaak Documenten (DRC) upload + zaak link (WP-51)

Extends the OpenZaak seam with IDocumentSource, sibling of IZaakSource
(WP-49/50): an upload always lands locally first (DocumentStore stays
the record of truth for preview/download/audit) and, when
Zgw:Enabled=true, is also registered as a DRC enkelvoudiginformatie-
object; once a zaak exists (IZaakSource.CreateZaak now also returns
its ZaakUrl), submit links each document to it via zaakinformatie-
object. FE upload/list DTOs are unchanged.

- ZgwOptions gains DrcBaseUrl + a category->informatieobjecttype URL
  map (the document analogue of ZaaktypeUrls).
- LocalDocumentSource is the same DocumentStore.Add/Link calls the
  endpoints used to make inline — zero behaviour change offline.
- OpenZaakDocumentSource POSTs the eio then the zaak link, persisting
  the DRC url (DocumentStore.SetDrcUrl) so linking doesn't re-upload.
- Factored the GET/POST-with-bearer-JWT plumbing shared with
  OpenZaakZaakSource into ZgwHttpClient; shared the stub handler
  between the two source test classes as ZgwStubHandler.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/src/BigRegister.Api/Zgw/OpenZaakDocumentSource.cs

@@ -0,0 +1,103 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using BigRegister.Api.Contracts;
+using BigRegister.Api.Data;
+
+namespace BigRegister.Api.Zgw;
+
+/// <summary>
+/// The <see cref="IDocumentSource"/> backed by a real OpenZaak / ZGW Documenten API (DRC,
+/// WP-51). An upload always lands locally first (<see cref="DocumentStore"/> stays the record
+/// of truth for preview/download/audit, same reasoning as <see cref="OpenZaakZaakSource"/>'s
+/// dual-write for aanvragen, WP-50) and is then ALSO registered as a DRC
+/// enkelvoudiginformatieobject, whose url is persisted (<see cref="DocumentStore.SetDrcUrl"/>)
+/// so <see cref="LinkToZaak"/> can find it later without a re-upload. Selected only when
+/// <c>Zgw:Enabled=true</c>; the default stays <see cref="LocalDocumentSource"/>.
+///
+/// Auth: a fresh HS256 JWT per request (<see cref="ZgwTokenProvider"/>), same as
+/// <see cref="OpenZaakZaakSource"/> — creating a document needs write scope on Documenten;
+/// linking one to a zaak needs write scope on Zaken (the zaakinformatieobject resource).
+/// </summary>
+public sealed class OpenZaakDocumentSource(HttpClient http, ZgwTokenProvider tokens, ZgwOptions options) : IDocumentSource
+{
+  private readonly ZgwHttpClient zgw = new(http, tokens);
+
+  // ponytail: sync-over-async — IDocumentSource is sync to match the local store + the
+  // existing sync upload/submit endpoints, same reasoning as OpenZaakZaakSource.
+  public UploadResponse Upload(
+      string localId, string categoryId, string wizardId, string fileName, string contentType,
+      byte[] content, string owner) =>
+      UploadAsync(localId, categoryId, wizardId, fileName, contentType, content, owner)
+          .GetAwaiter().GetResult();
+
+  private async Task<UploadResponse> UploadAsync(
+      string localId, string categoryId, string wizardId, string fileName, string contentType,
+      byte[] content, string owner)
+  {
+    var doc = DocumentStore.Add(localId, categoryId, wizardId, fileName, contentType, content, owner);
+
+    if (!options.InformatieobjecttypeUrls.TryGetValue(categoryId, out var informatieobjecttypeUrl))
+      throw new InvalidOperationException(
+          $"Zgw:InformatieobjecttypeUrls has no entry for category '{categoryId}'.");
+
+    var eio = await zgw.PostAsync<Eio>($"{options.DrcBaseUrl}/enkelvoudiginformatieobjecten", new CreateEioRequest(
+        Bronorganisatie: options.Bronorganisatie,
+        Creatiedatum: DateOnly.FromDateTime(doc.UploadedAt.UtcDateTime),
+        Titel: fileName,
+        Auteur: options.UserRepresentation,
+        Taal: "nld",
+        Formaat: contentType,
+        Bestandsnaam: fileName,
+        Inhoud: Convert.ToBase64String(content),
+        Informatieobjecttype: informatieobjecttypeUrl,
+        Identificatie: doc.DocumentId,
+        // ponytail: hardcoded "openbaar" (public) — real usage would likely vary the
+        // confidentiality level per category (e.g. an identity document is more sensitive
+        // than a diploma); a fixed value is enough to prove the seam end-to-end.
+        Vertrouwelijkheidaanduiding: "openbaar"));
+
+    DocumentStore.SetDrcUrl(doc.DocumentId, eio.Url);
+    return new UploadResponse(doc.DocumentId, doc.LocalId);
+  }
+
+  /// <summary>Local link always happens (dual-write, same reasoning as upload); additionally,
+  /// once a zaak exists, POST a zaakinformatieobject for every document that has a DRC url —
+  /// documents uploaded before Zgw:Enabled was ever true (or under a config gap) simply have
+  /// no DrcUrl yet and are skipped, matching "nothing extra to link" for the local case.</summary>
+  public void LinkToZaak(IReadOnlyList<string> documentIds, string? zaakUrl)
+  {
+    DocumentStore.Link(documentIds);
+    if (zaakUrl is null) return;
+    LinkToZaakAsync(documentIds, zaakUrl).GetAwaiter().GetResult();
+  }
+
+  private async Task LinkToZaakAsync(IReadOnlyList<string> documentIds, string zaakUrl)
+  {
+    foreach (var documentId in documentIds)
+    {
+      var drcUrl = DocumentStore.Get(documentId)?.DrcUrl;
+      if (drcUrl is null) continue;
+      await zgw.PostAsync<JsonElement>($"{options.ZrcBaseUrl}/zaakinformatieobjecten",
+          new CreateZaakInformatieobjectRequest(zaakUrl, drcUrl));
+    }
+  }
+
+  private sealed record Eio([property: JsonPropertyName("url")] string Url);
+
+  private sealed record CreateEioRequest(
+      [property: JsonPropertyName("bronorganisatie")] string Bronorganisatie,
+      [property: JsonPropertyName("creatiedatum")] DateOnly Creatiedatum,
+      [property: JsonPropertyName("titel")] string Titel,
+      [property: JsonPropertyName("auteur")] string Auteur,
+      [property: JsonPropertyName("taal")] string Taal,
+      [property: JsonPropertyName("formaat")] string Formaat,
+      [property: JsonPropertyName("bestandsnaam")] string Bestandsnaam,
+      [property: JsonPropertyName("inhoud")] string Inhoud,
+      [property: JsonPropertyName("informatieobjecttype")] string Informatieobjecttype,
+      [property: JsonPropertyName("identificatie")] string Identificatie,
+      [property: JsonPropertyName("vertrouwelijkheidaanduiding")] string Vertrouwelijkheidaanduiding);
+
+  private sealed record CreateZaakInformatieobjectRequest(
+      [property: JsonPropertyName("zaak")] string Zaak,
+      [property: JsonPropertyName("informatieobject")] string Informatieobject);
+}

backend/src/BigRegister.Api/Zgw/OpenZaakZaakSource.cs

@@ -1,5 +1,3 @@
-using System.Net.Http.Headers;
-using System.Net.Http.Json;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 using BigRegister.Api.Contracts;
@@ -27,6 +25,8 @@ public sealed record ZgwPage<T>(
 /// </summary>
 public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens, ZgwOptions options) : IZaakSource
 {
+  private readonly ZgwHttpClient zgw = new(http, tokens);
+
   // ponytail: sync-over-async — IZaakSource is sync to match the local store + the existing
   // sync /admin/cases endpoint, and ASP.NET Core has no sync-context to deadlock on. Make the
   // whole cases read path async (endpoint + CasesAdmin + interface) if OpenZaak becomes the
@@ -55,7 +55,7 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
     string? next = url;
     while (next is not null)
     {
-      var page = await GetAsync<ZgwPage<T>>(next);
+      var page = await zgw.GetAsync<ZgwPage<T>>(next);
       all.AddRange(page.Results);
       next = page.Next;
     }
@@ -65,21 +65,10 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
   /// <summary>A zaaktype's human label (<c>omschrijving</c>) from the Catalogi API.</summary>
   private async Task<string> ZaaktypeLabelAsync(string zaaktypeUrl)
   {
-    var zt = await GetAsync<Zaaktype>(zaaktypeUrl);
+    var zt = await zgw.GetAsync<Zaaktype>(zaaktypeUrl);
     return zt.Omschrijving;
   }
 
-  private async Task<T> GetAsync<T>(string url)
-  {
-    using var req = new HttpRequestMessage(HttpMethod.Get, url);
-    req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", tokens.Mint());
-    req.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
-    using var res = await http.SendAsync(req);
-    res.EnsureSuccessStatusCode();
-    return (await res.Content.ReadFromJsonAsync<T>())
-        ?? throw new InvalidOperationException($"ZGW GET {url} returned null body.");
-  }
-
   // --- Write path (WP-50): create a Zaak, then a Status, then a Rol ------------------------
 
   /// <summary>Create a zaak for a just-submitted aanvraag: POST zaak → resolve + POST the
@@ -91,16 +80,16 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
   /// already marked Submitted locally (ApplicationStore.Submit already ran) but has no zaak.
   /// Acceptable for a first write slice against a demo backend; a production arc would need a
   /// retry/reconciliation story (or an outbox) before this dual-write can be trusted.
-  public (string Referentie, AanvraagStatusDto Status) CreateZaak(Aanvraag aanvraag, DateTimeOffset now) =>
+  public (string Referentie, AanvraagStatusDto Status, string? ZaakUrl) CreateZaak(Aanvraag aanvraag, DateTimeOffset now) =>
       CreateZaakAsync(aanvraag, now).GetAwaiter().GetResult();
 
-  private async Task<(string Referentie, AanvraagStatusDto Status)> CreateZaakAsync(Aanvraag aanvraag, DateTimeOffset now)
+  private async Task<(string Referentie, AanvraagStatusDto Status, string? ZaakUrl)> CreateZaakAsync(Aanvraag aanvraag, DateTimeOffset now)
   {
     if (!options.ZaaktypeUrls.TryGetValue(aanvraag.Type, out var zaaktypeUrl))
       throw new InvalidOperationException(
           $"Zgw:ZaaktypeUrls has no entry for aanvraag type '{aanvraag.Type}'.");
 
-    var zaak = await PostAsync<ZgwZaak>($"{options.ZrcBaseUrl}/zaken", new CreateZaakRequest(
+    var zaak = await zgw.PostAsync<ZgwZaak>($"{options.ZrcBaseUrl}/zaken", new CreateZaakRequest(
         Zaaktype: zaaktypeUrl,
         Bronorganisatie: options.Bronorganisatie,
         VerantwoordelijkeOrganisatie: options.VerantwoordelijkeOrganisatie,
@@ -109,18 +98,18 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
             ?? throw new InvalidOperationException("Aanvraag has no Referentie yet — submit it locally first.")));
 
     var statustypeUrl = await FirstStatustypeUrlAsync(zaaktypeUrl);
-    await PostAsync<JsonElement>($"{options.ZrcBaseUrl}/statussen",
+    await zgw.PostAsync<JsonElement>($"{options.ZrcBaseUrl}/statussen",
         new CreateStatusRequest(zaak.Url, statustypeUrl, now));
 
     var roltypeUrl = await FirstInitiatorRoltypeUrlAsync(zaaktypeUrl);
-    await PostAsync<JsonElement>($"{options.ZrcBaseUrl}/rollen", new CreateRolRequest(
+    await zgw.PostAsync<JsonElement>($"{options.ZrcBaseUrl}/rollen", new CreateRolRequest(
         Zaak: zaak.Url,
         BetrokkeneType: "natuurlijk_persoon",
         Roltype: roltypeUrl,
         Roltoelichting: "Initiator",
         BetrokkeneIdentificatie: new BetrokkeneIdentificatie(aanvraag.Owner)));
 
-    return (zaak.Identificatie, ZgwZaakMapper.ToCreatedStatusDto(zaak.Identificatie));
+    return (zaak.Identificatie, ZgwZaakMapper.ToCreatedStatusDto(zaak.Identificatie), zaak.Url);
   }
 
   // ponytail: takes the first statustype (lowest volgnummer) / the first "initiator" roltype
@@ -129,7 +118,7 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
   // initiator role (the normal case); add per-type config if that ever stops holding.
   private async Task<string> FirstStatustypeUrlAsync(string zaaktypeUrl)
   {
-    var page = await GetAsync<ZgwPage<Statustype>>(
+    var page = await zgw.GetAsync<ZgwPage<Statustype>>(
         $"{options.ZtcBaseUrl}/statustypen?zaaktype={Uri.EscapeDataString(zaaktypeUrl)}");
     var first = page.Results.OrderBy(s => s.Volgnummer).FirstOrDefault()
         ?? throw new InvalidOperationException($"No statustype found for zaaktype {zaaktypeUrl}.");
@@ -138,24 +127,13 @@ public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens,
 
   private async Task<string> FirstInitiatorRoltypeUrlAsync(string zaaktypeUrl)
   {
-    var page = await GetAsync<ZgwPage<Roltype>>(
+    var page = await zgw.GetAsync<ZgwPage<Roltype>>(
         $"{options.ZtcBaseUrl}/roltypen?zaaktype={Uri.EscapeDataString(zaaktypeUrl)}&omschrijvingGeneriek=initiator");
     var first = page.Results.FirstOrDefault()
         ?? throw new InvalidOperationException($"No 'initiator' roltype found for zaaktype {zaaktypeUrl}.");
     return first.Url;
   }
 
-  private async Task<T> PostAsync<T>(string url, object body)
-  {
-    using var req = new HttpRequestMessage(HttpMethod.Post, url) { Content = JsonContent.Create(body) };
-    req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", tokens.Mint());
-    req.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
-    using var res = await http.SendAsync(req);
-    res.EnsureSuccessStatusCode();
-    return (await res.Content.ReadFromJsonAsync<T>())
-        ?? throw new InvalidOperationException($"ZGW POST {url} returned null body.");
-  }
-
   private sealed record Zaaktype([property: JsonPropertyName("omschrijving")] string Omschrijving);
 
   private sealed record Statustype(

backend/src/BigRegister.Api/Zgw/ZgwHttpClient.cs

@@ -0,0 +1,39 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+
+namespace BigRegister.Api.Zgw;
+
+/// <summary>
+/// Shared GET/POST-with-Bearer-JWT plumbing for the ZGW source classes. Factored out of
+/// <see cref="OpenZaakZaakSource"/> once <c>OpenZaakDocumentSource</c> (WP-51) needed the
+/// identical auth + JSON + error-handling boilerplate — every ZGW call mints a fresh token
+/// (<see cref="ZgwTokenProvider"/>) and expects/returns JSON.
+/// </summary>
+internal sealed class ZgwHttpClient(HttpClient http, ZgwTokenProvider tokens)
+{
+  public async Task<T> GetAsync<T>(string url)
+  {
+    using var req = new HttpRequestMessage(HttpMethod.Get, url);
+    Authorize(req);
+    using var res = await http.SendAsync(req);
+    res.EnsureSuccessStatusCode();
+    return (await res.Content.ReadFromJsonAsync<T>())
+        ?? throw new InvalidOperationException($"ZGW GET {url} returned null body.");
+  }
+
+  public async Task<T> PostAsync<T>(string url, object body)
+  {
+    using var req = new HttpRequestMessage(HttpMethod.Post, url) { Content = JsonContent.Create(body) };
+    Authorize(req);
+    using var res = await http.SendAsync(req);
+    res.EnsureSuccessStatusCode();
+    return (await res.Content.ReadFromJsonAsync<T>())
+        ?? throw new InvalidOperationException($"ZGW POST {url} returned null body.");
+  }
+
+  private void Authorize(HttpRequestMessage req)
+  {
+    req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", tokens.Mint());
+    req.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+  }
+}

backend/src/BigRegister.Api/Zgw/ZgwOptions.cs

@@ -6,9 +6,10 @@ namespace BigRegister.Api.Zgw;
 /// SQLite store; set <c>Zgw:Enabled=true</c> (plus the URLs + credentials) to source cases
 /// from a real OpenZaak.
 ///
-/// The ZGW standard is FIVE separate services, each its own base URL — Slice 1 only needs
-/// the Zaken API (ZRC) and, to resolve human labels for a zaaktype, the Catalogi API (ZTC).
-/// The others (DRC/BRC/NRC) arrive with later slices (WP-51/52).
+/// The ZGW standard is FIVE separate services, each its own base URL — slice 1 (WP-49) only
+/// needed the Zaken API (ZRC) and, to resolve human labels for a zaaktype, the Catalogi API
+/// (ZTC). WP-50 (create-zaak) stayed on those two; WP-51 adds the Documenten API (DRC).
+/// BRC/NRC arrive with later slices (WP-52+).
 /// </summary>
 public sealed class ZgwOptions
 {
@@ -43,4 +44,12 @@ public sealed class ZgwOptions
   /// <summary>RSIN of the organisation responsible for the zaak (<c>verantwoordelijkeOrganisatie</c>,
   /// WP-50) — usually the same RSIN as <see cref="Bronorganisatie"/>.</summary>
   public string VerantwoordelijkeOrganisatie { get; init; } = "";
+
+  /// <summary>Documenten API (DRC) base URL, e.g. <c>https://open-zaak.example/documenten/api/v1</c> (WP-51).</summary>
+  public string DrcBaseUrl { get; init; } = "";
+
+  /// <summary>Upload <c>CategoryId</c> (diploma/identiteit/taalvaardigheid/...) → informatieobjecttype
+  /// URL (Catalogi), so create-document (WP-51) knows which type to register per category —
+  /// the document analogue of <see cref="ZaaktypeUrls"/>.</summary>
+  public Dictionary<string, string> InformatieobjecttypeUrls { get; init; } = new();
 }