feat(studio): Welcome page Phase B — embedded doc reader (v0.38.0)
Second slice of the Welcome surface. Operator-facing
documentation now lives inside Studio as bundled assets and
renders inline via a modal sheet — no browser, no external
link, air-gap-tauglich.
- Four operator-readable explainers under `assets/docs/`,
each with an EN + DE pair:
architecture[_de].md — Hub / Module / Flow + how they fit
security[_de].md — sandbox model, declared perms,
operator ceiling
audit[_de].md — hash-chained log, WORM-1 mechanics,
`fai admin verify-events`
flows[_de].md — flow YAML, templating reference,
extract→summarize example
These are short (≈ 300-500 words each), operator-shaped
prose. Not copies of the architecture docs in
fai_platform/docs/architecture/ — those are
contributor-dense.
- pubspec.yaml declares `assets/docs/` so the markdown ships
inside the Studio binary. Air-gap deployments read them
with no network access.
- New `_DocReaderSheet` modal: 85 %-of-viewport bottom sheet,
drag handle + title bar with the doc icon and close button,
scrollable Markdown body styled to match Studio chrome.
Loads `assets/docs/<slug>_<locale>.md` first, falls back to
the EN file. Locale comes from
`Localizations.localeOf(context)`.
- `_DocsRow` on the Welcome page sits below the trust-posture
deck. Two-column grid on ≥ 640 dp, single column below.
Each card is icon + title + one-line blurb + chevron;
click opens the reader sheet for that slug.
- 12 new ARB keys for the docs section (header, blurb, four
card titles + blurbs, close button, error message).
- 4 new icons reused: `account_tree_outlined` (architecture),
`shield_outlined` (security), `verified_outlined` (audit),
`alt_route_outlined` (flows).
Implements Phase B of `docs/landing-page-design.md`. Phase C
(live getting-started checklist with persistent state) is the
last remaining slice.
Signed-off-by: flemming-it <stefan.a.flemming@googlemail.com>
This commit is contained in:
flemming-it
parent
3a7d0e74ad
commit
3b07d340d5
16 changed files with 1051 additions and 3 deletions
51
assets/docs/architecture.md
Normal file
51
assets/docs/architecture.md
Normal file
|
|
@ -0,0 +1,51 @@
|
||||||
|
# Architecture in one paragraph
|
||||||
|
|
||||||
|
F∆I has three concepts you'll meet everywhere: **Hub**,
|
||||||
|
**Module**, **Flow**.
|
||||||
|
|
||||||
|
**The hub** is a single Rust binary called `fai`. It runs as a
|
||||||
|
gRPC server, loads modules, executes flows, and writes events
|
||||||
|
to a SQLite database. One binary, no Docker, no message broker,
|
||||||
|
no cluster. You can run it on a laptop, a Raspberry Pi, or a
|
||||||
|
locked-down KRITIS server — same artefact every time.
|
||||||
|
|
||||||
|
**A module** is a small WebAssembly component that does one
|
||||||
|
thing well. Modules are sandboxed: each one declares the
|
||||||
|
network endpoints, files, and environment variables it needs,
|
||||||
|
and the hub enforces that list. A module that doesn't ask for
|
||||||
|
network access can't reach the network. Modules ship as `.fai`
|
||||||
|
bundles with a CycloneDX SBOM and a sigstore signature.
|
||||||
|
|
||||||
|
**A flow** is a YAML file with three top-level keys:
|
||||||
|
`inputs:`, `steps:`, `outputs:`. Steps run in declared order,
|
||||||
|
each step calls one module, and outputs from one step can feed
|
||||||
|
inputs of the next. Flows are deterministic — same inputs
|
||||||
|
produce the same audit trail.
|
||||||
|
|
||||||
|
## How the pieces fit
|
||||||
|
|
||||||
|
```
|
||||||
|
Studio ──gRPC──▶ Hub ──loads──▶ Module (WASM)
|
||||||
|
│
|
||||||
|
├──executes──▶ Flow (YAML chain of modules)
|
||||||
|
│
|
||||||
|
└──writes────▶ Audit log (hash-chained, in
|
||||||
|
SQLite; WORM-1 by construction)
|
||||||
|
```
|
||||||
|
|
||||||
|
## What you don't need
|
||||||
|
|
||||||
|
- No container runtime. The hub doesn't shell out to Docker
|
||||||
|
or Podman. Modules are WASM components loaded in-process.
|
||||||
|
- No external database. SQLite ships with the hub.
|
||||||
|
- No background services. One process; restart with
|
||||||
|
`fai daemon restart` — see Doctor → Daemon control.
|
||||||
|
|
||||||
|
## Where to go next in this app
|
||||||
|
|
||||||
|
- **Store** to discover modules and federated MCP / n8n
|
||||||
|
capabilities, install them in one click.
|
||||||
|
- **Flows** to run the sample flows that ship with the hub
|
||||||
|
(e.g. `extract-summarize`).
|
||||||
|
- **Audit** to see every event the hub recorded — the
|
||||||
|
hash-chained log is the platform's source of truth.
|
||||||
55
assets/docs/architecture_de.md
Normal file
55
assets/docs/architecture_de.md
Normal file
|
|
@ -0,0 +1,55 @@
|
||||||
|
# Architektur in einem Absatz
|
||||||
|
|
||||||
|
F∆I hat drei Konzepte, die dir überall begegnen: **Hub**,
|
||||||
|
**Modul**, **Flow**.
|
||||||
|
|
||||||
|
**Der Hub** ist ein einzelnes Rust-Binary namens `fai`. Er
|
||||||
|
läuft als gRPC-Server, lädt Module, führt Flows aus und
|
||||||
|
schreibt Ereignisse in eine SQLite-Datenbank. Ein Binary, kein
|
||||||
|
Docker, kein Message-Broker, kein Cluster. Du kannst ihn auf
|
||||||
|
einem Laptop, einem Raspberry Pi oder einem abgeriegelten
|
||||||
|
KRITIS-Server laufen lassen — immer dasselbe Artefakt.
|
||||||
|
|
||||||
|
**Ein Modul** ist eine kleine WebAssembly-Komponente, die eine
|
||||||
|
Sache gut macht. Module laufen in einer Sandbox: jedes deklariert
|
||||||
|
die Netzwerk-Endpunkte, Dateien und Umgebungsvariablen, die es
|
||||||
|
braucht, und der Hub setzt diese Liste durch. Ein Modul, das
|
||||||
|
keinen Netzwerkzugriff anfordert, kann das Netzwerk nicht
|
||||||
|
erreichen. Module kommen als `.fai`-Bundles mit CycloneDX-SBOM
|
||||||
|
und sigstore-Signatur.
|
||||||
|
|
||||||
|
**Ein Flow** ist eine YAML-Datei mit drei Top-Level-Schlüsseln:
|
||||||
|
`inputs:`, `steps:`, `outputs:`. Schritte laufen in deklarierter
|
||||||
|
Reihenfolge, jeder Schritt ruft ein Modul auf, und Ausgaben
|
||||||
|
eines Schritts können in die Eingaben des nächsten fließen.
|
||||||
|
Flows sind deterministisch — gleiche Eingaben erzeugen dieselbe
|
||||||
|
Audit-Spur.
|
||||||
|
|
||||||
|
## Wie die Teile zusammenpassen
|
||||||
|
|
||||||
|
```
|
||||||
|
Studio ──gRPC──▶ Hub ──lädt──▶ Modul (WASM)
|
||||||
|
│
|
||||||
|
├──führt aus──▶ Flow (YAML-Verkettung von Modulen)
|
||||||
|
│
|
||||||
|
└──schreibt────▶ Audit-Log (hash-verkettet, in
|
||||||
|
SQLite; WORM-1 qua Konstruktion)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Was du nicht brauchst
|
||||||
|
|
||||||
|
- Keine Container-Runtime. Der Hub ruft kein Docker oder Podman.
|
||||||
|
Module sind WASM-Komponenten, in-process geladen.
|
||||||
|
- Keine externe Datenbank. SQLite kommt mit dem Hub.
|
||||||
|
- Keine Hintergrunddienste. Ein Prozess; Neustart per
|
||||||
|
`fai daemon restart` — siehe Diagnose → Daemon-Steuerung.
|
||||||
|
|
||||||
|
## Wo es in dieser App weitergeht
|
||||||
|
|
||||||
|
- **Store** zum Entdecken von Modulen und föderierten MCP/n8n-
|
||||||
|
Fähigkeiten, Installation in einem Klick.
|
||||||
|
- **Flows** zum Ausführen der Beispiel-Flows, die mit dem Hub
|
||||||
|
kommen (z.B. `extract-summarize`).
|
||||||
|
- **Protokoll** für jedes vom Hub aufgezeichnete Ereignis — das
|
||||||
|
hash-verkettete Log ist die Single Source of Truth der
|
||||||
|
Plattform.
|
||||||
69
assets/docs/audit.md
Normal file
69
assets/docs/audit.md
Normal file
|
|
@ -0,0 +1,69 @@
|
||||||
|
# Tamper-evident audit log
|
||||||
|
|
||||||
|
Every action the hub takes goes into one append-only event
|
||||||
|
log. Module installs, flow runs, approval decisions, channel
|
||||||
|
switches, daemon restarts — all recorded with the same shape.
|
||||||
|
|
||||||
|
## What an event looks like
|
||||||
|
|
||||||
|
```
|
||||||
|
timestamp: 2026-05-08T14:32:11Z
|
||||||
|
event_id: ev_01H...
|
||||||
|
event_type: flow.completed
|
||||||
|
flow_name: extract-summarize
|
||||||
|
flow_execution: fe_01H...
|
||||||
|
duration_ms: 1240
|
||||||
|
module_name: text.summarize
|
||||||
|
module_version: 0.1.0
|
||||||
|
detail: { engine: "ollama", model_name: "gemma3:4b",
|
||||||
|
model_digest: "sha256:..." }
|
||||||
|
prev_event_sha256: 6f4e...8b5f
|
||||||
|
```
|
||||||
|
|
||||||
|
The `prev_event_sha256` field is the key. Every new event
|
||||||
|
hashes its content together with the previous event's hash. To
|
||||||
|
falsify event N, an attacker would need to rewrite every event
|
||||||
|
from N+1 onwards — and the chain head would no longer match
|
||||||
|
what the operator's last verification recorded.
|
||||||
|
|
||||||
|
## What "WORM-1" means
|
||||||
|
|
||||||
|
WORM-1 is our first WORM (write-once-read-many) tier:
|
||||||
|
|
||||||
|
- **Append-only**: the hub never deletes individual events.
|
||||||
|
The CLI / RPC has a single batch operation,
|
||||||
|
`clear_event_log`, which wipes the channel and seeds a
|
||||||
|
`chain.reset` marker carrying reviewer + reason. Refused on
|
||||||
|
beta / production channels.
|
||||||
|
- **Tamper-evident**: the chain reveals any retroactive edit.
|
||||||
|
Verification runs end-to-end on every Doctor-page load and
|
||||||
|
via `fai admin verify-events`.
|
||||||
|
- **Self-contained**: SQLite + chain hash is enough; no
|
||||||
|
external WORM sink needed.
|
||||||
|
|
||||||
|
WORM-2 (Linux append-only file attribute) and WORM-3 (external
|
||||||
|
WORM sink) are roadmap items, not yet shipped.
|
||||||
|
|
||||||
|
## What you'll see in this app
|
||||||
|
|
||||||
|
- **Doctor → Event log**: live "chain intact" / "tamper
|
||||||
|
detected" indicator with verified-event count. Click "Verify
|
||||||
|
now" for an explicit re-check.
|
||||||
|
- **Audit page**: live stream of recent events with filter
|
||||||
|
chips (flow / step / module). Click any row to see the full
|
||||||
|
event JSON.
|
||||||
|
- **Doctor → Daemon files → Audit-DB**: reveals the SQLite file
|
||||||
|
in your file manager.
|
||||||
|
|
||||||
|
## Reading the chain by hand
|
||||||
|
|
||||||
|
If you want to verify outside Studio:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
fai admin verify-events
|
||||||
|
# Prints "Hash chain intact: N events verified" or names the
|
||||||
|
# first event whose hash mismatches.
|
||||||
|
```
|
||||||
|
|
||||||
|
The chain is the source of truth — every other audit-related
|
||||||
|
piece of UI in Studio reads from it.
|
||||||
70
assets/docs/audit_de.md
Normal file
70
assets/docs/audit_de.md
Normal file
|
|
@ -0,0 +1,70 @@
|
||||||
|
# Manipulationssicheres Audit-Log
|
||||||
|
|
||||||
|
Jede Aktion des Hubs landet in einem append-only Event-Log.
|
||||||
|
Modul-Installationen, Flow-Läufe, Freigabe-Entscheidungen,
|
||||||
|
Kanal-Wechsel, Daemon-Neustarts — alle mit derselben Form
|
||||||
|
aufgezeichnet.
|
||||||
|
|
||||||
|
## So sieht ein Event aus
|
||||||
|
|
||||||
|
```
|
||||||
|
timestamp: 2026-05-08T14:32:11Z
|
||||||
|
event_id: ev_01H...
|
||||||
|
event_type: flow.completed
|
||||||
|
flow_name: extract-summarize
|
||||||
|
flow_execution: fe_01H...
|
||||||
|
duration_ms: 1240
|
||||||
|
module_name: text.summarize
|
||||||
|
module_version: 0.1.0
|
||||||
|
detail: { engine: "ollama", model_name: "gemma3:4b",
|
||||||
|
model_digest: "sha256:..." }
|
||||||
|
prev_event_sha256: 6f4e...8b5f
|
||||||
|
```
|
||||||
|
|
||||||
|
Das `prev_event_sha256`-Feld ist der Kern. Jedes neue Event
|
||||||
|
hasht seinen Inhalt zusammen mit dem Hash des vorherigen.
|
||||||
|
Wer Event N fälschen will, müsste alle Events ab N+1 neu
|
||||||
|
schreiben — und der Ketten-Kopf würde nicht mehr zu dem
|
||||||
|
passen, was der Operator zuletzt verifiziert hat.
|
||||||
|
|
||||||
|
## Was „WORM-1" bedeutet
|
||||||
|
|
||||||
|
WORM-1 ist unsere erste WORM-Stufe (write-once-read-many):
|
||||||
|
|
||||||
|
- **Append-only**: Der Hub löscht keine einzelnen Events. Die
|
||||||
|
CLI/RPC hat eine einzige Batch-Operation,
|
||||||
|
`clear_event_log`, die den Kanal komplett leert und einen
|
||||||
|
`chain.reset`-Marker mit Prüfer + Begründung seedet. Auf
|
||||||
|
beta-/production-Kanälen verweigert.
|
||||||
|
- **Manipulationssicher**: Die Kette zeigt jede nachträgliche
|
||||||
|
Änderung. Verifikation läuft bei jedem Doctor-Page-Load
|
||||||
|
komplett und über `fai admin verify-events`.
|
||||||
|
- **Selbst-tragend**: SQLite + Ketten-Hash genügen; keine
|
||||||
|
externe WORM-Senke nötig.
|
||||||
|
|
||||||
|
WORM-2 (Linux append-only Datei-Attribut) und WORM-3 (externe
|
||||||
|
WORM-Senke) sind Roadmap-Punkte, noch nicht ausgeliefert.
|
||||||
|
|
||||||
|
## Was du in dieser App siehst
|
||||||
|
|
||||||
|
- **Diagnose → Audit-Log**: Live-Anzeige „Kette intakt" /
|
||||||
|
„Manipulation erkannt" mit Anzahl verifizierter Events.
|
||||||
|
„Jetzt prüfen" für explizite Neu-Verifikation.
|
||||||
|
- **Protokoll-Seite**: Live-Stream der letzten Events mit
|
||||||
|
Filter-Chips (Flow / Step / Modul). Klick auf eine Zeile
|
||||||
|
öffnet das vollständige Event-JSON.
|
||||||
|
- **Diagnose → Daemon-Dateien → Audit-DB**: Zeigt die SQLite-
|
||||||
|
Datei im Datei-Manager.
|
||||||
|
|
||||||
|
## Die Kette per Hand prüfen
|
||||||
|
|
||||||
|
Wer außerhalb von Studio verifizieren will:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
fai admin verify-events
|
||||||
|
# Druckt „Hash-Kette intakt: N Events verifiziert" oder nennt
|
||||||
|
# das erste Event, dessen Hash nicht passt.
|
||||||
|
```
|
||||||
|
|
||||||
|
Die Kette ist die Single Source of Truth — jede andere Audit-
|
||||||
|
bezogene UI in Studio liest aus ihr.
|
||||||
90
assets/docs/flows.md
Normal file
90
assets/docs/flows.md
Normal file
|
|
@ -0,0 +1,90 @@
|
||||||
|
# Flow composition
|
||||||
|
|
||||||
|
A flow is a YAML file with three top-level keys: `inputs:`,
|
||||||
|
`steps:`, `outputs:`. Read top to bottom, it tells the hub
|
||||||
|
what kind of inputs to accept, which modules to call in what
|
||||||
|
order, and what to surface as the final result.
|
||||||
|
|
||||||
|
## Smallest possible flow
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: hello
|
||||||
|
description: Echo a name back as a greeting.
|
||||||
|
|
||||||
|
inputs:
|
||||||
|
name:
|
||||||
|
type: text
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- id: greet
|
||||||
|
module: debug.echo
|
||||||
|
inputs:
|
||||||
|
payload: "Hello, {{ inputs.name }}"
|
||||||
|
|
||||||
|
outputs:
|
||||||
|
greeting: "{{ steps.greet.outputs.payload }}"
|
||||||
|
```
|
||||||
|
|
||||||
|
`fai run flows/hello.yaml --input name=World` produces:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "greeting": "Hello, World" }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Real-world example: extract → summarize
|
||||||
|
|
||||||
|
The bundled `flows/extract-summarize.yaml` chains two modules:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
steps:
|
||||||
|
- id: extract
|
||||||
|
module: text.extract
|
||||||
|
inputs:
|
||||||
|
document: "{{ inputs.file }}"
|
||||||
|
|
||||||
|
- id: summarize
|
||||||
|
module: text.summarize
|
||||||
|
inputs:
|
||||||
|
text: "{{ steps.extract.outputs.text }}"
|
||||||
|
style: "three bullet points"
|
||||||
|
```
|
||||||
|
|
||||||
|
The `{{ steps.extract.outputs.text }}` template plumbs the
|
||||||
|
output of one step into the next. The flow engine type-coerces
|
||||||
|
JSON / FileRef / Text per the destination module's manifest, so
|
||||||
|
you don't need explicit conversion steps.
|
||||||
|
|
||||||
|
## Templating reference (short)
|
||||||
|
|
||||||
|
| Expression | Resolves to |
|
||||||
|
|------------------------------------|----------------------------|
|
||||||
|
| `{{ inputs.X }}` | input named X |
|
||||||
|
| `{{ steps.Y.outputs.Z }}` | output Z of step Y |
|
||||||
|
| `{{ env.OPENAI_API_KEY }}` | env var (must be declared) |
|
||||||
|
| `{{ now }}` | ISO-8601 UTC timestamp |
|
||||||
|
| `{{ flow.execution_id }}` | per-run id (audit-log key) |
|
||||||
|
|
||||||
|
## Audit posture
|
||||||
|
|
||||||
|
Every step emits four events:
|
||||||
|
|
||||||
|
- `step.started` — module name, version, manifest hash
|
||||||
|
- `step.completed` — duration, output size, well-known
|
||||||
|
fields auto-elevated (`model_digest`, `engine`, …)
|
||||||
|
- `step.failed` — error name + message
|
||||||
|
- `flow.completed` — sum of step durations, total events
|
||||||
|
|
||||||
|
All hash-chained into the same audit log. See the **Audit-log**
|
||||||
|
explainer for the chain mechanics.
|
||||||
|
|
||||||
|
## What you'll see in this app
|
||||||
|
|
||||||
|
- **Flows page**: list of saved flows under `~/.fai/data/flows/`.
|
||||||
|
Click `Run`, fill any required inputs, watch the result.
|
||||||
|
- **Audit page**: per-step events appear within seconds of a
|
||||||
|
flow finishing. Filter on `flow.` to see only flow-level
|
||||||
|
rows.
|
||||||
|
- **Store**: any installed module shows up as available for
|
||||||
|
`module:` in a flow YAML. Synthetic federated entries
|
||||||
|
(`mcp.<server>.<tool>`, `n8n.<endpoint>.<workflow>`) work
|
||||||
|
the same way.
|
||||||
92
assets/docs/flows_de.md
Normal file
92
assets/docs/flows_de.md
Normal file
|
|
@ -0,0 +1,92 @@
|
||||||
|
# Flow-Komposition
|
||||||
|
|
||||||
|
Ein Flow ist eine YAML-Datei mit drei Top-Level-Schlüsseln:
|
||||||
|
`inputs:`, `steps:`, `outputs:`. Von oben nach unten gelesen,
|
||||||
|
sagt sie dem Hub, welche Eingaben er akzeptiert, welche Module
|
||||||
|
in welcher Reihenfolge aufgerufen werden und was am Ende als
|
||||||
|
Ergebnis nach außen geht.
|
||||||
|
|
||||||
|
## Kleinster möglicher Flow
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
name: hello
|
||||||
|
description: Gibt einen Namen als Begrüßung zurück.
|
||||||
|
|
||||||
|
inputs:
|
||||||
|
name:
|
||||||
|
type: text
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- id: greet
|
||||||
|
module: debug.echo
|
||||||
|
inputs:
|
||||||
|
payload: "Hallo, {{ inputs.name }}"
|
||||||
|
|
||||||
|
outputs:
|
||||||
|
greeting: "{{ steps.greet.outputs.payload }}"
|
||||||
|
```
|
||||||
|
|
||||||
|
`fai run flows/hello.yaml --input name=Welt` ergibt:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{ "greeting": "Hallo, Welt" }
|
||||||
|
```
|
||||||
|
|
||||||
|
## Realbeispiel: extract → summarize
|
||||||
|
|
||||||
|
Der mitgelieferte Flow `flows/extract-summarize.yaml`
|
||||||
|
verkettet zwei Module:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
steps:
|
||||||
|
- id: extract
|
||||||
|
module: text.extract
|
||||||
|
inputs:
|
||||||
|
document: "{{ inputs.file }}"
|
||||||
|
|
||||||
|
- id: summarize
|
||||||
|
module: text.summarize
|
||||||
|
inputs:
|
||||||
|
text: "{{ steps.extract.outputs.text }}"
|
||||||
|
style: "drei Stichpunkte"
|
||||||
|
```
|
||||||
|
|
||||||
|
Das Template `{{ steps.extract.outputs.text }}` reicht die
|
||||||
|
Ausgabe eines Schritts an den nächsten weiter. Die Flow-Engine
|
||||||
|
konvertiert JSON / FileRef / Text passend zum Ziel-Modul-
|
||||||
|
Manifest, ohne explizite Wandlungs-Schritte.
|
||||||
|
|
||||||
|
## Templating-Referenz (kurz)
|
||||||
|
|
||||||
|
| Ausdruck | Löst sich auf zu |
|
||||||
|
|------------------------------------|------------------------------|
|
||||||
|
| `{{ inputs.X }}` | Eingabe namens X |
|
||||||
|
| `{{ steps.Y.outputs.Z }}` | Ausgabe Z von Schritt Y |
|
||||||
|
| `{{ env.OPENAI_API_KEY }}` | Env-Var (deklariert nötig) |
|
||||||
|
| `{{ now }}` | ISO-8601-UTC-Zeitstempel |
|
||||||
|
| `{{ flow.execution_id }}` | Lauf-ID (Audit-Log-Schlüssel)|
|
||||||
|
|
||||||
|
## Audit-Posture
|
||||||
|
|
||||||
|
Jeder Schritt emittiert vier Events:
|
||||||
|
|
||||||
|
- `step.started` — Modul-Name, Version, Manifest-Hash
|
||||||
|
- `step.completed` — Dauer, Output-Größe, gewhitelistete Felder
|
||||||
|
automatisch elevated (`model_digest`, `engine`, …)
|
||||||
|
- `step.failed` — Fehler-Name + Nachricht
|
||||||
|
- `flow.completed` — Summe der Schritt-Dauern, Events gesamt
|
||||||
|
|
||||||
|
Alle hash-verkettet im gleichen Audit-Log. Siehe Audit-Log-
|
||||||
|
Erklärung für die Ketten-Mechanik.
|
||||||
|
|
||||||
|
## Was du in dieser App siehst
|
||||||
|
|
||||||
|
- **Flows-Seite**: Liste der gespeicherten Flows unter
|
||||||
|
`~/.fai/data/flows/`. `Starten` klicken, geforderte Eingaben
|
||||||
|
ausfüllen, Ergebnis verfolgen.
|
||||||
|
- **Protokoll-Seite**: Schritt-Events erscheinen Sekunden
|
||||||
|
nach Flow-Ende. `Flow`-Filter zeigt nur Flow-Level-Zeilen.
|
||||||
|
- **Store**: Jedes installierte Modul taucht als verfügbares
|
||||||
|
`module:` in der Flow-YAML auf. Synthetische föderierte
|
||||||
|
Einträge (`mcp.<server>.<tool>`, `n8n.<endpoint>.<workflow>`)
|
||||||
|
funktionieren genauso.
|
||||||
66
assets/docs/security.md
Normal file
66
assets/docs/security.md
Normal file
|
|
@ -0,0 +1,66 @@
|
||||||
|
# Sandbox model
|
||||||
|
|
||||||
|
Every F∆I module runs inside a WebAssembly sandbox with no
|
||||||
|
ambient access to the host. The module can do exactly what it
|
||||||
|
declares in its `module.yaml` — and nothing else.
|
||||||
|
|
||||||
|
## What a module declares
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
permissions:
|
||||||
|
- net: api.openai.com # outbound HTTPS only
|
||||||
|
- net: 127.0.0.1:11434 # local Ollama
|
||||||
|
- fs.read: /var/lib/fai/in # read-only directory
|
||||||
|
- fs.write: /var/lib/fai/out # writable directory
|
||||||
|
- env: OPENAI_API_KEY # one specific env var
|
||||||
|
- hub: invoke # call other modules
|
||||||
|
```
|
||||||
|
|
||||||
|
Anything not on this list is impossible at runtime. A module
|
||||||
|
that forgets to ask for `net:` cannot reach the network at all.
|
||||||
|
The hub's `WasiCtxBuilder` wires only the declared preopens
|
||||||
|
and env vars — there is no escape hatch.
|
||||||
|
|
||||||
|
## What the operator controls
|
||||||
|
|
||||||
|
Operators add their own ceiling on top in `~/.fai/config.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
security:
|
||||||
|
module_allowlist: # only these modules may load
|
||||||
|
- "text.*"
|
||||||
|
module_denylist: # never load these
|
||||||
|
- "experimental.*"
|
||||||
|
max_permissions: # cap requests per scope
|
||||||
|
net: ["api.openai.com"]
|
||||||
|
fs.read: ["/var/lib/fai"]
|
||||||
|
require_signatures: true # reject unsigned bundles
|
||||||
|
require_sbom: true # reject bundles without CycloneDX
|
||||||
|
```
|
||||||
|
|
||||||
|
Modules whose declared permissions exceed the operator's
|
||||||
|
ceiling fail to load with an explicit error. The operator
|
||||||
|
ceiling is the second gate; the module's own declaration is
|
||||||
|
the first.
|
||||||
|
|
||||||
|
## What you'll see in this app
|
||||||
|
|
||||||
|
- The **Store** detail sheet for an installed module shows
|
||||||
|
the declared permissions list with icons (`net:` globe,
|
||||||
|
`fs.read:` folder, `fs.write:` edit, `env:` terminal).
|
||||||
|
- The **Doctor** page summary tile shows total module count
|
||||||
|
and capability count.
|
||||||
|
- A **flow run** that violates a permission fails with a
|
||||||
|
named error (`PermissionDenied: net:example.com`) in the
|
||||||
|
audit log — visible on the Audit page.
|
||||||
|
|
||||||
|
## What we don't have
|
||||||
|
|
||||||
|
- No process-level isolation between modules. They all run
|
||||||
|
inside one hub process. A WASM trap escalates to a flow-step
|
||||||
|
failure, not a hub crash, but heap exhaustion in one module
|
||||||
|
can pressure the others. Pooled instance mode is on the
|
||||||
|
roadmap.
|
||||||
|
- No live policy backend (OPA-style runtime decisions).
|
||||||
|
Permission lists are static at module-load time. Customer
|
||||||
|
-driven; deferred until a real deployment needs it.
|
||||||
68
assets/docs/security_de.md
Normal file
68
assets/docs/security_de.md
Normal file
|
|
@ -0,0 +1,68 @@
|
||||||
|
# Sandbox-Modell
|
||||||
|
|
||||||
|
Jedes F∆I-Modul läuft in einer WebAssembly-Sandbox ohne
|
||||||
|
ambienten Hostzugriff. Das Modul kann genau das, was es in
|
||||||
|
seiner `module.yaml` deklariert — und sonst nichts.
|
||||||
|
|
||||||
|
## Was ein Modul deklariert
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
permissions:
|
||||||
|
- net: api.openai.com # nur ausgehendes HTTPS
|
||||||
|
- net: 127.0.0.1:11434 # lokales Ollama
|
||||||
|
- fs.read: /var/lib/fai/in # nur-lese-Verzeichnis
|
||||||
|
- fs.write: /var/lib/fai/out # schreibbares Verzeichnis
|
||||||
|
- env: OPENAI_API_KEY # eine bestimmte Umgebungsvariable
|
||||||
|
- hub: invoke # andere Module aufrufen
|
||||||
|
```
|
||||||
|
|
||||||
|
Was nicht auf der Liste steht, ist zur Laufzeit unmöglich. Ein
|
||||||
|
Modul, das `net:` vergisst, kann das Netzwerk gar nicht
|
||||||
|
erreichen. Der `WasiCtxBuilder` des Hubs verdrahtet nur die
|
||||||
|
deklarierten Preopens und Env-Vars — keine Hintertür.
|
||||||
|
|
||||||
|
## Was der Operator kontrolliert
|
||||||
|
|
||||||
|
Operatoren setzen ihre eigene Obergrenze in
|
||||||
|
`~/.fai/config.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
security:
|
||||||
|
module_allowlist: # nur diese Module laden
|
||||||
|
- "text.*"
|
||||||
|
module_denylist: # diese nie laden
|
||||||
|
- "experimental.*"
|
||||||
|
max_permissions: # Cap je Scope
|
||||||
|
net: ["api.openai.com"]
|
||||||
|
fs.read: ["/var/lib/fai"]
|
||||||
|
require_signatures: true # unsignierte Bundles ablehnen
|
||||||
|
require_sbom: true # Bundles ohne CycloneDX ablehnen
|
||||||
|
```
|
||||||
|
|
||||||
|
Module, deren Berechtigungen die Operator-Obergrenze
|
||||||
|
überschreiten, scheitern beim Laden mit explizitem Fehler. Die
|
||||||
|
Operator-Obergrenze ist die zweite Schleuse; die Modul-eigene
|
||||||
|
Deklaration ist die erste.
|
||||||
|
|
||||||
|
## Was du in dieser App siehst
|
||||||
|
|
||||||
|
- Das **Store**-Detail-Sheet eines installierten Moduls zeigt
|
||||||
|
die Berechtigungsliste mit Icons (`net:` Globus, `fs.read:`
|
||||||
|
Ordner, `fs.write:` Stift, `env:` Terminal).
|
||||||
|
- Die **Diagnose**-Seite zeigt Modul-Anzahl und Capability-
|
||||||
|
Anzahl im Summary.
|
||||||
|
- Ein **Flow-Lauf**, der eine Berechtigung verletzt, schlägt
|
||||||
|
mit benanntem Fehler fehl (`PermissionDenied:
|
||||||
|
net:example.com`) — sichtbar im Protokoll.
|
||||||
|
|
||||||
|
## Was es nicht gibt
|
||||||
|
|
||||||
|
- Keine Prozess-Isolation zwischen Modulen. Alle laufen im
|
||||||
|
einen Hub-Prozess. Ein WASM-Trap eskaliert zum
|
||||||
|
Flow-Schritt-Fehler, nicht zum Hub-Crash, aber
|
||||||
|
Speicher-Überlastung in einem Modul kann die anderen
|
||||||
|
beeinträchtigen. Pooled-Instance-Modus ist auf der Roadmap.
|
||||||
|
- Keine Live-Policy-Backend (OPA-artige Laufzeit-
|
||||||
|
Entscheidungen). Berechtigungslisten sind statisch zur
|
||||||
|
Modul-Ladezeit. Kunden-getrieben; aufgeschoben bis ein
|
||||||
|
echter Einsatz es braucht.
|
||||||
|
|
@ -20,6 +20,19 @@
|
||||||
"welcomeTrustAuditBody": "Flow-Läufe, Installationen, Deinstallationen, Freigabe-Entscheidungen — alles wird in ein hash-verkettetes Audit-Log geschrieben. Die Diagnose-Seite verifiziert die Kette bei jedem Laden komplett.",
|
"welcomeTrustAuditBody": "Flow-Läufe, Installationen, Deinstallationen, Freigabe-Entscheidungen — alles wird in ein hash-verkettetes Audit-Log geschrieben. Die Diagnose-Seite verifiziert die Kette bei jedem Laden komplett.",
|
||||||
"welcomeTrustAirgapTitle": "Air-Gap-tauglich",
|
"welcomeTrustAirgapTitle": "Air-Gap-tauglich",
|
||||||
"welcomeTrustAirgapBody": "Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.",
|
"welcomeTrustAirgapBody": "Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.",
|
||||||
|
"welcomeDocsHeader": "DOKUMENTATION",
|
||||||
|
"welcomeDocsBody": "Operator-Erklärungen, inline gerendert. Kein Browser, kein externer Link — air-gap-tauglich.",
|
||||||
|
"welcomeDocArchitectureTitle": "Architektur in einem Absatz",
|
||||||
|
"welcomeDocArchitectureBlurb": "Hub, Modul, Flow — und wie die drei zusammenpassen.",
|
||||||
|
"welcomeDocSecurityTitle": "Sandbox-Modell",
|
||||||
|
"welcomeDocSecurityBlurb": "Was ein Modul deklariert, was der Operator deckelt, was der Hub durchsetzt.",
|
||||||
|
"welcomeDocAuditTitle": "Manipulationssicheres Audit-Log",
|
||||||
|
"welcomeDocAuditBlurb": "Wie die Hash-Kette funktioniert und warum WORM-1 für KRITIS reicht.",
|
||||||
|
"welcomeDocFlowsTitle": "Flow-Komposition",
|
||||||
|
"welcomeDocFlowsBlurb": "YAML-Grundlagen, Templating-Referenz, das Extract→Summarize-Beispiel.",
|
||||||
|
"welcomeDocClose": "Schließen",
|
||||||
|
"welcomeDocFailedToLoad": "Doku konnte nicht geladen werden: {error}",
|
||||||
|
"@welcomeDocFailedToLoad": { "placeholders": { "error": { "type": "String" } } },
|
||||||
"navDoctor": "Diagnose",
|
"navDoctor": "Diagnose",
|
||||||
"navModules": "Module",
|
"navModules": "Module",
|
||||||
"navStore": "Store",
|
"navStore": "Store",
|
||||||
|
|
|
||||||
|
|
@ -21,6 +21,19 @@
|
||||||
"welcomeTrustAuditBody": "Flow runs, install / uninstall actions, approval decisions — all of them write into a hash-chained audit log. The Doctor page verifies the chain end-to-end on every load.",
|
"welcomeTrustAuditBody": "Flow runs, install / uninstall actions, approval decisions — all of them write into a hash-chained audit log. The Doctor page verifies the chain end-to-end on every load.",
|
||||||
"welcomeTrustAirgapTitle": "Air-gap ready",
|
"welcomeTrustAirgapTitle": "Air-gap ready",
|
||||||
"welcomeTrustAirgapBody": "The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.",
|
"welcomeTrustAirgapBody": "The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.",
|
||||||
|
"welcomeDocsHeader": "DOCUMENTATION",
|
||||||
|
"welcomeDocsBody": "Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.",
|
||||||
|
"welcomeDocArchitectureTitle": "Architecture in one paragraph",
|
||||||
|
"welcomeDocArchitectureBlurb": "Hub, Module, Flow — and how the three fit together.",
|
||||||
|
"welcomeDocSecurityTitle": "Sandbox model",
|
||||||
|
"welcomeDocSecurityBlurb": "What a module declares, what the operator caps, what the hub enforces.",
|
||||||
|
"welcomeDocAuditTitle": "Tamper-evident audit log",
|
||||||
|
"welcomeDocAuditBlurb": "How the hash chain works and why WORM-1 is enough for KRITIS.",
|
||||||
|
"welcomeDocFlowsTitle": "Flow composition",
|
||||||
|
"welcomeDocFlowsBlurb": "YAML basics, templating reference, the extract→summarize example.",
|
||||||
|
"welcomeDocClose": "Close",
|
||||||
|
"welcomeDocFailedToLoad": "Could not load documentation: {error}",
|
||||||
|
"@welcomeDocFailedToLoad": { "placeholders": { "error": { "type": "String" } } },
|
||||||
"navDoctor": "Doctor",
|
"navDoctor": "Doctor",
|
||||||
"navModules": "Modules",
|
"navModules": "Modules",
|
||||||
"navStore": "Store",
|
"navStore": "Store",
|
||||||
|
|
|
||||||
|
|
@ -206,6 +206,78 @@ abstract class AppLocalizations {
|
||||||
/// **'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.'**
|
/// **'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.'**
|
||||||
String get welcomeTrustAirgapBody;
|
String get welcomeTrustAirgapBody;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocsHeader.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'DOCUMENTATION'**
|
||||||
|
String get welcomeDocsHeader;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocsBody.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.'**
|
||||||
|
String get welcomeDocsBody;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocArchitectureTitle.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Architecture in one paragraph'**
|
||||||
|
String get welcomeDocArchitectureTitle;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocArchitectureBlurb.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Hub, Module, Flow — and how the three fit together.'**
|
||||||
|
String get welcomeDocArchitectureBlurb;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocSecurityTitle.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Sandbox model'**
|
||||||
|
String get welcomeDocSecurityTitle;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocSecurityBlurb.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'What a module declares, what the operator caps, what the hub enforces.'**
|
||||||
|
String get welcomeDocSecurityBlurb;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocAuditTitle.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Tamper-evident audit log'**
|
||||||
|
String get welcomeDocAuditTitle;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocAuditBlurb.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'How the hash chain works and why WORM-1 is enough for KRITIS.'**
|
||||||
|
String get welcomeDocAuditBlurb;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocFlowsTitle.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Flow composition'**
|
||||||
|
String get welcomeDocFlowsTitle;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocFlowsBlurb.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'YAML basics, templating reference, the extract→summarize example.'**
|
||||||
|
String get welcomeDocFlowsBlurb;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocClose.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Close'**
|
||||||
|
String get welcomeDocClose;
|
||||||
|
|
||||||
|
/// No description provided for @welcomeDocFailedToLoad.
|
||||||
|
///
|
||||||
|
/// In en, this message translates to:
|
||||||
|
/// **'Could not load documentation: {error}'**
|
||||||
|
String welcomeDocFailedToLoad(String error);
|
||||||
|
|
||||||
/// No description provided for @navDoctor.
|
/// No description provided for @navDoctor.
|
||||||
///
|
///
|
||||||
/// In en, this message translates to:
|
/// In en, this message translates to:
|
||||||
|
|
|
||||||
|
|
@ -69,6 +69,49 @@ class AppLocalizationsDe extends AppLocalizations {
|
||||||
String get welcomeTrustAirgapBody =>
|
String get welcomeTrustAirgapBody =>
|
||||||
'Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.';
|
'Der gesamte Hub steckt in einem einzigen Binary für Linux, macOS und Windows. Sobald ein Modul installiert ist, läuft der Flow, der es nutzt, ohne weiteren Netzwerkzugriff — ideal für regulierte Umgebungen.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocsHeader => 'DOKUMENTATION';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocsBody =>
|
||||||
|
'Operator-Erklärungen, inline gerendert. Kein Browser, kein externer Link — air-gap-tauglich.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocArchitectureTitle => 'Architektur in einem Absatz';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocArchitectureBlurb =>
|
||||||
|
'Hub, Modul, Flow — und wie die drei zusammenpassen.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocSecurityTitle => 'Sandbox-Modell';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocSecurityBlurb =>
|
||||||
|
'Was ein Modul deklariert, was der Operator deckelt, was der Hub durchsetzt.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocAuditTitle => 'Manipulationssicheres Audit-Log';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocAuditBlurb =>
|
||||||
|
'Wie die Hash-Kette funktioniert und warum WORM-1 für KRITIS reicht.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocFlowsTitle => 'Flow-Komposition';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocFlowsBlurb =>
|
||||||
|
'YAML-Grundlagen, Templating-Referenz, das Extract→Summarize-Beispiel.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocClose => 'Schließen';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String welcomeDocFailedToLoad(String error) {
|
||||||
|
return 'Doku konnte nicht geladen werden: $error';
|
||||||
|
}
|
||||||
|
|
||||||
@override
|
@override
|
||||||
String get navDoctor => 'Diagnose';
|
String get navDoctor => 'Diagnose';
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -69,6 +69,49 @@ class AppLocalizationsEn extends AppLocalizations {
|
||||||
String get welcomeTrustAirgapBody =>
|
String get welcomeTrustAirgapBody =>
|
||||||
'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.';
|
'The whole hub fits in a single binary that runs on Linux, macOS and Windows. Once a module is installed, the flow it powers runs without further network access — perfect for regulated environments.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocsHeader => 'DOCUMENTATION';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocsBody =>
|
||||||
|
'Operator-facing explainers, rendered inline. No browser, no external link — air-gap-friendly.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocArchitectureTitle => 'Architecture in one paragraph';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocArchitectureBlurb =>
|
||||||
|
'Hub, Module, Flow — and how the three fit together.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocSecurityTitle => 'Sandbox model';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocSecurityBlurb =>
|
||||||
|
'What a module declares, what the operator caps, what the hub enforces.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocAuditTitle => 'Tamper-evident audit log';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocAuditBlurb =>
|
||||||
|
'How the hash chain works and why WORM-1 is enough for KRITIS.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocFlowsTitle => 'Flow composition';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocFlowsBlurb =>
|
||||||
|
'YAML basics, templating reference, the extract→summarize example.';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String get welcomeDocClose => 'Close';
|
||||||
|
|
||||||
|
@override
|
||||||
|
String welcomeDocFailedToLoad(String error) {
|
||||||
|
return 'Could not load documentation: $error';
|
||||||
|
}
|
||||||
|
|
||||||
@override
|
@override
|
||||||
String get navDoctor => 'Doctor';
|
String get navDoctor => 'Doctor';
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -26,7 +26,7 @@ import 'widgets/widgets.dart';
|
||||||
/// Studio's own build version. Bump on every UI commit so the
|
/// Studio's own build version. Bump on every UI commit so the
|
||||||
/// running app self-identifies — visible in the sidebar header
|
/// running app self-identifies — visible in the sidebar header
|
||||||
/// and quick-glance proof that you're seeing the current build.
|
/// and quick-glance proof that you're seeing the current build.
|
||||||
const String kStudioVersion = '0.37.0';
|
const String kStudioVersion = '0.38.0';
|
||||||
|
|
||||||
Future<void> main() async {
|
Future<void> main() async {
|
||||||
WidgetsFlutterBinding.ensureInitialized();
|
WidgetsFlutterBinding.ensureInitialized();
|
||||||
|
|
|
||||||
|
|
@ -9,8 +9,12 @@
|
||||||
// getting-started checklist.
|
// getting-started checklist.
|
||||||
|
|
||||||
import 'package:flutter/material.dart';
|
import 'package:flutter/material.dart';
|
||||||
|
import 'package:flutter/services.dart' show rootBundle;
|
||||||
|
import 'package:flutter_markdown/flutter_markdown.dart';
|
||||||
|
|
||||||
|
import '../data/system_actions.dart';
|
||||||
import '../l10n/app_localizations.dart';
|
import '../l10n/app_localizations.dart';
|
||||||
|
import '../theme/theme.dart';
|
||||||
import '../theme/tokens.dart';
|
import '../theme/tokens.dart';
|
||||||
|
|
||||||
class WelcomePage extends StatelessWidget {
|
class WelcomePage extends StatelessWidget {
|
||||||
|
|
@ -48,6 +52,10 @@ class WelcomePage extends StatelessWidget {
|
||||||
_SectionLabel(textKey: _SectionLabelKey.trust),
|
_SectionLabel(textKey: _SectionLabelKey.trust),
|
||||||
SizedBox(height: FaiSpace.md),
|
SizedBox(height: FaiSpace.md),
|
||||||
_TrustPosture(),
|
_TrustPosture(),
|
||||||
|
SizedBox(height: FaiSpace.xxl),
|
||||||
|
_SectionLabel(textKey: _SectionLabelKey.docs),
|
||||||
|
SizedBox(height: FaiSpace.md),
|
||||||
|
_DocsRow(),
|
||||||
],
|
],
|
||||||
),
|
),
|
||||||
),
|
),
|
||||||
|
|
@ -128,7 +136,7 @@ class _Hero extends StatelessWidget {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
enum _SectionLabelKey { pillars, trust }
|
enum _SectionLabelKey { pillars, trust, docs }
|
||||||
|
|
||||||
class _SectionLabel extends StatelessWidget {
|
class _SectionLabel extends StatelessWidget {
|
||||||
final _SectionLabelKey textKey;
|
final _SectionLabelKey textKey;
|
||||||
|
|
@ -141,6 +149,7 @@ class _SectionLabel extends StatelessWidget {
|
||||||
final text = switch (textKey) {
|
final text = switch (textKey) {
|
||||||
_SectionLabelKey.pillars => l.welcomePillarsHeader,
|
_SectionLabelKey.pillars => l.welcomePillarsHeader,
|
||||||
_SectionLabelKey.trust => l.welcomeTrustHeader,
|
_SectionLabelKey.trust => l.welcomeTrustHeader,
|
||||||
|
_SectionLabelKey.docs => l.welcomeDocsHeader,
|
||||||
};
|
};
|
||||||
return Text(
|
return Text(
|
||||||
text,
|
text,
|
||||||
|
|
@ -349,3 +358,291 @@ class _TrustRow extends StatelessWidget {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// Doc-card entries — each links to a bundled markdown file
|
||||||
|
/// under `assets/docs/`. The slug is the filename stem; the
|
||||||
|
/// loader picks `<slug>.md` or `<slug>_de.md` per locale.
|
||||||
|
class _DocEntry {
|
||||||
|
final String slug;
|
||||||
|
final IconData icon;
|
||||||
|
final String Function(AppLocalizations) title;
|
||||||
|
final String Function(AppLocalizations) blurb;
|
||||||
|
const _DocEntry({
|
||||||
|
required this.slug,
|
||||||
|
required this.icon,
|
||||||
|
required this.title,
|
||||||
|
required this.blurb,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
final List<_DocEntry> _kDocs = <_DocEntry>[
|
||||||
|
_DocEntry(
|
||||||
|
slug: 'architecture',
|
||||||
|
icon: Icons.account_tree_outlined,
|
||||||
|
title: (l) => l.welcomeDocArchitectureTitle,
|
||||||
|
blurb: (l) => l.welcomeDocArchitectureBlurb,
|
||||||
|
),
|
||||||
|
_DocEntry(
|
||||||
|
slug: 'security',
|
||||||
|
icon: Icons.shield_outlined,
|
||||||
|
title: (l) => l.welcomeDocSecurityTitle,
|
||||||
|
blurb: (l) => l.welcomeDocSecurityBlurb,
|
||||||
|
),
|
||||||
|
_DocEntry(
|
||||||
|
slug: 'audit',
|
||||||
|
icon: Icons.verified_outlined,
|
||||||
|
title: (l) => l.welcomeDocAuditTitle,
|
||||||
|
blurb: (l) => l.welcomeDocAuditBlurb,
|
||||||
|
),
|
||||||
|
_DocEntry(
|
||||||
|
slug: 'flows',
|
||||||
|
icon: Icons.alt_route_outlined,
|
||||||
|
title: (l) => l.welcomeDocFlowsTitle,
|
||||||
|
blurb: (l) => l.welcomeDocFlowsBlurb,
|
||||||
|
),
|
||||||
|
];
|
||||||
|
|
||||||
|
/// Two-by-two doc grid on wide windows, single column on
|
||||||
|
/// narrow. Each card opens `_DocReaderSheet` for its slug.
|
||||||
|
class _DocsRow extends StatelessWidget {
|
||||||
|
const _DocsRow();
|
||||||
|
|
||||||
|
@override
|
||||||
|
Widget build(BuildContext context) {
|
||||||
|
final l = AppLocalizations.of(context)!;
|
||||||
|
return Column(
|
||||||
|
crossAxisAlignment: CrossAxisAlignment.start,
|
||||||
|
children: [
|
||||||
|
Text(
|
||||||
|
l.welcomeDocsBody,
|
||||||
|
style: Theme.of(context).textTheme.bodySmall?.copyWith(
|
||||||
|
color: Theme.of(context).colorScheme.onSurfaceVariant,
|
||||||
|
),
|
||||||
|
),
|
||||||
|
const SizedBox(height: FaiSpace.md),
|
||||||
|
LayoutBuilder(
|
||||||
|
builder: (context, constraints) {
|
||||||
|
final twoCols = constraints.maxWidth >= 640;
|
||||||
|
final cardWidth =
|
||||||
|
twoCols ? (constraints.maxWidth - FaiSpace.md) / 2 : double.infinity;
|
||||||
|
return Wrap(
|
||||||
|
spacing: FaiSpace.md,
|
||||||
|
runSpacing: FaiSpace.md,
|
||||||
|
children: [
|
||||||
|
for (final d in _kDocs)
|
||||||
|
SizedBox(
|
||||||
|
width: cardWidth,
|
||||||
|
child: _DocCard(entry: d),
|
||||||
|
),
|
||||||
|
],
|
||||||
|
);
|
||||||
|
},
|
||||||
|
),
|
||||||
|
],
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
class _DocCard extends StatelessWidget {
|
||||||
|
final _DocEntry entry;
|
||||||
|
const _DocCard({required this.entry});
|
||||||
|
|
||||||
|
@override
|
||||||
|
Widget build(BuildContext context) {
|
||||||
|
final theme = Theme.of(context);
|
||||||
|
final l = AppLocalizations.of(context)!;
|
||||||
|
return Material(
|
||||||
|
color: theme.colorScheme.surfaceContainer,
|
||||||
|
borderRadius: BorderRadius.circular(FaiRadius.md),
|
||||||
|
child: InkWell(
|
||||||
|
onTap: () => _DocReaderSheet.show(context, entry),
|
||||||
|
borderRadius: BorderRadius.circular(FaiRadius.md),
|
||||||
|
child: Container(
|
||||||
|
padding: const EdgeInsets.all(FaiSpace.lg),
|
||||||
|
decoration: BoxDecoration(
|
||||||
|
borderRadius: BorderRadius.circular(FaiRadius.md),
|
||||||
|
border: Border.all(color: theme.colorScheme.outlineVariant),
|
||||||
|
),
|
||||||
|
child: Row(
|
||||||
|
crossAxisAlignment: CrossAxisAlignment.start,
|
||||||
|
children: [
|
||||||
|
Icon(entry.icon, size: 22, color: theme.colorScheme.primary),
|
||||||
|
const SizedBox(width: FaiSpace.lg),
|
||||||
|
Expanded(
|
||||||
|
child: Column(
|
||||||
|
crossAxisAlignment: CrossAxisAlignment.start,
|
||||||
|
children: [
|
||||||
|
Text(
|
||||||
|
entry.title(l),
|
||||||
|
style: theme.textTheme.titleSmall?.copyWith(
|
||||||
|
fontWeight: FontWeight.w600,
|
||||||
|
),
|
||||||
|
),
|
||||||
|
const SizedBox(height: 4),
|
||||||
|
Text(
|
||||||
|
entry.blurb(l),
|
||||||
|
style: theme.textTheme.bodySmall?.copyWith(
|
||||||
|
color: theme.colorScheme.onSurfaceVariant,
|
||||||
|
height: 1.4,
|
||||||
|
),
|
||||||
|
),
|
||||||
|
],
|
||||||
|
),
|
||||||
|
),
|
||||||
|
Icon(
|
||||||
|
Icons.chevron_right,
|
||||||
|
size: 18,
|
||||||
|
color: theme.colorScheme.onSurfaceVariant,
|
||||||
|
),
|
||||||
|
],
|
||||||
|
),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/// Modal bottom-sheet that loads the markdown for a doc entry
|
||||||
|
/// from `assets/docs/<slug>[_de].md` and renders it inline via
|
||||||
|
/// flutter_markdown. No browser, no network — KRITIS-friendly.
|
||||||
|
class _DocReaderSheet extends StatefulWidget {
|
||||||
|
final _DocEntry entry;
|
||||||
|
|
||||||
|
const _DocReaderSheet({required this.entry});
|
||||||
|
|
||||||
|
static Future<void> show(BuildContext context, _DocEntry entry) {
|
||||||
|
return showModalBottomSheet<void>(
|
||||||
|
context: context,
|
||||||
|
isScrollControlled: true,
|
||||||
|
backgroundColor: Theme.of(context).colorScheme.surfaceContainer,
|
||||||
|
shape: const RoundedRectangleBorder(
|
||||||
|
borderRadius: BorderRadius.vertical(top: Radius.circular(FaiRadius.md)),
|
||||||
|
),
|
||||||
|
builder: (_) => _DocReaderSheet(entry: entry),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
@override
|
||||||
|
State<_DocReaderSheet> createState() => _DocReaderSheetState();
|
||||||
|
}
|
||||||
|
|
||||||
|
class _DocReaderSheetState extends State<_DocReaderSheet> {
|
||||||
|
late final Future<String> _content;
|
||||||
|
|
||||||
|
@override
|
||||||
|
void initState() {
|
||||||
|
super.initState();
|
||||||
|
_content = _load();
|
||||||
|
}
|
||||||
|
|
||||||
|
Future<String> _load() async {
|
||||||
|
final locale = Localizations.localeOf(context).languageCode;
|
||||||
|
final localised = 'assets/docs/${widget.entry.slug}_$locale.md';
|
||||||
|
final fallback = 'assets/docs/${widget.entry.slug}.md';
|
||||||
|
try {
|
||||||
|
return await rootBundle.loadString(localised);
|
||||||
|
} catch (_) {
|
||||||
|
return rootBundle.loadString(fallback);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
@override
|
||||||
|
Widget build(BuildContext context) {
|
||||||
|
final theme = Theme.of(context);
|
||||||
|
final l = AppLocalizations.of(context)!;
|
||||||
|
final maxHeight = MediaQuery.of(context).size.height * 0.85;
|
||||||
|
return ConstrainedBox(
|
||||||
|
constraints: BoxConstraints(maxHeight: maxHeight),
|
||||||
|
child: Column(
|
||||||
|
mainAxisSize: MainAxisSize.min,
|
||||||
|
children: [
|
||||||
|
Padding(
|
||||||
|
padding: const EdgeInsets.symmetric(vertical: FaiSpace.sm),
|
||||||
|
child: Container(
|
||||||
|
width: 40,
|
||||||
|
height: 4,
|
||||||
|
decoration: BoxDecoration(
|
||||||
|
color: theme.colorScheme.outlineVariant,
|
||||||
|
borderRadius: BorderRadius.circular(2),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
Padding(
|
||||||
|
padding: const EdgeInsets.fromLTRB(
|
||||||
|
FaiSpace.xxl,
|
||||||
|
FaiSpace.sm,
|
||||||
|
FaiSpace.lg,
|
||||||
|
FaiSpace.sm,
|
||||||
|
),
|
||||||
|
child: Row(
|
||||||
|
children: [
|
||||||
|
Icon(widget.entry.icon, size: 20, color: theme.colorScheme.primary),
|
||||||
|
const SizedBox(width: FaiSpace.sm),
|
||||||
|
Expanded(
|
||||||
|
child: Text(
|
||||||
|
widget.entry.title(l),
|
||||||
|
style: theme.textTheme.titleMedium?.copyWith(
|
||||||
|
fontWeight: FontWeight.w600,
|
||||||
|
),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
IconButton(
|
||||||
|
icon: const Icon(Icons.close, size: 18),
|
||||||
|
visualDensity: VisualDensity.compact,
|
||||||
|
tooltip: l.welcomeDocClose,
|
||||||
|
onPressed: () => Navigator.pop(context),
|
||||||
|
),
|
||||||
|
],
|
||||||
|
),
|
||||||
|
),
|
||||||
|
const Divider(height: 1),
|
||||||
|
Flexible(
|
||||||
|
child: FutureBuilder<String>(
|
||||||
|
future: _content,
|
||||||
|
builder: (context, snap) {
|
||||||
|
if (snap.connectionState == ConnectionState.waiting) {
|
||||||
|
return const Padding(
|
||||||
|
padding: EdgeInsets.all(FaiSpace.xxl),
|
||||||
|
child: Center(child: CircularProgressIndicator()),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (snap.hasError) {
|
||||||
|
return Padding(
|
||||||
|
padding: const EdgeInsets.all(FaiSpace.xxl),
|
||||||
|
child: Text(
|
||||||
|
l.welcomeDocFailedToLoad(snap.error.toString()),
|
||||||
|
style: theme.textTheme.bodyMedium?.copyWith(
|
||||||
|
color: theme.colorScheme.error,
|
||||||
|
),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
return Markdown(
|
||||||
|
data: snap.data ?? '',
|
||||||
|
padding: const EdgeInsets.all(FaiSpace.xxl),
|
||||||
|
selectable: true,
|
||||||
|
onTapLink: (text, href, title) async {
|
||||||
|
if (href != null && href.isNotEmpty) {
|
||||||
|
await SystemActions.openInOs(href);
|
||||||
|
}
|
||||||
|
},
|
||||||
|
styleSheet: MarkdownStyleSheet.fromTheme(theme).copyWith(
|
||||||
|
p: theme.textTheme.bodyMedium?.copyWith(height: 1.5),
|
||||||
|
code: FaiTheme.mono(
|
||||||
|
size: 12,
|
||||||
|
color: theme.colorScheme.onSurface,
|
||||||
|
),
|
||||||
|
codeblockDecoration: BoxDecoration(
|
||||||
|
color: theme.colorScheme.surfaceContainerHigh,
|
||||||
|
borderRadius: BorderRadius.circular(FaiRadius.sm),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
},
|
||||||
|
),
|
||||||
|
),
|
||||||
|
],
|
||||||
|
),
|
||||||
|
);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
name: fai_studio
|
name: fai_studio
|
||||||
description: "F∆I Studio — desktop GUI for the F∆I hub"
|
description: "F∆I Studio — desktop GUI for the F∆I hub"
|
||||||
publish_to: 'none'
|
publish_to: 'none'
|
||||||
version: 0.37.0
|
version: 0.38.0
|
||||||
|
|
||||||
environment:
|
environment:
|
||||||
sdk: ^3.11.0-200.1.beta
|
sdk: ^3.11.0-200.1.beta
|
||||||
|
|
@ -34,3 +34,9 @@ dev_dependencies:
|
||||||
flutter:
|
flutter:
|
||||||
uses-material-design: true
|
uses-material-design: true
|
||||||
generate: true
|
generate: true
|
||||||
|
# Bundled operator-facing documentation rendered inline by
|
||||||
|
# the Welcome page. Each doc has a `_de.md` sibling for the
|
||||||
|
# German locale; the loader picks the right pair at runtime.
|
||||||
|
# Air-gap-friendly — no network calls to read these.
|
||||||
|
assets:
|
||||||
|
- assets/docs/
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue