@voxgig/sdkgen 4.32.0 → 4.33.0

package/project/.sdk/src/cmp/c/Test_c.ts

@@ -8,6 +8,7 @@ import { cmp, each, Folder, File, Content, entityCollection } from '@voxgig/sdkg
 
 import { TestEntity } from './TestEntity_c'
 import { TestDirect } from './TestDirect_c'
+import { TestClean } from './TestClean_c'
 import { ReadmeExamplesTest } from './ReadmeExamplesTest_c'
 
 
@@ -42,6 +43,8 @@ int main(void) {
       TestDirect({ target, entity })
     })
 
+    TestClean({ target })
+
     // Validate the documented C examples in the READMEs are well-formed.
     ReadmeExamplesTest({ target })
   })

package/project/.sdk/src/cmp/c/fragment/Entity.fragment.c

@@ -116,6 +116,15 @@ static voxgig_value* entyvar_run_op(entyvar_entity* self, Context* ctx,
   return done_util(ctx, err);
 }
 
+// A step's error does not pass through make_error in stream, so it and the
+// explain record are cleaned on the way out.
+static voxgig_value* entyvar_stream_fail(Context* ctx, PNError* pe, PNError** err) {
+  clean_explain_util(ctx);
+  clean_error_util(ctx, pe);
+  *err = pe;
+  return NULL;
+}
+
 // Streaming operation. Runs `action` through the full pipeline and returns a
 // List of the result items, so the `streaming` feature's incremental output
 // is reachable from a generated entity (a normal op call materialises the
