@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/security.md

@@ -0,0 +1,330 @@
+---
+title: "Sicherheit"
+description: "Sicherheitsmodell für agentennative Apps: Eingabevalidierung, SQL-Injection-Prävention, XSS, Datenbereichsbestimmung, Geheimnisverwaltung und Authentifizierungsmuster."
+---
+
+# Sicherheit
+
+Agent-native Apps sind standardmäßig sicher konzipiert. Das Framework bietet automatischen Schutz auf mehreren Ebenen – Sie erhalten sofort Datenisolation auf SQL-Ebene, parametrisierte Abfragen, Eingabevalidierung und Authentifizierung.
+
+## Was Sie kostenlos bekommen und was Sie besitzen {#what-you-own}
+
+```an-diagram title="Defense in layers" summary="The framework owns most of the threat surface; you own two things — tagging tables for scoping and validating external input."
+{
+  "html": "<div class=\"sec-layers\"><div class=\"diagram-card free\"><span class=\"diagram-pill ok\">Framework owns</span><small class=\"diagram-muted\">SQL isolation &middot; parameterized queries &middot; XSS escaping &middot; auth guard &middot; CSRF cookies &middot; secret encryption</small></div><div class=\"diagram-card you\"><span class=\"diagram-pill warn\">You own</span><small class=\"diagram-muted\">A. tag tables with ownableColumns() &amp; route through access guards<br>B. give every action a Zod schema &amp; send user URLs through the SSRF guard</small></div></div>",
+  "css": ".sec-layers{display:flex;flex-direction:column;gap:12px}.sec-layers .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+}
+```
+
+Wenn Sie auf den Standardmustern aufbauen, verwaltet das Framework bereits den größten Teil der Bedrohungsoberfläche für Sie:
+
+- **Datenisolation** – Agent SQL wird neu geschrieben, sodass er nur die Zeilen des aktuellen Benutzers (und der aktiven Organisation) sehen kann. Siehe [Data Scoping](#data-scoping).
+- **SQL-Einspritzung** – `db-query`/`db-exec` und Drizzle werden immer parametriert. Siehe [SQL Injection Prevention](#sql-injection).
+- **XSS** – React wird automatisch maskiert, TipTap und `react-markdown` werden desinfiziert. Siehe [XSS Prevention](#xss).
+- **Auth & CSRF** – jeder `defineAction` ist authentifiziert; Cookies sind `httpOnly` + `SameSite=lax`. Siehe [Authentication](#auth).
+- **Geheime Verschlüsselung** – Anmeldeinformationen und der Tresor werden im Ruhezustand verschlüsselt. Siehe [Secrets Management](#secrets).
+
+Das lässt eine kleine Fläche übrig, über die Sie tatsächlich nachdenken müssen:
+
+- **A. Markieren Sie Ihre Tabellen für den Scoping.** Fügen Sie `owner_email` (und `org_id` für Teamdaten) über [`ownableColumns()`](#data-scoping) hinzu und leiten Sie Drizzle-Lese-/Schreibvorgänge über [access guards](#access-guards).
+- **B. Externe Eingaben validieren und weiterleiten.** Geben Sie jeder Aktion einen Zod [`schema:`](#input-validation) und senden Sie jeden serverseitigen Abruf eines Benutzers/Agenten URL über [SSRF guard](#ssrf).
+
+Machen Sie diese beiden richtig und der Rest sind Standardeinstellungen. Das [Production Checklist](#production-checklist) ist die einseitige Bestätigung vor dem Versand.
+
+## Sicherheit durch Design {#secure-by-design}
+
+Die Framework-Architektur verhindert häufige Schwachstellen, wenn Sie die Standardmuster verwenden:
+
+| Sicherheitslücke   | Framework-Schutz                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| SQL-Injektion      | Parametrierte Abfragen in `db-query`/`db-exec` und Drizzle ORM                                |
+| XSS                | React automatisches Escapezeichen JSX; TipTap bereinigt Rich Text                             |
+| Datenlecks         | Scoping auf SQL-Ebene über temporäre Ansichten (`owner_email`, `org_id`)                      |
+| Auth-Umgehung      | Auth Guard schützt automatisch alle `defineAction`-Endpunkte                                  |
+| Eingabeinjektion   | Zod-Schemavalidierung in `defineAction`                                                       |
+| CSRF               | `SameSite=lax` + `httpOnly`-Cookies                                                           |
+| Geheime Enthüllung | `.env` gitignored; Anmeldeinformationen und Tresor im Ruhezustand verschlüsselt (AES-256-GCM) |
+| SSRF               | `ssrfSafeFetch` blockiert interne Ziele/Metadatenziele + Umleitungs-Neubindung                |
+
+## Eingabevalidierung {#input-validation}
+
+Verwenden Sie `defineAction` mit einem Zod `schema:` für jede Aktion. Das Framework validiert die Eingabe automatisch, bevor Ihr Code ausgeführt wird:
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200).describe("Note title"),
+    content: z.string().optional().describe("Note body"),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — invalid input never reaches here
+  },
+});
+```
+
+Ungültige Eingabe gibt eindeutige Fehlermeldungen zurück (400 für HTTP, strukturierter Fehler für Agentenanrufe). Das ältere `parameters:`-Format bietet keine Laufzeitvalidierung.
+
+## SQL Injektionsprävention {#sql-injection}
+
+Die Tools `db-query` und `db-exec` des Frameworks verwenden parametrisierte Abfragen. Benutzereingaben werden als Argumente übergeben und niemals in die SQL-Zeichenfolge interpoliert:
+
+```ts
+// SAFE — parameterized query (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
+
+// SAFE — Drizzle ORM (always generates parameterized queries)
+await db.insert(notes).values({ title, ownerEmail: email });
+
+// DANGEROUS — string concatenation (never do this)
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`);
+```
+
+```an-callout
+{
+  "tone": "risk",
+  "body": "Never build SQL by string concatenation or template literals. Pass user input as `args` to `exec` / `db-query`, or use Drizzle — both always parameterize. The `pnpm guards` checks catch unscoped and concatenated queries at CI time."
+}
+```
+
+## XSS Prävention {#xss}
+
+React maskiert automatisch alle JSX-Ausdrücke. Zusätzliche Richtlinien:
+
+- Verwenden Sie `dangerouslySetInnerHTML` niemals mit benutzergesteuerten Inhalten
+- Verwenden Sie niemals `innerHTML`, `eval()` oder `document.write()`
+- Verwenden Sie für die Rich-Text-Bearbeitung TipTap (Framework-Abhängigkeit) – es bereinigt durch sein Schema
+- Verwenden Sie zum Rendern von Markdown `react-markdown` – es wird sicher in React-Elemente konvertiert
+
+## Serverseitiger Abruf (SSRF) {#ssrf}
+
+Jeder serverseitige `fetch` eines benutzer- oder agentengesteuerten URL muss den Framework-SSRF-Guard durchlaufen, oder er kann auf Cloud-Metadaten (`169.254.169.254`), `localhost` oder interne Dienste verweisen:
+
+```ts
+import { ssrfSafeFetch } from "@agent-native/core/extensions/url-safety";
+
+const res = await ssrfSafeFetch(userProvidedUrl, {}, { maxRedirects: 3 });
+```
+
+`ssrfSafeFetch` blockiert private/interne Ziele, überprüft die aufgelöste IP zum Zeitpunkt der Verbindung erneut (DNS-Neubindung) und validiert jeden Umleitungs-Hop erneut, sodass ein öffentliches URL nicht in das private Netzwerk umleiten kann. Der Erweiterungs-Iframe-Proxy `upload-image` und der Design-Token-Importer leiten alle darüber weiter. Für eine Prüfung nur vor dem Flug verwenden Sie `isBlockedExtensionUrlWithDns(url)` mit `redirect: "manual"`.
+
+## Datenumfang {#data-scoping}
+
+In der Produktion beschränkt das Framework automatisch Agenten-SQL-Abfragen auf die Daten des aktuellen Benutzers. Dies wird auf SQL-Ebene erzwungen – Agenten können es nicht umgehen. Dieser Abschnitt ist die kanonische Referenz für die Scoping-Pipeline. Der Link zu den Dokumenten [Authentication](/docs/authentication) und [Multi-Tenancy](/docs/multi-tenancy) finden Sie hier für die Mechanik.
+
+### Die Scoping-Pipeline {#scoping-pipeline}
+
+Scoping fließt von der authentifizierten Sitzung bis hinunter zu SQL, den der Agent ausführt:
+
+```
+session.orgId → AGENT_ORG_ID → SQL row scoping
+```
+
+```an-diagram title="The scoping pipeline" summary="Agent SQL never touches base tables directly — it reads through a temporary view scoped to the current identity, so a bare table name can only return owned rows."
+{
+  "html": "<div class=\"scope-pipe\"><div class=\"diagram-node\">Signed-in session<br><small class=\"diagram-muted\">email &middot; orgId</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Request context<br><small class=\"diagram-muted\">AGENT_ORG_ID</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Temporary VIEW<br><small class=\"diagram-muted\">WHERE owner_email = ? AND org_id = ?</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">Agent SQL<br><small class=\"diagram-muted\">bare table names only</small></div></div>",
+  "css": ".scope-pipe{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.scope-pipe .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.scope-pipe .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Die angemeldete Sitzung trägt `email` und (wenn eine Organisation aktiv ist) `orgId`. Das Framework stellt den Anforderungskontext dieser Sitzung her, stellt die aktive Organisation dem Agenten SQL als `AGENT_ORG_ID` zur Verfügung und schreibt jede Abfrage neu, sodass nur Zeilen angezeigt werden können, die der aktuellen Identität gehören. Der gleiche Pfad gilt unabhängig davon, ob die Abfrage von UI, einer Aktion oder dem Agenten kommt – der Agent kann keine Daten für eine Organisation lesen, der der Benutzer nicht angehört.
+
+### Scoping pro Benutzer (`owner_email`)
+
+Jede Tabelle mit benutzerspezifischen Daten **muss** eine `owner_email`-Textspalte haben. Verwenden Sie den Eigenschaftsnamen „camelCase Drizzle“ – `accessFilter` liest `resourceTable.ownerEmail`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  ownableColumns,
+} from "@agent-native/core/db/schema";
+
+// Minimal: just the owner column
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ownerEmail: text("owner_email").notNull(), // REQUIRED — camelCase property
+});
+
+// Or use ownableColumns() to add owner_email + org_id + visibility in one call
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ...ownableColumns(),
+});
+```
+
+Das Framework erstellt temporäre SQL-Ansichten, die Abfragen automatisch filtern:
+
+```sql
+CREATE TEMPORARY VIEW "notes" AS
+  SELECT * FROM main."notes"
+  WHERE "owner_email" = 'alice@example.com';
+```
+
+Bei INSERT-Anweisungen wird `owner_email` automatisch eingefügt, wenn die Spalte noch nicht vorhanden ist.
+
+Die Tools `db-query`/`db-exec` lehnen schemaqualifizierte Tabellenverweise (`public.<table>`, `main.<table>`) ab – ein qualifizierter Name wird in die Basistabelle aufgelöst und würde die obige temporäre Ansicht umgehen. Agenten verwenden bloße Tabellennamen; Der Geltungsbereich wird automatisch angewendet.
+
+### Pro-Organisation-Scoping (`org_id`)
+
+Fügen Sie für Mehrbenutzer-Apps, in denen Teams Daten teilen, eine `org_id`-Spalte hinzu. Wenn beide Spalten vorhanden sind, gelten für Abfragen beide Spalten: `WHERE owner_email = ? AND org_id = ?`.
+
+Der `ownableColumns()`-Schemahelfer fügt `owner_email`, `org_id` und `visibility` in einem Aufruf hinzu, sodass neue mandantenfähige Tabellen standardmäßig den vollständigen Scoping-Vertrag erhalten:
+
+```ts
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  ...ownableColumns(), // adds owner_email + org_id + visibility
+});
+```
+
+```an-schema title="What ownableColumns() adds" summary="The three columns that make a table tenant-aware and shareable."
+{
+  "entities": [
+    {
+      "id": "ownable",
+      "name": "ownable resource",
+      "note": "Any table that spreads ...ownableColumns()",
+      "fields": [
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "Creator. Auto-filled by write actions; auto-injected on INSERT." },
+        { "name": "org_id", "type": "text", "nullable": true, "note": "Owner's active org at creation. Drives org-visibility checks." },
+        { "name": "visibility", "type": "enum", "nullable": false, "note": "private | org | public — coarse default, defaults to private." }
+      ]
+    }
+  ]
+}
+```
+
+### Zugriffsschutz in actions {#access-guards}
+
+Der Rohagent SQL wird durch die oben genannten temporären Ansichten abgedeckt. Aktionscode, der direkt mit Drizzle abfragt, sollte die Zugriffshilfen des Frameworks durchlaufen, damit Lese- und Schreibvorgänge auf die aktuelle Identität beschränkt bleiben:
+
+- **`accessFilter`** – gibt das `WHERE`-Prädikat zurück, das eine Abfrage auf Zeilen beschränkt, die der aktuelle Benutzer/die aktuelle Organisation sehen kann. Verwenden Sie es in Listen-/Leseabfragen.
+- **`resolveAccess`** – löst den effektiven Zugriffsbereich (Eigentümer, Organisation, freigegeben) für die aktuelle Anfrage auf.
+- **`assertAccess`** – schützt einen Schreib- oder Einzeldatensatz-Lesevorgang und löst aus, wenn die aktuelle Identität möglicherweise nicht auf die Zielzeile wirkt.
+
+Mit `ownableColumns()` erstellte Tabellen erfordern diese bereichsbezogenen Lese- und Schreibvorgänge. Benutzerdefinierte Nitro-Routen müssen den Anforderungskontext herstellen, bevor besitzbare Daten abgefragt werden. Die `guard-no-unscoped-queries`-Prüfung (ausgeführt über `pnpm guards`) erzwingt dies zum CI-Zeitpunkt. Den vollständigen Helfer API finden Sie im `sharing`-Skill.
+
+### Validierung
+
+```bash
+pnpm action db-check-scoping           # Check all tables have owner_email
+pnpm action db-check-scoping --require-org  # Also require org_id
+```
+
+## Geheimnisverwaltung {#secrets}
+
+| Geheimtyp                                          | Speicherort                                                           |
+| -------------------------------------------------- | --------------------------------------------------------------------- |
+| Schlüssel auf Bereitstellungsebene (einer pro App) | `.env`-Datei (gitignored, nur serverseitig)                           |
+| API-Schlüssel pro Benutzer/pro Organisation        | `saveCredential` / `resolveCredential` (im Ruhezustand verschlüsselt) |
+| Registrierte Geheimnisse (Sidebar-Tresor)          | `app_secrets`-Tresor (im Ruhezustand verschlüsselt)                   |
+| OAuth-Tokens (Google, GitHub)                      | `oauth_tokens`-Speicher über `saveOAuthTokens()`                      |
+| Sitzungstoken                                      | Automatisch (Better Auth erledigt dies)                               |
+
+Anmeldeinformationen pro Benutzer/pro Organisation und der Tresor werden im Ruhezustand mit AES-256-GCM verschlüsselt, verschlüsselt durch `SECRETS_ENCRYPTION_KEY` (Rückfall auf `BETTER_AUTH_SECRET`); Die Produktion weigert sich, ohne sie anzufangen. Um alle bereits vorhandenen Klartext-Anmeldeinformationszeilen zu verschlüsseln, führen Sie `pnpm action db-migrate-encrypt-credentials` (idempotent, nicht destruktiv) aus.
+
+Speichern Sie niemals Geheimnisse in `settings`, `application_state`, Quellcode oder Aktionsantworten. Verwenden Sie die oben genannten APIs für Anmeldeinformationen/Tresor – sie übernehmen sowohl die Verschlüsselung als auch die Festlegung des Scopings pro Benutzer.
+
+## Authentifizierung {#auth}
+
+Die Authentifizierung erfolgt automatisch. Die vollständige Einrichtung finden Sie in den [Authentication](/docs/authentication)-Dokumenten.
+
+**Wichtige Punkte für die Sicherheit:**
+
+- `defineAction`-Endpunkte werden automatisch durch den Authentifizierungsschutz geschützt
+- Benutzerdefinierte `/api/`-Routen müssen `getSession(event)` aufrufen und das Ergebnis überprüfen
+- Zustandsänderungsvorgänge sollten POST verwenden (die Standardeinstellung für actions)
+- `SameSite=lax`- und `httpOnly`-Cookies verhindern die meisten CSRF-Angriffe
+
+## A2A Identitätsüberprüfung {#a2a-identity}
+
+Wenn Apps einander über das A2A-Protokoll anrufen, überprüfen sie die Identität mithilfe von JWT-Tokens, die mit einem gemeinsamen Geheimnis signiert sind:
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+1. App A signiert einen JWT, der `sub: "steve@example.com"` enthält
+2. App B überprüft die JWT-Signatur mit demselben Geheimnis
+3. App B liest den verifizierten `sub`-Anspruch in den Anforderungskontext
+4. Es gilt der Datenbereich – App B zeigt nur Steves Daten
+
+Ohne `A2A_SECRET` in der Produktion geben jeder A2A-Endpunkt und der `/_agent-native/integrations/process-task`-Self-Fire-Endpunkt **503** zurück. Legen Sie es für jede App fest, die A2A-Verkehr anruft oder empfängt. (Für die lokale Entwicklung erlaubt das Framework weiterhin nicht authentifizierte Aufrufe.)
+
+## Eingehender Webhooks {#webhooks}
+
+Eingehende Webhook-Handler (Resend, SendGrid, Slack, Telegram, WhatsApp, Recall.ai, Deepgram, Zoom, Google Docs Pub/Sub) lehnen gefälschte Anfragen standardmäßig in der Produktion ab: Wenn die entsprechende signierende geheime Umgebungsvariable fehlt, gibt der Handler 401 zurück, anstatt sie zu akzeptieren und zu versenden.
+
+Dies war zuvor eine „Warnen und Akzeptieren“-Haltung – legen Sie das Geheimnis fest, das Ihnen sonst entgehen würde, oder entscheiden Sie sich für das alte Verhalten mit `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` nur für lokale Entwickler. Informationen zu den Signaturgeheimnisvariablen pro Integration finden Sie unter [Messaging](/docs/messaging#env-vars).
+
+## Produktionscheckliste {#production-checklist}
+
+### Auth & Geheimnisse
+
+- [ ] `BETTER_AUTH_SECRET` ist auf eine zufällige Zeichenfolge mit mehr als 32 Zeichen (`openssl rand -hex 32`) festgelegt, es sei denn, es handelt sich um eine gehostete Arbeitsbereichsbereitstellung, die von `A2A_SECRET` abgeleitet wird
+- [ ] `OAUTH_STATE_SECRET` wird auf eine separate zufällige Zeichenfolge mit mehr als 32 Zeichen gesetzt (`BETTER_AUTH_SECRET` nicht wiederverwenden) – siehe [OAuth State Signing](#oauth-state)
+- [ ] `A2A_SECRET` wird für jede App festgelegt, die A2A-Verkehr aufruft oder empfängt – siehe [A2A Identity Verification](#a2a-identity)
+- [ ] `SECRETS_ENCRYPTION_KEY`-Set (oder verlassen Sie sich auf den `BETTER_AUTH_SECRET`-Fallback) – siehe [Secrets Management](#secrets)
+- [ ] `AUTH_SKIP_EMAIL_VERIFICATION` ist **nicht** in der Produktion festgelegt (oder nur bei QA-Vorschaubereitstellungen festgelegt)
+
+### Webhook-Geheimnisse (legen Sie diejenigen für die von Ihnen verwendeten Integrationen fest)
+
+- [ ] Signierungsgeheimnissatz für jede aktivierte eingehende Integration – siehe [Inbound Webhooks](#webhooks) und [Messaging](/docs/messaging#env-vars) für die Liste pro Integration.
+- [ ] `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` ist **nicht** in Produkt festgelegt
+
+### Schema
+
+- [ ] Jede benutzerseitige Tabelle hat `owner_email`, Mehrbenutzertabellen auch `org_id` – siehe [Data Scoping](#data-scoping)
+- [ ] Lese-/Schreibvorgänge in der Ownable-Tabelle erfolgen über [access guards](#access-guards)
+- [ ] Alle actions verwenden `defineAction` mit Zod `schema:` – siehe [Input Validation](#input-validation)
+- [ ] Serverseitige Abrufe von Benutzer-/Agent-URLs erfolgen über `ssrfSafeFetch` – siehe [SSRF](#ssrf)
+- [ ] Kein `dangerouslySetInnerHTML` mit Benutzerinhalten (oder die Ausgabe erfolgt über DOMPurify)
+- [ ] Kein durch Zeichenfolge verkettetes SQL
+- [ ] `pnpm guards` ist sauber (`guard-no-unscoped-queries`, `guard-no-env-credentials`, `guard-no-env-mutation`, `guard-no-localhost-fallback`, `guard-no-unscoped-credentials`, `guard-no-drizzle-push`)
+- [ ] Getestet mit zwei Benutzerkonten, um die Datenisolation zu überprüfen
+
+### Verschiedene Härtung
+
+- [ ] `AGENT_NATIVE_DEBUG_ERRORS` ist **nicht** in echten Produkten festgelegt (nur bei Debug-Vorschauen)
+- [ ] `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK` ist **nicht** festgelegt, es sei denn, Ihre Organisation teilt tatsächlich Arbeitsbereichsschlüssel – siehe [Cross-User Tooling Secrets](#tooling-secrets)
+- [ ] In mandantenfähigen Bereitstellungen **bringen Benutzer ihr eigenes `ANTHROPIC_API_KEY` mit** – das Framework weigert sich, auf die Umgebungsvariable auf Bereitstellungsebene zurückzugreifen
+
+---
+
+In den folgenden Abschnitten werden Nischenumgebungsflags behandelt, die Sie nur in bestimmten Bereitstellungen erreichen. Die meisten Apps berühren sie nie.
+
+## OAuth Zustandssignierung {#oauth-state}
+
+OAuth-Flows (Google, Atlassian, Zoom) signieren ihren Statusumschlag mit einem dedizierten HMAC-Schlüssel:
+
+```bash
+OAUTH_STATE_SECRET=$(openssl rand -hex 32)
+```
+
+Früher wurde auf `GOOGLE_CLIENT_SECRET` zurückgegriffen (ein mit Google geteilter Berechtigungsnachweis) – ein Leak des Google-Geheimnisses hätte es Angreifern ermöglicht, OAuth-Staatsumschläge zu fälschen. Der dedizierte Schlüssel ist unabhängig von Geheimnissen Dritter. Wenn `OAUTH_STATE_SECRET` nicht festgelegt ist, greift das Framework auf `BETTER_AUTH_SECRET` zurück; Gehostete Arbeitsbereichsbereitstellungen können auch einen zweckgebundenen OAuth-Schlüssel aus dem bereits erforderlichen `A2A_SECRET` ableiten. Wenn keines dieser Servergeheimnisse verfügbar ist, schlagen OAuth-Flows in der Produktion fehl.
+
+`redirect_uri`-Abfrageparameter werden auch anhand einer Zulassungsliste validiert (gleicher Ursprung + Framework-`/_agent-native/...`-Pfade). Benutzerdefinierte OAuth-Flows in Vorlagen sollten vor dem Signieren des Status den `isAllowedOAuthRedirectUri()`-Helfer des Frameworks verwenden.
+
+## Cross-User-Tooling-Geheimnisse {#tooling-secrets}
+
+Tools und Automatisierungen, die auf `${keys.NAME}` verweisen, lösen Geheimnisse standardmäßig pro Benutzer auf. Der Workspace-Scope-Fallback ist in dieser Version **standardmäßig deaktiviert** – ein böswilliges Organisationsmitglied könnte andernfalls einen Workspace `OPENAI_API_KEY` einschleusen und die API-Aufrufe anderer Mitglieder abfangen.
+
+Wenn Ihre Organisation tatsächlich arbeitsbereichsweite Schlüssel teilt (z. B. einen einzelnen Unternehmens-Stripe-Schlüssel), kehren Sie zum alten Verhalten zurück mit:
+
+```bash
+AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
+```
+
+Für geheime Schreibvorgänge im Arbeitsbereichsbereich ist unabhängig von diesem Flag weiterhin die Rolle „Organisationsbesitzer/-administrator“ erforderlich.

package/docs/content/locales/de-DE/server.md

@@ -0,0 +1,253 @@
+---
+title: "Server"
+description: "Nitro-Serverrouten, Plugins, im Framework bereitgestellte Routen, Anforderungskontext und SQL-gestützte Synchronisierung."
+---
+
+# Server
+
+Agent-native Apps verwenden [Nitro](https://nitro.build) für Serverrouten und Plugins. Das meiste Produktverhalten sollte in [Actions](/docs/actions) leben; Benutzerdefinierte Routen gelten für Protokolloberflächen, für die actions nicht geeignet ist: Uploads, Streaming, öffentliche Seiten, webhooks-, OAuth-Rückrufe und anbieterspezifische APIs.
+
+```an-diagram title="What runs on the server" summary="Actions are the default. Custom file routes and framework-mounted routes share the same Nitro app and the same SQL database."
+{
+  "html": "<div class=\"diagram-server\"><div class=\"diagram-col entry\"><div class=\"diagram-node\">Browser / UI</div><div class=\"diagram-node\">Agent loop</div><div class=\"diagram-node\">External clients<br><small class=\"diagram-muted\">HTTP · MCP · A2A</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Nitro server</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">default surface</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/_agent-native/*</span><small class=\"diagram-muted\">framework routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">/api/*</span><small class=\"diagram-muted\">custom file routes</small></div><div class=\"diagram-row\"><span class=\"diagram-pill\">plugins</span><small class=\"diagram-muted\">startup: migrations, jobs</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL database<br><small class=\"diagram-muted\">Drizzle · the coordination point</small></div></div>",
+  "css": ".diagram-server{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-server .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-server .diagram-panel{display:flex;flex-direction:column;gap:8px;padding:14px 16px}.diagram-server .diagram-row{display:flex;align-items:center;gap:8px}.diagram-server .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Dateibasierte Routen {#file-based-routes}
+
+Routen leben in `server/routes/` und Nitro ordnet Dateinamen Methoden und Pfaden zu:
+
+```text
+server/routes/
+  api/
+    health.get.ts              -> GET  /api/health
+    uploads.post.ts            -> POST /api/uploads
+    webhooks/
+      stripe.post.ts           -> POST /api/webhooks/stripe
+  [...page].get.ts             -> SSR catch-all for public pages
+```
+
+Jede Route exportiert einen `defineEventHandler`:
+
+```ts
+// server/routes/api/health.get.ts
+import { defineEventHandler } from "h3";
+
+export default defineEventHandler(() => ({
+  ok: true,
+  service: "my-template",
+}));
+```
+
+### Routenbenennungskonventionen {#route-naming-conventions}
+
+| Dateinamenmuster   | HTTP-Methode | Beispielpfad                  |
+| ------------------ | ------------ | ----------------------------- |
+| `index.get.ts`     | GET          | `/api/items`                  |
+| `index.post.ts`    | POST         | `/api/items`                  |
+| `[id].get.ts`      | GET          | `/api/items/:id`              |
+| `[id].patch.ts`    | PATCH        | `/api/items/:id`              |
+| `[id].delete.ts`   | DELETE       | `/api/items/:id`              |
+| `[...slug].get.ts` | GET          | `/api/items/*` oder Catch-All |
+
+## Actions für App-Vorgänge bevorzugen {#actions-first}
+
+Wenn UI und Agent beide etwas tun müssen, definieren Sie eine Aktion anstelle einer benutzerdefinierten API-Route. Actions wird automatisch zu:
+
+- Agent-Tools.
+- Typisierte Frontend-Hooks.
+- HTTP-Endpunkte unter `/_agent-native/actions/:name`.
+- MCP- und A2A-aufrufbare Tools.
+- CLI-Befehle für die Entwicklung.
+
+Verwenden Sie benutzerdefinierte `/api/*`-Routen nur, wenn Sie ein routenförmiges Protokoll oder Binär-/Streaming-Verhalten benötigen. Siehe [Actions](/docs/actions).
+
+## One-Shot-Textvervollständigung {#complete-text}
+
+Der Großteil der KI-Arbeit sollte über den Agenten-Chat erfolgen, damit Benutzer sehen, steuern und prüfen können
+was passiert ist. Für schmale serverseitige Transformationen, die absichtlich nicht benötigt werden
+Tools, Chat-Verlauf oder Ausführungsstatus verwenden `completeText()` als expliziten Escape
+Luke.
+
+```ts
+// actions/classify-message.ts
+import { defineAction } from "@agent-native/core/action";
+import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Classify a short message",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
+    const result = await completeText({
+      systemPrompt:
+        "Return exactly one label: urgent, follow-up, waiting, or archive.",
+      input: body,
+      maxOutputTokens: 16,
+      temperature: 0,
+    });
+
+    return { label: result.text.trim() };
+  },
+});
+```
+
+`completeText()` läuft über dieselbe konfigurierte Engine-Ebene wie der Agent
+Chat, einschließlich Builder, Anthropic, AI SDK-Anbieter, Benutzer-/App-Modellstandards,
+Anfragebezogene Geheimnisse und Engine-normalisierte Fehler. Es ist nur für den Server verfügbar. nicht
+Modellanbieter aus Client-Code aufrufen. Wenn der Vorgang benutzerorientiert ist, schließen Sie ihn ein
+in einer Aktion, damit UI und Agent die gleiche Fähigkeit teilen.
+
+## Kontext und Zugriff anfordern {#request-context}
+
+Actions, das vom Framework bereitgestellt wird, wird automatisch mit dem Anforderungskontext ausgeführt. Bei benutzerdefinierten Routen ist dies nicht der Fall. Wenn eine benutzerdefinierte Route besitzbare Ressourcen liest oder schreibt, laden Sie die Sitzung und schließen Sie die Arbeit ein:
+
+```an-annotated-code title="Scoping a custom route to the request user"
+{
+  "filename": "server/routes/api/projects.get.ts",
+  "language": "ts",
+  "code": "import { defineEventHandler, createError } from \"h3\";\nimport { getSession, runWithRequestContext } from \"@agent-native/core/server\";\nimport { getDb } from \"../../db/index.js\";\nimport { accessFilter } from \"@agent-native/core/sharing\";\nimport * as schema from \"../../db/schema\";\n\nexport default defineEventHandler(async (event) => {\n  const session = await getSession(event);\n  if (!session?.email) {\n    throw createError({ statusCode: 401, statusMessage: \"Unauthorized\" });\n  }\n\n  return runWithRequestContext(\n    { userEmail: session.email, orgId: session.orgId },\n    async () => {\n      const db = getDb();\n      return db\n        .select()\n        .from(schema.projects)\n        .where(accessFilter(schema.projects, schema.projectShares));\n    },\n  );\n});",
+  "annotations": [
+    { "lines": "7-10", "label": "Custom routes have no auto-context", "note": "Unlike actions, a file route must load the session itself and fail closed when there is no authenticated user." },
+    { "lines": "12-13", "label": "Establish request context", "note": "`runWithRequestContext` makes the user/org available to scoping helpers for the duration of the work." },
+    { "lines": "18-19", "label": "Scope ownable reads", "note": "`accessFilter` constrains the query to rows the caller may see. Never run an unscoped `db.select().from(ownableTable)` here." }
+  ]
+}
+```
+
+`getDb` wird pro App über `createGetDb(schema)` in `server/db/index.ts` erstellt, daher importieren benutzerdefinierte Routen es aus der Vorlage (`../../db/index.js`), nicht aus `@agent-native/core/db`; siehe [Database — Where the DB Client Lives](/docs/database#db-client). Führen Sie `db.select().from(ownableTable)` ohne Gültigkeitsbereich nicht in benutzerdefinierten Routen aus.
+
+## Server-Plugins {#server-plugins}
+
+Plugins leben in `server/plugins/` und werden beim Start ausgeführt. Verwenden Sie sie für Migrationen, Anbietereinrichtung, wiederkehrende Jobs, Integrationsadapter und Framework-Plugin-Konfiguration.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+Migrationen müssen additiv sein. Fügen Sie niemals destruktives SQL in Startup-Plugins ein.
+
+## Framework-montierte Routen {#framework-routes}
+
+Das Framework mountet seine eigenen Routen unter `/_agent-native/`. Behandeln Sie diesen Namespace als reserviert.
+
+| Routenpräfix                     | Zweck                                                                                 |
+| -------------------------------- | ------------------------------------------------------------------------------------- |
+| `/_agent-native/actions/:name`   | Aktion HTTP Endpunkte                                                                 |
+| `/_agent-native/agent-chat`      | Agent-Chat-Schleife                                                                   |
+| `/_agent-native/poll`            | SQL-gestützte UI-Synchronisierung                                                     |
+| `/_agent-native/resources/*`     | Arbeitsbereichsressourcen                                                             |
+| `/_agent-native/extensions/*`    | Laufzeiterweiterungen und Erweiterungs-Proxy (Legacy-Alias: `/_agent-native/tools/*`) |
+| `/_agent-native/integrations/*`  | Messaging-/Webhook-Integrationen                                                      |
+| `/_agent-native/a2a`             | Agent-zu-Agent JSON-RPC                                                               |
+| `/_agent-native/mcp`             | MCP-Endpunkt                                                                          |
+| `/_agent-native/onboarding/*`    | Setup-Checkliste                                                                      |
+| `/_agent-native/observability/*` | Spuren, Feedback, Bewertungen, Experimente                                            |
+| `/_agent-native/file-upload`     | Endpunkt des Datei-Upload-Anbieters                                                   |
+
+Benutzerdefinierte App-Routen sollten `/api/*`, öffentliche App-Pfade oder anbieterspezifische Rückrufpfade verwenden, die nicht mit `/_agent-native/` kollidieren.
+
+## SQL-Backed Sync {#sync}
+
+Agent-native verlässt sich nicht auf Dateisystem-Watcher oder einen Sticky-In-Memory-Status. Wenn actions oder Framework-Helfer Daten ändern, erhöht sich die Datenbanksynchronisierungsversion. Der Client-Hook `useDbSync()` fragt `/_agent-native/poll` ab und macht React-Abfragecaches ungültig.
+
+Dies funktioniert bei serverlosen und Multi-Instanz-Bereitstellungen, da die Datenbank der Koordinationspunkt ist. Wenn Sie benutzerdefinierte Mutationen außerhalb von actions schreiben, verwenden Sie Framework-Helfer oder geben Sie die entsprechende Synchronisierungsinvalidierung aus, also öffnen Sie die Aktualisierung von UIs.
+
+```an-diagram title="SQL-backed sync loop" summary="No watchers, no sticky state. A write bumps a version in SQL; every client polls the version and refetches."
+{
+  "html": "<div class=\"diagram-sync\"><div class=\"diagram-box\" data-rough>Action / helper<br><small class=\"diagram-muted\">mutates data</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong><small class=\"diagram-muted\">sync version increments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&larr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">useDbSync()<br><small class=\"diagram-muted\">polls /_agent-native/poll</small></div><div class=\"diagram-pill ok\">invalidate caches &rarr; UI refreshes</div></div></div>",
+  "css": ".diagram-sync{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-sync .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:flex-start}.diagram-sync .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The poll endpoint" method="GET" path="/_agent-native/poll"
+{
+  "method": "GET",
+  "path": "/_agent-native/poll",
+  "summary": "Return the current per-source database sync versions so the client can detect changes.",
+  "description": "`useDbSync()` calls this on an interval (and falls back to it when SSE is unavailable). When a returned version is higher than the client's last-seen value, the matching React Query caches are invalidated and refetch.",
+  "auth": "Session cookie (request-scoped identity)",
+  "responses": [
+    { "status": "200", "description": "Current sync versions keyed by source." }
+  ]
+}
+```
+
+## Webhooks {#webhooks}
+
+Eingehender webhooks sollte überprüft werden, bestehen bleiben und schnell zurückkehren. Für lang andauernde Agentenarbeiten sollte das Muster der Integrationswarteschlange verwendet werden:
+
+1. Überprüfen Sie die Plattformsignatur oder Challenge.
+2. Dauerhafte Arbeit in SQL einfügen.
+3. Selbstauslösen einer signierten Prozessorroute.
+4. 200 sofort zurückgeben.
+5. Lassen Sie die neue Prozessorausführung die Agentenschleife ausführen und das Ergebnis veröffentlichen.
+
+```an-diagram title="Integration queue pattern" summary="The webhook handler returns in milliseconds; a separate signed execution runs the slow agent work."
+{
+  "html": "<div class=\"diagram-webhook\"><div class=\"diagram-box\" data-rough>Inbound webhook<br><small class=\"diagram-muted\">Slack · Stripe · email</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel\" data-rough><strong>Handler</strong><div class=\"diagram-step\"><span class=\"diagram-pill\">1</span><small class=\"diagram-muted\">verify signature</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><small class=\"diagram-muted\">insert work into SQL</small></div><div class=\"diagram-step\"><span class=\"diagram-pill\">3</span><small class=\"diagram-muted\">self-fire processor</small></div><div class=\"diagram-step\"><span class=\"diagram-pill ok\">4</span><small class=\"diagram-muted\">return 200 now</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Signed processor<br><small class=\"diagram-muted\">runs agent loop, posts result</small></div></div>",
+  "css": ".diagram-webhook{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-webhook .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-webhook .diagram-step{display:flex;align-items:center;gap:8px}.diagram-webhook .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+> [!WARNING]
+> Verlassen Sie sich nicht auf unerwartete Versprechen, nachdem Sie eine Antwort zurückgegeben haben – serverlose Hosts frieren die Ausführung ein. Informationen zur kanonischen Integrationswarteschlange finden Sie unter [Messaging](/docs/messaging).
+
+## Fortgeschritten: Fluchtluken {#advanced-escape-hatches}
+
+Die meisten Vorlagen benötigen diese nie. Nitro-Dateirouten und der Agent des Frameworks
+Das Chat-Plugin verbindet bereits den App-Server und den Produktionsagenten-Handler.
+Ergreifen Sie sie nur, wenn Sie eine benutzerdefinierte Serverintegration außerhalb von
+Standard-Vorlagen-Plugin-Stack.
+
+### Programmatische H3-Server {#create-server}
+
+Für benutzerdefinierte Pakete oder Tests, die direkt eine H3-App benötigen, `createServer()`
+gibt eine vorkonfigurierte App und einen vorkonfigurierten Router zurück:
+
+```ts
+import { createServer } from "@agent-native/core/server";
+import { defineEventHandler } from "h3";
+
+const { app, router } = createServer();
+
+router.get(
+  "/api/health",
+  defineEventHandler(() => ({ ok: true })),
+);
+```
+
+### Produktionsagenten-Handler {#agent-handler}
+
+Das Agent-Chat-Plugin des Frameworks mountet bereits den Produktions-Agent-Handler
+für Vorlagen. Rufen Sie `createProductionAgentHandler()` beim Erstellen nur direkt auf
+eine benutzerdefinierte Serverintegration außerhalb des Standard-Vorlagen-Plugin-Stacks –
+Ansonsten passen Sie den Agenten über `AGENTS.md`, skills, actions usw. an.
+Agent-Chat-Plugin.
+
+```ts
+import { createProductionAgentHandler } from "@agent-native/core/server";
+
+const handler = createProductionAgentHandler({
+  scripts,
+  systemPrompt: "You are the app agent...",
+});
+```