mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 10:59:59 +00:00
kevinveenbirkenbachandClaude Opus 5
c55f508e05
The cosmos generator linked a consumer to its provider only through an '<role>' in group_names reference or an explicit provides: name. A hard dependency has neither -- pinning the provider on unconditionally is exactly what removes the Jinja reference the generator was reading -- so web-svc-asset's bond to web-svc-file vanished from the diagram the moment it became binding. Match a service key against the provider's own primary key from the registry, in both directions. Services the role turns off drew a solid 1:1 edge, claiming a mandatory relationship for something that carries nothing at deploy time. They now render as a red 0..0 edge; edge merging gained a real precedence so a provider consumed through two keys stays live when only one is off. Named colour, not hex: a '#' opens an entity code in the mermaid lexer and turns the whole diagram into a parse error on GitHub. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
156 lines
3.9 KiB
Markdown
156 lines
3.9 KiB
Markdown
# sys-token-store
|
|
|
|
## Description
|
|
|
|
`sys-token-store` is a lightweight Ansible helper role for **resolving and persisting per-user application tokens** in a unified and idempotent way.
|
|
|
|
It provides a **single source of truth** for application tokens while keeping runtime usage simple and consistent across roles.
|
|
|
|
The role is intentionally **not a secret generator**.
|
|
It only **stores and propagates tokens that already exist** (e.g. created by bootstrap processes or provided externally).
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This role stores and manages per-user application tokens in a local YAML store file (idempotent read/write helpers).
|
|
|
|
## Cosmos
|
|
|
|
The diagram places sys-token-store in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph role [sys-token-store 💻]
|
|
svc_token_store["token-store"]
|
|
end
|
|
```
|
|
|
|
Solid `1:1` edges are fixed relationships; dashed `0..1` edges are conditional (enabled only in matching deployments); red `0..0` edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in `meta/main.yml`.
|
|
|
|
## Features
|
|
|
|
- **Automated provisioning:** Configured by Ansible without manual steps.
|
|
|
|
## Core Principles
|
|
|
|
- **Single logic for all roles**
|
|
- Always resolve tokens as: **`users → token store → empty`**
|
|
- **No implicit token generation**
|
|
- Empty tokens are rejected
|
|
- **Idempotent persistence**
|
|
- Store file is only rewritten when content actually changes
|
|
- **Lookup-based runtime resolution**
|
|
- Tokens are resolved through `lookup('users')`, which hydrates from the store on each lookup call
|
|
- **Case-sensitive keys**
|
|
- User keys and application IDs must match exactly
|
|
|
|
---
|
|
|
|
## Token Resolution Order
|
|
|
|
When resolving a token, the following order is used:
|
|
|
|
1. `lookup('users', '<user>').tokens.<application_id>`
|
|
2. Token store file (`tokens.yml`)
|
|
3. Empty string (`''`)
|
|
|
|
No automatic fallback generation happens.
|
|
|
|
---
|
|
|
|
## Store Format
|
|
|
|
Tokens are stored in a single YAML file:
|
|
|
|
```yaml
|
|
users:
|
|
administrator:
|
|
tokens:
|
|
web-app-matomo: "46e50b0eb52d0d141a7d6cf9b3d0b3e2"
|
|
```
|
|
|
|
Default location:
|
|
|
|
```
|
|
/var/lib/infinito/secrets/tokens.yml
|
|
```
|
|
|
|
Permissions are restricted to root by default.
|
|
|
|
---
|
|
|
|
## Provided Tasks
|
|
|
|
### `write.yml`
|
|
|
|
Persists a token so it is available through the `users` lookup on subsequent reads.
|
|
|
|
This is the **canonical way** to store tokens.
|
|
|
|
**Input**
|
|
|
|
- `sys_token_store_user_key`
|
|
- `sys_token_store_app`
|
|
- `sys_token_store_token` (must be non-empty)
|
|
|
|
**Effects**
|
|
|
|
- Updates the token store file (idempotent)
|
|
- Makes the token available via `lookup('users', '<user>').tokens['<app>']`
|
|
- Exports `sys_token_store_token`
|
|
|
|
Empty tokens are rejected explicitly.
|
|
|
|
---
|
|
|
|
## Usage Examples
|
|
|
|
---
|
|
|
|
### Persist a token
|
|
|
|
```yaml
|
|
- include_role:
|
|
name: sys-token-store
|
|
tasks_from: write.yml
|
|
vars:
|
|
sys_token_store_user_key: administrator
|
|
sys_token_store_app: web-app-matomo
|
|
sys_token_store_token: "{{ matomo_token_value }}"
|
|
```
|
|
|
|
After this, the token is available as:
|
|
|
|
```yaml
|
|
lookup('users', 'administrator').tokens['web-app-matomo']
|
|
```
|
|
|
|
---
|
|
|
|
## What This Role Does *Not* Do
|
|
|
|
- ❌ No token generation
|
|
- ❌ No encryption
|
|
- ❌ No user management
|
|
- ❌ No application-specific logic
|
|
|
|
It is a **generic infrastructure helper**.
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
- Keep all user and application keys lowercase
|
|
- Use stable `application_id` values
|
|
- Let application roles create tokens
|
|
- Let `sys-token-store` handle persistence
|
|
|
|
---
|
|
|
|
## Credits
|
|
|
|
Implemented by **[Kevin Veen-Birkenbach](https://www.veen.world)**.
|
|
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code) and maintained by [Kevin Veen-Birkenbach](https://www.veen.world).
|
|
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).
|