@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/perl/feature/secrets/plugins/Voxgig/Sekreto/Plugins/Onepassword.pm

@@ -0,0 +1,132 @@
+# VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (perl/plugins/Voxgig/Sekreto/Plugins/Onepassword.pm)
+# Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package Voxgig::Sekreto::Plugins::Onepassword;
+
+# The onepassword plugin: 1Password through a Connect server.
+#
+# NOT IN THE CORE. A `Sekreto` can build this kind only if the calling
+# project passed this definition in through the `plugins` option; the
+# core loads nothing under `plugins/` (docs/design/plugin-providers.md).
+#
+# A port of typescript/plugins/onepassword.ts, which is canonical.
+
+use strict;
+use warnings;
+
+use Exporter 'import';
+
+use Voxgig::Sekreto ();
+use Voxgig::Sekreto::Providers qw(providerplugin);
+use Voxgig::Sekreto::Addr ();
+use Voxgig::Sekreto::Plugins::Httpjson ();
+
+our @EXPORT_OK = qw(onepassword);
+
+# 1Password, through a Connect server.
+#
+# The item titled `api.token` (titles keep their dots), in the named
+# vault. The value is the field with purpose PASSWORD, or the field
+# labelled `value`. A vault that cannot be found is an error - config
+# names it, so its absence is a broken store, not a missing secret.
+{
+
+    package Voxgig::Sekreto::Plugins::Onepassword::Provider;
+
+    sub new {
+        my ( $class, $opts ) = @_;
+        return bless { opts => $opts || {}, vaultid => undef }, $class;
+    }
+
+    sub authheaders {
+        my ($self) = @_;
+        return { 'authorization' => 'Bearer ' . ( $self->{opts}{token} || '' ) };
+    }
+
+    sub resolvevault {
+        my ( $self, $addr ) = @_;
+
+        my $want = $self->{opts}{vault} || '';
+        Voxgig::Sekreto::fail('sekreto: onepassword: no vault') if '' eq $want;
+
+        my ( $status, $body ) = Voxgig::Sekreto::Plugins::Httpjson::fetchjson( 'GET',
+            $addr . '/v1/vaults', $self->authheaders() );
+
+        Voxgig::Sekreto::fail(
+            'sekreto: onepassword error: ' . $status . ': listing vaults')
+          if 200 != $status || 'ARRAY' ne ref( $body || '' );
+
+        for my $entry (@$body) {
+            next if 'HASH' ne ref( $entry || '' );
+            return Voxgig::Sekreto::Plugins::Httpjson::stringof( $entry->{id} )
+              if ( defined $entry->{id} && !ref( $entry->{id} ) && $want eq $entry->{id} )
+              || ( defined $entry->{name} && !ref( $entry->{name} ) && $want eq $entry->{name} );
+        }
+
+        Voxgig::Sekreto::fail( 'sekreto: onepassword: no vault named ' . $want );
+    }
+
+    sub lookup {
+        my ( $self, $name ) = @_;
+
+        Voxgig::Sekreto::checkname($name);
+
+        ( my $addr = $self->{opts}{addr} || '' ) =~ s{/$}{};
+        Voxgig::Sekreto::fail('sekreto: onepassword: no addr') if '' eq $addr;
+        Voxgig::Sekreto::Addr::checkaddr($addr);
+
+        $self->{vaultid} = $self->resolvevault($addr) if !defined $self->{vaultid};
+
+        my $filter = Voxgig::Sekreto::Plugins::Httpjson::urlenc( 'title eq "' . $name . '"' );
+        my ( $status, $found ) = Voxgig::Sekreto::Plugins::Httpjson::fetchjson( 'GET',
+            $addr . '/v1/vaults/' . $self->{vaultid} . '/items?filter=' . $filter,
+            $self->authheaders() );
+
+        Voxgig::Sekreto::fail(
+            'sekreto: onepassword error: ' . $status . ': finding ' . $name )
+          if 200 != $status || 'ARRAY' ne ref( $found || '' );
+
+        return undef if 0 == scalar(@$found);
+
+        my ( $itemstatus, $item ) = Voxgig::Sekreto::Plugins::Httpjson::fetchjson( 'GET',
+            $addr . '/v1/vaults/' . $self->{vaultid} . '/items/' . $found->[0]{id},
+            $self->authheaders() );
+
+        Voxgig::Sekreto::fail(
+            'sekreto: onepassword error: ' . $itemstatus . ': reading ' . $name )
+          if 200 != $itemstatus;
+
+        my $fields =
+          ( 'HASH' eq ref( $item || '' ) && 'ARRAY' eq ref( $item->{fields} || '' ) )
+          ? $item->{fields}
+          : [];
+
+        for my $field (@$fields) {
+            next if 'HASH' ne ref( $field || '' );
+            return Voxgig::Sekreto::Plugins::Httpjson::stringof( $field->{value} )
+              if defined $field->{purpose} && 'PASSWORD' eq $field->{purpose};
+        }
+        for my $field (@$fields) {
+            next if 'HASH' ne ref( $field || '' );
+            return Voxgig::Sekreto::Plugins::Httpjson::stringof( $field->{value} )
+              if defined $field->{label} && 'value' eq $field->{label};
+        }
+
+        return undef;
+    }
+
+    sub describe {
+        my ($self) = @_;
+        return 'onepassword:' . ( $self->{opts}{vault} || '' );
+    }
+}
+
+
+# The plugin: the `onepassword` provider kind, as a voxgig/plugin
+# definition.
+sub onepassword {
+    return providerplugin( 'onepassword',
+        sub { Voxgig::Sekreto::Plugins::Onepassword::Provider->new( $_[0] ) } );
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugins/Voxgig/Sekreto/Plugins/Proc.pm

@@ -0,0 +1,102 @@
+# VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (perl/plugins/Voxgig/Sekreto/Plugins/Proc.pm)
+# Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package Voxgig::Sekreto::Plugins::Proc;
+
+# The child-process half of the two plugins that read a store through its
+# own CLI - boru and secretspec - in one place and OUTSIDE the core: a
+# chain of built-ins never loads IPC::Open3.
+#
+# The canonical port has no module of this shape because node's
+# `spawnSync` needs no wrapper; perl's open3 does, and duplicating seventy
+# lines of it in two plugins would be two places for a deadlock to hide.
+
+use strict;
+use warnings;
+
+use Exporter 'import';
+
+use IO::Select ();
+use IPC::Open3 ();
+use Symbol     ();
+
+our @EXPORT_OK = qw(runcmd);
+
+# Voxgig::Sekreto is loaded by every consumer of this module, and the
+# failure path is called by name rather than imported so that nothing here
+# has to care which of the two was loaded first.
+sub fail { return Voxgig::Sekreto::fail(@_) }
+
+# Run a command, returning (stdout, stderr, exit status).
+#
+# open3 rather than backticks: the argument list is passed through without a
+# shell, so an alias never gets word-split or interpreted, and stderr is
+# captured separately from the secret on stdout.
+sub runcmd {
+    my (@argv) = @_;
+
+    my ( $in, $out );
+    my $err = Symbol::gensym();
+
+    my $pid = eval { IPC::Open3::open3( $in, $out, $err, @argv ) };
+
+    fail( 'sekreto: cannot run ' . $argv[0] . ': ' . $@ ) if !$pid;
+
+    # The child's stdin is closed rather than left open on a pipe nobody
+    # writes to, so a CLI that reads it - one prompting for a passphrase when
+    # its environment variable is absent - sees EOF and gives up instead of
+    # waiting forever.
+    close($in);
+
+    # Both streams are drained TOGETHER. Reading stdout to EOF and only then
+    # reading stderr deadlocks the moment the child writes more than one pipe
+    # buffer (64 KiB on Linux) to stderr: this process is blocked waiting for
+    # stdout, the child is blocked waiting for room on stderr, and neither can
+    # move. Nothing in this library sets a timeout, so that hang is permanent.
+    # secretspec's diagnostics are box-drawn and reach that size easily.
+    my $sel = IO::Select->new( $out, $err );
+    my %text = ( fileno($out) => '', fileno($err) => '' );
+
+    while ( my @ready = $sel->can_read ) {
+        for my $handle (@ready) {
+            my $chunk = '';
+            my $got = sysread( $handle, $chunk, 65536 );
+            if ( !defined $got || 0 == $got ) {
+                $sel->remove($handle);
+                next;
+            }
+            $text{ fileno($handle) } .= $chunk;
+        }
+    }
+
+    my $outtext = $text{ fileno($out) };
+    my $errtext = $text{ fileno($err) };
+
+    close($out);
+    close($err);
+
+    waitpid( $pid, 0 );
+
+    # $? packs the exit code in the HIGH byte and the killing signal in the
+    # low one, so `$? >> 8` alone reads a signal-killed child as exit 0 - and
+    # the caller then returns its empty stdout as the secret, discarding
+    # whatever the child managed to say on stderr. A boru that printed
+    # "vault sealed" and was then OOM-killed handed the application '' as a
+    # live credential.
+    #
+    # A child that died from a signal did not answer. Reported as the shells
+    # do, 128 + the signal, so it is non-zero and distinguishable. waitpid
+    # failure leaves $? at -1, whose low bits are 127, which is also non-zero
+    # - the safe direction.
+    my $raw    = $?;
+    my $status = ( $raw & 127 ) ? 128 + ( $raw & 127 ) : ( $raw >> 8 );
+
+    return (
+        defined $outtext ? $outtext : '',
+        defined $errtext ? $errtext : '',
+        $status,
+    );
+}
+
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugins/Voxgig/Sekreto/Plugins/Secretspec.pm

@@ -0,0 +1,132 @@
+# VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (perl/plugins/Voxgig/Sekreto/Plugins/Secretspec.pm)
+# Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package Voxgig::Sekreto::Plugins::Secretspec;
+
+# The secretspec plugin: SecretSpec (https://secretspec.dev) through its
+# CLI.
+#
+# NOT IN THE CORE. A `Sekreto` can build this kind only if the calling
+# project passed this definition in through the `plugins` option; the
+# core loads nothing under `plugins/` (docs/design/plugin-providers.md).
+#
+# A port of typescript/plugins/secretspec.ts, which is canonical.
+
+use strict;
+use warnings;
+
+use Exporter 'import';
+
+use Voxgig::Sekreto ();
+use Voxgig::Sekreto::Providers qw(providerplugin);
+use Voxgig::Sekreto::Plugins::Proc ();
+
+our @EXPORT_OK = qw(secretspec);
+
+# Does this SecretSpec failure mean "no such secret" rather than "I could
+# not answer"?
+#
+# SecretSpec says `Secret 'API_TOKEN' not found` for both a name it does not
+# declare and one declared with no value, and both are misses: this store
+# does not hold it, so the chain carries on.
+#
+# MATCHED ON THE WHOLE PHRASE, NOT ON "not found". SecretSpec also says
+# `Provider backend 'keyring' not found`, which is a store that could not
+# answer at all - and reading that as a miss is the worst failure this
+# library has, because the chain then falls through to a weaker store
+# without saying so. The key is required to appear, so the two cannot be
+# confused.
+sub secretspecmiss {
+    my ( $why, $key ) = @_;
+    return index( $why, "Secret '" . $key . "' not found" ) >= 0 ? 1 : 0;
+}
+
+# SecretSpec (https://secretspec.dev).
+#
+# SecretSpec is a declaration - a `secretspec.toml` naming the secrets a
+# project needs - plus a chain of its own backends to satisfy them from.
+# That makes it the same shape as sekreto one level down, and the reason to
+# support it is the same reason sekreto exists: a project that has already
+# declared its secrets there should not have to declare them again here.
+#
+# Read through its CLI, as boru is, because that is the interface it offers
+# a program in another language: `secretspec get API_TOKEN` prints the value
+# on stdout and nothing else. A sekreto name maps to a SecretSpec key
+# exactly as it maps to an environment variable - `api.token` is
+# `API_TOKEN` - which is the convention SecretSpec's own examples use.
+#
+# `backend` selects one of SecretSpec's backends (`--provider`, e.g.
+# `keyring` or `dotenv://.env`) and is called `backend` here only because
+# `provider` already means something else in this library.
+#
+# A reason is required, not optional: SecretSpec records every read in an
+# audit log and refuses to read at all without one. sekreto sends `sekreto`
+# unless told otherwise, so the audit trail says which tool asked.
+{
+
+    package Voxgig::Sekreto::Plugins::Secretspec::Provider;
+
+    sub new {
+        my ( $class, $command, $file, $profile, $backend, $reason, $prefix ) = @_;
+        return bless {
+            command => $command || 'secretspec',
+            file    => $file,
+            profile => $profile,
+            backend => $backend,
+            reason  => $reason,
+            prefix  => $prefix,
+        }, $class;
+    }
+
+    sub lookup {
+        my ( $self, $name ) = @_;
+
+        my $key = Voxgig::Sekreto::envkey( $name, $self->{prefix} );
+
+        my @args;
+        push @args, '--file', $self->{file} if $self->{file};
+        push @args, 'get', $key;
+        push @args, '--provider', $self->{backend} if $self->{backend};
+        push @args, '--profile', $self->{profile} if $self->{profile};
+        push @args, '--reason', ( $self->{reason} || 'sekreto' );
+
+        my ( $out, $err, $status ) =
+          Voxgig::Sekreto::Plugins::Proc::runcmd( $self->{command}, @args );
+
+        if ( 0 == $status ) {
+            # The value and one newline, and nothing else.
+            $out =~ s/\n\z//;
+            return $out;
+        }
+
+        $err =~ s/^\s+|\s+$//g;
+
+        return undef if Voxgig::Sekreto::Plugins::Secretspec::secretspecmiss( $err, $key );
+
+        Voxgig::Sekreto::fail(
+            'sekreto: secretspec error: ' . ( '' eq $err ? 'exit ' . $status : $err ) );
+    }
+
+    sub describe {
+        my ($self) = @_;
+        return 'secretspec' . ( $self->{backend} ? ':' . $self->{backend} : '' );
+    }
+}
+
+
+# The plugin: the `secretspec` provider kind, as a voxgig/plugin
+# definition.
+sub secretspec {
+    return providerplugin(
+        'secretspec',
+        sub {
+            my ($spec) = @_;
+            return Voxgig::Sekreto::Plugins::Secretspec::Provider->new(
+                $spec->{command}, $spec->{file},   $spec->{profile},
+                $spec->{backend}, $spec->{reason}, $spec->{prefix}
+            );
+        }
+    );
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/plugins/Voxgig/Sekreto/Plugins/Sigv4.pm

@@ -0,0 +1,190 @@
+# VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (perl/plugins/Voxgig/Sekreto/Plugins/Sigv4.pm)
+# Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package Voxgig::Sekreto::Plugins::Sigv4;
+
+# AWS Signature Version 4, hand-rolled.
+#
+# UNDER plugins/, WITH THE AWS PLUGIN, and not in the core: this is the
+# sharpest instance of the line the split draws, because signing is the one
+# thing here that needs a hash function, and the core of no port imports
+# one. Only `awssecrets` and `awsparams` use it
+# (docs/design/plugin-providers.md).
+#
+# The AWS providers need exactly one thing from the AWS SDK - request
+# signing - and taking the SDK for it would break the no-dependency rule
+# that keeps ten ports honest. SigV4 is a stable, published algorithm
+# built from HMAC-SHA256, which Digest::SHA (core Perl) already has.
+#
+# `sigv4` is pure: the caller passes the timestamp, so the same input
+# yields the same signature everywhere. That is what lets the shared spec
+# carry known-answer cases that all ten ports must reproduce bit-for-bit,
+# and lets the integration mock recompute the signature server-side.
+#
+# A port of typescript/plugins/sigv4.ts, which is canonical.
+
+use strict;
+use warnings;
+
+use Digest::SHA ();
+
+use Exporter 'import';
+
+our @EXPORT_OK = qw(sigv4 uriescape);
+
+sub sha256hex {
+    my ($text) = @_;
+    utf8::encode($text) if utf8::is_utf8($text);
+    return Digest::SHA::sha256_hex($text);
+}
+
+# Digest::SHA takes (data, key); the callers here say (key, data), the
+# way every SigV4 description writes the key chain, so the flip is done
+# once, in one place.
+sub hmac {
+    my ( $key, $text ) = @_;
+    utf8::encode($text) if utf8::is_utf8($text);
+    return Digest::SHA::hmac_sha256( $text, $key );
+}
+
+sub hmachex {
+    my ( $key, $text ) = @_;
+    utf8::encode($text) if utf8::is_utf8($text);
+    return Digest::SHA::hmac_sha256_hex( $text, $key );
+}
+
+# RFC 3986 escaping, which is stricter than most languages' default
+# URL-encoding: uppercase hex, and everything outside the unreserved
+# characters (ALPHA / DIGIT / '-' / '.' / '_' / '~') is escaped - AWS
+# wants `!`, `'`, `(`, `)` and `*` escaped too.
+#
+# Httpjson's `urlenc` has the same body and is deliberately not this
+# function: this one is part of a signature the spec pins, and depending on
+# it made every store client load a hash function to escape a URL.
+sub uriescape {
+    my ($text) = @_;
+    utf8::encode($text) if utf8::is_utf8($text);
+    $text =~ s/([^A-Za-z0-9\-._~])/sprintf( '%%%02X', ord($1) )/ge;
+    return $text;
+}
+
+# Undo percent-encoding, byte by byte.
+sub uridecode {
+    my ($text) = @_;
+    $text =~ s/%([0-9A-Fa-f]{2})/chr( hex($1) )/ge;
+    return $text;
+}
+
+# The canonical query string: each pair RFC 3986-escaped, sorted by
+# escaped key then escaped value.
+sub canonicalquery {
+    my ($query) = @_;
+
+    return '' if '' eq $query;
+
+    my @pairs;
+    for my $pair ( split( /&/, $query, -1 ) ) {
+        my $eq    = index( $pair, '=' );
+        my $key   = -1 == $eq ? $pair : substr( $pair, 0, $eq );
+        my $value = -1 == $eq ? ''    : substr( $pair, $eq + 1 );
+        push @pairs, [ uriescape( uridecode($key) ), uriescape( uridecode($value) ) ];
+    }
+
+    @pairs = sort { $a->[0] cmp $b->[0] || $a->[1] cmp $b->[1] } @pairs;
+
+    return join( '&', map { $_->[0] . '=' . $_->[1] } @pairs );
+}
+
+# Pull the host (with any port), path and query out of a URL, the way a
+# WHATWG URL object presents them: the scheme's default port is dropped
+# from the host, and an empty path reads as `/`.
+sub parseurl {
+    my ($url) = @_;
+
+    my ( $scheme, $host, $path, $query ) =
+      ( defined $url ? $url : '' ) =~ m{^(https?)://([^/?#]+)([^?#]*)(?:\?([^#]*))?};
+
+    die 'sekreto: sigv4: not a parseable url: ' . ( defined $url ? $url : '' ) . "\n"
+      if !defined $host;
+
+    $host =~ s/:443$// if 'https' eq $scheme;
+    $host =~ s/:80$//  if 'http' eq $scheme;
+
+    return (
+        $host,
+        ( defined $path && '' ne $path ) ? $path : '/',
+        defined $query ? $query : '',
+    );
+}
+
+# Sign one request. Returns (a map of) the headers to attach:
+# authorization, x-amz-date, and x-amz-security-token when a session
+# token was given.
+sub sigv4 {
+    my ($input) = @_;
+
+    my ( $host, $path, $query ) = parseurl( $input->{url} );
+
+    my $datetime = $input->{datetime};
+    my $date     = substr( $datetime, 0, 8 );
+    my $body     = defined $input->{body} ? $input->{body} : '';
+
+    # Every header that will be signed: the caller's extras, plus host and
+    # x-amz-date (and the session token when present), lower-cased and
+    # trimmed the way the canonical form requires.
+    # Canonical header values are trimmed AND internally collapsed -
+    # AWS folds sequential whitespace to one space before signing, so a
+    # header like "a  b" must sign as "a b" or the service refuses it.
+    my %headers;
+    my $extra = $input->{headers} || {};
+    for my $key ( keys %$extra ) {
+        my $value = defined $extra->{$key} ? "$extra->{$key}" : '';
+        $value =~ s/^\s+|\s+$//g;
+        $value =~ s/\s+/ /g;
+        $headers{ lc($key) } = $value;
+    }
+    $headers{host}                   = $host;
+    $headers{'x-amz-date'}           = $datetime;
+    $headers{'x-amz-security-token'} = $input->{session} if $input->{session};
+
+    my @names            = sort keys %headers;
+    my $canonicalheaders = join( '', map { $_ . ':' . $headers{$_} . "\n" } @names );
+    my $signedheaders    = join( ';', @names );
+
+    my $canonicalrequest = join( "\n",
+        uc( $input->{method} ),
+        $path,
+        canonicalquery($query),
+        $canonicalheaders,
+        $signedheaders,
+        sha256hex($body),
+    );
+
+    my $scope = $date . '/' . $input->{region} . '/' . $input->{service} . '/aws4_request';
+
+    my $stringtosign =
+      join( "\n", 'AWS4-HMAC-SHA256', $datetime, $scope, sha256hex($canonicalrequest) );
+
+    my $kdate     = hmac( 'AWS4' . $input->{secret}, $date );
+    my $kregion   = hmac( $kdate,                    $input->{region} );
+    my $kservice  = hmac( $kregion,                  $input->{service} );
+    my $ksigning  = hmac( $kservice,                 'aws4_request' );
+    my $signature = hmachex( $ksigning, $stringtosign );
+
+    my %out = (
+        authorization => 'AWS4-HMAC-SHA256 Credential='
+          . $input->{keyid} . '/'
+          . $scope
+          . ', SignedHeaders='
+          . $signedheaders
+          . ', Signature='
+          . $signature,
+        'x-amz-date' => $datetime,
+    );
+
+    $out{'x-amz-security-token'} = $input->{session} if $input->{session};
+
+    return \%out;
+}
+
+1;

package/project/.sdk/tm/perl/feature/secrets/sekreto/Voxgig/Sekreto/Addr.pm

@@ -0,0 +1,124 @@
+# VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (perl/lib/Voxgig/Sekreto/Addr.pm)
+# Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+package Voxgig::Sekreto::Addr;
+
+# Where an address is judged: is this an http(s) address at all, and may a
+# token be sent to it in the clear?
+#
+# CORE, not a plugin, although only the plugins dial anything. The rule
+# that a credential never crosses the network in plaintext is sekreto's
+# rather than any one store's, and a custom provider written by a consumer
+# gets it for free by calling `checkaddr` - which it can only do if the
+# core carries it.
+#
+# A port of typescript/src/provider/addr.ts, which is canonical.
+
+use strict;
+use warnings;
+
+use Exporter 'import';
+
+our @EXPORT_OK = qw(checkaddr safeaddr);
+
+# Voxgig::Sekreto uses this module, so a `use` back would be a cycle: the
+# failure path is called by name at run time instead.
+sub fail { return Voxgig::Sekreto::fail(@_) }
+
+# An address with any userinfo replaced by `[redacted]`, for messages.
+#
+# Every refusal below names the address it refused, and one of them fires
+# precisely because the address carries a credential - so printing it
+# verbatim wrote the password to stderr and into the logs. It cannot be
+# cleaned up afterwards either: that password was never resolved as a secret,
+# so redact() has never seen it and never will. The host is what a reader
+# needs to identify which chain entry is at fault; the userinfo is not.
+sub safeaddr {
+    my ($addr) = @_;
+
+    my $mark = index( $addr, '://' );
+    return $addr if -1 == $mark;
+
+    my $rest = substr( $addr, $mark + 3 );
+    my ($authority) = $rest =~ m{\A([^/?\#]*)};
+    $authority = '' if !defined $authority;
+
+    my $at = rindex( $authority, '@' );
+    return $addr if -1 == $at;
+
+    return substr( $addr, 0, $mark + 3 ) . '[redacted]' . substr( $addr, $mark + 3 + $at );
+}
+
+
+# Refuse to send a secret-bearing credential in the clear.
+#
+# A vault API is HTTPS in any real deployment; plaintext is a dev-mode
+# convenience. Sending a token over http to anything but the local machine
+# puts both the token and the secret it fetches on the wire for anyone on
+# the path, so sekreto will not do it. Loopback stays allowed: that is
+# `vault server -dev`, `boru vault serve`, and this repo's own test
+# harness.
+#
+# The address is read by hand, in the same handful of steps in every port,
+# rather than by each platform's URL parser. That is deliberate. Twelve
+# parsers disagree about malformed input - where userinfo ends, whether
+# `0177.0.0.1` is loopback, what an unclosed bracket means - and a check that
+# answers differently in different ports is not a check. (Core Perl has no
+# URL parser in any case - URI is not core, and this library takes no
+# dependencies.)
+#
+# The rule this parse obeys, and the reason it can be trusted: it is never
+# more permissive than the HTTP client that will dial the address. It ends
+# the authority at '/', '?' or '#' only, so a client that also breaks on '\'
+# (WHATWG does) can only ever see a SHORTER host than this does. It refuses
+# userinfo outright rather than locating its end - which also settles a
+# disagreement with HTTP::Tiny, whose own parse strips userinfo at the FIRST
+# '@' where the RFC says the last. It compares the host literally, so a
+# numeric form no parser here agrees on is refused rather than guessed at.
+sub checkaddr {
+    my ($addr) = @_;
+
+    my $scheme =
+          0 == index( $addr, 'https://' ) ? 'https://'
+        : 0 == index( $addr, 'http://' )  ? 'http://'
+        :                                   '';
+
+    fail( 'sekreto: not an http(s) address: ' . safeaddr($addr) ) if '' eq $scheme;
+
+    my $rest = substr( $addr, length($scheme) );
+    my ($authority) = $rest =~ m{\A([^/?\#]*)};
+    $authority = '' if !defined $authority;
+
+    # Userinfo is refused outright rather than parsed around, and on https as
+    # well as http. No store this library speaks authenticates by userinfo -
+    # they take a token or a signature - so an address carrying one is a
+    # mistake at best. At worst it is the attack this whole function exists to
+    # stop: `http://localhost:8200@evil.example.com/` is a request to
+    # evil.example.com that reads, to anything that splits the authority on
+    # ':', as loopback.
+    fail( 'sekreto: refusing an address with embedded credentials: ' . safeaddr($addr) )
+        if -1 != index( $authority, '@' );
+
+    # An opening bracket with no closing one is not an address at all.
+    fail( 'sekreto: not a valid http(s) address: ' . safeaddr($addr) )
+        if 0 == index( $authority, '[' ) && -1 == index( $authority, ']' );
+
+    return if 'https://' eq $scheme;
+
+    # A bracketed IPv6 literal keeps its brackets. Splitting the authority on
+    # the first colon yields '[', so `http://[::1]:8200` could never match -
+    # which made the '[::1]' entry below unreachable, and refused a legitimate
+    # local vault.
+    my $host =
+        0 == index( $authority, '[' )
+        ? substr( $authority, 0, index( $authority, ']' ) + 1 )
+        : ( split( /:/, $authority, 2 ) )[0];
+    $host = '' if !defined $host;
+    $host = lc $host;
+
+    return if grep { $_ eq $host } ( 'localhost', '127.0.0.1', '::1', '[::1]' );
+
+    fail( 'sekreto: refusing to send a token in plaintext to ' . safeaddr($addr) . ' (use https)' );
+}
+
+1;