I agree with Tanktalus' comments. I wanted to read the code but it is quite hard to find the code with the POD all mixed up with it. Please consider making the code easier to read and the POD easier to read (and both easier to maintain) by keeping them separate.

I would rename the get() method to something very distinctive. It would be useful to be able to search for all instances of, for example, unhide_string() to audit the places where the sensitive data is being exposed to ensure they are all appropriate.

I can see the motivation for auto_get() but I also don't think it will be enough of a solution.

I'd probably go for a more direct approach at preventing specific leakage. The first thing is to prevent the sensitive string from being logged.

So provide a class that you can tie the log file handle to such that any uses of the file handle set a global "unsecure" flag:

sub Text::Hidden::Handle::PRINT {
    local( $Text::Hidden::SECURE ) = 0;
    ...
}

sub Text::Hidden::as_string {
    my( $self ) = @_;
    return $self->{value}
        if  $SECURE;
    return $self->get_obscured_value();
}
[download]

Another place you don't want to leak such information is into a database. I'd be tempted to walk caller() information looking for DBI or DBD::* modules, though I somewhat worry about the efficiency of that. Perhaps one only need walk a couple of levels up for such a check, though.

So, there will be some situations where you can unhide the sensitive string only a couple of places where it is actually used. There will be other situations where the value is used in in a bunch of code, some of which you have no control over and you just want to identify the few places where information can escape the process and block those exits. auto_get() may be sufficient for many of these second cases but I also think it will be harder to get working that way.

And that last point means that you should provide a debug option that logs the places where the string value was asked for and whether a hidden or unhidden version was provided.

Pod moved. I can agree that a grepable accessor name is a good idea.

auto_get does already support code references for the purpose of walking the stack looking for specific things. I imagine a ::Util package with some convenience functions for building such callbacks would be possible - along with some tweaks to the implementation to make subclassing and/or applying roles easier (to permit Text::Hidden::HideFrom::DBI)

The major take-home that I am getting from the tied filehandle and DBD/DBI examples is that I should not completely abandon the "Default Allow" camp... I think I could get the "unsecure" filehandles, ::HideFrom::* roles, and auto_get lists to work together in a secure and predictable fashion. Am I properly interpreting your suggestions?

Note: The debug option is currently spelled "cluck => 1" but does currently lack a note specifying whether the string was or was not unmasked. I agree that "debug" is probably a better name.

Thank you for your comments... I guess I will have to clean this up and upload it now.

Good Day,
    Dean

Revised the synopsis in the original post (well... now it is entering into tutorial territory)

I don't see how a tied filehandle with a default unhidden policy is going to be a good idea at all. Consider:

open my $LOG, ">", "/var/log/my_app.log";
tie $LOG, "Text::Hidden::Handle", force => "hidden";

my $ccn = Text::Hidden->new( "1234567887654321", default => "unhidden"
+ );

print $LOG $ccn;              # OK
print $LOG "Got CCN: $ccn";   # Oops! - premature stringification
[download]

Sure, interpolating a default unhidden string is always going to be "dangerous", but the fragility near a filehandle that pretends to force the values to hidden seems too far over the top. Unless I misunderstood your suggestions.

I have however, added default unhidden and hide_from options as well as manual mask forcing. Additionally, I have added localized policy setting so that one need not globally choose default unhidden (see examples in OP). Do you think that the revised synopsis addresses your concerns / describes a potentially usable tool?

Good Day,
    Dean

That's part of why you should write your logs in JSON format! But, yes, excellent point.

I wonder if overload.pm can cause "foo $bar" to return an overload'ed object since it should compile down to "foo " . $bar and you should be able to overload concatenation. If so, then it could return an object that stringifies to "foo XXXXX" somewhere inside of 'print'.

Sorry, I can't take the time to test that at the moment.

- tye