# Plover 1Password
[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]
This [Plover][] [extension][] [plugin][] contains a [meta][] that allows you to
retrieve secrets defined in your [1Password][] vaults.
## Install
1. In the Plover application, open the Plugins Manager (either click the Plugins
Manager icon, or from the `Tools` menu, select `Plugins Manager`).
2. From the list of plugins, find `plover-1password`
3. Click "Install/Update"
4. When it finishes installing, restart Plover
5. Complete the [Setup][] steps
6. After re-opening Plover, open the Configuration screen (either click the
Configuration icon, or from the main Plover application menu, select
`Preferences...`)
7. Open the Plugins tab
8. Check the box next to `plover_1password` to activate the plugin
## Setup
Setting up 1Password to allow this plugin to make connections is a bit of an
involved process, but you will only have to do it once.
### Create a new Vault
Since 1Password does not allow third-party applications to access your Private
or Personal vaults, you will need to put secrets you intend to access from
Plover into a separate vault. Therefore, either [create a new vault][]
specifically for Plover to access, or use another existing non-Private/Personal
vault you have.
Individual secrets cannot be shared across vaults, so if you have information in
your Personal vault you want Plover to access, you will need to [move or copy
items][] from your Personal vault to the vault that Plover will access.
### Create a Service Account Token
Follow the steps to [create a Service Account][], which will enable Plover to
talk to 1Password.
This plugin only needs to retrieve secrets from 1Password, so when you get to
the "Grant vault access" section of the Service Account creation process, after
choosing the vault that Plover will access, set its access permissions to
"Read Items" only.
Once the Service Account Token has been generated (and you save it to one of
your vaults), you will need to copy the token into a local [environment
variable][] called `OP_SERVICE_ACCOUNT_TOKEN`, as per the requirements of the
[1Password Python SDK][], which this plugin uses to connect with 1Password:
**macOS or Linux**
In your `.bashrc`/`.zshrc` etc add:
```bash
export OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>
```
**Windows**
In your
`C:\Users\<user name>\Documents\WindowsPowerShell\Microsoft.Powershell_profile.ps1`
etc add:
```powershell
$ENV:OP_SERVICE_ACCOUNT_TOKEN = "<your-service-account-token>"
```
### Install 1Password CLI and turn on desktop app integration
Follow all the steps to [Get started with 1Password CLI][] to install the
[1Password Command-line tool][], and turn on its [1Password app integration][].
Once you have completed this step, a new [Copy Secret Reference][] option will
become available to you in the `v` dropdown menu, next to the Copy button, at
the end of each field in your document item. It is these [secret references][],
which can be thought of as references or pointers to where a secret is saved,
rather than the value of the secret itself, that will be used directly in steno
outline translations. They have the following format:
```txt
op://<vault-name>/<item-name>/[section-name/]<field-name>
```
> [!NOTE]
> Secret references adhere to the following set of [syntax rules][]:
>
> - alphanumeric characters (`a-z`, `A-Z`, `0-9`)
> - `-`, `_`, `.` and the whitespace character
>
> Therefore, make sure your vault, item, section, and field names adhere to
> these rules and do not contain any other types of characters.
## How To Use
In your steno outline translations, use the [secret references][] provided by
1Password to specify the secret you wish to retrieve.
For example, the following outline would retrieve the "Mobile" secret defined in
a "Plover" vault, within a "Personal" item, under a "Phone" section:
```json
"TPOEPB/TPOEPB": "{:1PASSWORD:op://Plover/Personal/Phone/Mobile}"
```
If you are publishing or sharing your steno dictionaries publicly, and/or do not
want to specify the names of your vaults or items etc in your outlines, you can
define them instead within local environment variables on your computer, and
the plugin will expand them inline:
**macOS or Linux**
```json
"TPOEPB/TPOEPB": "{:1PASSWORD:op://$VAULT_NAME/$ITEM_NAME/$SECTION_NAME/Mobile}"
```
**Windows**
```json
"TPOEPB/TPOEPB": "{:1PASSWORD:op://$ENV:VAULT_NAME/$ENV:ITEM_NAME/$ENV:SECTION_NAME/Mobile}"
```
Given that the plugin is making a connection out to 1Password, it can take a few
seconds before the secret value actually outputs (or you are shown an error).
> [!NOTE]
> Service account tokens are subject to [rate limits][] by 1Password, but they
> should be more than enough for normal usage of this plugin.
## Development
Clone from GitHub with [git][] and install test-related dependencies:
```console
git clone git@github.com:paulfioravanti/plover-1password.git
cd plover-1password
python -m pip install --editable ".[test]"
```
If you are a [Tmuxinator][] user, you may find my [plover-1password project
file][] of reference.
### Python Version
Plover's Python environment currently uses version 3.9 (see Plover's
[`workflow_context.yml`][] to confirm the current version).
So, in order to avoid unexpected issues, use your runtime version manager to
make sure your local development environment also uses Python 3.9.x.
### Testing
- [Pytest][] with [pytest-asyncio][] are used for testing in this plugin.
- [Coverage.py][] and [pytest-cov][] are used for test coverage, and to run
coverage within Pytest
- [Pylint][] is used for code quality
- [Mypy][] is used for static type checking
Currently, the only parts able to be tested are ones that do not rely directly
on Plover.
Run tests, coverage, and linting with the following commands:
```console
pytest --cov --cov-report=term-missing
pylint plover_1password
mypy plover_1password
```
To get a HTML test coverage report:
```console
coverage run --module pytest
coverage html
open htmlcov/index.html
```
If you are a [`just`][] user, you may find the [`justfile`][] useful during
development in running multiple test commands. You can run the following command
from the project root directory:
```console
just --working-directory . --justfile test/justfile
```
### Deploying Changes
After making any code changes, deploy the plugin into Plover with the following
command:
```console
plover --script plover_plugins install --editable .
```
> Where `plover` in the command is a reference to your locally installed version
> of Plover. See the [Invoke Plover from the command line][] page for details on
> how to create that reference.
When necessary, the plugin can be uninstalled via the command line with the
following command:
```console
plover --script plover_plugins uninstall plover-1password
```
[1Password]: https://1password.com/
[1Password app integration]: https://developer.1password.com/docs/cli/app-integration/
[1Password Command-line tool]: https://1password.com/downloads/command-line/
[1Password Python SDK]: https://github.com/1Password/onepassword-sdk-python
[Build Status image]: https://github.com/paulfioravanti/plover-1password/actions/workflows/ci.yml/badge.svg
[Build Status url]: https://github.com/paulfioravanti/plover-1password/actions/workflows/ci.yml
[Copy Secret Reference]: https://developer.1password.com/docs/cli/secret-reference-syntax/#with-the-1password-desktop-app
[Coverage.py]: https://github.com/nedbat/coveragepy
[create a new vault]: https://support.1password.com/create-share-vaults/#create-a-vault
[create a Service Account]: https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account
[environment variable]: https://en.wikipedia.org/wiki/Environment_variable
[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html
[Get started with 1Password CLI]: https://developer.1password.com/docs/cli/get-started/
[git]: https://git-scm.com/
[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line
[`just`]: https://github.com/casey/just
[`justfile`]: ./test/justfile
[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen
[linting url]: https://github.com/pylint-dev/pylint
[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html
[move or copy items]: https://support.1password.com/move-copy-items/
[Mypy]: https://github.com/python/mypy
[plover-1password project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_1password.yml
[PyPI downloads image]: https://img.shields.io/pypi/dm/plover-1password
[PyPI version image]: https://img.shields.io/pypi/v/plover-1password
[PyPI url]: https://pypi.org/project/plover-1password/
[Plover]: https://www.openstenoproject.org/
[Plover Plugins Registry]: https://github.com/openstenoproject/plover_plugins_registry
[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins
[Pylint]: https://github.com/pylint-dev/pylint
[Pytest]: https://pytest.org/
[pytest-asyncio]: https://github.com/pytest-dev/pytest-asyncio
[pytest-cov]: https://github.com/pytest-dev/pytest-cov/
[rate limits]: https://developer.1password.com/docs/service-accounts/rate-limits/#hourly-limits
[secret reference]: https://developer.1password.com/docs/cli/secret-reference-syntax/
[secret references]: https://developer.1password.com/docs/cli/secret-reference-syntax/
[Setup]: ./#Setup
[syntax rules]: https://developer.1password.com/docs/cli/secret-reference-syntax/#syntax-rules
[Tmuxinator]: https://github.com/tmuxinator/tmuxinator
[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml
Raw data
{
"_id": null,
"home_page": "https://github.com/paulfioravanti/plover-1password",
"name": "plover-1password",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "plover plover_plugin",
"author": "Paul Fioravanti",
"author_email": "paul@paulfioravanti.com",
"download_url": "https://files.pythonhosted.org/packages/77/14/8ca716589a66c6ff0eae2ce047527a7f7c5632bc0493ecd0cb87a33300f5/plover_1password-0.4.2.tar.gz",
"platform": null,
"description": "# Plover 1Password\n\n[![Build Status][Build Status image]][Build Status url] [![PyPI - Version][PyPI version image]][PyPI url] [![PyPI - Downloads][PyPI downloads image]][PyPI url] [![linting: pylint][linting image]][linting url]\n\nThis [Plover][] [extension][] [plugin][] contains a [meta][] that allows you to\nretrieve secrets defined in your [1Password][] vaults.\n\n## Install\n\n1. In the Plover application, open the Plugins Manager (either click the Plugins\n Manager icon, or from the `Tools` menu, select `Plugins Manager`).\n2. From the list of plugins, find `plover-1password`\n3. Click \"Install/Update\"\n4. When it finishes installing, restart Plover\n5. Complete the [Setup][] steps\n6. After re-opening Plover, open the Configuration screen (either click the\n Configuration icon, or from the main Plover application menu, select\n `Preferences...`)\n7. Open the Plugins tab\n8. Check the box next to `plover_1password` to activate the plugin\n\n## Setup\n\nSetting up 1Password to allow this plugin to make connections is a bit of an\ninvolved process, but you will only have to do it once.\n\n### Create a new Vault\n\nSince 1Password does not allow third-party applications to access your Private\nor Personal vaults, you will need to put secrets you intend to access from\nPlover into a separate vault. Therefore, either [create a new vault][]\nspecifically for Plover to access, or use another existing non-Private/Personal\nvault you have.\n\nIndividual secrets cannot be shared across vaults, so if you have information in\nyour Personal vault you want Plover to access, you will need to [move or copy\nitems][] from your Personal vault to the vault that Plover will access.\n\n### Create a Service Account Token\n\nFollow the steps to [create a Service Account][], which will enable Plover to\ntalk to 1Password.\n\nThis plugin only needs to retrieve secrets from 1Password, so when you get to\nthe \"Grant vault access\" section of the Service Account creation process, after\nchoosing the vault that Plover will access, set its access permissions to\n\"Read Items\" only.\n\nOnce the Service Account Token has been generated (and you save it to one of\nyour vaults), you will need to copy the token into a local [environment\nvariable][] called `OP_SERVICE_ACCOUNT_TOKEN`, as per the requirements of the\n[1Password Python SDK][], which this plugin uses to connect with 1Password:\n\n**macOS or Linux**\n\nIn your `.bashrc`/`.zshrc` etc add:\n\n```bash\nexport OP_SERVICE_ACCOUNT_TOKEN=<your-service-account-token>\n```\n\n**Windows**\n\nIn your\n`C:\\Users\\<user name>\\Documents\\WindowsPowerShell\\Microsoft.Powershell_profile.ps1`\netc add:\n\n```powershell\n$ENV:OP_SERVICE_ACCOUNT_TOKEN = \"<your-service-account-token>\"\n```\n\n### Install 1Password CLI and turn on desktop app integration\n\nFollow all the steps to [Get started with 1Password CLI][] to install the\n[1Password Command-line tool][], and turn on its [1Password app integration][].\n\nOnce you have completed this step, a new [Copy Secret Reference][] option will\nbecome available to you in the `v` dropdown menu, next to the Copy button, at\nthe end of each field in your document item. It is these [secret references][],\nwhich can be thought of as references or pointers to where a secret is saved,\nrather than the value of the secret itself, that will be used directly in steno\noutline translations. They have the following format:\n\n```txt\nop://<vault-name>/<item-name>/[section-name/]<field-name>\n```\n\n> [!NOTE]\n> Secret references adhere to the following set of [syntax rules][]:\n> \n> - alphanumeric characters (`a-z`, `A-Z`, `0-9`)\n> - `-`, `_`, `.` and the whitespace character\n>\n> Therefore, make sure your vault, item, section, and field names adhere to\n> these rules and do not contain any other types of characters.\n\n## How To Use\n\nIn your steno outline translations, use the [secret references][] provided by\n1Password to specify the secret you wish to retrieve.\n\nFor example, the following outline would retrieve the \"Mobile\" secret defined in\na \"Plover\" vault, within a \"Personal\" item, under a \"Phone\" section:\n\n```json\n\"TPOEPB/TPOEPB\": \"{:1PASSWORD:op://Plover/Personal/Phone/Mobile}\"\n```\n\nIf you are publishing or sharing your steno dictionaries publicly, and/or do not\nwant to specify the names of your vaults or items etc in your outlines, you can\ndefine them instead within local environment variables on your computer, and\nthe plugin will expand them inline:\n\n**macOS or Linux**\n\n```json\n\"TPOEPB/TPOEPB\": \"{:1PASSWORD:op://$VAULT_NAME/$ITEM_NAME/$SECTION_NAME/Mobile}\"\n```\n\n**Windows**\n\n```json\n\"TPOEPB/TPOEPB\": \"{:1PASSWORD:op://$ENV:VAULT_NAME/$ENV:ITEM_NAME/$ENV:SECTION_NAME/Mobile}\"\n```\n\nGiven that the plugin is making a connection out to 1Password, it can take a few\nseconds before the secret value actually outputs (or you are shown an error).\n\n> [!NOTE]\n> Service account tokens are subject to [rate limits][] by 1Password, but they\n> should be more than enough for normal usage of this plugin.\n\n## Development\n\nClone from GitHub with [git][] and install test-related dependencies:\n\n```console\ngit clone git@github.com:paulfioravanti/plover-1password.git\ncd plover-1password\npython -m pip install --editable \".[test]\"\n```\n\nIf you are a [Tmuxinator][] user, you may find my [plover-1password project\nfile][] of reference.\n\n### Python Version\n\nPlover's Python environment currently uses version 3.9 (see Plover's\n[`workflow_context.yml`][] to confirm the current version).\n\nSo, in order to avoid unexpected issues, use your runtime version manager to\nmake sure your local development environment also uses Python 3.9.x.\n\n### Testing\n\n- [Pytest][] with [pytest-asyncio][] are used for testing in this plugin.\n- [Coverage.py][] and [pytest-cov][] are used for test coverage, and to run\n coverage within Pytest\n- [Pylint][] is used for code quality\n- [Mypy][] is used for static type checking\n\nCurrently, the only parts able to be tested are ones that do not rely directly\non Plover.\n\nRun tests, coverage, and linting with the following commands:\n\n```console\npytest --cov --cov-report=term-missing\npylint plover_1password\nmypy plover_1password\n```\n\nTo get a HTML test coverage report:\n\n```console\ncoverage run --module pytest\ncoverage html\nopen htmlcov/index.html\n```\n\nIf you are a [`just`][] user, you may find the [`justfile`][] useful during\ndevelopment in running multiple test commands. You can run the following command\nfrom the project root directory:\n\n```console\njust --working-directory . --justfile test/justfile\n```\n\n### Deploying Changes\n\nAfter making any code changes, deploy the plugin into Plover with the following\ncommand:\n\n```console\nplover --script plover_plugins install --editable .\n```\n\n> Where `plover` in the command is a reference to your locally installed version\n> of Plover. See the [Invoke Plover from the command line][] page for details on\n> how to create that reference.\n\nWhen necessary, the plugin can be uninstalled via the command line with the\nfollowing command:\n\n```console\nplover --script plover_plugins uninstall plover-1password\n```\n\n[1Password]: https://1password.com/\n[1Password app integration]: https://developer.1password.com/docs/cli/app-integration/\n[1Password Command-line tool]: https://1password.com/downloads/command-line/\n[1Password Python SDK]: https://github.com/1Password/onepassword-sdk-python\n[Build Status image]: https://github.com/paulfioravanti/plover-1password/actions/workflows/ci.yml/badge.svg\n[Build Status url]: https://github.com/paulfioravanti/plover-1password/actions/workflows/ci.yml\n[Copy Secret Reference]: https://developer.1password.com/docs/cli/secret-reference-syntax/#with-the-1password-desktop-app\n[Coverage.py]: https://github.com/nedbat/coveragepy\n[create a new vault]: https://support.1password.com/create-share-vaults/#create-a-vault\n[create a Service Account]: https://developer.1password.com/docs/service-accounts/get-started/#create-a-service-account\n[environment variable]: https://en.wikipedia.org/wiki/Environment_variable\n[extension]: https://plover.readthedocs.io/en/latest/plugin-dev/extensions.html\n[Get started with 1Password CLI]: https://developer.1password.com/docs/cli/get-started/\n[git]: https://git-scm.com/\n[Invoke Plover from the command line]: https://github.com/openstenoproject/plover/wiki/Invoke-Plover-from-the-command-line\n[`just`]: https://github.com/casey/just\n[`justfile`]: ./test/justfile\n[linting image]: https://img.shields.io/badge/linting-pylint-yellowgreen\n[linting url]: https://github.com/pylint-dev/pylint\n[meta]: https://plover.readthedocs.io/en/latest/plugin-dev/metas.html\n[move or copy items]: https://support.1password.com/move-copy-items/\n[Mypy]: https://github.com/python/mypy\n[plover-1password project file]: https://github.com/paulfioravanti/dotfiles/blob/master/tmuxinator/plover_1password.yml\n[PyPI downloads image]: https://img.shields.io/pypi/dm/plover-1password\n[PyPI version image]: https://img.shields.io/pypi/v/plover-1password\n[PyPI url]: https://pypi.org/project/plover-1password/\n[Plover]: https://www.openstenoproject.org/\n[Plover Plugins Registry]: https://github.com/openstenoproject/plover_plugins_registry\n[plugin]: https://plover.readthedocs.io/en/latest/plugins.html#types-of-plugins\n[Pylint]: https://github.com/pylint-dev/pylint\n[Pytest]: https://pytest.org/\n[pytest-asyncio]: https://github.com/pytest-dev/pytest-asyncio\n[pytest-cov]: https://github.com/pytest-dev/pytest-cov/\n[rate limits]: https://developer.1password.com/docs/service-accounts/rate-limits/#hourly-limits\n[secret reference]: https://developer.1password.com/docs/cli/secret-reference-syntax/\n[secret references]: https://developer.1password.com/docs/cli/secret-reference-syntax/\n[Setup]: ./#Setup\n[syntax rules]: https://developer.1password.com/docs/cli/secret-reference-syntax/#syntax-rules\n[Tmuxinator]: https://github.com/tmuxinator/tmuxinator\n[`workflow_context.yml`]: https://github.com/openstenoproject/plover/blob/master/.github/workflows/ci/workflow_context.yml\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Safely fetch secrets from 1Password defined in steno outlines.",
"version": "0.4.2",
"project_urls": {
"Homepage": "https://github.com/paulfioravanti/plover-1password"
},
"split_keywords": [
"plover",
"plover_plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3b7bb5cfdcfb52a674cb86a6bd1cebcd898600f1bee58a113be012f4265f863",
"md5": "62684819e3692806fb2600bf718bda3d",
"sha256": "debf796ce850593f4dbdbfa47fd9d91fe7313560b082ae96e3c2c087dea61ed8"
},
"downloads": -1,
"filename": "plover_1password-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62684819e3692806fb2600bf718bda3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 25213,
"upload_time": "2024-10-10T06:23:58",
"upload_time_iso_8601": "2024-10-10T06:23:58.624538Z",
"url": "https://files.pythonhosted.org/packages/c3/b7/bb5cfdcfb52a674cb86a6bd1cebcd898600f1bee58a113be012f4265f863/plover_1password-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77148ca716589a66c6ff0eae2ce047527a7f7c5632bc0493ecd0cb87a33300f5",
"md5": "f552678649f57e04249b4616604239d9",
"sha256": "5f69ade204e9a7ddd72f466843186c73da57fd5b3a4ec3eb8b81c7810b794ef8"
},
"downloads": -1,
"filename": "plover_1password-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "f552678649f57e04249b4616604239d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25055,
"upload_time": "2024-10-10T06:24:00",
"upload_time_iso_8601": "2024-10-10T06:24:00.210036Z",
"url": "https://files.pythonhosted.org/packages/77/14/8ca716589a66c6ff0eae2ce047527a7f7c5632bc0493ecd0cb87a33300f5/plover_1password-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 06:24:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulfioravanti",
"github_project": "plover-1password",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "plover-1password"
}
JSON
