feat(backend): expand stamdata + OpenZaak-ready cases seam (WP-49)

Stamdata: add beroepen, opleidingen (temporal), and specialismen tables to the
schema-driven catalog (zero UI code). opleidingen.beroep and specialismen.beroep
both reference beroepen.code — the first stamdata->stamdata references, enforced by
two new StamdataRef entries in the CI gate.

OpenZaak/ZGW (WP-49, slice 1 — read-only zaken): introduce IZaakSource as the cases
read seam. Default LocalZaakSource reads the local SQLite store (offline); an
OpenZaakZaakSource (Zgw/ client: HS256 per-call JWT, ZGW->existing-DTO mapper,
paginating HTTP source) is selected behind Zgw:Enabled (default false). The FE never
changes — same ApplicationSummaryDto, no api-client drift. Unit-tested with fixtures
+ a stub HttpMessageHandler; no live OpenZaak needed.

Docs: ADR-0005, reference/openzaak-integration.md, WP-49..52 roadmap, stamdata.md
update, README index rows.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/src/BigRegister.Api/Data/IZaakSource.cs

@@ -0,0 +1,21 @@
+using BigRegister.Api.Contracts;
+
+namespace BigRegister.Api.Data;
+
+/// <summary>
+/// The cases (zaken) READ seam (WP-49). A "zaak" in ZGW terms is an <see cref="Aanvraag"/>
+/// here; this interface is the one injection point that lets a real ZGW backend (OpenZaak)
+/// replace the local SQLite store <em>behind the same <see cref="ApplicationSummaryDto"/>
+/// contract</em> — so the frontend never changes (BFF-lite anti-corruption, ADR-0001).
+///
+/// Default binding is <see cref="LocalZaakSource"/> (offline). Setting <c>Zgw:Enabled=true</c>
+/// swaps in <c>OpenZaakZaakSource</c>. Slice 1 is read-only; create/update stay on the
+/// local write path until WP-50. The interface returns the wire DTO (not the domain
+/// <see cref="Aanvraag"/>) precisely so each source owns its own mapping — the OpenZaak
+/// source maps a ZGW Zaak into this shape, the local source maps the stored aanvraag.
+/// </summary>
+public interface IZaakSource
+{
+  /// <summary>Every case, newest-first (the admin cross-owner list, WP-36).</summary>
+  IReadOnlyList<ApplicationSummaryDto> ListCases(DateTimeOffset now);
+}

backend/src/BigRegister.Api/Data/LocalZaakSource.cs

@@ -0,0 +1,15 @@
+using BigRegister.Api.Contracts;
+
+namespace BigRegister.Api.Data;
+
+/// <summary>
+/// The default <see cref="IZaakSource"/> — the cases come from the local SQLite
+/// <see cref="ApplicationStore"/>, exactly as before the seam existed (WP-49). Zero
+/// behaviour change: this is the same <c>ListAll().ToAdminSummaryDto(now)</c> the
+/// <c>/admin/cases</c> endpoint used to call inline.
+/// </summary>
+public sealed class LocalZaakSource : IZaakSource
+{
+  public IReadOnlyList<ApplicationSummaryDto> ListCases(DateTimeOffset now) =>
+      ApplicationStore.ListAll().Select(a => a.ToAdminSummaryDto(now)).ToList();
+}

backend/src/BigRegister.Api/Program.cs

@@ -10,6 +10,7 @@ using BigRegister.Domain.Intake;
 using BigRegister.Domain.Letters;
 using BigRegister.Domain.Registrations;
 using BigRegister.Domain.Submissions;
+using BigRegister.Api.Zgw;
 using BigRegister.Stamdata;
 using Microsoft.EntityFrameworkCore;
 using Microsoft.Extensions.Logging.Console;
