From ae143d7a88e827978d07d86de0b2e3f4eb4b2254 Mon Sep 17 00:00:00 2001 From: Abiba Date: Fri, 3 Jul 2026 19:10:22 +0000 Subject: [PATCH] Add Stirling-PDF agent API access contract + skill. OAuth2 configured but disabled (needs license). --- infrastructure-control.prose.md | 5 +- stirling-pdf-agent-access.prose.md | 81 ++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 2 deletions(-) create mode 100644 stirling-pdf-agent-access.prose.md diff --git a/infrastructure-control.prose.md b/infrastructure-control.prose.md index a367d0f..18db5ba 100644 --- a/infrastructure-control.prose.md +++ b/infrastructure-control.prose.md @@ -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` diff --git a/stirling-pdf-agent-access.prose.md b/stirling-pdf-agent-access.prose.md new file mode 100644 index 0000000..672c623 --- /dev/null +++ b/stirling-pdf-agent-access.prose.md @@ -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