@voxgig/sdkgen 4.32.1 → 4.33.0

package/project/.sdk/src/cmp/elixir/TestClean_elixir.ts

@@ -0,0 +1,666 @@
+import {
+  cmp,
+  each,
+  File,
+  Content,
+  isAuthSuppressed,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+} from '@voxgig/sdkgen'
+
+
+import {
+  elixirString,
+} from './utility_elixir'
+
+
+// The canary sweep, the elixir port of TestClean_ts.ts: see that component.
+const TestClean = cmp(function TestClean(props: any) {
+  const { model } = props.ctx$
+  const { entity } = props
+
+  const auth = {
+    suppressed: isAuthSuppressed(model),
+    where: resolveAuthIn(model),
+    name: 'header' === resolveAuthIn(model)
+      ? resolveAuthName(model).toLowerCase() : resolveAuthName(model),
+    basic: isHttpBasicAuth(model),
+  }
+
+  File({ name: 'clean_test.exs' }, () => Content(render(model, entity, auth)))
+})
+
+
+const OP_ORDER: Record<string, number> = { list: 0, load: 1 }
+const OPS = ['list', 'load', 'create', 'update', 'remove']
+
+
+// The path parameters an operation's points declare, as the runtime config
+// carries them under points[].args.params.
+function pointParams(opdef: any): string[] {
+  const names: string[] = []
+  for (const point of each(opdef?.points || [])) {
+    if (false === point?.a) continue
+    for (const arg of each(point?.g?.params || [])) {
+      if (false !== arg?.a && 'string' === typeof arg?.n && !names.includes(arg.n)) {
+        names.push(arg.n)
+      }
+    }
+  }
+  return names
+}
+
+
+// The operations to try, list and load first: a required path parameter is
+// what usually stops a candidate, and the read ops need none.
+function candidates(Name: string, entity: any[]): string {
+  const rows: { rank: number, text: string }[] = []
+  each(entity, (e: any) => {
+    for (const op of Object.keys(e.op || {})) {
+      if (!OPS.includes(op)) continue
+      rows.push({
+        rank: OP_ORDER[op] ?? 2,
+        text: `      {${elixirString(e.name + '.' + op)}, fn sdk -> ${Name}.${e.name}(sdk) end,
+       fn ent, match, ctrl -> ${Name}.Entity.${e.Name}.${op}(ent, args(match), ctrl) end,
+       [${pointParams(e.op[op]).map((p) => elixirString(p)).join(', ')}]}`,
+      })
+    }
+  })
+  rows.sort((a, b) => a.rank - b.rank)
+  return rows.map((r) => r.text).join(',\n')
+}
+
+
+function render(model: any, entity: any[], auth: {
+  suppressed: boolean, where: string, name: string, basic: boolean
+}): string {
+  const Name = model.const.Name
+
+  return `# ${Name} SDK canary sweep (generated by @voxgig/sdkgen).
+#
+# Every credential slot holds a distinctive value, every diagnostic feature
+# this SDK ships is switched on with a capturing sink, a real operation runs
+# through every outcome, and every string that leaves the SDK is searched for
+# the canaries and their encoded forms. It also proves its own sensitivity:
+# with clean switched off the canary MUST show.
+#
+# A struct node inspects as a handle, so the SDK's own records (the error's
+# result and spec, the explain record, every sink record, the context's
+# to_data) are also read through the struct JSON; a raw client, entity or
+# context node is not, since that is a dump of the heap rather than a
+# serialisation the SDK performs.
+
+defmodule ${Name}.CleanTest do
+  use ExUnit.Case
+
+  alias Voxgig.Struct, as: S
+  alias ${Name}.Helpers, as: H
+  alias ${Name}.FeatureHarness, as: FH
+
+  # Generated: the credential's wire placement is fixed when the SDK is built.
+  @auth %{suppressed: ${auth.suppressed}, where: ${elixirString(auth.where)},
+          name: ${elixirString(auth.name)}, basic: ${auth.basic}}
+
+  @canary %{
+    apikey: "CANARY-APIKEY-k9x2m7q4p1",
+    secret: "CANARY-SECRET-w3e8r5t2y6",
+    header: "CANARY-HEADER-z1x4c7v0b3",
+    value: "CANARY-VALUE-n5m8b2v9c4"
+  }
+
+  @mask "[redacted]"
+
+  # Every form a canary can travel in.
+  defp forms_of do
+    Enum.flat_map(Map.values(@canary), fn v -> [v, Base.encode64(v), S.escurl(v)] end) ++
+      [Base.encode64(@canary.apikey <> ":" <> @canary.secret)]
+  end
+
+  defp leaks(text), do: Enum.filter(forms_of(), &String.contains?(text, &1))
+
+  # Header maps keep the caller's spelling; the assertion should not care.
+  defp header(m, name) do
+    if S.ismap(m) do
+      Enum.find_value(H.entries(m), fn {k, v} ->
+        if String.downcase(to_string(k)) == String.downcase(name), do: v
+      end)
+    end
+  end
+
+  defp push(name, kind, f) do
+    try do
+      [%{name: name <> ":" <> kind, text: to_string(f.())}]
+    rescue
+      _ -> []
+    catch
+      _, _ -> []
+    end
+  end
+
+  # Every default print of a value, as a sink each.
+  defp forms(name, val) do
+    push(name, "inspect", fn -> inspect(val, limit: :infinity, printable_limit: :infinity) end) ++
+      push(name, "raw", fn -> inspect(val, structs: false, limit: :infinity, printable_limit: :infinity) end) ++
+      if is_exception(val) do
+        push(name, "message", fn -> Exception.message(val) end) ++
+          push(name, "format", fn -> Exception.format(:error, val) end) ++
+          push(name, "json", fn -> S.jsonify(val) end)
+      else
+        []
+      end
+  end
+
+  # The SDK's own data, through the struct JSON as well.
+  defp data_forms(name, node) do
+    forms(name, node) ++
+      push(name, "json", fn -> S.jsonify(node) end) ++
+      push(name, "stringify", fn -> S.stringify(node) end)
+  end
+
+  defp error_forms(e) do
+    forms("error", e) ++
+      if match?(%${Name}.Error{}, e) do
+        data_forms("error.result", e.result) ++ data_forms("error.spec", e.spec)
+      else
+        []
+      end
+  end
+
+  defp result_forms(out) do
+    cond do
+      S.ismap(out) and S.getprop(out, "_client") != nil ->
+        forms("result", out) ++ data_forms("result.data", S.getprop(out, "_data"))
+
+      S.islist(out) ->
+        forms("result", out)
+
+      true ->
+        data_forms("result", out)
+    end
+  end
+
+  defp add(sinks, items), do: Enum.each(items, fn s -> S.setprop(sinks, S.size(sinks), s) end)
+  defp sink_list(sinks), do: Enum.map(H.entries(sinks), &elem(&1, 1))
+
+  # Captures the serialised context from inside the pipeline: what a hook
+  # author would hand to a logger.
+  defp capture_feature(sinks) do
+    cap = fn hook ->
+      fn ctx ->
+        add(sinks, forms("ctx@" <> hook, ctx))
+        add(sinks, data_forms("ctxdata@" <> hook, ${Name}.Context.to_data(ctx)))
+        nil
+      end
+    end
+
+    S.jm([
+      "name", "capture", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PreRequest", cap.("PreRequest"),
+      "PreResponse", cap.("PreResponse"),
+      "PreUnexpected", cap.("PreUnexpected")
+    ])
+  end
+
+  defp response(status, data, headers) do
+    h = S.jm(["content-type", "application/json"])
+    Enum.each(headers, fn {k, v} -> S.setprop(h, k, v) end)
+
+    S.jm([
+      "status", status,
+      "statusText", if(status < 400, do: "OK", else: "ERR"),
+      "headers", h,
+      "body", S.jsonify(data),
+      "json", fn -> data end
+    ])
+  end
+
+  defp scenarios do
+    [
+      {"ok",
+       fn _url, _fd ->
+         {response(200, S.jm(["id", "i1", "name", "n1"]), [{"x-session-token", "RESP-TOKEN-a1b2c3d4e5"}]), nil}
+       end},
+      {"notfound", fn _url, _fd -> {response(404, S.jm(["error", "no such record"]), []), nil} end},
+      {"server", fn _url, _fd -> {response(500, S.jm(["error", "boom"]), []), nil} end},
+      {"transport",
+       fn url, _fd ->
+         {nil, ${Name}.Error.new("transport", "socket hang up (URL was: \\"" <> url <> "\\")")}
+       end},
+      {"notjson",
+       fn _url, _fd ->
+         {S.jm([
+            "status", 200, "statusText", "OK", "headers", S.jm([]), "body", "<html>",
+            "json", fn -> raise "Unexpected token < in JSON" end
+          ]), nil}
+       end}
+    ]
+  end
+
+  defp make_sdk(respond, sinks, cleanopts, extra \\\\ []) do
+    capture = fn name -> fn rec -> add(sinks, data_forms(name, rec)) end end
+    feature = S.jm([])
+
+    on = fn name, kvs ->
+      if FH.has_feature(name), do: S.setprop(feature, name, S.jm(["active", true] ++ kvs))
+    end
+
+    on.("log", ["logger", capture.("log")])
+    on.("debug", ["onEntry", capture.("debug")])
+    on.("audit", ["sink", capture.("audit")])
+    on.("telemetry", ["exporter", capture.("telemetry")])
+    on.("cost", ["sink", capture.("cost")])
+    on.("metrics", [])
+    on.("clienttrack", [])
+
+    clean = S.jm(["values", @canary.value])
+    Enum.each(cleanopts, fn {k, v} -> S.setprop(clean, k, v) end)
+
+    ${Name}.new(
+      S.jm([
+        "apikey", @canary.apikey,
+        "secret", @canary.secret,
+        "headers", S.jm(["X-Custom-Token", @canary.header]),
+        "clean", clean,
+        "feature", feature,
+        "extend", S.jt([capture_feature(sinks) | extra]),
+        "utility", S.jm(["fetcher", fn _ctx, url, fd -> respond.(url, fd) end])
+      ])
+    )
+  end
+
+  # A fresh struct node of the match, since an operation may keep what it is
+  # given.
+  defp args(match), do: S.jm(Enum.flat_map(match, fn {k, v} -> [k, v] end))
+
+  # The operations this SDK generated, read ops first.
+  defp candidates do
+    [
+${candidates(Name, entity)}
+    ]
+  end
+
+  # The first operation that completes against a plain 200: with no
+  # arguments, else with every path parameter its points declare filled in.
+  defp usable_op do
+    plain =
+      ${Name}.new(
+        S.jm([
+          "apikey", @canary.apikey,
+          "utility", S.jm(["fetcher", fn _c, _u, _f -> {response(200, S.jm(["id", "i1"]), []), nil} end])
+        ])
+      )
+
+    Enum.find_value(candidates(), fn {name, acc, op, params} ->
+      filled = Map.new(params, fn p -> {p, "p1"} end)
+
+      Enum.find_value([%{}, filled], fn match ->
+        try do
+          op.(acc.(plain), match, S.jm([]))
+          {name, acc, op, match}
+        rescue
+          _ -> nil
+        catch
+          _, _ -> nil
+        end
+      end)
+    end)
+  end
+
+  # A feature that raises from inside the pipeline, quoting the request it
+  # saw: an error make_error never handled.
+  defp throw_feature(unexpected) do
+    saw = fn ctx -> "hook saw " <> S.jsonify(S.getprop(ctx, "spec")) end
+
+    S.jm([
+      "name", "throwhook", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PreResponse", fn ctx -> raise saw.(ctx) end,
+      # Fired from the operation's rescue, before its cleaning.
+      "PreUnexpected", fn ctx -> if unexpected, do: raise(saw.(ctx)) end
+    ])
+  end
+
+  # A stream that fails while the caller iterates it, quoting a credential.
+  defp stream_feature do
+    S.jm([
+      "name", "streamthrow", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PreDone", fn ctx ->
+        S.setprop(S.getprop(ctx, "result"), "stream",
+          fn -> Stream.map([1], fn _ -> raise "stream saw " <> @canary.apikey end) end)
+      end
+    ])
+  end
+
+  # A stream that succeeds, yielding the result's items.
+  defp stream_ok_feature do
+    S.jm([
+      "name", "streamok", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PreDone", fn ctx ->
+        result = S.getprop(ctx, "result")
+        rd = S.getprop(result, "resdata")
+        items = if S.islist(rd), do: Enum.map(H.entries(rd), &elem(&1, 1)), else: List.wrap(rd)
+        S.setprop(result, "stream", fn -> items end)
+      end
+    ])
+  end
+
+  # The target operation, streamed through its entity.
+  defp stream_of(sdk, {name, acc, _op, match}, callopts) do
+    ent = acc.(sdk)
+    mod = S.getprop(ent, "_module")
+    mod.stream(ent, List.last(String.split(name, ".")), S.jm(["reqmatch", args(match)]), callopts)
+  end
+
+  # Features that fail the operation with the SDK's own error, whose code
+  # quotes a registered value: one refuses it as rbac does, and records the
+  # error PreUnexpected hands a hook; the other raises.
+  defp deny_feature(sinks) do
+    S.jm([
+      "name", "denyhook", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PrePoint", fn ctx ->
+        err = ${Name}.Context.make_error(ctx, "denied:" <> @canary.value, "denied")
+        S.setprop(S.getprop(ctx, "out"), "point", err)
+      end,
+      "PreUnexpected", fn ctx ->
+        add(sinks, error_forms(S.getprop(S.getprop(ctx, "ctrl"), "err")))
+        nil
+      end
+    ])
+  end
+
+  defp raise_feature do
+    S.jm([
+      "name", "raisehook", "version", "0.0.1", "active", true, "options", S.jm([]),
+      "init", fn _ctx, _opts -> nil end,
+      "PreResponse", fn _ctx -> raise ${Name}.Error.new("raised:" <> @canary.value, "raised") end
+    ])
+  end
+
+  defp drive(sdk, {_name, acc, op, match}, ctrl, sinks) do
+    ent = acc.(sdk)
+    # A caller may keep the record it passed rather than read ctrl.explain.
+    held = S.getprop(ctrl, "explain")
+
+    {out, err} =
+      try do
+        {op.(ent, match, ctrl), nil}
+      rescue
+        e -> {nil, e}
+      end
+
+    if err != nil, do: add(sinks, error_forms(err))
+    if out != nil, do: add(sinks, result_forms(out))
+    explain = S.getprop(ctrl, "explain")
+    if explain != nil, do: add(sinks, data_forms("explain", explain))
+    if held != nil and held != explain, do: add(sinks, data_forms("explain:held", held))
+    err
+  end
+
+  @no_target "no operation of this SDK completes against a plain 200; nothing to sweep"
+
+  # ExUnit has no runtime skip, so a sweep with nothing to drive says so.
+  test "no credential leaves the SDK in any form" do
+    case usable_op() do
+      nil -> IO.puts("SKIP no credential leaves the SDK in any form: " <> @no_target)
+      target -> sweep(target)
+    end
+  end
+
+  test "the sweep can see a leak: clean switched off shows the credential" do
+    case usable_op() do
+      nil -> IO.puts("SKIP the sweep can see a leak: " <> @no_target)
+      target -> sweep_blind(target)
+    end
+  end
+
+  defp sweep(target) do
+    sinks = S.jt([])
+
+    variants = [
+      {"throw", fn -> S.jm([]) end},
+      {"explain", fn -> S.jm(["explain", S.jm([])]) end},
+      {"nothrow", fn -> S.jm(["throw", false, "explain", S.jm([])]) end}
+    ]
+
+    {errors, explains} =
+      Enum.reduce(scenarios(), {%{}, %{}}, fn {sname, respond}, acc ->
+        Enum.reduce(variants, acc, fn {vname, mkctrl}, {errors, explains} ->
+          sdk = make_sdk(respond, sinks, [])
+          ctrl = mkctrl.()
+          err = drive(sdk, target, ctrl, sinks)
+          add(sinks, forms("sdk", sdk))
+          key = sname <> "/" <> vname
+          errors = if err != nil, do: Map.put(errors, key, err), else: errors
+          ex = S.getprop(ctrl, "explain")
+          explains = if ex != nil, do: Map.put(explains, key, ex), else: explains
+          {errors, explains}
+        end)
+      end)
+
+    # A credential mistyped as a map is rejected by validation, whose message
+    # quotes the value it rejected.
+    rejected =
+      try do
+        ${Name}.new(S.jm(["apikey", S.jm(["value", @canary.apikey]), "clean", S.jm(["values", @canary.value])]))
+        nil
+      rescue
+        e -> e
+      end
+
+    assert rejected != nil, "a credential mistyped as a map should be rejected"
+    add(sinks, forms("rejected", rejected))
+
+    # An error a feature hook raises, quoting the request, skips make_error.
+    [{_name, ok} | _] = scenarios()
+
+    for unexpected <- [false, true] do
+      hooked = make_sdk(ok, sinks, [], [throw_feature(unexpected)])
+      err = drive(hooked, target, S.jm(["explain", S.jm([])]), sinks)
+      assert err != nil, "the throwing hook should fail the operation"
+    end
+
+    # Iterating a stream runs through the same cleaning path as the operation,
+    # and the explain record the caller passed is cleaned however it ends.
+    for {name, extra} <- [{"stream", [stream_feature()]}, {"stream-ok", [stream_ok_feature()]}, {"stream-plain", []}] do
+      explain = S.jm([])
+      callopts = S.jm(["ctrl", S.jm(["explain", explain])])
+
+      streamerr =
+        try do
+          Enum.to_list(stream_of(make_sdk(ok, sinks, [], extra), target, callopts))
+          nil
+        rescue
+          e -> e
+        end
+
+      assert (name == "stream") == (streamerr != nil), name <> ": only the failing stream raises"
+      if streamerr != nil, do: add(sinks, forms(name, streamerr))
+      assert S.size(explain) > 0, name <> ": the explain record was not filled"
+      add(sinks, data_forms(name <> ":explain", explain))
+    end
+
+    # A feature's own error keeps its code, which is cleaned like the message:
+    # returned, handed to a hook, raised by a hook, and nested in a record.
+    denied = drive(make_sdk(ok, sinks, [], [deny_feature(sinks)]), target, S.jm([]), sinks)
+    assert denied != nil, "the refusing hook should fail the operation"
+    raised = drive(make_sdk(ok, sinks, [], [raise_feature()]), target, S.jm([]), sinks)
+    assert raised != nil, "the raising hook should fail the operation"
+
+    nested =
+      ${Name}.Utility.clean_impl(${Name}.get_root_ctx(make_sdk(ok, sinks, [])),
+        S.jm(["err", ${Name}.Error.new("nested:" <> @canary.value, "nested")]))
+
+    add(sinks, data_forms("nested", nested))
+
+    # A client given no clean block at all masks by the schema defaults.
+    [_ok, {_nf, notfound_respond} | _] = scenarios()
+
+    bare =
+      ${Name}.new(
+        S.jm([
+          "apikey", @canary.apikey,
+          "secret", @canary.secret,
+          "headers", S.jm(["X-Custom-Token", @canary.header]),
+          "utility", S.jm(["fetcher", fn _ctx, url, fd -> notfound_respond.(url, fd) end])
+        ])
+      )
+
+    barerr = drive(bare, target, S.jm([]), sinks)
+    assert barerr != nil, "the 404 scenario must fail without a clean block"
+
+    # The raw path returns its failure rather than raising it.
+    [_ok, _nf, _server, {_tr, transport_respond} | _] = scenarios()
+    direct = ${Name}.direct(make_sdk(transport_respond, sinks, []), S.jm(["path", "raw"]))
+    assert S.getprop(direct, "ok") == false, "a transport failure should fail direct()"
+    add(sinks, forms("direct", S.getprop(direct, "err")))
+
+    all = sink_list(sinks)
+    leaked = Enum.filter(all, fn s -> leaks(s.text) != [] end)
+
+    IO.puts("clean: swept #{length(all)} surface(s), #{length(leaked)} leak(s)")
+
+    assert leaked == [],
+           "credential leaked through: " <>
+             Enum.map_join(leaked, "; ", fn s -> s.name <> " [" <> Enum.join(leaks(s.text), ", ") <> "]" end)
+
+    # The positive half: the slot the credential travelled in is masked, and
+    # an unregistered token in a response header is masked by name.
+    notfound = errors["notfound/throw"]
+    assert notfound != nil, "the 404 scenario must throw"
+    assert match?(%${Name}.Error{}, notfound), "the 404 error is an SDK error"
+    assert ${Name}.Error.status(notfound) == 404
+    spec = notfound.spec
+
+    unless @auth.suppressed do
+      case @auth.where do
+        "query" ->
+          assert header(S.getprop(spec, "query"), @auth.name) == @mask
+
+        "cookie" ->
+          assert String.contains?(to_string(header(S.getprop(spec, "headers"), "cookie")), @mask)
+
+        _ ->
+          assert String.ends_with?(to_string(header(S.getprop(spec, "headers"), @auth.name)), @mask)
+      end
+    end
+
+    assert header(S.getprop(spec, "headers"), "x-custom-token") == @mask
+    assert denied.code == "denied:" <> @mask
+    assert raised.code == "raised:" <> @mask
+    assert S.getpath(nested, "err.code") == "nested:" <> @mask
+    assert header(S.getprop(barerr.spec, "headers"), "x-custom-token") == @mask
+
+    explained = explains["ok/explain"]
+    result = if explained != nil, do: S.getprop(explained, "result"), else: nil
+    assert S.ismap(result), "the explain record should carry the result"
+    assert header(S.getprop(result, "headers"), "x-session-token") == @mask
+  end
+
+  defp sweep_blind(target) do
+    sinks = S.jt([])
+    [_ok, {_name, notfound} | _] = scenarios()
+    sdk = make_sdk(notfound, sinks, [{"active", false}])
+    err = drive(sdk, target, S.jm([]), sinks)
+    assert err != nil
+
+    # Explaining a failure must not cost it its error.
+    explained =
+      drive(make_sdk(notfound, S.jt([]), [{"active", false}]), target, S.jm(["explain", S.jm([])]), S.jt([]))
+
+    assert explained != nil and Exception.message(explained) == Exception.message(err),
+           "with clean off, explain lost the error"
+
+    assert Enum.any?(sink_list(sinks), fn s -> leaks(s.text) != [] end),
+           "with clean off, nothing showed the canary: the sweep is blind"
+
+    unless @auth.suppressed do
+      text = S.jsonify(err.spec)
+
+      assert String.contains?(text, @canary.apikey) or
+               String.contains?(text, Base.encode64(@canary.apikey <> ":" <> @canary.secret)),
+             "the raw spec should carry the credential when clean is off"
+    end
+  end
+
+  test "a registered value used as a property name is masked, collisions kept" do
+    cfg = ${Name}.Utility.make_clean_config(S.jm(["keys", "key,secret,token"]))
+    ctx = S.jm(["options", S.jm(["__derived__", S.jm(["clean", cfg])])])
+    ${Name}.Utility.clean_add_impl(ctx, "ZZVAL-abc123")
+    ${Name}.Utility.clean_add_impl(ctx, "ZZVAL-xyz789")
+    out = ${Name}.Utility.clean_impl(ctx, S.jm(["ZZVAL-abc123", 1, "ZZVAL-xyz789", 2, "plain", 3]))
+    assert S.getprop(out, @mask) == 1
+    assert S.getprop(out, @mask <> "#1") == 2
+    assert S.getprop(out, "plain") == 3
+    assert "ZZVAL-abc123" not in S.keysof(out)
+  end
+
+  # A feature's name is not a field name: a feature called secrets does not
+  # make its settings secret, though a sensitive field inside it still is. An
+  # entity block, of entity settings or seeded records, is not read at all.
+  test "a feature's name is read as a name" do
+    record = S.jm(["zztoken", S.jm(["ZZTOKEN01", S.jm(["note", "PLAINRECORD-t5r3e1w9"])])])
+
+    client =
+      ${Name}.new(
+        S.jm([
+          "apikey", @canary.apikey,
+          "feature",
+          S.jm([
+            "secrets", S.jm(["active", false, "name", "ZZNAME-feat123", "token", "ZZTOKEN-feat456"]),
+            "test", S.jm(["active", false, "entity", record])
+          ]),
+          "entity", S.jm(["zztoken", S.jm(["alias", S.jm(["zzkey", "PLAINALIAS-m2n4b6v8"])])])
+        ])
+      )
+
+    ctx = ${Name}.get_root_ctx(client)
+    assert ${Name}.Utility.clean_impl(ctx, "ZZNAME-feat123 ZZTOKEN-feat456") == "ZZNAME-feat123 " <> @mask
+    assert ${Name}.Utility.clean_impl(ctx, "record PLAINRECORD-t5r3e1w9") == "record PLAINRECORD-t5r3e1w9"
+    assert ${Name}.Utility.clean_impl(ctx, "alias PLAINALIAS-m2n4b6v8") == "alias PLAINALIAS-m2n4b6v8"
+  end
+
+  test "the generated config's own clean block is honoured" do
+    config = S.jm(["options", S.jm(["clean", S.jm(["keys", "zzsens", "values", "CONFIG-SEEDED-1"])])])
+    ctx = S.jm(["config", config, "options", S.jm(["clean", S.jm(["values", "CALLER-SEEDED-2"])])])
+    cctx = S.jm(["options", ${Name}.Utility.make_options_impl(ctx)])
+
+    assert ${Name}.Utility.clean_impl(cctx, "a CONFIG-SEEDED-1 b CALLER-SEEDED-2") ==
+             "a " <> @mask <> " b " <> @mask
+
+    out = ${Name}.Utility.clean_impl(cctx, S.jm(["my_zzsens", "x", "other", "y"]))
+    assert S.getprop(out, "my_zzsens") == @mask
+    assert S.getprop(out, "other") == "y"
+    assert S.getpath(config, "options.clean.keys") == "zzsens"
+    assert S.getpath(config, "options.clean.values") == "CONFIG-SEEDED-1"
+  end
+
+  test "clean_add_sensitive registers every scalar under a sensitive name, at any depth" do
+    cfg = ${Name}.Utility.make_clean_config(S.jm(["keys", "key,secret,token"]))
+    ctx = S.jm(["options", S.jm(["__derived__", S.jm(["clean", cfg])])])
+
+    ${Name}.Utility.clean_add_sensitive(ctx, S.jm([
+      "apikey", S.jm(["value", "NESTED-SECRET-1"]),
+      "headers", S.jm(["X-Api-Token", S.jt(["LISTED-SECRET-2"])]),
+      "secret", 123456789,
+      "name", "not-a-secret"
+    ]))
+
+    values = Enum.map(H.entries(S.getprop(cfg, "values")), &elem(&1, 1))
+    assert "NESTED-SECRET-1" in values
+    assert "LISTED-SECRET-2" in values
+    assert "123456789" in values
+    refute "not-a-secret" in values
+  end
+end
+`
+}
+
+
+export {
+  TestClean
+}

package/project/.sdk/src/cmp/elixir/Test_elixir.ts

@@ -8,6 +8,7 @@ import { cmp, each, Folder, File, Content, entityCollection } from '@voxgig/sdkg
 
 import { TestEntity } from './TestEntity_elixir'
 import { TestDirect } from './TestDirect_elixir'
+import { TestClean } from './TestClean_elixir'
 import { ReadmeExamplesTest } from './ReadmeExamplesTest_elixir'
 
 
@@ -39,6 +40,9 @@ end
       TestDirect({ target, entity })
     })
 
+    // The canary sweep (test/clean_test.exs), picked up by `mix test`.
+    TestClean({ target, entity })
+
     // Validate the documented elixir examples in the README/REFERENCE docs.
     ReadmeExamplesTest({ target })
   })

package/project/.sdk/src/cmp/elixir/fragment/Main.fragment.ex

@@ -209,7 +209,7 @@ defmodule ProjectName do
 
         cond do
           fetch_err != nil ->
-            S.jm(["ok", false, "err", fetch_err])
+            S.jm(["ok", false, "err", Utility.clean(ctx, fetch_err)])
 
           fetched == nil ->
             S.jm(["ok", false, "err", Context.make_error(ctx, "direct_no_response", "response: undefined")])