@@ -40,6 +41,22 @@ builder.Services.AddCors(o => o.AddPolicy(SpaCors, p =>
 // override it (ConnectionStrings:AppDb) without touching this file.
 Db.ConnectionString = builder.Configuration.GetConnectionString("AppDb") ?? Db.ConnectionString;
 
+// WP-49: the cases (zaken) READ path goes through IZaakSource so a real ZGW backend
+// (OpenZaak) can replace the local SQLite store behind the same DTO contract — the FE never
+// changes (ADR-0001). Default = LocalZaakSource (offline). Zgw:Enabled=true swaps in the
+// OpenZaak client (needs the base URLs + credentials in the Zgw config section).
+var zgw = builder.Configuration.GetSection("Zgw").Get<ZgwOptions>() ?? new ZgwOptions();
+if (zgw.Enabled)
+{
+  builder.Services.AddSingleton(zgw);
+  builder.Services.AddSingleton<ZgwTokenProvider>();
+  builder.Services.AddHttpClient<IZaakSource, OpenZaakZaakSource>();
+}
+else
+{
+  builder.Services.AddSingleton<IZaakSource, LocalZaakSource>();
+}
+
 var app = builder.Build();
 
 // Migrate on every startup, seed nothing (WP-22): unlike SeedData's read-only
@@ -314,11 +331,8 @@ api.MapPost("/applications/{id}/submit", (string id, SubmitApplicationRequest re
 .Produces(StatusCodes.Status404NotFound);
 
 // --- Admin cases (WP-36): cross-owner list + admin delete, gated by `cases:manage`. ---
-api.MapGet("/admin/cases", (HttpContext ctx) => CasesAdmin(ctx, () =>
-{
-  var now = DateTimeOffset.UtcNow;
-  return Results.Ok(ApplicationStore.ListAll().Select(a => a.ToAdminSummaryDto(now)).ToList());
-}))
+api.MapGet("/admin/cases", (HttpContext ctx, IZaakSource zaken) => CasesAdmin(ctx, () =>
+    Results.Ok(zaken.ListCases(DateTimeOffset.UtcNow))))
 .Produces<List<ApplicationSummaryDto>>()
 .ProducesProblem(StatusCodes.Status403Forbidden);
 

backend/src/BigRegister.Api/Stamdata/Beroep.cs

@@ -0,0 +1,13 @@
+namespace BigRegister.Stamdata;
+
+/// <summary>
+/// One row of the beroepen (BIG professions) stamdata (config-as-code, ADR-0004): the
+/// master list of registered professions. The first property (<see cref="Code"/>) is the
+/// table key by convention (see <c>StamdataTable</c>) and the target of the FK-like
+/// references from <c>opleidingen</c> and <c>specialismen</c> (see
+/// <c>StamdataValidationTests</c>). Non-temporal — a profession is either registrable or it
+/// isn't; the mapping's validity window lives on <c>opleidingen</c>.
+///
+/// This is the typed shape <c>beroepen.json</c> deserializes into.
+/// </summary>
+public sealed record Beroep(string Code, string Naam);

backend/src/BigRegister.Api/Stamdata/Opleiding.cs

@@ -0,0 +1,14 @@
+namespace BigRegister.Stamdata;
+
+/// <summary>
+/// One row of the opleidingen (study programs) stamdata (config-as-code, ADR-0004): a study
+/// program and the BIG profession it leads to, valid for a period. The first property
+/// (<see cref="Code"/>) is the table key; <see cref="Beroep"/> holds a <c>beroepen.Code</c>
+/// — a stamdata → stamdata reference the build gate enforces (<c>StamdataValidationTests</c>),
+/// so orphaning a beroep fails CI, never prod. Temporal (<see cref="GeldigVan"/>/
+/// <see cref="GeldigTot"/>, half-open <c>[van, tot)</c>): a null <see cref="GeldigTot"/>
+/// means "still valid"; a future <see cref="GeldigVan"/> pre-schedules a program.
+///
+/// This is the typed shape <c>opleidingen.json</c> deserializes into.
+/// </summary>
+public sealed record Opleiding(string Code, string Naam, string Beroep, DateOnly GeldigVan, DateOnly? GeldigTot);

backend/src/BigRegister.Api/Stamdata/Specialisme.cs

@@ -0,0 +1,13 @@
+namespace BigRegister.Stamdata;
+
+/// <summary>
+/// One row of the specialismen (professional specialisms) stamdata (config-as-code,
+/// ADR-0004): a registered specialism and the base BIG profession it belongs to. The first
+/// property (<see cref="Code"/>) is the table key; <see cref="Beroep"/> holds a
+/// <c>beroepen.Code</c> — the second stamdata → stamdata reference the build gate enforces
+/// (<c>StamdataValidationTests</c>), demonstrating one table referenced by two others.
+/// Non-temporal.
+///
+/// This is the typed shape <c>specialismen.json</c> deserializes into.
+/// </summary>
+public sealed record Specialisme(string Code, string Naam, string Beroep);

backend/src/BigRegister.Api/Stamdata/StamdataCatalog.cs

@@ -11,6 +11,9 @@ public static class StamdataCatalog
   public static readonly IReadOnlyList<StamdataTable> All = new[]
   {
     StamdataTable.Of<ProfessionMapping>("professions", "Opleiding → beroep"),
+    StamdataTable.Of<Beroep>("beroepen", "Beroepen (BIG)"),
+    StamdataTable.Of<Opleiding>("opleidingen", "Opleidingen → beroep"),
+    StamdataTable.Of<Specialisme>("specialismen", "Specialismen → beroep"),
     // PolicyQuestions and future tables migrate here, same one-liner each.
   };
 

backend/src/BigRegister.Api/Stamdata/beroepen.json

@@ -0,0 +1,10 @@
+[
+  { "code": "arts", "naam": "Arts" },
+  { "code": "verpleegkundige", "naam": "Verpleegkundige" },
+  { "code": "fysiotherapeut", "naam": "Fysiotherapeut" },
+  { "code": "apotheker", "naam": "Apotheker" },
+  { "code": "tandarts", "naam": "Tandarts" },
+  { "code": "verloskundige", "naam": "Verloskundige" },
+  { "code": "gz-psycholoog", "naam": "Gezondheidszorgpsycholoog" },
+  { "code": "psychotherapeut", "naam": "Psychotherapeut" }
+]

backend/src/BigRegister.Api/Stamdata/opleidingen.json

@@ -0,0 +1,10 @@
+[
+  { "code": "geneeskunde", "naam": "Geneeskunde", "beroep": "arts", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "verpleegkunde", "naam": "Verpleegkunde (hbo-v)", "beroep": "verpleegkundige", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "fysiotherapie", "naam": "Fysiotherapie", "beroep": "fysiotherapeut", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "farmacie", "naam": "Farmacie", "beroep": "apotheker", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "tandheelkunde", "naam": "Tandheelkunde", "beroep": "tandarts", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "verloskunde", "naam": "Verloskunde", "beroep": "verloskundige", "geldigVan": "2000-01-01", "geldigTot": null },
+  { "code": "gz-psychologie", "naam": "Gezondheidszorgpsychologie", "beroep": "gz-psycholoog", "geldigVan": "2005-01-01", "geldigTot": null },
+  { "code": "inservice-a", "naam": "Inservice A-opleiding (verpleegkunde, oud)", "beroep": "verpleegkundige", "geldigVan": "2000-01-01", "geldigTot": "2012-01-01" }
+]

backend/src/BigRegister.Api/Stamdata/specialismen.json

@@ -0,0 +1,8 @@
+[
+  { "code": "huisartsgeneeskunde", "naam": "Huisartsgeneeskunde", "beroep": "arts" },
+  { "code": "cardiologie", "naam": "Cardiologie", "beroep": "arts" },
+  { "code": "kindergeneeskunde", "naam": "Kindergeneeskunde", "beroep": "arts" },
+  { "code": "ziekenhuisfarmacie", "naam": "Ziekenhuisfarmacie", "beroep": "apotheker" },
+  { "code": "orthodontie", "naam": "Orthodontie", "beroep": "tandarts" },
+  { "code": "geriatriefysiotherapie", "naam": "Geriatriefysiotherapie", "beroep": "fysiotherapeut" }
+]

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

@@ -0,0 +1,82 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using BigRegister.Api.Contracts;
+using BigRegister.Api.Data;
+
+namespace BigRegister.Api.Zgw;
+
+/// <summary>One page of a ZGW list response — the uniform <c>{count,next,previous,results}</c>
+/// envelope every ZGW collection uses. <c>next</c> is a full URL (or null) to follow.</summary>
+public sealed record ZgwPage<T>(
+    [property: JsonPropertyName("count")] int Count,
+    [property: JsonPropertyName("next")] string? Next,
+    [property: JsonPropertyName("results")] IReadOnlyList<T> Results);
+
+/// <summary>
+/// The <see cref="IZaakSource"/> backed by a real OpenZaak / ZGW Zaken API (WP-49). Reads
+/// zaken (following pagination), resolves each zaaktype's human label from the Catalogi API
+/// (cached), and maps into <see cref="ApplicationSummaryDto"/> via <see cref="ZgwZaakMapper"/>.
+/// Selected only when <c>Zgw:Enabled=true</c>; the default stays <see cref="LocalZaakSource"/>.
+///
+/// Auth: a fresh HS256 JWT per request (<see cref="ZgwTokenProvider"/>) on the Authorization
+/// header. Reading a zaak needs read scope on BOTH Zaken and Catalogi (zaaktype resolution).
+/// </summary>
+public sealed class OpenZaakZaakSource(HttpClient http, ZgwTokenProvider tokens, ZgwOptions options) : IZaakSource
+{
+  // 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
+  // default and this blocking call shows up under load.
+  public IReadOnlyList<ApplicationSummaryDto> ListCases(DateTimeOffset now) =>
+      ListCasesAsync().GetAwaiter().GetResult();
+
+  private async Task<IReadOnlyList<ApplicationSummaryDto>> ListCasesAsync()
+  {
+    var zaken = await GetAllAsync<ZgwZaak>($"{options.ZrcBaseUrl}/zaken");
+    var labels = new Dictionary<string, string>();
+    var result = new List<ApplicationSummaryDto>(zaken.Count);
+    foreach (var z in zaken)
+    {
+      if (!labels.TryGetValue(z.Zaaktype, out var label))
+        labels[z.Zaaktype] = label = await ZaaktypeLabelAsync(z.Zaaktype);
+      result.Add(ZgwZaakMapper.ToSummaryDto(z, label));
+    }
+    return result;
+  }
+
+  /// <summary>Follow the <c>next</c> links, accumulating every page's results.</summary>
+  private async Task<IReadOnlyList<T>> GetAllAsync<T>(string url)
+  {
+    var all = new List<T>();
+    string? next = url;
+    while (next is not null)
+    {
+      var page = await GetAsync<ZgwPage<T>>(next);
+      all.AddRange(page.Results);
+      next = page.Next;
+    }
+    return all;
+  }
+
+  /// <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);
+    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.");
+  }
+
+  private sealed record Zaaktype([property: JsonPropertyName("omschrijving")] string Omschrijving);
+}

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

@@ -0,0 +1,34 @@
+namespace BigRegister.Api.Zgw;
+
+/// <summary>
+/// Config for connecting to OpenZaak / the ZGW APIs (WP-49), bound from the <c>Zgw</c>
+/// section of appsettings. Disabled by default so the POC runs fully offline on the local
+/// 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).
+/// </summary>
+public sealed class ZgwOptions
+{
+  public bool Enabled { get; init; }
+
+  /// <summary>Zaken API (ZRC) base URL, e.g. <c>https://open-zaak.example/zaken/api/v1</c>.</summary>
+  public string ZrcBaseUrl { get; init; } = "";
+
+  /// <summary>Catalogi API (ZTC) base URL — used to resolve a zaaktype URL to its label.</summary>
+  public string ZtcBaseUrl { get; init; } = "";
+
+  /// <summary>Client ID registered in the Autorisaties API (goes into the JWT <c>iss</c>/<c>client_id</c>).</summary>
+  public string ClientId { get; init; } = "";
+
+  /// <summary>Client secret — the HS256 signing key for the JWT. Held only by the BFF, never the browser.</summary>
+  public string Secret { get; init; } = "";
+
+  /// <summary>End-user identity for the ZGW audit trail (JWT <c>user_id</c>). Wire from the session in prod.</summary>
+  public string UserId { get; init; } = "big-register-bff";
+
+  /// <summary>Human-readable end-user name for the audit trail (JWT <c>user_representation</c>).</summary>
+  public string UserRepresentation { get; init; } = "BIG-register BFF";
+}

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

@@ -0,0 +1,43 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace BigRegister.Api.Zgw;
+
+/// <summary>
+/// Mints the JWT that authenticates the BFF to the ZGW APIs (WP-49). OpenZaak expects a
+/// short-lived HS256 assertion signed with the client secret, carrying <c>iss</c>/
+/// <c>client_id</c> (identity), <c>iat</c> (issued-at), and <c>user_id</c>/
+/// <c>user_representation</c> (for the ZGW audit trail). There is no OAuth refresh dance —
+/// OpenZaak rejects tokens more than an hour past <c>iat</c>, so we <b>mint a fresh token
+/// per call</b> (cheap, keeps iat current and the audit user correct).
+///
+/// ponytail: hand-rolled base64url JWT with <see cref="HMACSHA256"/> — a ZGW token is a
+/// plain HS256 JWS, so this ~15 lines beats adding Microsoft.IdentityModel.* just to sign
+/// three claims. Swap in a library if we ever need RS256 / JWKS.
+/// </summary>
+public sealed class ZgwTokenProvider(ZgwOptions options)
+{
+  public string Mint()
+  {
+    var header = new { alg = "HS256", typ = "JWT" };
+    var payload = new
+    {
+      iss = options.ClientId,
+      iat = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
+      client_id = options.ClientId,
+      user_id = options.UserId,
+      user_representation = options.UserRepresentation,
+    };
+
+    var signingInput = $"{Encode(header)}.{Encode(payload)}";
+    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(options.Secret));
+    var signature = Base64Url(hmac.ComputeHash(Encoding.UTF8.GetBytes(signingInput)));
+    return $"{signingInput}.{signature}";
+  }
+
+  private static string Encode(object o) => Base64Url(JsonSerializer.SerializeToUtf8Bytes(o));
+
+  private static string Base64Url(byte[] bytes) =>
+      Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+}

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

@@ -0,0 +1,58 @@
+using System.Text.Json.Serialization;
+using BigRegister.Api.Contracts;
+
+namespace BigRegister.Api.Zgw;
+
+/// <summary>
+/// The subset of a ZGW Zaak (Zaken API / ZRC) the read slice needs. The full resource has
+/// dozens of fields; we bind only what maps to <see cref="ApplicationSummaryDto"/>. Note the
+/// two ZGW traits that force an anti-corruption layer: <see cref="Url"/> is the resource's
+/// identity (not a bare id), and <see cref="Zaaktype"/> is a URL <em>into another service</em>
+/// (Catalogi/ZTC) that must be resolved to a human label.
+/// </summary>
+public sealed record ZgwZaak(
+    [property: JsonPropertyName("url")] string Url,
+    [property: JsonPropertyName("identificatie")] string Identificatie,
+    [property: JsonPropertyName("zaaktype")] string Zaaktype,
+    [property: JsonPropertyName("startdatum")] DateOnly Startdatum,
+    [property: JsonPropertyName("einddatum")] DateOnly? Einddatum,
+    [property: JsonPropertyName("registratiedatum")] DateOnly? Registratiedatum);
+
+/// <summary>
+/// Anti-corruption map: ZGW Zaak → the existing <see cref="ApplicationSummaryDto"/> the FE
+/// already renders (WP-49). This is where "URL as identity" and the cross-service zaaktype
+/// join get flattened away, so nothing downstream (the FE) sees ZGW shapes.
+/// </summary>
+public static class ZgwZaakMapper
+{
+  /// <summary>Last path segment of a ZGW resource URL — the uuid that identifies it.</summary>
+  public static string Uuid(string url) => url.TrimEnd('/').Split('/').Last();
+
+  public static ApplicationSummaryDto ToSummaryDto(ZgwZaak z, string zaaktypeLabel)
+  {
+    // ponytail: coarse status map — an open zaak (no einddatum) is In behandeling, a closed
+    // one is Goedgekeurd. Real fidelity (statustype/resultaat lookups) is a later slice; the
+    // Afgewezen path needs the resultaat resource. Enough to prove the seam end-to-end.
+    var status = z.Einddatum is null
+        ? new AanvraagStatusDto("InBehandeling", Referentie: z.Identificatie, Manual: true)
+        : new AanvraagStatusDto("Goedgekeurd", Referentie: z.Identificatie);
+
+    var created = Iso(z.Registratiedatum ?? z.Startdatum);
+    var updated = Iso(z.Einddatum ?? z.Registratiedatum ?? z.Startdatum);
+
+    return new ApplicationSummaryDto(
+        Id: Uuid(z.Url),
+        Type: zaaktypeLabel,
+        Status: status,
+        DocumentIds: Array.Empty<string>(),   // zaak↔document links arrive with WP-51 (DRC)
+        CreatedAt: created,
+        UpdatedAt: updated,
+        SubmittedAt: created,
+        Owner: z.Identificatie);              // real initiator (rol/BSN) needs a rollen lookup — later slice
+  }
+
+  // Keep the wire shape identical to the local source (round-trip datetime): a ZGW date
+  // becomes midnight UTC so the FE's date parsing sees the same format either backend.
+  private static string Iso(DateOnly d) =>
+      d.ToDateTime(TimeOnly.MinValue, DateTimeKind.Utc).ToString("o");
+}

backend/src/BigRegister.Api/appsettings.json

@@ -5,5 +5,15 @@
       "Microsoft.AspNetCore": "Warning"
     }
   },
-  "AllowedHosts": "*"
+  "AllowedHosts": "*",
+  "_Zgw": "WP-49: set Enabled=true + the URLs/credentials to source cases from a real OpenZaak. Off = local SQLite store (offline POC default).",
+  "Zgw": {
+    "Enabled": false,
+    "ZrcBaseUrl": "",
+    "ZtcBaseUrl": "",
+    "ClientId": "",
+    "Secret": "",
+    "UserId": "big-register-bff",
+    "UserRepresentation": "BIG-register BFF"
+  }
 }