SKALD.md: document OAuth deliver, auth in index, oauth/show.html

SKALD.md

@@ -1,8 +1,10 @@
 # Skald Connectors Marketplace
 
-_Updated: 2026-07-16_
+_Updated: 2026-07-17_
 
 **Remote**: `https://git.skaldagent.net/dguiducci/skald-connectors.git` (branch: `main`)
+**Live**: `https://connectors.skaldagent.net/`
+**OAuth callback**: `https://connectors.skaldagent.net/oauth/show.html`
 
 ## Cos'è
 
@@ -19,6 +21,8 @@ Due tipi di connector:
 connectors/
 ├── connectors.json          ← INDICE (radice di fiducia unica)
 ├── index.html               ← Catalogo UI (legge connectors.json via fetch)
+├── oauth/
+│   └── show.html            ← OAuth callback receiver (client-side, no backend)
 ├── gmail/                   ← Un connector per cartella
 │   ├── connector.json       ← Configurazione tecnica
 │   ├── gmail_mcp_server.py  ← Script MCP
@@ -26,8 +30,22 @@ connectors/
 │   ├── requirements.txt     ← Dipendenze Python
 │   ├── icon_sm.svg          ← Icona piccola (48×48)
 │   └── icon_lg.svg          ← Icona grande (es. preview)
+├── email/
+│   ├── connector.json
+│   ├── email_mcp_server.py
+│   ├── verify.py
+│   ├── requirements.txt
+│   ├── icon_sm.svg
+│   └── icon_lg.svg
+├── ssh/
+│   ├── connector.json
+│   ├── ssh_mcp_server.py
+│   ├── requirements.txt
+│   ├── icon_sm.svg
+│   └── icon_lg.svg
 └── tavily/
     ├── connector.json
+    ├── verify.py
     ├── icon_sm.png
     └── icon_lg.png
 ```
@@ -51,8 +69,18 @@ Non ha hash di sé stesso — in futuro potrà essere firmato digitalmente.
       "user_description": "Read, send, and manage Gmail emails via OAuth...",
       "requires": ["OAUTH", "PYTHON"],
       "tags": ["email", "mcp", "local", "google"],
+      "auth": {
+        "type": "oauth2",
+        "provider": "google",
+        "scopes": [
+          "https://www.googleapis.com/auth/gmail.modify",
+          "https://www.googleapis.com/auth/gmail.labels"
+        ]
+      },
       "folder": "gmail",
       "files": [
+| `auth` | per OAuth | Oggetto con `type`, `provider`, `scopes` per badge UI (NO `deliver` qui, è nel manifest) |
+
         {"path": "gmail_mcp_server.py",  "sha256": "a50d4da9621f7a4b092f...", "size": 46772},
         {"path": "gmail_oauth_setup.py", "sha256": "e488acb289c43a3e6d54...", "size": 3627},
         {"path": "icon_lg.svg",          "sha256": "93c8d9c8dae96f0206e5...", "size": 254},
@@ -119,7 +147,12 @@ Configurazione tecnica per l'attivazione del connector.
     "scopes": [
       "https://www.googleapis.com/auth/gmail.modify",
       "https://www.googleapis.com/auth/gmail.labels"
-    ]
+    ],
+    "deliver": {
+      "as": "file",
+      "format": "google_authorized_user",
+      "path": "{secrets}/gmail_creds.json"
+    }
   },
   "mcp_config": {
     "command": "python3",
@@ -197,9 +230,13 @@ Struttura che descrive come il connector gestisce l'autenticazione:
 // API key in header
 {"type": "api_key", "delivery": "header", "param": "X-API-Key"}
 
-// OAuth2
+// OAuth2 — provider SOLO slug (Skald risolve endpoint + client secrets)
 {"type": "oauth2", "provider": "google", "scopes": ["...", "..."]}
 
+// OAuth2 con deliver (come Skald consegna la credenziale al processo MCP)
+{"type": "oauth2", "provider": "google", "scopes": ["..."],
+ "deliver": {"as": "file", "format": "google_authorized_user", "path": "{secrets}/gmail_creds.json"}}
+
 // Password / app-password fornita via variabili d'ambiente
 {"type": "password", "delivery": "env"}
 
@@ -207,6 +244,18 @@ Struttura che descrive come il connector gestisce l'autenticazione:
 {"type": "none"}
 ```
 
+### Campo deliver (solo OAuth2)
+
+Dichiara **come** Skald consegna la credenziale OAuth ottenuta al processo del server MCP.
+
+| Campo | Obbligatorio | Descrizione |
+|-------|-------------|-------------|
+| `as` | ✅ | `"file"` (su disco) o `"env"` (variabile d'ambiente) |
+| `format` | ✅ | Nome della serializzazione — es. `"google_authorized_user"` (JSON Google che `from_authorized_user_file` legge), `"refresh_token"`, `"access_token"` |
+| `path` | solo `as=file` | Path con placeholder `{secrets}` (Skald lo espande a dir per-utente a runtime). DEVE matchare il path in `mcp_config.env`. |
+
+Il feed NON contiene MAI: `client_id`, `client_secret`, `endpoint` URL, `redirect_uri`. Questi sono risolti lato Skald a partire dal nome del `provider`.
+
 ## Campo env (variabili d'ambiente)
 
 Usato quando `requires` include `ENV`. È un **array** che dichiara le variabili
@@ -390,7 +439,7 @@ sudo find /var/www/connectors.skaldagent.net/ -type f -exec chmod 644 {} \;
 | ID | Nome | Tipo | Scope | Auth | Verify |
 |----|------|------|-------|------|--------|
 | `tavily` | Tavily | `mcp_remote` | `global` | api_key (`{SECRET:tavilyApiKey}` in URL) | `verify.py` (HTTP probe `/search`) |
-| `gmail` | Gmail | `mcp_local` | `user` | oauth2 (Google) | ⏳ Fase 2 — il flusso OAuth non è ancora cablato in skald |
+| `gmail` | Gmail | `mcp_local` | `user` | oauth2 (Google) + deliver: `file/google_authorized_user` | ⏳ Fase 2 — OAuth via loopback listener |
 | `email` | Email (IMAP/SMTP) | `mcp_local` | `user` | password (env) | `verify.py` (IMAP+SMTP probe) |
 | `ssh` | SSH Remote Access | `mcp_local` | `user` | none (auth runtime per-alias) | — (nessun setup credential) |
 **Stato del verify-before-save in skald**: `email` e `tavily` hanno `verify` completo