Metadata-Version: 2.5
Name: omraade
Version: 1.0.2
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
```

The application itself can also be configured via environment variables, which have to start with the prefix
`OMRAADE_`, followed by the option, with all parts of the variable separated by underscores (`_`). For example, to
provide the database path via ENV, the following invocations are equivalent:

```shell
# Generic ENV via `export` followed by application call
export OMRAADE_DATABASE=/dev/shm/example.kdbx
omraade run --password "Example password" -- printenv
# In-line ENV during application call
OMRAADE_DATABASE=/dev/shm/example.kdbx omraade run --password "Example password" -- printenv
# Explicit command-line argument during application call
omraade run --database /dev/shm/example.kdbx --password "Example password" -- printenv
```

If both an environment variable and a command-line argument are present, CLI arguments take precedence and override
applicable ENVs.

### 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 its 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 arbitrary 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 (if no fragment is
specified, `omraade` will return the `password` attribute for Keepass secrets).

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.
