# AgentLinkWP

[![Gateway status](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fagentlinkwp-gateway.saadsufianbarzanji.workers.dev%2Fhealth&query=%24.status&label=gateway&up_message=online&up_color=brightgreen)](https://agentlinkwp-gateway.saadsufianbarzanji.workers.dev/health)
[![Last commit](https://img.shields.io/github/last-commit/AIGenArt/AgentLinkWP/main?label=last%20commit)](https://github.com/AIGenArt/AgentLinkWP/commits/main)
[![License](https://img.shields.io/badge/connector-GPL--2.0--or--later-blue)](LICENSE)

**Live gateway:** [`agentlinkwp-gateway.saadsufianbarzanji.workers.dev`](https://agentlinkwp-gateway.saadsufianbarzanji.workers.dev/health)

AgentLinkWP forbinder ChatGPT og andre MCP-kompatible AI-agenter med flere selvhostede WordPress-sites. Brugeren medbringer selv AI-klient og eventuelle betalte WordPress-tjenester; AgentLinkWP kalder ingen betalt AI-model.

Produktionsarkitekturen er bevidst lille:

- **AgentLinkWP Gateway** på Cloudflare Workers med Streamable HTTP på `/mcp`.
- **GitHub OAuth** som login med PKCE og allowlist af uforanderlige numeriske GitHub-bruger-ID'er.
- **Cloudflare KV** til kortlivede OAuth-stateværdier og udstedte MCP-tokens.
- **Cloudflare D1** til krypterede, kortlivede ændringsplaner og metadata-only audit.
- **AgentLinkWP Connector** i hvert WordPress-site som den endelige lokale sikkerhedsgrænse.

GitHub opbevarer kildekode og CI. GitHub er ikke runtime.

## Hvorfor denne arkitektur

AgentLinkWP skal give bred WordPress-management uden at give en AI en universel vej uden om WordPress' sikkerhedsmodel. Alle handlinger skal passere:

1. MCP OAuth 2.1, GitHub OAuth med upstream PKCE og Workerens kontrol af numerisk GitHub-bruger-ID.
2. Gatewayens validering, plan og eksakte bekræftelsesfrase.
3. Den valgte sides maksimale rettighedsloft.
4. Connectorens live allow/deny-politik og ufravigelige hard blocks.
5. Den dedikerede WordPress-brugers normale capabilities.
6. For writes til eksisterende generiske REST-ressourcer: et prepare-time fingerprint, der genkontrolleres umiddelbart før apply.
7. Efter vedvarende writes: uafhængig read-back eller anden specifik eftertilstandsverifikation.

En `deny`-regel vinder altid. Break glass kan bruges til kendte, eksplicit klassificerede højrisiko-operationer. Det kan **ikke** åbne ukendte write-ruter eller ophæve lokale hard blocks.

### Ufravigelige AI-grænser

Følgende må brugeren fortsat gøre manuelt i WordPress/servermiljøet, men AgentLinkWP-broen må ikke gøre dem:

- ukendte eller uklassificerede REST-writes;
- AgentLinkWP Connectorens egen deaktivering eller sletning;
- rå PHP- eller JavaScript-ændringer i theme-workspaces;
- kritiske eller uklassificerede WordPress-settings uden en særskilt typed adapter;
- plugin-, theme- eller core-opdateringer, hvis en rigtig backup-integration ikke kan verificere et nyligt restore-punkt for både filer og database.

## Relevante funktioner

| Område | Understøttelse |
|---|---|
| Flere websites | Separate aliaser, credentials, politikker og audit |
| Indhold | Indlæg, sider, kladder, publicering og versionsbeskyttede typed flows |
| REST | Signeret læsning og planlagte writes til klassificerede WordPress/WooCommerce-ruter; eksisterende ressourcer fingerprintes ved prepare og genkontrolleres før apply |
| Write-verifikation | Vedvarende core/WooCommerce-writes læses tilbage efter write og ønskede felter/datatyper sammenlignes |
| Abilities API | Discovery, schema-inspektion og bekræftet udførelse på WordPress 6.9+; sideeffekter mærkes ikke falsk som verificerede uden en state assertion |
| Temaer | Isoleret kladde, filliste, sikker ikke-eksekverbar filskrivning, preview og særskilt publicering |
| Vedligehold | Cache samt plugin-/tema-/core-opdateringer med rettigheder og restore-capable backup-gate |
| Audit | Metadata om plan, udførelse, fejl og verification; ingen credentials eller indholdsbody |

## Versionslås før write

Typed content-flows bruger WordPress' `modified_gmt`, og theme-file-flows bruger SHA-256. Den generiske REST-prepare-flow bruger et deterministisk JSON-fingerprint af den konkrete ressource. Ved `apply_change` læser gatewayen ressourcen igen og sammenligner fingerprintet **før** write. Hvis noget har ændret sig siden prepare, markeres planen som failed og intet skrives.

Collection-create er bevidst undtaget fra precondition, fordi oprettelse af en ny ressource ikke overskriver en eksisterende ressource. Collection-level update/delete gennem den generiske kanal er blokeret.

## Undgå silent success

Et HTTP 2xx-svar er ikke i sig selv bevis på, at en ændring blev gemt. For vedvarende WordPress- og WooCommerce-writes udfører Connectoren derfor en separat intern REST-læsning efter callbacken. De felter AgentLinkWP bad om at ændre, kontrolleres mod den faktisk gemte ressource, inklusive datatyper hvor det er relevant.

Et write får kun `_agentlinkwp_verification.status = "verified"`, når der findes en konkret eftertilstandsassertion. Gatewayen markerer ikke en persistent plan som `applied`, hvis den forventede verification-marker mangler. Handlinger som cache flush eller en vilkårlig Ability får ikke automatisk dette mærke.

## Verificerede backups

Et backup-ID er ikke et restore-punkt. Før plugin-, theme- eller core-opdateringer kræver Connectoren derfor en provider-uafhængig backup-descriptor, som verificerer det aktuelle site, backupens alder, både filer og database samt en reel restore-kapacitet. Standardvinduet er 30 minutter.

Selve backup-provider-kontrakten er dokumenteret i [`docs/BACKUP_PROVIDERS.md`](docs/BACKUP_PROVIDERS.md). AgentLinkWP hardcoder ikke en bestemt host eller backup-tjeneste.

## Sikker tema-redigering

Aktive temafiler redigeres aldrig direkte. Connectoren kloner det aktive tema til en isoleret workspace-mappe og håndhæver:

- maksimum 2.000 filer og 100 MiB pr. workspace;
- maksimum 1 MiB pr. læst eller skrevet fil;
- læsning af `.php`, `.css`, `.js`, `.json`, `.html`, `.htm` og `.txt`;
- AI-write kun til ikke-eksekverbare `.css`, `.json`, `.html`, `.htm` og `.txt`;
- blokering af `<script>`, `javascript:` og inline event handlers i HTML writes;
- eksisterende filer kræver SHA-256 versionslås før write;
- atomisk temp-fil + rename og efterfølgende SHA-256-verifikation;
- PHP/JS-fingerprint ved workspace-oprettelse og ny kontrol umiddelbart før publish;
- publish nægtes, hvis eksekverbar PHP/JS-kode har ændret sig;
- separat preview og eksplicit bekræftet aktivering.

`DISALLOW_FILE_MODS` respekteres.

## Repository

```text
gateway/                              Cloudflare Worker, D1 migration og remote MCP
wordpress-plugin/agentlinkwp-connector/  WordPress-sikkerhedsplugin
config/permission-catalog.json        Gatewayens rettighedskatalog
src/ og tests/                        Transportuafhængig kontrakt-/sikkerhedsharness
docs/                                 Dansk installation, rettigheder og testprompts
```

`src/`-harnessen bruges til automatiske kontrakt- og WordPress-tests. Produktionsforbindelsen kører online via `gateway/`.

## Lokal validering af kode

Node.js 22.18 eller nyere kræves af det aktuelle Cloudflare/Wrangler-toolchain.

```bash
npm ci
npm run check
npm run check:gateway
npm run check:php
npm test
npm run build
npm run package:plugin
npm run test:wordpress
```

## Cloudflare-opsætning

1. Opret D1-databasen `agentlinkwp` og KV-namespace `agentlinkwp-oauth`, og indsæt deres ID'er i `gateway/wrangler.jsonc`.
2. Deploy Worker-koden og opret en GitHub OAuth App med callback `https://<worker>/callback`.
3. Sæt GitHub-klientoplysninger, `ALLOWED_GITHUB_USER_IDS`, `COOKIE_ENCRYPTION_KEY`, `PLAN_KEY` og `SITES_JSON` som Worker secrets.
4. Kør D1-migrationen, og forbind ChatGPT til `https://<worker>/mcp`.

Eksempelkommandoer findes i [Cloudflare-installationen](docs/CLOUDFLARE_DA.md).

## Bevidste grænser

- Page-builder-data som Elementor-, Divi- og Bricks-layouts ændres ikke direkte, før der er en builder-specifik adapter med schema- og round-trip-tests.
- Vilkårlig shell, rå PHP-/JavaScript-udførelse og SQL writes eksponeres ikke.
- Ukendte write-ruter bliver ikke gjort tilgængelige via break glass; de kræver først en typed adapter og test.
- En read-only SQL-diagnostik og et større sæt native vedligeholdelseskommandoer tilføjes først, når de har særskilte allowlists og negative tests.
- Backup-provider-kontrakten verificerer, at en restore-vej eksisterer; en fuld site-restore gennem AI-broen er ikke implementeret og skal have sin egen typed, særskilt godkendte sikkerhedsmodel.
- Første installation skal prøves på staging og med et verificeret backup-/restore-punkt.

Se [SECURITY.md](SECURITY.md) for trusselsmodel og rapportering.

## Licens

AgentLinkWP Connector er GPL-2.0-or-later. Gateway-koden kan holdes privat i dette repository.