@@ -162,27 +171,27 @@ voxgig_value* entyvar_stream(Entity* e, const char* action, voxgig_value* args,
 
   feature_hook_util(ctx, "PrePoint");
   voxgig_value* point = make_point_util(ctx, &pe);
-  if (pe) { *err = pe; return NULL; }
+  if (pe) return entyvar_stream_fail(ctx, pe, err);
   ctx_out_set_point_val(ctx, point);
 
   feature_hook_util(ctx, "PreSpec");
   Spec* spec = make_spec_util(ctx, &pe);
-  if (pe) { *err = pe; return NULL; }
+  if (pe) return entyvar_stream_fail(ctx, pe, err);
   ctx->out_spec = spec;
 
   feature_hook_util(ctx, "PreRequest");
   Response* resp = make_request_util(ctx, &pe);
-  if (pe) { *err = pe; return NULL; }
+  if (pe) return entyvar_stream_fail(ctx, pe, err);
   ctx->out_request = resp;
 
   feature_hook_util(ctx, "PreResponse");
   Response* resp2 = make_response_util(ctx, &pe);
-  if (pe) { *err = pe; return NULL; }
+  if (pe) return entyvar_stream_fail(ctx, pe, err);
   ctx->out_response = resp2;
 
   feature_hook_util(ctx, "PreResult");
   SdkResult* result = make_result_util(ctx, &pe);
-  if (pe) { *err = pe; return NULL; }
+  if (pe) return entyvar_stream_fail(ctx, pe, err);
   ctx->out_result = result;
 
   feature_hook_util(ctx, "PreDone");
@@ -191,6 +200,8 @@ voxgig_value* entyvar_stream(Entity* e, const char* action, voxgig_value* args,
   // back to the materialised items so `stream` always yields.
   SdkResult* res = ctx->result;
   if (res && res->stream) {
+    // done() does not run on this path, so its record is cleaned here.
+    clean_explain_util(ctx);
     return res->stream(res->stream_ud);
   }
 

package/project/.sdk/src/cmp/c/fragment/Main.fragment.c

@@ -188,7 +188,7 @@ static voxgig_value* sdk_raw_request(
   PNError* ferr = NULL;
   voxgig_value* fetched = utility_fetch(utility, ctx, url, fetchdef, &ferr);
   if (ferr) {
-    return err_map(ferr->msg);
+    return err_map(clean_str(ctx, ferr->msg));
   }
 
   if (v_is_noval(fetched) || v_is_null(fetched)) {

package/project/.sdk/src/cmp/clojure/PrepareAuth_clojure.ts

@@ -121,6 +121,9 @@ function basicBlock(): string {
                     (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
                           b64 (.encodeToString (java.util.Base64/getEncoder)
                                                (.getBytes ^String (str apikey ":" (if (missing? secret) "" secret)) "UTF-8"))]
+                      ;; The joined, encoded pair is a wire form neither
+                      ;; credential's own registration covers.
+                      (ucall ctx :clean-add b64)
                       (.put ^java.util.Map headers HEADER-AUTH
                             (if (= auth-prefix "") b64 (str auth-prefix " " b64))))))
 ${headerPlace(16)})`

package/project/.sdk/src/cmp/clojure/TestClean_clojure.ts

@@ -0,0 +1,473 @@
+import {
+  cmp,
+  each,
+  File,
+  Content,
+  isAuthSuppressed,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+} from '@voxgig/sdkgen'
+
+
+// The canary sweep, the clojure port of TestClean_ts.ts: see that component.
+const TestClean = cmp(function TestClean(props: any) {
+  const { model } = props.ctx$
+  const { target, 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.' + target.ext }, () => 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(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: `   {:name "${e.name}.${op}"
+    :accessor (fn [sdk] (api/${e.name} sdk nil))
+    :params [${pointParams(e.op[op]).map(cljstr).join(' ')}]
+    :op (fn [ent match ctrl] (e-${e.name}/${op} ent (args match) ctrl))
+    :stream (fn [ent match callopts] (e-${e.name}/stream ent ${cljstr(op)} (vs/jm "reqmatch" (args match)) callopts))}`,
+      })
+    }
+  })
+  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 {
+  let requires = ''
+  each(entity, (e: any) => {
+    requires += `\n            [sdk.entity.${e.name} :as e-${e.name}]`
+  })
+
+  return `;; ${model.const.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.
+(ns sdk.test.clean
+  (:require [sdk.api :as api]
+            [sdk.core :as core]
+            [sdk.test.feature :as feature]
+            [sdk.testutil :as t]
+            [voxgig.struct :as vs]
+            [clojure.string :as str]${requires}))
+
+;; Generated: the credential's wire placement is fixed when the SDK is built.
+(def AUTH {:suppressed ${auth.suppressed} :where ${cljstr(auth.where)}
+           :name ${cljstr(auth.name)} :basic ${auth.basic}})
+
+(def CANARY {:apikey "CANARY-APIKEY-k9x2m7q4p1"
+             :secret "CANARY-SECRET-w3e8r5t2y6"
+             :header "CANARY-HEADER-z1x4c7v0b3"
+             :value "CANARY-VALUE-n5m8b2v9c4"
+             :config "CANARY-CONFIG-h6j3k8l2m5"})
+
+(def MASK "[redacted]")
+
+(defn- b64 [^String s]
+  (.encodeToString (java.util.Base64/getEncoder) (.getBytes s "UTF-8")))
+
+;; Every form a canary can travel in.
+(def FORMS
+  (vec (concat (mapcat (fn [v] [v (b64 v) (vs/escurl v)]) (vals CANARY))
+               [(b64 (str (:apikey CANARY) ":" (:secret CANARY)))])))
+
+(defn- leaks [^String text] (filterv (fn [^String f] (.contains text f)) FORMS))
+
+;; Header maps keep the caller's spelling; the assertion should not care.
+(defn- header [m name]
+  (when (instance? java.util.Map m)
+    (some (fn [k] (when (= (str/lower-case (str k)) (str/lower-case (str name)))
+                    (.get ^java.util.Map m k)))
+          (vec (.keySet ^java.util.Map m)))))
+
+;; Every default print and serialisation of a value, as a sink each.
+(defn- forms [name val]
+  (let [out (atom [])
+        push (fn [kind f]
+               (try (swap! out conj {:name (str name ":" kind) :text (str (f))})
+                    (catch Throwable _ nil)))]
+    (push "pr" #(pr-str val))
+    (push "str" #(str val))
+    (push "json" #(vs/jsonify val))
+    (when (instance? Throwable val)
+      (push "message" #(ex-message val))
+      (push "data" #(pr-str (ex-data val)))
+      (push "map" #(pr-str (Throwable->map val)))
+      (push "sdk-pr" #(pr-str (core/ex->sdk val)))
+      (push "sdk-json" #(vs/jsonify (core/err->data (core/ex->sdk val))))
+      (push "stack" #(let [sw (java.io.StringWriter.)]
+                       (.printStackTrace ^Throwable val (java.io.PrintWriter. sw))
+                       (str sw))))
+    @out))
+
+;; Captures the serialised context from inside the pipeline: what a hook
+;; author would hand to a logger.
+(defn- capture-feature [sinks]
+  (let [cap (fn [hook] (fn [ctx] (swap! sinks into (forms (str "ctx@" hook) ctx))))]
+    (atom {:name "capture" :active true :version "0.0.1" :_options nil
+           "init" (fn [_ctx _opts] nil)
+           "PreRequest" (cap "PreRequest")
+           "PreResponse" (cap "PreResponse")
+           ;; The SDK's own error as a hook reads it, which an observability
+           ;; feature logs.
+           "PreUnexpected" (fn [ctx]
+                             ((cap "PreUnexpected") ctx)
+                             (let [err (core/oget (core/oget ctx :ctrl) :err)]
+                               (when (core/sdk-error? err)
+                                 (swap! sinks into (forms "ctrl.err@PreUnexpected" err)))))})))
+
+(defn- response [status data headers]
+  (let [h (vs/jm "content-type" "application/json")]
+    (doseq [[k v] headers] (.put ^java.util.Map h k v))
+    (vs/jm "status" status "statusText" (if (< status 400) "OK" "ERR")
+           "headers" h "body" (vs/jsonify data) "json" (fn [] data))))
+
+(def SCENARIOS
+  [{:name "ok"
+    :respond (fn [_url _fd] [(response 200 (vs/jm "id" "i1" "name" "n1")
+                                       {"x-session-token" "RESP-TOKEN-a1b2c3d4e5"}) nil])}
+   {:name "notfound"
+    :respond (fn [_url _fd] [(response 404 (vs/jm "error" "no such record") {}) nil])}
+   {:name "server"
+    :respond (fn [_url _fd] [(response 500 (vs/jm "error" "boom") {}) nil])}
+   {:name "transport"
+    :respond (fn [url _fd] [nil (core/make-error-obj "transport"
+                                                     (str "socket hang up (URL was: \\"" url "\\")"))])}
+   ;; The SDK's own error, its code quoting a registered value.
+   {:name "coded"
+    :respond (fn [_url _fd] [nil (core/make-error-obj (str "denied_" (:apikey CANARY)) "coded failure")])}
+   {:name "notjson"
+    :respond (fn [_url _fd] [(vs/jm "status" 200 "statusText" "OK" "headers" (vs/jm)
+                                    "body" "<html>"
+                                    "json" (fn [] (throw (RuntimeException. "Unexpected token < in JSON")))) nil])}])
+
+(defn- make-sdk [scenario sinks cleanopts & extra]
+  (let [capture (fn [name] (fn [rec] (swap! sinks into (forms name rec))))
+        feature (vs/jm)
+        on (fn [name & kvs] (when (feature/feature-present? name)
+                              (.put ^java.util.Map feature name (apply vs/jm "active" true kvs))))]
+    (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")
+    (let [clean (vs/jm "values" (:value CANARY))]
+      (doseq [[k v] (or cleanopts {})] (.put ^java.util.Map clean k v))
+      (api/make-sdk (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
+                           "headers" (vs/jm "X-Custom-Token" (:header CANARY))
+                           "clean" clean
+                           "feature" feature
+                           "extend" (apply vs/jt (capture-feature sinks) extra)
+                           "utility" (vs/jm "fetcher" (fn [_fctx url fd] ((:respond scenario) url fd))))))))
+
+;; A fresh struct map of the match, since an operation may keep what it is
+;; given.
+(defn- args [match]
+  (let [m (vs/jm)]
+    (doseq [[k v] match] (.put ^java.util.Map m k v))
+    m))
+
+;; The operations this SDK generated, read ops first.
+(def CANDIDATES
+  [
+${candidates(entity)}
+   ])
+
+;; The first operation that completes against a plain 200: with no
+;; arguments, else with every path parameter its points declare filled in.
+(defn- usable-op []
+  (let [plain (api/make-sdk (vs/jm "apikey" (:apikey CANARY)
+                                   "utility" (vs/jm "fetcher" (fn [_ _ _] [(response 200 (vs/jm "id" "i1") {}) nil]))))]
+    (some (fn [c]
+            (some (fn [match]
+                    (try ((:op c) ((:accessor c) plain) match (vs/jm))
+                         (assoc c :match match)
+                         (catch Throwable _ nil)))
+                  [{} (into {} (map (fn [p] [p "p1"]) (:params c)))]))
+          CANDIDATES)))
+
+;; A feature that throws from inside the pipeline, quoting the request it
+;; saw: an error make-error never handled.
+(defn- hook-saw [ctx]
+  (let [sp (core/oget ctx :spec)]
+    (RuntimeException. (str "hook saw " (pr-str (if (instance? clojure.lang.IDeref sp) @sp sp))))))
+
+(defn- throw-feature [unexpected]
+  (atom {:name "throwhook" :active true :version "0.0.1" :_options nil
+         "init" (fn [_ctx _opts] nil)
+         "PreResponse" (fn [ctx] (throw (hook-saw ctx)))
+         ;; Fired from the operation's catch, before its cleaning.
+         "PreUnexpected" (fn [ctx] (when unexpected (throw (hook-saw ctx))))}))
+
+;; A stream that fails while it is realised, quoting a credential.
+(defn- stream-throw-feature []
+  (atom {:name "streamthrow" :active true :version "0.0.1" :_options nil
+         "init" (fn [_ctx _opts] nil)
+         "PreDone" (fn [ctx]
+                     (core/oset! (core/oget ctx :result) :stream
+                                 (fn [] (map (fn [_] (throw (RuntimeException. (str "stream saw " (:apikey CANARY)))))
+                                             [1]))))}))
+
+;; A stream that succeeds, yielding the result's items.
+(defn- stream-ok-feature []
+  (atom {:name "streamok" :active true :version "0.0.1" :_options nil
+         "init" (fn [_ctx _opts] nil)
+         "PreDone" (fn [ctx]
+                     (let [result (core/oget ctx :result)
+                           rd (core/oget result :resdata)
+                           items (cond (vs/islist rd) (vec rd) (nil? rd) [] :else [rd])]
+                       (core/oset! result :stream (fn [] items))))}))
+
+;; A feature that throws the SDK's own error, its code quoting a registered
+;; value: an SDK error make-error never handled.
+(defn- coded-throw-feature []
+  (atom {:name "codedhook" :active true :version "0.0.1" :_options nil
+         "init" (fn [_ctx _opts] nil)
+         "PreResponse" (fn [_ctx]
+                         (core/sdk-throw (core/make-error-obj (str "denied_" (:apikey CANARY))
+                                                              "coded hook failure")))}))
+
+(defn- drive [sdk target ctrl sinks]
+  (let [ent ((:accessor target) sdk)
+        ;; A caller may keep the record it passed rather than read ctrl.explain.
+        held (vs/getprop ctrl "explain")
+        [out err] (try [((:op target) ent (:match target) ctrl) nil] (catch Throwable e [nil e]))
+        explain (vs/getprop ctrl "explain")]
+    (when err (swap! sinks into (forms "error" err)))
+    (when (some? out) (swap! sinks into (forms "result" out)))
+    (when (some? explain) (swap! sinks into (forms "explain" explain)))
+    (when (and (some? held) (not (identical? held explain))) (swap! sinks into (forms "explain:held" held)))
+    err))
+
+(def ^:private NO-TARGET "no operation of this SDK completes against a plain 200; nothing to sweep")
+
+(defn run [rec]
+  (t/run-check rec "clean-no-credential-leaves-the-sdk"
+    (fn []
+      (if-let [target (usable-op)]
+        (let [sinks (atom []) errors (atom {}) explains (atom {}) featured (atom {})]
+          (doseq [scenario SCENARIOS
+                  variant [{:name "throw" :ctrl (fn [] (vs/jm))}
+                           {:name "explain" :ctrl (fn [] (vs/jm "explain" (vs/jm)))}
+                           {:name "nothrow" :ctrl (fn [] (vs/jm "throw" false "explain" (vs/jm)))}]]
+            (let [sdk (make-sdk scenario sinks nil)
+                  ctrl ((:ctrl variant))
+                  err (drive sdk target ctrl sinks)
+                  key (str (:name scenario) "/" (:name variant))]
+              (when err (swap! errors assoc key err))
+              (when-let [ex (vs/getprop ctrl "explain")] (swap! explains assoc key ex))
+              (swap! sinks into (forms "sdk" sdk))
+              (swap! sinks conj {:name "sdk:slots" :text (pr-str (into {} sdk))})))
+          ;; A credential mistyped as a map is rejected by validation, whose
+          ;; message quotes the value it rejected.
+          (let [rejected (try (api/make-sdk (vs/jm "apikey" (vs/jm "value" (:apikey CANARY))
+                                                   "clean" (vs/jm "values" (:value CANARY))))
+                              nil
+                              (catch Throwable e e))]
+            (t/is-some rejected "a credential mistyped as a map should be rejected")
+            (swap! sinks into (forms "rejected" rejected)))
+          ;; An error a feature hook throws, quoting the request, skips make-error.
+          (doseq [unexpected [false true]]
+            (let [hooked (make-sdk (first SCENARIOS) sinks nil (throw-feature unexpected))]
+              (t/is-some (drive hooked target (vs/jm "explain" (vs/jm)) sinks)
+                         "the throwing hook should fail the operation")))
+          ;; Streaming runs through the same cleaning path as the operation,
+          ;; and the explain record the caller passed is cleaned however it ends.
+          (doseq [[name extra] [["stream" [(stream-throw-feature)]] ["stream-ok" [(stream-ok-feature)]]
+                                ["stream-plain" []]]]
+            (let [streamed (apply make-sdk (first SCENARIOS) sinks nil extra)
+                  explain (vs/jm)
+                  err (try (vec ((:stream target) ((:accessor target) streamed) (:match target)
+                                 (vs/jm "ctrl" (vs/jm "explain" explain))))
+                           nil
+                           (catch Throwable e e))]
+              (t/is-eq (some? err) (= "stream" name) (str name ": only the failing stream throws"))
+              (when err (swap! sinks into (forms name err)))
+              (t/is-true (pos? (.size ^java.util.Map explain)) (str name ": the explain record was not filled"))
+              (swap! sinks into (forms (str name ":explain") explain))))
+          (let [codedhook (make-sdk (first SCENARIOS) sinks nil (coded-throw-feature))
+                err (drive codedhook target (vs/jm) sinks)]
+            (t/is-some err "the coded hook should fail the operation")
+            (swap! errors assoc "codedhook" err))
+          ;; direct() returns its error rather than throwing it.
+          (doseq [scenario [(nth SCENARIOS 3) (nth SCENARIOS 4)]]
+            (let [raw (api/direct (make-sdk scenario sinks nil) (vs/jm "path" "raw"))]
+              (t/is-eq (vs/getprop raw "ok") false (str (:name scenario) ": direct() fails"))
+              (swap! errors assoc (str "direct/" (:name scenario)) (vs/getprop raw "err"))
+              (swap! sinks into (forms "direct" (vs/getprop raw "err")))))
+          ;; The generated config's own clean block is read beside the
+          ;; caller's, and is not changed by it.
+          (let [config (vs/jm "options" (vs/jm "clean" (vs/jm "keys" "zzsens" "values" (:config CANARY))))
+                built (core/u-make-options
+                       (atom {:config config :options (vs/jm "clean" (vs/jm "values" (:value CANARY)))}))
+                cfgctx (atom {:options built})
+                seeded (core/u-clean cfgctx (str "config " (:config CANARY) " caller " (:value CANARY)))]
+            (swap! sinks conj {:name "config-clean" :text (str seeded)})
+            (t/is-eq seeded (str "config " MASK " caller " MASK) "the config's clean values are registered")
+            (t/is-deep (core/u-clean cfgctx (vs/jm "my_zzsens" "x" "other" "y"))
+                       (vs/jm "my_zzsens" MASK "other" "y") "the config's clean keys apply")
+            (t/is-deep (vs/getpath config "options.clean") (vs/jm "keys" "zzsens" "values" (:config CANARY))
+                       "the config's clean block is unchanged"))
+          ;; With no clean option at all, the schema defaults still apply.
+          (let [bare (api/make-sdk (vs/jm "apikey" (:apikey CANARY) "secret" (:secret CANARY)
+                                          "headers" (vs/jm "X-Custom-Token" (:header CANARY))
+                                          "utility" (vs/jm "fetcher" (fn [_fctx url fd]
+                                                                       ((:respond (nth SCENARIOS 1)) url fd)))))]
+            (t/is-some (drive bare target (vs/jm "explain" (vs/jm)) sinks) "the 404 should fail without a clean option"))
+          ;; A feature's name is not a field name: only the sensitive names
+          ;; inside its settings register. An entity block, of entity settings
+          ;; or seeded records keyed by entity name and id, is not read at all.
+          (let [record (vs/jm "zztoken" (vs/jm "ZZTOKEN01" (vs/jm "note" "PLAINRECORD-t5r3e1w9")))
+                sdk (api/make-sdk (vs/jm "apikey" (:apikey CANARY)
+                                         "feature" (vs/jm "zzsecrets" (vs/jm "active" false "kind" "PLAINSETTING-q8w2e4r6")
+                                                          "zzfeat" (vs/jm "active" false "apitoken" "FEATTOKEN-z9y8x7w6")
+                                                          "test" (vs/jm "active" false "entity" record))
+                                         "entity" (vs/jm "zztoken" (vs/jm "alias" (vs/jm "zzkey" "PLAINALIAS-m2n4b6v8")))))
+                root (core/client-root-ctx sdk)]
+            (reset! featured {:plain (core/u-clean root "kind PLAINSETTING-q8w2e4r6")
+                              :token (core/u-clean root "token FEATTOKEN-z9y8x7w6")
+                              :record (core/u-clean root "record PLAINRECORD-t5r3e1w9")
+                              :alias (core/u-clean root "alias PLAINALIAS-m2n4b6v8")}))
+          (let [leaked (filterv (fn [s] (seq (leaks (:text s)))) @sinks)]
+            (println (str "clean: swept " (count @sinks) " surface(s), " (count leaked) " leak(s)"))
+            (t/is-eq (count leaked) 0
+                     (str "credential leaked through: "
+                          (str/join "; " (map (fn [s] (str (:name s) " [" (str/join ", " (leaks (:text s))) "]"))
+                                              leaked)))))
+          ;; The positive half: the slot the credential travelled in is
+          ;; masked, and an unregistered token in a response header is masked
+          ;; by name.
+          (let [notfound (get @errors "notfound/throw")
+                sdkerr (core/ex->sdk notfound)]
+            (t/is-some notfound "the 404 scenario must throw")
+            (t/is-some sdkerr "the 404 error is an SDK error")
+            (t/is-eq (vs/getprop (:result sdkerr) "status") 404 "status 404")
+            (let [spec (:spec sdkerr)]
+              (when-not (:suppressed AUTH)
+                (cond
+                  (= "query" (:where AUTH))
+                  (t/is-eq (header (vs/getprop spec "query") (:name AUTH)) MASK "query credential masked")
+                  (= "cookie" (:where AUTH))
+                  (t/is-true (str/includes? (str (header (vs/getprop spec "headers") "cookie")) MASK)
+                             (str "cookie: " (header (vs/getprop spec "headers") "cookie")))
+                  :else
+                  (t/is-true (str/ends-with? (str (header (vs/getprop spec "headers") (:name AUTH))) MASK)
+                             (str (:name AUTH) ": " (header (vs/getprop spec "headers") (:name AUTH))))))
+              (t/is-eq (header (vs/getprop spec "headers") "x-custom-token") MASK "custom token header masked")))
+          (doseq [key ["coded/throw" "codedhook"]]
+            (t/is-eq (:code (core/ex->sdk (get @errors key))) (str "denied_" MASK)
+                     (str key ": the error keeps its code, masked")))
+          (t/is-eq (:code (get @errors "direct/transport")) "transport" "direct() returns the fetcher's error")
+          (t/is-eq (:code (get @errors "direct/coded")) (str "denied_" MASK)
+                   "direct() returns the fetcher's error, its code masked")
+          (t/is-eq (:plain @featured) "kind PLAINSETTING-q8w2e4r6" "a feature's name does not register its settings")
+          (t/is-eq (:token @featured) (str "token " MASK) "a sensitive setting inside a feature registers")
+          (t/is-eq (:record @featured) "record PLAINRECORD-t5r3e1w9" "a seeded record does not register")
+          (t/is-eq (:alias @featured) "alias PLAINALIAS-m2n4b6v8" "an entity setting does not register")
+          (let [explained (get @explains "ok/explain")
+                result (vs/getprop explained "result")]
+            (t/is-some result "the explain record should carry the result")
+            (t/is-eq (header (vs/getprop result "headers") "x-session-token") MASK "response token masked")))
+        (println (str "SKIP clean-no-credential-leaves-the-sdk: " NO-TARGET)))))
+
+  (t/run-check rec "clean-the-sweep-can-see-a-leak"
+    (fn []
+      (if-let [target (usable-op)]
+        (let [sinks (atom [])
+              sdk (make-sdk (nth SCENARIOS 1) sinks {"active" false})
+              err (drive sdk target (vs/jm) sinks)
+              ;; Explaining a failure must not cost it its error.
+              explained (drive (make-sdk (nth SCENARIOS 1) (atom []) {"active" false})
+                               target (vs/jm "explain" (vs/jm)) (atom []))]
+          (t/is-some err "the 404 scenario must throw")
+          (t/is-eq (ex-message explained) (ex-message err) "with clean off, explain lost the error")
+          (t/is-true (some (fn [s] (seq (leaks (:text s)))) @sinks)
+                     "with clean off, nothing showed the canary: the sweep is blind")
+          (when-not (:suppressed AUTH)
+            (let [text (pr-str (:spec (core/ex->sdk err)))]
+              (t/is-true (or (str/includes? text (:apikey CANARY))
+                             (str/includes? text (b64 (str (:apikey CANARY) ":" (:secret CANARY)))))
+                         "the raw spec should carry the credential when clean is off"))))
+        (println (str "SKIP clean-the-sweep-can-see-a-leak: " NO-TARGET)))))
+
+  (t/run-check rec "clean-a-registered-value-used-as-a-property-name"
+    (fn []
+      (let [cfg (core/make-clean-config (vs/jm "keys" "key,secret,token"))
+            ctx (atom {:options (vs/jm "__derived__" (vs/jm "clean" cfg))})]
+        (core/u-clean-add ctx "ZZVAL-abc123")
+        (core/u-clean-add ctx "ZZVAL-xyz789")
+        (let [out (core/u-clean ctx (vs/jm "ZZVAL-abc123" 1 "ZZVAL-xyz789" 2 "plain" 3))]
+          (t/is-eq (vs/getprop out MASK) 1 "a registered name is masked")
+          (t/is-eq (vs/getprop out (str MASK "#1")) 2 "a colliding masked name is numbered")
+          (t/is-eq (vs/getprop out "plain") 3 "a plain name is kept")
+          (t/is-nil (vs/getprop out "ZZVAL-abc123") "the registered name is gone")))))
+
+  (t/run-check rec "clean-add-sensitive-registers-every-scalar-under-a-sensitive-name"
+    (fn []
+      (let [cfg (core/make-clean-config (vs/jm "keys" "key,secret,token"))
+            ctx (atom {:options (vs/jm "__derived__" (vs/jm "clean" cfg))})
+            values (vs/getprop cfg "values")]
+        (core/u-clean-add-sensitive ctx (vs/jm "apikey" (vs/jm "value" "NESTED-SECRET-1")
+                                               "headers" (vs/jm "X-Api-Token" (vs/jt "LISTED-SECRET-2"))
+                                               "secret" 123456789
+                                               "name" "not-a-secret"))
+        (t/is-true (.contains ^java.util.List values "NESTED-SECRET-1") "nested under apikey")
+        (t/is-true (.contains ^java.util.List values "LISTED-SECRET-2") "listed under a token header")
+        (t/is-true (.contains ^java.util.List values "123456789") "a number, as its text")
+        (t/is-false (.contains ^java.util.List values "not-a-secret") "an ordinary name"))))
+  nil)
+`
+}
+
+
+function cljstr(s: string): string {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+
+export {
+  TestClean
+}

package/project/.sdk/src/cmp/clojure/Test_clojure.ts

@@ -7,6 +7,7 @@ import { cmp, each, File, Content, Folder, entityCollection } from '@voxgig/sdkg
 
 import { TestEntity } from './TestEntity_clojure'
 import { TestDirect } from './TestDirect_clojure'
+import { TestClean } from './TestClean_clojure'
 import { ReadmeExamplesTest } from './ReadmeExamplesTest_clojure'
 
 
@@ -54,6 +55,11 @@ const Test = cmp(function Test(props: any) {
         Content(`  nil)
 `)
       })
+
+      // The canary sweep, required by test_runner.clj as sdk.test.clean.
+      Folder({ name: 'test' }, () => {
+        TestClean({ target, entity })
+      })
     })
   })
 })

package/project/.sdk/src/cmp/clojure/fragment/Entity.fragment.clj

@@ -109,8 +109,15 @@
                                   (post-done)
                                   ((core/uget ctx :done) ctx))))))))))))))))
     (catch Throwable operr
-      ; #PreUnexpected-Hook
-      (throw operr))))
+      ;; What a hook throws here must not escape the cleaning below.
+      (let [err (try
+                  ; #PreUnexpected-Hook
+                  operr
+                  (catch Throwable hookerr hookerr))]
+        ;; An error a hook threw, SDK-shaped or not, never passed through
+        ;; make-error.
+        (core/clean-explain! ctx)
+        (throw (core/clean-throwable ctx err))))))
 
 ;; Streaming operation. Runs `action` (an op name, e.g. "list") through the
 ;; full pipeline and returns a LAZY SEQUENCE of result items, so the
@@ -152,12 +159,15 @@
                      (vs/islist item) (mapv unwrap (vec item))
                      :else item))
           ;; Inbound: prefer the streaming feature's iterator; else fall back
-          ;; to the materialised items so stream always yields.
-          raw (if (and result (fn? (core/oget result :stream)))
-                (vec ((core/oget result :stream)))
-                (let [rd (when result (core/oget result :resdata))]
-                  (cond (vs/islist rd) (vec rd) (nil? rd) [] :else [rd])))
-          items (mapv unwrap raw)]
+          ;; to the materialised items so stream always yields. Realised after
+          ;; run-op has returned, so what the stream throws is cleaned here.
+          items (try
+                  (mapv unwrap
+                        (if (and result (fn? (core/oget result :stream)))
+                          (vec ((core/oget result :stream)))
+                          (let [rd (when result (core/oget result :resdata))]
+                            (cond (vs/islist rd) (vec rd) (nil? rd) [] :else [rd]))))
+                  (catch Throwable e (throw (core/clean-throwable ctx e))))]
       ;; A lazy sequence that checks `signal` between yields.
       (letfn [(lz [xs] (lazy-seq
                          (when (and (seq xs) (not (signalled?)))

package/project/.sdk/src/cmp/cpp/PrepareAuth_cpp.ts

@@ -187,6 +187,9 @@ ${clear(spec.where, 6)}
       std::string b64 = authBase64(
         (apikey.is_string() ? apikey.as_string() : "") + ":" +
         (!noSecret && secret.is_string() ? secret.as_string() : ""));
+      // The joined, encoded pair is a wire form neither credential's own
+      // registration covers.
+      ctx->utility->cleanAdd(ctx, Value(b64));
       if (authPrefix.empty()) {
         map_put(headers, CRED_NAME, Value(b64));
       } else {