envref 0.1.0__tar.gz

envref-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+# Real values never belong here; .env files in this repo are examples.
+.env
+.env.*
+!.env.example

envref-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-11-07
+
+First release. Extracted from a private automation repository where the
+1Password path had run daily for a year.
+
+- `.env` files whose values may be `{{ scheme://… }}` references.
+- Resolvers: `op://` (1Password, via the `op` CLI with a cached session and
+  Touch ID sign-in, or via a service account), `keychain://` (macOS Keychain),
+  `file://`, `env://`.
+- Third-party resolvers through the `envref.resolvers` entry-point group.
+- CLI: `envref run`, `export`, `check`, `doctor`, `op save-password`.

envref-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Haglund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

envref-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: envref
+Version: 0.1.0
+Summary: A .env where any value can be a reference into a secret store, resolved at load time. op://, keychain://, file://, env://, and your own.
+Project-URL: Homepage, https://github.com/sebaheg/envref
+Project-URL: Repository, https://github.com/sebaheg/envref
+Project-URL: Issues, https://github.com/sebaheg/envref/issues
+Project-URL: Changelog, https://github.com/sebaheg/envref/blob/main/CHANGELOG.md
+Author: Sebastian Haglund
+License: MIT
+License-File: LICENSE
+Keywords: 1password,dotenv,environment,keychain,secrets,twelve-factor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: op
+Requires-Dist: onepassword-sdk>=0.3; (python_version < '3.14') and extra == 'op'
+Description-Content-Type: text/markdown
+
+# envref
+
+A `.env` where any value can be a reference into a secret store, resolved
+when the file is loaded.
+
+```dotenv
+# .env
+ATTIO_KEY={{ op://work/Attio/api_key }}          # 1Password
+DB_PASSWORD={{ keychain://myapp/postgres }}      # macOS Keychain
+TLS_KEY={{ file://~/.ssh/server.pem }}           # a file's contents
+GITHUB_TOKEN={{ env://GH_TOKEN }}                # another variable
+REGION=eu-north-1                                # a plain literal
+```
+
+```bash
+envref run -- python app.py       # app.py sees ATTIO_KEY=<the real key>
+```
+
+```python
+import envref
+envref.load(".env")               # same thing, into os.environ
+```
+
+The file holds no secrets, so it can be committed. The scheme of each
+reference picks the backend. Four ship built in, and your own takes one class
+and one entry point.
+
+## Why
+
+`op run`, `berglas exec`, `chamber exec` and friends each do this for one
+store. Teams rarely have one store. A laptop has 1Password and Keychain, a
+container has a service account, a CI job has its own vault, and the same
+`.env` should work in all three with the same names. `envref` keeps the file
+format (plain dotenv, plus `{{ scheme://… }}`), and makes the backend a plugin.
+
+## Install
+
+```bash
+uv tool install envref            # CLI
+pip install envref                # library, zero dependencies
+pip install 'envref[op]'          # + 1Password service-account support (SDK)
+```
+
+The `op://` CLI path needs only the [`op`](https://developer.1password.com/docs/cli/)
+binary on PATH, no extra.
+
+## Resolvers
+
+| Scheme | Resolves to | Needs |
+| --- | --- | --- |
+| `op://vault/item/field` | a 1Password field | `op` CLI, or `OP_SERVICE_ACCOUNT_TOKEN` + `envref[op]` |
+| `keychain://service/account` | a macOS Keychain generic password | macOS |
+| `file://path` | the file's contents, one trailing newline dropped | — |
+| `env://NAME` | another environment variable | — |
+
+A value written as `{{ scheme://… }}` is always a reference, and an unknown
+scheme is an error. A bare `scheme://…` without braces is resolved only when a
+resolver for that scheme is installed, so `URL=https://example.com` stays a
+literal and `KEY=op://vault/item/field` still works for files written for
+`op read`.
+
+### 1Password in detail
+
+Two modes, chosen by the environment:
+
+- **Service account** when `OP_SERVICE_ACCOUNT_TOKEN` is set. The SDK resolves
+  every reference in one round trip. No binary, no biometrics. For containers.
+- **CLI** otherwise. Every reference goes through one `op inject`. If `op` has
+  no session, `envref` signs in: the account password comes from Keychain
+  behind Touch ID if you stored it with `envref op save-password`, or from the
+  terminal if not. The session token is cached in `~/.cache/envref/` so a
+  burst of commands costs one sign-in; concurrent processes share it through
+  a lock. See [SECURITY.md](SECURITY.md) for what that cache means.
+
+Session caching presumes "biometric unlock for the CLI" is off in the
+1Password app. With it on, `op` prompts per invocation and `envref` holds no
+token.
+
+Knobs: `OP_ACCOUNT` (shorthand, when several accounts are signed in),
+`ENVREF_OP_SESSION_TTL` (seconds, default 1500, `0` disables the cache),
+`ENVREF_OP_KEYCHAIN_SERVICE` / `ENVREF_OP_KEYCHAIN_ACCOUNT` (where the
+password is stored, default `envref-op` / the account's email).
+
+## CLI
+
+```bash
+envref run [-f FILE]... [--override] -- cmd args   # exec cmd with the resolved environment
+envref export [-f FILE]... [--format shell|dotenv|json]
+envref check [-f FILE]...                          # resolve and report per key; never prints a value
+envref doctor                                      # installed resolvers and whether each can run here
+envref op save-password [--account SHORTHAND]      # store the 1Password password in Keychain for Touch ID sign-in
+```
+
+`-f` repeats. The first file to set a name wins, so `-f .env.refs -f .env`
+lets a local `.env` fill in what the shared references file lacks without
+overriding it. Default is `.env`.
+
+## Library
+
+```python
+import envref
+
+values = envref.load(".env.refs", ".env")        # dict, also exported into os.environ
+values = envref.load(".env", export=False)       # dict only
+envref.load(".env", override=True)               # let the file win over existing variables
+
+entries = envref.parse(text)                     # list[Entry], refs identified
+envref.resolve(entries, registry={"op": ...})    # bring your own resolvers
+```
+
+Errors are typed: `UnknownScheme`, `ResolverUnavailable` (the backend cannot
+run here: no `op`, not macOS, no token) and `ResolveError` (which references
+failed and why, in `.failures`). All derive from `EnvrefError`.
+
+## Writing a resolver
+
+```python
+# myenvref/aws.py
+class SecretsManagerResolver:
+    scheme = "awssm"
+
+    def resolve(self, refs: list[str]) -> dict[str, str]:
+        # refs are every awssm:// reference in the file, deduplicated: batch them.
+        ...
+        return {ref: value for ref, value in ...}
+
+    def doctor(self) -> str:          # optional, shown by `envref doctor`
+        return "ok"
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."envref.resolvers"]
+awssm = "myenvref.aws:SecretsManagerResolver"
+```
+
+Installed next to `envref`, `{{ awssm://… }}` now resolves. An entry point
+with a built-in's name replaces it.
+
+## Prior art
+
+[`teller`](https://github.com/tellerops/teller) and
+[`novops`](https://github.com/PierreBeucher/novops) are multi-provider too,
+with the mapping in a YAML config rather than inline in the `.env`.
+[`berglas`](https://github.com/GoogleCloudPlatform/berglas) has inline
+`sm://` references, for Google Cloud only. [`dotenvx`](https://dotenvx.com)
+encrypts the values rather than referencing them. `op inject` is what the
+`{{ }}` syntax comes from, and any `.env.op` written for it is a valid
+`envref` file.
+
+## Status
+
+Extracted in November 2026 from a private automation repository where the
+1Password path had run daily for a year, on a laptop and in scheduled
+containers. The other resolvers are new. macOS and Linux; Keychain and Touch
+ID are macOS only.
+
+MIT.

envref-0.1.0/README.md

@@ -0,0 +1,158 @@
+# envref
+
+A `.env` where any value can be a reference into a secret store, resolved
+when the file is loaded.
+
+```dotenv
+# .env
+ATTIO_KEY={{ op://work/Attio/api_key }}          # 1Password
+DB_PASSWORD={{ keychain://myapp/postgres }}      # macOS Keychain
+TLS_KEY={{ file://~/.ssh/server.pem }}           # a file's contents
+GITHUB_TOKEN={{ env://GH_TOKEN }}                # another variable
+REGION=eu-north-1                                # a plain literal
+```
+
+```bash
+envref run -- python app.py       # app.py sees ATTIO_KEY=<the real key>
+```
+
+```python
+import envref
+envref.load(".env")               # same thing, into os.environ
+```
+
+The file holds no secrets, so it can be committed. The scheme of each
+reference picks the backend. Four ship built in, and your own takes one class
+and one entry point.
+
+## Why
+
+`op run`, `berglas exec`, `chamber exec` and friends each do this for one
+store. Teams rarely have one store. A laptop has 1Password and Keychain, a
+container has a service account, a CI job has its own vault, and the same
+`.env` should work in all three with the same names. `envref` keeps the file
+format (plain dotenv, plus `{{ scheme://… }}`), and makes the backend a plugin.
+
+## Install
+
+```bash
+uv tool install envref            # CLI
+pip install envref                # library, zero dependencies
+pip install 'envref[op]'          # + 1Password service-account support (SDK)
+```
+
+The `op://` CLI path needs only the [`op`](https://developer.1password.com/docs/cli/)
+binary on PATH, no extra.
+
+## Resolvers
+
+| Scheme | Resolves to | Needs |
+| --- | --- | --- |
+| `op://vault/item/field` | a 1Password field | `op` CLI, or `OP_SERVICE_ACCOUNT_TOKEN` + `envref[op]` |
+| `keychain://service/account` | a macOS Keychain generic password | macOS |
+| `file://path` | the file's contents, one trailing newline dropped | — |
+| `env://NAME` | another environment variable | — |
+
+A value written as `{{ scheme://… }}` is always a reference, and an unknown
+scheme is an error. A bare `scheme://…` without braces is resolved only when a
+resolver for that scheme is installed, so `URL=https://example.com` stays a
+literal and `KEY=op://vault/item/field` still works for files written for
+`op read`.
+
+### 1Password in detail
+
+Two modes, chosen by the environment:
+
+- **Service account** when `OP_SERVICE_ACCOUNT_TOKEN` is set. The SDK resolves
+  every reference in one round trip. No binary, no biometrics. For containers.
+- **CLI** otherwise. Every reference goes through one `op inject`. If `op` has
+  no session, `envref` signs in: the account password comes from Keychain
+  behind Touch ID if you stored it with `envref op save-password`, or from the
+  terminal if not. The session token is cached in `~/.cache/envref/` so a
+  burst of commands costs one sign-in; concurrent processes share it through
+  a lock. See [SECURITY.md](SECURITY.md) for what that cache means.
+
+Session caching presumes "biometric unlock for the CLI" is off in the
+1Password app. With it on, `op` prompts per invocation and `envref` holds no
+token.
+
+Knobs: `OP_ACCOUNT` (shorthand, when several accounts are signed in),
+`ENVREF_OP_SESSION_TTL` (seconds, default 1500, `0` disables the cache),
+`ENVREF_OP_KEYCHAIN_SERVICE` / `ENVREF_OP_KEYCHAIN_ACCOUNT` (where the
+password is stored, default `envref-op` / the account's email).
+
+## CLI
+
+```bash
+envref run [-f FILE]... [--override] -- cmd args   # exec cmd with the resolved environment
+envref export [-f FILE]... [--format shell|dotenv|json]
+envref check [-f FILE]...                          # resolve and report per key; never prints a value
+envref doctor                                      # installed resolvers and whether each can run here
+envref op save-password [--account SHORTHAND]      # store the 1Password password in Keychain for Touch ID sign-in
+```
+
+`-f` repeats. The first file to set a name wins, so `-f .env.refs -f .env`
+lets a local `.env` fill in what the shared references file lacks without
+overriding it. Default is `.env`.
+
+## Library
+
+```python
+import envref
+
+values = envref.load(".env.refs", ".env")        # dict, also exported into os.environ
+values = envref.load(".env", export=False)       # dict only
+envref.load(".env", override=True)               # let the file win over existing variables
+
+entries = envref.parse(text)                     # list[Entry], refs identified
+envref.resolve(entries, registry={"op": ...})    # bring your own resolvers
+```
+
+Errors are typed: `UnknownScheme`, `ResolverUnavailable` (the backend cannot
+run here: no `op`, not macOS, no token) and `ResolveError` (which references
+failed and why, in `.failures`). All derive from `EnvrefError`.
+
+## Writing a resolver
+
+```python
+# myenvref/aws.py
+class SecretsManagerResolver:
+    scheme = "awssm"
+
+    def resolve(self, refs: list[str]) -> dict[str, str]:
+        # refs are every awssm:// reference in the file, deduplicated: batch them.
+        ...
+        return {ref: value for ref, value in ...}
+
+    def doctor(self) -> str:          # optional, shown by `envref doctor`
+        return "ok"
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."envref.resolvers"]
+awssm = "myenvref.aws:SecretsManagerResolver"
+```
+
+Installed next to `envref`, `{{ awssm://… }}` now resolves. An entry point
+with a built-in's name replaces it.
+
+## Prior art
+
+[`teller`](https://github.com/tellerops/teller) and
+[`novops`](https://github.com/PierreBeucher/novops) are multi-provider too,
+with the mapping in a YAML config rather than inline in the `.env`.
+[`berglas`](https://github.com/GoogleCloudPlatform/berglas) has inline
+`sm://` references, for Google Cloud only. [`dotenvx`](https://dotenvx.com)
+encrypts the values rather than referencing them. `op inject` is what the
+`{{ }}` syntax comes from, and any `.env.op` written for it is a valid
+`envref` file.
+
+## Status
+
+Extracted in November 2026 from a private automation repository where the
+1Password path had run daily for a year, on a laptop and in scheduled
+containers. The other resolvers are new. macOS and Linux; Keychain and Touch
+ID are macOS only.
+
+MIT.

envref-0.1.0/SECURITY.md

@@ -0,0 +1,52 @@
+# Security
+
+## Threat model
+
+`envref` moves secrets from a store into a process's environment. It never
+stores a secret itself, with one deliberate exception described below. What
+you should know before trusting it:
+
+**The file is not secret.** An `.env` of references holds the names of your
+vaults and items, which is an inventory of what you use. Treat it like source
+code: fine in a private repository, think twice in a public one.
+
+**Resolved values live in the environment of the process you start.** Any
+child process inherits them, and on most systems any process running as the
+same user can read another process's environment. This is true of every
+secrets-to-env tool; `envref` adds nothing and removes nothing here.
+
+**The 1Password CLI resolver caches a session token.** With "biometric unlock
+for the CLI" turned off in 1Password, `op signin` returns a session token that
+is good for about 30 minutes of inactivity. `envref` writes it to
+`$XDG_CACHE_HOME/envref/op-session.json` (default `~/.cache/envref/`), mode
+0600, and re-uses it so a burst of commands costs one sign-in rather than one
+per command. The trade: during that window, any process running as your user
+can read the token and, with it, every item the account can see, with no
+Touch ID. If that is unacceptable for your machine, set
+`ENVREF_OP_SESSION_TTL=0` to disable the cache, or turn biometric CLI unlock
+on in 1Password, in which case `op` prompts per invocation and `envref` never
+holds a token.
+
+**The 1Password account password may live in macOS Keychain.** `envref op
+save-password` stores it as a generic password item, so that an expired
+session can be renewed without typing. Reading it goes through a small Swift
+helper that requires Touch ID (`LAContext`, biometrics only) before calling
+`security find-generic-password`. Without Touch ID hardware, or without
+`swiftc`, the read falls back to `security` alone, which shows the system's
+own authorisation dialog. The helper is compiled from source on first use
+into the cache directory; it is not shipped as a binary.
+
+**The service-account path holds a bearer token in the environment.** That is
+how 1Password service accounts work. Scope the account to one vault that holds
+only what the job needs, so a leaked token reads five items rather than every
+credential you own. `envref` fails loudly when a reference points outside the
+granted vault rather than falling back to another method.
+
+**Resolvers are code.** A third-party resolver installed through the
+`envref.resolvers` entry point runs with your privileges and sees every
+reference of its scheme. Install resolvers the way you install any dependency.
+
+## Reporting
+
+Open a private security advisory on GitHub, or email the address on the
+author's GitHub profile. Please do not open a public issue for a vulnerability.

envref-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "envref"
+version = "0.1.0"
+description = "A .env where any value can be a reference into a secret store, resolved at load time. op://, keychain://, file://, env://, and your own."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Sebastian Haglund" }]
+keywords = ["dotenv", "secrets", "1password", "keychain", "environment", "twelve-factor"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.optional-dependencies]
+# 1Password service accounts (unattended, no `op` binary). The CLI path needs
+# nothing but the `op` binary on PATH.
+op = ["onepassword-sdk>=0.3; python_version < '3.14'"]
+
+[project.urls]
+Homepage = "https://github.com/sebaheg/envref"
+Repository = "https://github.com/sebaheg/envref"
+Issues = "https://github.com/sebaheg/envref/issues"
+Changelog = "https://github.com/sebaheg/envref/blob/main/CHANGELOG.md"
+
+[project.scripts]
+envref = "envref.cli:main"
+
+# Third-party resolvers register here: `name` is the URL scheme, the value a
+# `module:Class` whose instances have `.resolve(refs) -> dict[str, str]`.
+[project.entry-points."envref.resolvers"]
+env = "envref.resolvers.env:EnvResolver"
+file = "envref.resolvers.file:FileResolver"
+keychain = "envref.resolvers.keychain:KeychainResolver"
+op = "envref.resolvers.op:OnePasswordResolver"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envref"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/envref", "tests", "README.md", "LICENSE", "CHANGELOG.md", "SECURITY.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

envref-0.1.0/src/envref/__init__.py

@@ -0,0 +1,40 @@
+"""envref — a .env where any value can be a reference into a secret store.
+
+    ATTIO_KEY={{ op://vault/Attio/api_key }}
+    DB_PASSWORD={{ keychain://myapp/db }}
+    TLS_KEY={{ file://~/.ssh/server.pem }}
+    REGION=eu-north-1
+
+    >>> import envref
+    >>> envref.load(".env")          # resolves every reference, exports the rest
+
+The scheme of a reference picks the resolver. Four ship built in (`op`,
+`keychain`, `file`, `env`); others register through the `envref.resolvers`
+entry-point group.
+"""
+
+from envref.core import (
+    EnvrefError,
+    Resolver,
+    ResolveError,
+    ResolverUnavailable,
+    UnknownScheme,
+    load,
+    resolve,
+)
+from envref.parse import Entry, parse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Entry",
+    "EnvrefError",
+    "ResolveError",
+    "Resolver",
+    "ResolverUnavailable",
+    "UnknownScheme",
+    "__version__",
+    "load",
+    "parse",
+    "resolve",
+]