Add Stirling-PDF agent API access contract + skill. OAuth2 configured but disabled (needs license).

2026-07-03 19:10:22 +00:00
parent 8dfbad5415
commit ae143d7a88
2 changed files with 84 additions and 2 deletions
@@ -142,11 +142,12 @@ description: >

 ### Home Stack Services

-**Stirling-PDF** (deployed 2026-07-03):
- URL: `http://192.168.68.7:8989`
+**Stirling-PDF** (deployed 2026-07-03, Authentik SSO 2026-07-03):
+- URL: `https://pdf.sysloggh.net` (public) / `http://192.168.68.7:8989` (direct)
 - Swagger: `http://192.168.68.7:8989/swagger-ui.html`
 - Admin credentials: `admin` / `kakashi20stirling`
 - API key: `adefaef837314afc37803747049c2e73f456da97699ff1b02b391347c4a3cb88`
+- Authentik OAuth2: configured but disabled (requires paid Server license). Ready to enable: set `SECURITY_OAUTH2_ENABLED=true` + `SECURITY_LOGINMETHOD=all`
 - Compose: `/opt/home_stack/docker-compose.yml`
 - Control script: `/opt/home_stack/infra-control.sh`

@@ -0,0 +1,81 @@
+---
+kind: function
+name: stirling-pdf-agent-access
+version: 1.0.0
+description: >
+  Agent API access pattern for Stirling-PDF. All Syslog agents (Hermes, pi)
+  use the global API key for programmatic PDF operations. No user login,
+  no OAuth — just the X-API-Key header. Designed for automated document
+  processing workflows.
+author: Abiba (pi agent)
+---
+
+# Stirling-PDF Agent Access Contract
+
+## Architecture
+
+```
+Agent (Hermes/pi) ──curl + X-API-Key──► Stirling-PDF (:8989) ──► /configs, /logs
+                                              │
+                                    docker-vm (192.168.68.7)
+```
+
+## Connection Details
+
+| Field | Value |
+|-------|-------|
+| Base URL | `http://192.168.68.7:8989` |
+| Auth Method | API Key (header) |
+| Header Name | `X-API-Key` |
+| API Key | `adefaef837314afc37803747049c2e73f456da97699ff1b02b391347c4a3cb88` |
+| Key Source | `SECURITY_CUSTOMGLOBALAPIKEY` in `/opt/home_stack/docker-compose.yml` |
+| Swagger | `http://192.168.68.7:8989/swagger-ui.html` |
+| Health | `http://192.168.68.7:8989/api/v1/info/status` |
+
+## Agent Integration
+
+### Hermes Agents
+
+The shared skill `stirling-pdf-api` is available in RA-H OS. Hermes agents load it
+from the knowledge graph and use the documented curl patterns.
+
+### pi (Abiba)
+
+Direct bash invocations:
+```bash
+curl -X POST "http://192.168.68.7:8989/api/v1/split-pdf" \
+  -H "X-API-Key: adefaef837314afc37803747049c2e73f456da97699ff1b02b391347c4a3cb88" \
+  -F "fileInput=@/path/to/file.pdf" \
+  -F "pageNumbers=1,2,3" \
+  -o /tmp/output.zip
+```
+
+## Supported Operations
+
+| Operation | Endpoint | Input | Output |
+|-----------|----------|-------|--------|
+| Split PDF | `POST /api/v1/split-pdf` | PDF + page numbers | ZIP of PDFs |
+| Merge PDFs | `POST /api/v1/merge-pdfs` | 2+ PDFs | Single PDF |
+| PDF → Images | `POST /api/v1/convert/pdf-to-img` | PDF + format | ZIP of images |
+| Images → PDF | `POST /api/v1/convert/img-to-pdf` | 1+ images | Single PDF |
+| OCR PDF | `POST /api/v1/ocr-pdf` | Scanned PDF | Searchable PDF |
+| Compress PDF | `POST /api/v1/compress-pdf` | PDF + level | Smaller PDF |
+| Remove Pages | `POST /api/v1/remove-pages` | PDF + page list | Trimmed PDF |
+| Rotate PDF | `POST /api/v1/rotate-pdf` | PDF + angle | Rotated PDF |
+| Add Password | `POST /api/v1/add-password` | PDF + password | Encrypted PDF |
+| Remove Password | `POST /api/v1/remove-password` | PDF + password | Unlocked PDF |
+| Add Watermark | `POST /api/v1/add-watermark` | PDF + text | Watermarked PDF |
+| PDF Info | `POST /api/v1/pdf-info` | PDF | JSON metadata |
+
+## Security
+
+- API key stored ONLY in docker-compose (survives upgrades)
+- API key bypasses user authentication — agents don't need user accounts
+- docker-vm is internal (192.168.68.7), not exposed to internet directly
+- Public access via NetBird nginx: `https://pdf.sysloggh.net` (user login only, agents use internal IP)
+
+## Related Contracts
+
+- `infrastructure-control.prose.md` — docker-vm ecosystem, Stirling-PDF service details
+- `hermes-config-template.prose.md` — agent configuration template
+- Shared skill: `stirling-pdf-api` — API usage patterns and curl examples for agents