/ 
Password-OnePassword-OPCLI-0.002
River stage one • 1 direct dependent • 1 total dependent
/ Password::OnePassword::OPCLI

NAME

Password::OnePassword::OPCLI - get items out of 1Password with the "op" CLI

VERSION

version 0.002

SYNOPSIS

Achtung! The interface for this library might change a lot. The author is still figuring out how to make it make sense. That's partly because he doesn't want to think too hard about errors, and partly because the op:// URL scheme used by 1Password isn't really sufficient for his use. Still, this is roughly how you can use it:

my $one_pw = Password::OnePassword::OPCLI->new;

# Get the string found in one field in your 1Password storage:
my $string = $one_pw->get_field("op://Private/PAUSE API/credential");

# Get the complete document for an item, as a hashref:
my $pw_item = $one_pw->get_item("op://Work/GitHub");

PERL VERSION

This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.)

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

METHODS

new

my $one_pw = Password::OnePassword::OPCLI->new;

This is a do-almost-nothing constructor. It's only here so that methods are instance methods, not class methods. Someday, there may be more arguments to this, but for now, there are not.

get_item

my $hashref = $one_pw->get_item($locator);

This looks up an item in 1Password, returning a hashref representing the secret from 1Password.

The $locator should be either a Password::OnePassword::OPCLI::Locator object or a string that coerced into one, for which see "LOCATOR STRINGS".

If the locator specifies a field name, an exception will be raised.

get_field

my $str = $one_pw->get_field($locator);

This looks up an item in 1Password, using the op read command.

The $locator should be either a Password::OnePassword::OPCLI::Locator object or a string that coerced into one, for which see "LOCATOR STRINGS". The string you get from using the "Copy Secret Reference" feature of 1Password, as long as the 1Password account is not ambiguous at runtime.

If the locator does not specify a field name, an exception will be raised.

It will return the string form of whatever is stored in that field. If it can't find the field, if it can't authenticate, or in any case other than "everything worked", it will raise an exception.

get_otp

my $otp = $one_pw->get_otp($locator);

This looks up an item in 1Password, using the op read command. The item is assumed to be an OTP-type field. Instead of returning the field's value, which would be the TOTP secret, this method will return the one-time password for the current time.

The $locator argument works the same as the argument to the get_field method.

If op can't find the field, if the field isn't an OTP field, if it can't authenticate, or in any case other than "everything worked", the library will raise an exception.

LOCATOR STRINGS

1Password offers op:// URLs for fetching things via op, but they're not quite good enough, at least for this author's needs. First off, if you use the "Copy Secret Reference" feature of 1Password, you'll end up with a string like this on your clipboard:

op://Private/Super Mario Fan Club/password

This refers to a single field in the vault item. You can pass this to the op read command. If you want to fetch the whole secret item, though, you can't just drop the third part of the path to pass to op item get. If you have that URL and want to get the whole item, you need to parse it and build a command-line invocation yourself.

There's a worse problem, too. A two-part (item, not field) URL makes sense because you just drop one piece of data from the three-part URL. But these URLs are also missing a place for the account. If you've got more than one 1Password account on your laptop, like both work and personal, you can't unambiguously specify a credential with only a string. This really undercuts the value of the op:// URIs as (for example) environment variables. You end up having to set a second environment variable indicating which account to use, and if you need to access more than one vault in a program, the complexity piles up.

Password::OnePassword::OPCLI works with "locator" objects, which the user shouldn't really need to think about. The user of the library can pass in a string that can be parsed into a locator, either as a normal three-part op:// URL, or as a bogus-but-comprehensible two-part URL, or as an OPCLI-specific string like this:

opcli:a=${Account}:v=${Vault}:i=${Item}:f=${Field}

Order is not important and only the item property is required. To represent the URL above (op://Private/Super Mario Fan Club/password) in this format, you'd write:

opcli:v=Private:i=Super Mario Fan Club:f=password

Later, if you realized that you need to specify an account, you could tack it on the end:

opcli:v=Private:i=Super Mario Fan Club:f=password:a=Personal

The value of property will be URI-decoded before use. This won't matter, generally, but you'll need to know if it you want to use locators with % or : in property values, at least.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

CONTRIBUTOR

Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.