@voxgig/sdkgen 4.32.1 → 4.33.0

package/project/.sdk/tm/perl/utility/clean.pm

@@ -3,13 +3,357 @@
 use strict;
 use warnings;
 
+use File::Basename ();
+use Cwd ();
+use Scalar::Util ();
+use MIME::Base64 ();
+
+my $__dir;
+BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
+require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
+require(Cwd::abs_path("$__dir/../core/helpers.pm"));
+require(Cwd::abs_path("$__dir/../schema.pm"));
+
+# Everything that leaves the pipeline passes through clean: the error, the
+# explain record, the serialised context, and whatever a feature emits.
+# Two layers: every registered secret VALUE (and its encoded forms) is
+# replaced wherever it appears in a string, and every value under a
+# sensitive KEY name is masked whatever it holds. Inside the pipeline data
+# stays raw, so a hook can still read the header it must add to.
+package ProjectNameCleanSupport;
+
+my $MAXDEPTH = 32;
+my $CIRCULAR = '[circular]';
+
+# Marks a value the copy omits (a coderef), as ts omits `undefined`.
+my $DROP = \'drop';
+
+sub _dropped {
+  my ($v) = @_;
+  return ref $v && Scalar::Util::refaddr($v) == Scalar::Util::refaddr($DROP) ? 1 : 0;
+}
+
+sub normkey {
+  my ($key) = @_;
+  my $k = lc("$key");
+  $k =~ s/[-_]//g;
+  return $k;
+}
+
+sub splitkeys {
+  my ($keys) = @_;
+  return [] unless defined $keys && !ref $keys;
+  return [ grep { '' ne $_ } map { normkey($_) } split /\s*,\s*/, "$keys" ];
+}
+
+# The comma-separated literal values a caller registers; a list is taken
+# as-is for a caller that has one.
+sub splitvalues {
+  my ($values) = @_;
+  if (Voxgig::Struct::islist($values)) {
+    return [ grep { defined $_ && !ref $_ } @$values ];
+  }
+  return [] unless defined $values && !ref $values;
+  return [ grep { '' ne $_ } split /\s*,\s*/, "$values" ];
+}
+
+# The spec carries numbers as strings, so every target reads it alike.
+sub count {
+  my ($val, $dflt) = @_;
+  return $dflt unless defined $val && !ref $val && Scalar::Util::looks_like_number($val);
+  my $n = int($val);
+  return $n < 0 ? $dflt : $n;
+}
+
+# The derived block make_options builds; a context without options
+# (make_error is reached with a bare one) falls back to the schema
+# defaults, so nothing leaves raw for want of a constructor. A plain hash
+# stands in for a context before one exists (make_options).
+sub config {
+  my ($ctx) = @_;
+  my $opts = (defined $ctx && ref $ctx && (Scalar::Util::reftype($ctx) // '') eq 'HASH')
+    ? $ctx->{options} : undef;
+  my $derived = Voxgig::Struct::ismap($opts) ? $opts->{__derived__} : undef;
+  my $cfg = Voxgig::Struct::ismap($derived) ? $derived->{clean} : undef;
+  return $cfg if Voxgig::Struct::ismap($cfg) && Voxgig::Struct::islist($cfg->{values});
+  return make_config(ProjectNameSchema::optspec()->{clean});
+}
+
+sub make_config {
+  my ($cleanopts) = @_;
+  my $o = Voxgig::Struct::ismap($cleanopts) ? $cleanopts : {};
+  my $min = count($o->{min}, 4);
+  return {
+    'active' => ProjectNameHelpers::is_false($o->{active}) ? 0 : 1,
+    'keys' => splitkeys($o->{keys}),
+    'values' => [],
+    'mask' => (defined $o->{mask} && !ref $o->{mask}) ? "$o->{mask}" : '[redacted]',
+    'hint' => count($o->{hint}, 0),
+    'min' => ($min < 1 ? 1 : $min),
+  };
+}
+
+# encodeURIComponent, byte for byte: the form a query credential travels in.
+sub pct {
+  my ($value) = @_;
+  my $b = "$value";
+  utf8::encode($b) if utf8::is_utf8($b);
+  $b =~ s/([^A-Za-z0-9\-_.!~*'()])/sprintf('%%%02X', ord($1))/ge;
+  return $b;
+}
+
+# The JSON string escape, as a JSON dump would write the value.
+sub jsonesc {
+  my ($value) = @_;
+  my $s = "$value";
+  $s =~ s/\\/\\\\/g;
+  $s =~ s/"/\\"/g;
+  $s =~ s/\n/\\n/g;
+  $s =~ s/\r/\\r/g;
+  $s =~ s/\t/\\t/g;
+  $s =~ s/([\x00-\x1f])/sprintf('\\u%04x', ord($1))/ge;
+  return $s;
+}
+
+# The encoded forms a value travels in: Basic and Bearer both carry base64,
+# a query credential is percent-encoded, and a JSON dump escapes it.
+sub forms {
+  my ($value) = @_;
+  my @out = ("$value");
+  my $add = sub {
+    my ($s) = @_;
+    push @out, $s if defined $s && '' ne $s && !grep { $_ eq $s } @out;
+  };
+  my $b = "$value";
+  utf8::encode($b) if utf8::is_utf8($b);
+  $add->(MIME::Base64::encode_base64($b, ''));
+  $add->(pct($value));
+  $add->(jsonesc($value));
+  return @out;
+}
+
+# Register a secret value. Idempotent; shorter than `min` is not a secret
+# the SDK can mask without blanking ordinary text.
+sub add {
+  my ($ctx, $value) = @_;
+  my $cfg = config($ctx);
+  return unless defined $value && !ref $value && length("$value") >= $cfg->{min};
+  my $values = $cfg->{values};
+  my $changed = 0;
+  for my $form (forms($value)) {
+    next if length($form) < $cfg->{min} || grep { $_ eq $form } @$values;
+    push @$values, $form;
+    $changed = 1;
+  }
+  @$values = sort { length($b) <=> length($a) } @$values if $changed;
+  return;
+}
+
+sub mask_value {
+  my ($cfg, $value) = @_;
+  my $hint = $cfg->{hint};
+  return $cfg->{mask} . substr($value, -$hint) if $hint > 0 && length($value) > 2 * $hint;
+  return $cfg->{mask};
+}
+
+# The scalar comes back untouched when no value matches, so a number stays
+# a number.
+sub clean_string {
+  my ($cfg, $text) = @_;
+  my $out = $text;
+  my $hit = 0;
+  for my $value (@{ $cfg->{values} }) {
+    next if index("$out", $value) < 0;
+    my $masked = mask_value($cfg, $value);
+    my $q = quotemeta $value;
+    $out = "$out";
+    $out =~ s/$q/$masked/g;
+    $hit = 1;
+  }
+  return $hit ? $out : $text;
+}
+
+sub sensitive_key {
+  my ($cfg, $key) = @_;
+  return 0 unless defined $key && !ref $key;
+  my $nk = normkey($key);
+  for my $k (@{ $cfg->{keys} }) {
+    return 1 if index($nk, $k) >= 0;
+  }
+  return 0;
+}
+
+# A plain-data copy of what is about to leave: TO_JSON is honoured (an
+# entity gives its data, a context its record), coderefs are dropped,
+# cycles are cut, and no live object is shared with the copy - masking the
+# copy must never mask the pipeline's own spec. Any other blessed hash
+# copies as its fields; the error keeps its context out of them.
+sub snapshot {
+  my ($cfg, $val, $key, $depth, $seen) = @_;
+  return $val unless defined $val;
+
+  if (!ref $val) {
+    return sensitive_key($cfg, $key) ? mask_value($cfg, "$val") : clean_string($cfg, $val);
+  }
+
+  if (Voxgig::Struct::is_jbool($val) || Voxgig::Struct::is_jnull($val) || Voxgig::Struct::is_none($val)) {
+    return sensitive_key($cfg, $key) ? $cfg->{mask} : $val;
+  }
+
+  my $type = Scalar::Util::reftype($val) // '';
+  return $DROP unless 'HASH' eq $type || 'ARRAY' eq $type;
+
+  my $addr = Scalar::Util::refaddr($val);
+  return $CIRCULAR if $depth >= $MAXDEPTH || $seen->{$addr};
+  return $cfg->{mask} if sensitive_key($cfg, $key);
+
+  $seen->{$addr} = 1;
+  my $out;
+  if ('ARRAY' eq $type) {
+    $out = [];
+    for (my $i = 0; $i < @$val; $i++) {
+      my $v = snapshot($cfg, $val->[$i], "$i", $depth + 1, $seen);
+      push @$out, $v unless _dropped($v);
+    }
+  }
+  elsif (Scalar::Util::blessed($val) && $val->isa('ProjectNameError')) {
+    $out = plain($cfg, $val, $depth, $seen);
+    $out->{message} = clean_string($cfg, defined $val->{msg} ? "$val->{msg}" : '');
+  }
+  elsif (Scalar::Util::blessed($val) && $val->can('TO_JSON')) {
+    my $json = eval { $val->TO_JSON };
+    $out = $@ ? plain($cfg, $val, $depth, $seen) : snapshot($cfg, $json, $key, $depth + 1, $seen);
+  }
+  else {
+    $out = plain($cfg, $val, $depth, $seen);
+  }
+  delete $seen->{$addr};
+  return $out;
+}
+
+sub plain {
+  my ($cfg, $val, $depth, $seen) = @_;
+  my $out = {};
+  for my $k (sort keys %$val) {
+    my $v = snapshot($cfg, $val->{$k}, $k, $depth + 1, $seen);
+    $out->{ clean_name($cfg, $out, $k) } = $v unless _dropped($v);
+  }
+  return $out;
+}
+
+# A registered value used as a property name is masked like any other
+# string; names that mask alike take a counter, so none is lost. Callers
+# visit keys sorted, so the counters are stable.
+sub clean_name {
+  my ($cfg, $out, $key) = @_;
+  my $name = clean_string($cfg, $key);
+  return $name if $name eq $key || !exists $out->{$name};
+  my $i = 1;
+  $i++ while exists $out->{"$name#$i"};
+  return "$name#$i";
+}
+
+# Clean a value on its way out. A string is redacted; an SDK error is
+# redacted IN PLACE (it is about to be thrown, and its identity matters to
+# the caller); another blessed object is not this SDK's to rewrite and comes
+# back as it is; anything else comes back as a masked plain-data copy.
+sub clean {
+  my ($ctx, $val) = @_;
+  my $cfg = config($ctx);
+
+  return $val unless $cfg->{active};
+  return $val unless defined $val;
+  return clean_string($cfg, $val) unless ref $val;
+
+  if (Scalar::Util::blessed($val)) {
+    return $val unless $val->isa('ProjectNameError');
+    $val->{msg} = clean_string($cfg, "$val->{msg}") if defined $val->{msg};
+    for my $k (sort keys %$val) {
+      next if 'msg' eq $k;
+      my $v = $val->{$k};
+      if (defined $v && !ref $v) {
+        $v = sensitive_key($cfg, $k) ? mask_value($cfg, "$v") : clean_string($cfg, $v);
+      }
+      elsif (ref $v && (Scalar::Util::reftype($v) // '') =~ /\A(?:HASH|ARRAY)\z/) {
+        $v = snapshot($cfg, $v, $k, 1, {});
+      }
+      my $name = clean_string($cfg, $k);
+      delete $val->{$k} if $name ne $k;
+      $val->{ $name eq $k ? $k : clean_name($cfg, $val, $k) } = $v;
+    }
+    return $val;
+  }
+
+  my $out = snapshot($cfg, $val, undef, 0, {});
+  return _dropped($out) ? undef : $out;
+}
+
+# Every scalar under a sensitive name, at any depth and of any shape: a
+# credential mistyped as a map or a number is still a credential, and the
+# validation error that rejects it quotes it.
+sub add_sensitive {
+  my ($ctx, $val, $under, $depth, $seen) = @_;
+  $depth //= 0;
+  $seen //= {};
+  return if !defined $val || $depth >= $MAXDEPTH;
+  if (!ref $val) {
+    add($ctx, "$val") if $under;
+    return;
+  }
+  my $type = Scalar::Util::reftype($val) // '';
+  return unless 'HASH' eq $type || 'ARRAY' eq $type;
+  return if $seen->{ Scalar::Util::refaddr($val) }++;
+  if ('HASH' eq $type) {
+    add_sensitive($ctx, $val->{$_}, $under || key($ctx, $_), $depth + 1, $seen) for keys %$val;
+  }
+  else {
+    add_sensitive($ctx, $_, $under, $depth + 1, $seen) for @$val;
+  }
+  return;
+}
+
+# A feature's name is not a field name: only the sensitive names inside its
+# settings count, so `secrets` does not make every setting a secret. Entity
+# blocks (per-entity settings, seeded records) hold no credential.
+sub add_options {
+  my ($ctx, $opts) = @_;
+  my %scan = %$opts;
+  my $feature = delete $scan{feature};
+  delete $scan{entity};
+  $scan{test} = no_entity($scan{test}) if exists $scan{test};
+  add_sensitive($ctx, \%scan);
+  my @blocks = Voxgig::Struct::ismap($feature) ? values %$feature
+    : Voxgig::Struct::islist($feature) ? @$feature : ($feature);
+  add_sensitive($ctx, no_entity($_)) for @blocks;
+  return;
+}
+
+sub no_entity {
+  my ($block) = @_;
+  return $block unless Voxgig::Struct::ismap($block);
+  my %copy = %$block;
+  delete $copy{entity};
+  return \%copy;
+}
+
+# Is this key name sensitive under the context's clean configuration?
+sub key {
+  my ($ctx, $key) = @_;
+  return sensitive_key(config($ctx), $key);
+}
+
 package ProjectNameUtilities;
 
 our %REGISTRY;
 
 $REGISTRY{clean} = sub {
   my ($ctx, $val) = @_;
-  return $val;
+  return ProjectNameCleanSupport::clean($ctx, $val);
+};
+
+$REGISTRY{clean_add} = sub {
+  my ($ctx, $value) = @_;
+  return ProjectNameCleanSupport::add($ctx, $value);
 };
 
 1;

package/project/.sdk/tm/perl/utility/done.pm

@@ -5,6 +5,7 @@ use warnings;
 
 use File::Basename ();
 use Cwd ();
+use Scalar::Util ();
 
 my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
@@ -17,12 +18,7 @@ our %REGISTRY;
 
 $REGISTRY{done} = sub {
   my ($ctx) = @_;
-  my $ctrl = $ctx->{ctrl};
-  if ($ctrl->{explain}) {
-    $ctrl->{explain} = $ctx->{utility}{clean}->($ctx, $ctrl->{explain});
-    my $er = $ctrl->{explain}{result};
-    delete $er->{err} if Voxgig::Struct::ismap($er);
-  }
+  $REGISTRY{clean_explain}->($ctx);
   if ($ctx->{result} && $ctx->{result}{ok}) {
     return $ctx->{result}{resdata};
   }
@@ -31,4 +27,26 @@ $REGISTRY{done} = sub {
   return $ctx->{utility}{make_error}->($ctx, undef);
 };
 
+# The caller's own hash is the explain record (the control is built from it,
+# and a stream copies only its ctrl), so the cleaned copy is written back
+# INTO it: assigning a fresh hash would leave the caller holding the raw one.
+$REGISTRY{clean_explain} = sub {
+  my ($ctx) = @_;
+  my $explain = $ctx->{ctrl}{explain};
+  return unless Voxgig::Struct::ismap($explain);
+  my $cleaned = $ctx->{utility}{clean}->($ctx, $explain);
+  if (Voxgig::Struct::ismap($cleaned)
+    && Scalar::Util::refaddr($cleaned) != Scalar::Util::refaddr($explain)) {
+    %$explain = %$cleaned;
+  }
+  # A copy: with clean off, explain.result is the live result make_error reads.
+  my $er = $explain->{result};
+  if (Voxgig::Struct::ismap($er)) {
+    my %pruned = %$er;
+    delete $pruned{err};
+    $explain->{result} = \%pruned;
+  }
+  return;
+};
+
 1;

package/project/.sdk/tm/perl/utility/make_error.pm

@@ -13,6 +13,7 @@ require(Cwd::abs_path("$__dir/../core/context.pm"));
 require(Cwd::abs_path("$__dir/../core/operation.pm"));
 require(Cwd::abs_path("$__dir/../core/result.pm"));
 require(Cwd::abs_path("$__dir/../core/error.pm"));
+require(Cwd::abs_path("$__dir/clean.pm"));
 
 package ProjectNameUtilities;
 
@@ -33,11 +34,14 @@ $REGISTRY{make_error} = sub {
   $err = $result->{err} if !defined $err;
   $err = $ctx->make_error('unknown', 'unknown error') if !defined $err;
 
+  # A bare context (no client, no utility) still cleans, through the
+  # schema defaults.
+  my $clean = ($ctx->{utility} && $ctx->{utility}{clean}) || $REGISTRY{clean};
+
   my $errmsg = (Scalar::Util::blessed($err) && $err->isa('ProjectNameError'))
     ? $err->{msg} : "$err";
   $errmsg =~ s/\s+\z//;
-  my $msg = "ProjectNameSDK: $opname: $errmsg";
-  $msg = $ctx->{utility}{clean}->($ctx, $msg);
+  my $msg = $clean->($ctx, "ProjectNameSDK: $opname: $errmsg");
 
   $result->{err} = undef;
   my $spec = $ctx->{spec};
@@ -46,12 +50,21 @@ $REGISTRY{make_error} = sub {
     $ctx->{ctrl}{explain}{err} = { 'message' => $msg };
   }
 
+  # The context stays reachable for a debugger (`$err->ctx`) and is part of
+  # no dump of the error; result and spec are cleaned COPIES, so masking
+  # them never masks the pipeline's own objects.
   my $sdk_err = ProjectNameError->new('', $msg, $ctx);
-  $sdk_err->{result} = $ctx->{utility}{clean}->($ctx, $result);
-  $sdk_err->{spec} = $ctx->{utility}{clean}->($ctx, $spec);
+  $sdk_err->{result} = $clean->($ctx, $result);
+  $sdk_err->{spec} = $clean->($ctx, $spec);
   $sdk_err->{code} = $err->{code}
     if Scalar::Util::blessed($err) && $err->isa('ProjectNameError');
 
+  # Promote the HTTP status to the top level, so a consumer can branch on
+  # `$err->{status}` instead of reaching into `$err->{result}`.
+  $sdk_err->{status} = defined $result->{status} ? $result->{status} : -1;
+
+  $clean->($ctx, $sdk_err);
+
   $ctx->{ctrl}{err} = $sdk_err;
 
   # Fire PreUnexpected so observability features (metrics, telemetry, audit,

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -11,6 +11,7 @@ BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
 require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
 require(Cwd::abs_path("$__dir/../core/helpers.pm"));
 require(Cwd::abs_path("$__dir/../schema.pm"));
+require(Cwd::abs_path("$__dir/clean.pm"));
 
 package ProjectNameUtilities;
 
@@ -89,6 +90,27 @@ $REGISTRY{make_options} = sub {
   $opts = {} unless Voxgig::Struct::ismap($opts);
   delete $opts->{extend};
 
+  my $config = $ctx->{config} || {};
+  my $cfgopts = Voxgig::Struct::ismap($config->{options}) ? $config->{options} : {};
+
+  # The secret registry exists BEFORE validation, fed from the raw input, so
+  # the constructor's own rejection of a mistyped credential is clean too.
+  my $cleancfg = ProjectNameCleanSupport::make_config(Voxgig::Struct::merge([
+    {},
+    grep { Voxgig::Struct::ismap($_) }
+      (Voxgig::Struct::clone(ProjectNameSchema::optspec()->{clean}),
+        Voxgig::Struct::clone($cfgopts->{clean}), $opts->{clean}),
+  ]));
+  my $cleanctx = { 'options' => { '__derived__' => { 'clean' => $cleancfg } } };
+  my %rawscan = %$opts;
+  delete $rawscan{clean};
+  ProjectNameCleanSupport::add_options($cleanctx, \%rawscan);
+  for my $block ($cfgopts, $opts) {
+    for my $raw (@{ ProjectNameCleanSupport::splitvalues(ProjectNameHelpers::gpath($block, 'clean.values')) }) {
+      ProjectNameCleanSupport::add($cleanctx, $raw);
+    }
+  }
+
   # Feature add-order. options.feature may be given as an ordered ARRAY of
   # { name, active, ...opts } entries (the array position IS the order in
   # which features are added), or as a { name => {opts} } map. Normalize an
@@ -111,9 +133,6 @@ $REGISTRY{make_options} = sub {
     $opts->{feature} = \%fmap;
   }
 
-  my $config = $ctx->{config} || {};
-  my $cfgopts = Voxgig::Struct::ismap($config->{options}) ? $config->{options} : {};
-
   # THE OPTION SPEC IS GENERATED, NOT WRITTEN HERE.
   #
   # Built from the model: `main.kit.optspec` for the standard options, plus one
@@ -146,7 +165,10 @@ $REGISTRY{make_options} = sub {
   # TARGETS, so without this one client's options (headers, server, ...) are
   # written into the shared config and inherited by every client after it.
   my $merged = Voxgig::Struct::merge([{}, Voxgig::Struct::clone($cfgopts), $opts]);
-  my $validated = Voxgig::Struct::validate($merged, $optspec);
+  my $validated = eval { Voxgig::Struct::validate($merged, $optspec) };
+  if (my $verr = $@) {
+    die ProjectNameCleanSupport::clean($cleanctx, $verr);
+  }
   $opts = Voxgig::Struct::ismap($validated) ? $validated : {};
 
   # Restore the suppression the optspec default would otherwise erase.
@@ -162,15 +184,6 @@ $REGISTRY{make_options} = sub {
     $opts->{extend} = $extend_raw;
   }
 
-  my $clean_keys = ProjectNameHelpers::gpath($opts, 'clean.keys');
-  $clean_keys = 'key,token,id' unless defined $clean_keys && !ref $clean_keys;
-  my @parts;
-  for my $p (split /,/, $clean_keys) {
-    $p =~ s/^\s+|\s+$//g;
-    push @parts, Voxgig::Struct::escre($p) if '' ne $p;
-  }
-  my $keyre = join('|', @parts);
-
   # Resolve the feature add-order: an explicit array order (above) wins;
   # otherwise order the map test-first, then the remaining names sorted, so
   # the outcome is deterministic and `test` is always the base transport.
@@ -197,10 +210,16 @@ $REGISTRY{make_options} = sub {
   }
 
   $opts->{__derived__} = {
-    'clean' => ('' eq $keyre ? {} : { 'keyre' => $keyre }),
+    'clean' => $cleancfg,
     'featureorder' => \@featureorder,
   };
 
+  # Again over the merged result: the config's own defaults can carry one.
+  # The extend instances are live objects, not option data.
+  my %scan = %$opts;
+  delete @scan{qw(__derived__ extend clean)};
+  ProjectNameCleanSupport::add_options($cleanctx, \%scan);
+
   return $opts;
 };
 

package/project/.sdk/tm/php/core/Context.php

@@ -11,7 +11,7 @@ require_once __DIR__ . '/Response.php';
 require_once __DIR__ . '/Error.php';
 require_once __DIR__ . '/Helpers.php';
 
-class ProjectNameContext
+class ProjectNameContext implements \JsonSerializable
 {
     public string $id;
     public array $out;
@@ -149,4 +149,27 @@ class ProjectNameContext
     {
         return new ProjectNameError($code, $msg, $this);
     }
+
+    // The serialised context leaves the pipeline (a logger, a dump), so it
+    // is cleaned; the live fields stay raw for the pipeline's own use.
+    public function jsonSerialize(): mixed
+    {
+        $record = [
+            'id' => $this->id,
+            'op' => $this->op,
+            'spec' => $this->spec,
+            'entity' => $this->entity,
+            'result' => $this->result,
+            'response' => $this->response,
+            'meta' => $this->meta,
+        ];
+        $clean = null === $this->utility ? null : $this->utility->clean;
+        return is_callable($clean) ? $clean($this, $record) : $record;
+    }
+
+    public function __debugInfo(): array
+    {
+        $record = $this->jsonSerialize();
+        return is_array($record) ? $record : ['record' => $record];
+    }
 }

package/project/.sdk/tm/php/core/Error.php

@@ -3,13 +3,12 @@ declare(strict_types=1);
 
 // ProjectName SDK error
 
-class ProjectNameError extends \Exception
+class ProjectNameError extends \Exception implements \JsonSerializable
 {
     public bool $is_sdk_error;
     public string $sdk;
     public string $sdk_code;
     public string $msg;
-    public mixed $ctx;
     public mixed $result;
     public mixed $spec;
 
@@ -24,6 +23,12 @@ class ProjectNameError extends \Exception
     // same field; php needs it spelled out because the class is typed.
     public int $status;
 
+    // The context stays reachable for a debugger (`ctx()`) and out of every
+    // serialiser: print_r and json_encode take the record below, and
+    // var_export renders a closure as empty where a property would dump the
+    // context's whole object graph, options and credential included.
+    private ?\Closure $ctxref;
+
     public function __construct(string $code = '', string $msg = '', mixed $ctx = null)
     {
         parent::__construct($msg);
@@ -31,12 +36,19 @@ class ProjectNameError extends \Exception
         $this->sdk = 'ProjectName';
         $this->sdk_code = $code;
         $this->msg = $msg;
-        $this->ctx = $ctx;
+        $this->ctxref = null === $ctx ? null : static function () use ($ctx): mixed {
+            return $ctx;
+        };
         $this->result = null;
         $this->spec = null;
         $this->status = -1;
     }
 
+    public function ctx(): mixed
+    {
+        return null === $this->ctxref ? null : ($this->ctxref)();
+    }
+
     public function error(): string
     {
         return $this->msg;
@@ -46,4 +58,23 @@ class ProjectNameError extends \Exception
     {
         return $this->msg;
     }
+
+    // What make_error attached is already cleaned; the context is not part
+    // of the record.
+    public function jsonSerialize(): array
+    {
+        return [
+            'sdk' => $this->sdk,
+            'code' => $this->sdk_code,
+            'message' => $this->getMessage(),
+            'status' => $this->status,
+            'result' => $this->result,
+            'spec' => $this->spec,
+        ];
+    }
+
+    public function __debugInfo(): array
+    {
+        return $this->jsonSerialize();
+    }
 }

package/project/.sdk/tm/php/core/UtilityType.php

@@ -6,6 +6,8 @@ declare(strict_types=1);
 class ProjectNameUtility
 {
     public mixed $clean = null;
+    public mixed $clean_add = null;
+    public mixed $clean_explain = null;
     public mixed $done = null;
     public mixed $make_error = null;
     public mixed $feature_add = null;
@@ -57,6 +59,8 @@ class ProjectNameUtility
     {
         $u = new ProjectNameUtility();
         $u->clean = $src->clean;
+        $u->clean_add = $src->clean_add;
+        $u->clean_explain = $src->clean_explain;
         $u->done = $src->done;
         $u->make_error = $src->make_error;
         $u->feature_add = $src->feature_add;

package/project/.sdk/tm/php/feature/AuditFeature.php

@@ -86,7 +86,7 @@ class ProjectNameAuditFeature extends ProjectNameBaseFeature
             : ($this->options['actor'] ?? null);
         $actor = (is_string($actor) && $actor !== '') ? $actor : 'anonymous';
 
-        $record = [
+        $record = ($ctx->utility->clean)($ctx, [
             'seq' => $this->seq,
             'ts' => $this->_now(),
             'actor' => $actor,
@@ -95,7 +95,7 @@ class ProjectNameAuditFeature extends ProjectNameBaseFeature
             'outcome' => $outcome,
             'status' => $ctx->result !== null ? $ctx->result->status : null,
             'correlationId' => $ctx->id,
-        ];
+        ]);
 
         $client = $this->client;
         $client->_audit['records'][] = $record;