Metadata-Version: 2.5
Name: omraade
Version: 1.0.0
Summary: Inject ENV secrets from secure sources
Project-URL: Repository, https://gitlab.com/rmk2/omraade
Author-email: rmk2 <ryko@rmk2.org>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.14
Requires-Dist: pykeepass~=4.2
Description-Content-Type: text/markdown

# omraade

Omraade ([ɔmroːdeː], normally spelled område), from the Swedish word for "area", is an application that injects secrets
defined via references in environment variables securely from a backend secret store. By storing references to a
secret's location within a secret store rather than its content itself, a secret's actual content cannot simply be read
from the environment (or an .env file etc.) by other applications. Instead, `omraade` then requests the referenced
content from the secret store.

The most common usage for injection is running another command while only resolving secret references during the
command's execution (i.e., during its runtime), discarding the resolved environment afterwards.

## Usage

This project provides a command-line application `omraade`, either as a Python application, or optionally as a compiled
binary independent of a local Python environment.

The application supports a number of command-line arguments, which can be listed via `--help`. The application uses
subcommands to dispatch specific functionality, and subcommand-specific arguments can be listed via
`<subcommand> --help`:

```
usage: app.py [-h] [--scheme SCHEME] [--backend {keepass}] [-d PATH] [-P PASSWORD] [-K KEYFILE] {run} ...

options:
  -h, --help            show this help message and exit

config:
  --scheme SCHEME       Omraade URI scheme, default: omraade
  --backend {keepass}   Omraade secret store backend, default: keepass

keepass:
  -d, --database PATH   Keepass database path
  -P, --password PASSWORD
                        Keepass database password
  -K, --keyfile KEYFILE
                        Keepass database keyfile

subcommands:
  {run}
    run
```

### Example

Let's assume that secrets are stored in a local [Keepass](https://keepass.info/) database. The database's filename can
be specified via `--database <filename>`, and it's password via `--password`. With this information,
`omraade` is able to find and decrypt the database.

References to secrets contained within this database can then be stored as environment variables, referencing the
`omraade` URI scheme, e.g.:

```
export TEST_FOO="omraade:/First/Second/Push#token"
```

This instructs `omraade` to look for a secret with the title `Push`, located in the nested groups `First` -> `Second`.
The URI fragment further instructs `omraade` to return the value from the `token` attribute (or it's default `password`
attribute if unspecified).

In order to wrap the command `printenv` by running
`omraade run --database <filename> --password <password> -- printenv`, the
`omraade` application first unlocks the relevant database, then replaces all valid `omraade` URIs with their resolved
values from the Keepass database, and sets this as the active environment for the `printenv` command. The environment is
not exported, so as soon as the wrapped command returns, `omraade` terminates, thus both discarding the resolved values
in its temporary environment and closing the open database again.

## Development

This project is written in python3. It uses `uv` for dependency management, `pytest` for testing, `black` for
formatting, and `nuitka` for binary compilation.
