String/Redactable.pm

filter: Statementstmt 87.2% 48 / 55 Branchbran 75.0% 3 / 4 Conditioncond 66.6% 2 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 61.9% 13 / 21 Podpod 100% 5 / 5 totaltotal 78.8% 71 / 90 CC 6 SCAR 5.9
CC
6
Cov
85%
new
4.2
__ANON__
2.0
__ANON__
2.0
CRAP 1.8
↑ Summary Tie/String/Redactable.pm »
1 6 ▶use v5.20;
Subroutine BEGIN: called CC=1 SCAR=0.0
2 6 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 package String::Redactable;
5 6 ▶use experimental qw(signatures);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 6 ▶use warnings::register;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 6 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 6 ▶use Encode ();
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 6 our $VERSION = '1.088';
12  
13 =encoding utf8
14  
15 =head1 NAME
16  
17 String::Redactable - A string that automatically redacts itself
18  
19 =head1 SYNOPSIS
20  
21 use String::Redactable;
22  
23 my $string = String::Redactable->new( $sensitive_text );
24  
25 say $string; # '<redacted string>'
26 say $string->to_str_unsafe; # unredacted text
27  
28 =head1 DESCRIPTION
29  
30 C<String::Redactable> tries to prevent you from accidentally exposing
31 a sensitive string, such as a password, in a larger string, such as a
32 log message or data dump.
33  
34 When you carelessly use this as a simple string, you get back the
35 literal string C<*redacted data*>. To get the actual string, you call
36 C<to_str_unsafe>:
37  
38 $password->to_str_unsafe;
39  
40 This is not designed to completely protect the sensitive data from
41 prying eyes. This is simply the UTF-8 encoded version of the value that
42 is XOR-ed by an object-specific key that is not stored with the object.
43 All of that is undone by C<to_str_unsafe>.
44  
45 Beyond that, this module uses L<overload> and other tricks to prevent
46 the actual string from showing up in output and other strings.
47  
48 =head2 Notes on serializers
49  
50 C<String::Redactable> objects resist serialization to the best of
51 their ability. At worst, the serialization shows the internal string
52 for the object, which does not expose the key used to XOR the UTF-8
53 encoded string.
54  
55 Since the XOR keys are not stored in the object (and those keys are
56 removed when the object goes out of scope), these values cannot be
57 serialized and re-inflated. But, that's what you want.
58  
59 =over 4
60  
61 =item * L<Data::Dumper> - cannot use C<$Data::Dump::Freezer> because that
62 requires the
63  
64 =item * L<Storable> -
65  
66 =item * JSON modules - this supports C<TO_JSON>
67  
68 =item * YAML -
69  
70  
71 =back
72  
73 =head2 Methods
74  
75 =over 4
76  
77 =item new
78  
79 =cut
80  
81 use overload
82 24 ▶ q("") => sub { $_[0]->placeholder },
Subroutine BEGIN: called CC=1 SCAR=0.5
Subroutine __ANON__: called CC=1 SCAR=0.0
83 0 ▶ '0+' => sub { 0 },
Subroutine __ANON__: not called CC=1 SCAR=6.9
84 0 ▶ '-X' => sub { () },
Subroutine __ANON__: not called CC=1 SCAR=6.9
85  
86 0 ▶ map { $_ => sub { () } } qw(
Subroutine __ANON__: not called CC=1 SCAR=0.4
87 <=> cmp
88 lt le gt ge eq ne
89 ~~
90 )
91 6 ;
92  
93 6 my %keys = ();
94  
95 8 ▶my $new_key = sub ($class, $length = 512) {
Subroutine __ANON__: called CC=2 SCAR=6.9
96 8 state $rc = require List::Util;
97 substr(
98 join( '',
99 List::Util::shuffle(
100 8 map { List::Util::shuffle( 'A' .. 'Z', 'a' .. 'z', qw(= ! : ;) ) } 1 .. 25
101 )
102 ),
103 0, $length
104 )
105 ;
106 6 };
107  
108 =item new( STRING )
109  
110 Creates an object that hides that string by XOR-ing it with another string that
111 is not stored in the object, and is not a package variable.
112  
113 This does not mean that the original string can't be recovered in other ways if
114 someone wanted to try hard enough, but it keeps you from unintentionally dumping
115 it into output where it shouldn't be.
116  
117 =cut
118  
119 10 ▶sub new ($class, $string, $opts={}) {
Subroutine new: called CC=4 SCAR=14.4
Pod documented
120 10 ▶ unless( length $string ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (length $string) 0 10 10
121 0 carp sprintf "Argument to %s::new is zero length", __PACKAGE__;
122 0 return;
123 }
124  
125 10 ▶ my $key = $opts->{'key'} // $new_key->( 5 * length $string );
Condition66%2/3
$opts->{"key"} // &$new_key(5 * length($string))
l!l&&r!l&&!r
280
MC/DC0%0/2
$opts->{"key"} // &$new_key(5 * length($string))
$opts->{"key"} &$new_key(5 * length($string))
Truth table66%2/3
A // B
A= $opts->{"key"}B= &$new_key(5 * length($string))
ABresult
1X1
011
000
126  
127 10 my $encoded = Encode::encode( 'UTF-8', $string );
128 10 my $hidden = ($encoded ^ $key);
129 10 my $self = bless \$hidden, $class;
130 10 ▶ { local $SIG{__WARN__} = sub {}; $keys{overload::StrVal($self)} = $key };
Subroutine __ANON__: not called CC=1 SCAR=0.0
131 10 $self;
132 }
133  
134 10 ▶sub DESTROY ($self) {
Subroutine DESTROY: called CC=1 SCAR=0.0
135 10 ▶ local $SIG{__WARN__} = sub {};
Subroutine __ANON__: not called CC=1 SCAR=0.0
136 10 delete $keys{overload::StrVal($self)};
137 }
138  
139 =item placeholder
140  
141 The value that is substituted for the actual string.
142  
143 =cut
144  
145 54 ▶sub placeholder ( $class ) {
Subroutine placeholder: called CC=2 SCAR=6.9
Pod documented
146 54 state $rc = require Carp;
147 54 ▶ Carp::cluck(
Branch: 1 branch
BranchTrueFalseTotal
if warnings::enabled() 36 18 54
148 "Possible unintended interpolation of a redactable string",
149 ) if warnings::enabled();
150 54 '<redacted data>'
151 }
152  
153 =item STORABLE_freeze
154  
155 Redact strings used in L<Storable>.
156  
157 =cut
158  
159 0 ▶sub STORABLE_freeze ($self, $cloning) {
Subroutine STORABLE_freeze: not called CC=1 SCAR=6.9
Pod documented
160 0 $self->placeholder;
161 }
162  
163 =item TO_JSON
164  
165 Redact the string in serializers that respect C<TO_JSON>.
166  
167 =cut
168  
169 0 ▶sub TO_JSON {
Subroutine TO_JSON: not called CC=1 SCAR=6.9
Pod documented
170 0 $_[0]->placeholder;
171 }
172  
173 =item to_str_unsafe
174  
175 Returns the string that you are trying to hide.
176  
177 =cut
178  
179 12 ▶sub to_str_unsafe ($self) {
Subroutine to_str_unsafe: called CC=1 SCAR=0.0
Pod documented
180 12 ▶ local $SIG{__WARN__} = sub {};
Subroutine __ANON__: not called CC=1 SCAR=0.0
181 12 my $encoded = ($$self ^ $keys{overload::StrVal($self)}) =~ s/\000+\z//r;
182 12 Encode::decode( 'UTF-8', $encoded );
183 }
184  
185 =back
186  
187 =head1 TO DO
188  
189  
190 =head1 SEE ALSO
191  
192  
193 =head1 SOURCE AVAILABILITY
194  
195 This source is on Github:
196  
197 http://github.com/briandfoy/string-redactable
198  
199 =head1 AUTHOR
200  
201 brian d foy, C<< <briandfoy@pobox.com> >>
202  
203 =head1 COPYRIGHT AND LICENSE
204  
205 Copyright © 2025-2026, brian d foy, All Rights Reserved.
206  
207 You may redistribute this under the terms of the Artistic License 2.0.
208  
209 =cut
210  
211 6 __PACKAGE__;
↑ Summary Tie/String/Redactable.pm »